--- name: docs-project-management description: "Universal, project-agnostic playbook for managing an ENTIRE project inside the repo's docs/ folder — the docs/-native system of record, reusable in any project, new or existing, with no external issue tracker. Defines WHAT it manages: the work-item TAXONOMY (Roadmap → docs/ROADMAP.md + docs/roadmap.json, PRD → docs/prd/, TRD → docs/trd/, Epic → docs/epics/, User Story → docs/user_stories/, Test Case → docs/test_cases/, Bug → docs/bugs/, per-session team reports → docs/sessions/, feature work-log → docs/reports/), the cross-document LINK GRAPH written as relative-markdown links (User Story part-of Epic; Test Case is-tested-by User Story; Bug blocks its story; PRD↔TRD), the YAML-frontmatter STATUS lifecycle + the bookend rule (transition status: forward before starting work, again when done), required frontmatter fields, the mandatory Test Case Template and the Bug+RCA report format, the TEAM WORK-REPORTING convention (one session folder per run; every agent bookends a start/completion report there + appends to its feature log), and the docs/ vs .ai_log/ split — durable records are committed markdown in docs/; .ai_log/ holds ONLY temporary git-ignored evidence (screenshots, run logs, scratch payloads, pipeline-state handoff JSON) passed by path and PROMOTED to docs/ if it turns out durable. Attached to EVERY agent." --- TASKLANG TYPE SKILL IDENTITY "Docs Project Management (the docs/-native system of record)" > A universal, reusable playbook for running a whole project — requirements, planning, build > tracking, testing, bugs, and team reporting — as committed markdown inside the repo's `docs/` > folder. It works in ANY project, in any stack, from day one of a NEW project: no external issue > tracker, no ticket system, no proprietary tooling. A work item is a markdown file with YAML > frontmatter; a relationship is a relative markdown link; a status change is a frontmatter edit; > the full history is git. > > It does three jobs: > 1. WORK-ITEM MODEL — WHAT document types exist (PRD, TRD, Epic, User Story, Test Case, Bug, > Roadmap), WHERE each lives, HOW they link, and HOW status is tracked. > 2. TEAM WORK-REPORTING — HOW every agent/contributor reports its work so anyone can see, in one > committed place, everything that was done (who, what, when, with which evidence). > 3. DURABLE vs TEMPORARY — WHAT belongs in committed `docs/` versus the git-ignored `.ai_log/` > temp-evidence folder, and when to promote content from one to the other. --- ## §1 Document types — WHAT the system manages > Every work item is a committed markdown file in its `docs/` subfolder: descriptive kebab-case > filename (never an opaque ID), YAML frontmatter for status/metadata, relative-markdown links for > relationships. Full field-level detail: [[work-item-taxonomy]]. TABLE document-types COLUMNS: Type, Lives in, What it is / holds ROW: Project brief | docs/project_brief.md | The product spec — the SOURCE OF TRUTH the whole project derives from; wins over any assumption ROW: Project config| docs/project_config/info.md | The single home for project-specific FACTS (product name, app name, stack, domain, scope, success scenarios) — agents read it instead of hard-coding facts ROW: Roadmap | docs/ROADMAP.md + docs/roadmap.json | The milestone/release plan (human file) + a machine-readable MIRROR of every work item's current status (JSON cache, regenerated from docs/, committed) ROW: PRD | docs/prd/ | Product Requirements Document — WHAT to build and WHY: objectives, in-scope / out-of-scope, testable acceptance criteria per success scenario ROW: TRD | docs/trd/ | Technical Requirements Document — HOW to build it: architecture, data model, migrations, jobs, authz. Canonical TRD home; keep `index.json` (machine registry, one entry per TRD) + `index.md` (human index) beside the files ROW: Epic | docs/epics/ | A large feature/theme grouping related User Stories; carries goal + scope + its story list ROW: User Story | docs/user_stories/ | The smallest shippable requirement — "as a I want " + numbered acceptance criteria; filename `NNN-.md` ROW: Test Case | docs/test_cases/ | A verification script for ONE behavior — numbered navigate→action→expected steps; filename `tc-NNN-.md`; MUST follow the [[test-case-template]] and link its story "is tested by" ROW: Bug | docs/bugs/ | A defect AND its Root-Cause-Analysis in ONE file — Symptom/Reproduction + 5-Whys RCA + Preventative Action at detection; Fix/diff/Resolved sections completed by whoever fixes it ([[bug-rca-report]]); `blocks` its story ROW: Session report| docs/sessions/-/ | Per-run team work folder — a README manifest + one bookended report per agent/phase ([[session-reporting]]) ROW: Feature log | docs/reports/feature-log.md + feature-log/ | The team work-log split by feature: one lean index row per feature, linking a per-feature file where each run appends a row RULES - Filenames: descriptive kebab-case, never opaque IDs. External refs (ticket numbers), when they exist, go in frontmatter + the title line — not the filename. - Each subfolder may carry a `template_.md` seed; new items copy its shape. - Only APPROVED/final content advances status; drafts stay in their lifecycle state. --- ## §2 The link graph — HOW documents relate > Every relationship is a labelled RELATIVE-MARKDOWN link in a `## Linked Documents` section, written > in BOTH files (add the reciprocal link). No link-type IDs, no tracker mechanics — the label carries > the semantic. Full table + exact syntax: [[link-graph]]. - User Story **is part of** its Epic; the Epic lists it back (**realized by**). - Test Case ↔ User Story is ALWAYS **"is tested by"** (story side) / **"tests"** (test-case side) — never "relates to" or "part of". - Bug **blocks** the User Story it breaks; the story links the bug back. - PRD ↔ TRD cross-link (**specified by**); User Story is **derived from** its PRD. --- ## §3 Status lifecycle — HOW progress is tracked > Status lives in each file's YAML frontmatter `status:` field; changing status = editing that field. > Full lifecycle, required frontmatter fields, and the signature convention: [[status-lifecycle]]. LIFECYCLE status VALUES: backlog → ready → in_progress → in_review → qa → done (blocked = orthogonal flag) > Pick the closest value per item type: a Bug walks open → in_progress → fixed → verified → closed; > a Test Case walks draft → ready → automated. BOOKEND both-ends - ON START: set `status: in_progress` BEFORE touching the work; stamp `updated:`. - ON COMPLETION: set the next appropriate state (`in_review` / `qa` / `done`); stamp `updated:`. - NEVER leave a worked file on its old status — that is an incomplete bookend. SIGNATURE - Sign every file update / report entry: `— v ()`. --- ## §4 Team work-reporting — HOW work becomes visible > One committed place per run where anyone can see all work done. Full layout, report schema, and > per-role sections: [[session-reporting]]. 1. The orchestrator (or the first agent of a run) CREATES the session folder `docs/sessions/-/` with a `README.md` manifest (request, plan, a phase→agent→status→report table) and passes `session_dir` to every worker. 2. EVERY agent bookends its run there — `/-.md`, created with a STARTING entry, updated on COMPLETION (work done, work items touched as links, evidence links), flipping its row in the session README. 3. Each agent ALSO appends a run-row to its feature's log `docs/reports/feature-log/.md` (indexed by the lean `docs/reports/feature-log.md`). 4. Reports carry the role-specific section: QA → coverage report; security → findings + verdict; devops → deploy/CI status; architect → gate verdict; PM → acceptance verdict. --- ## §5 `docs/` vs `.ai_log/` — durable vs temporary > The one split that keeps context lean AND the record complete. Never confuse the two. **`docs/` — durable, committed, the system of record.** Anything with lasting value lives here: specs, decisions, work items, reports, audits, backlog/deferred-work notes, coverage summaries. **`.ai_log/` — temporary, git-ignored, evidence offload ONLY.** The folder is tracked via `.gitkeep`; its CONTENTS are ignored and therefore never committed — anything left only there is effectively lost. Belongs in `.ai_log/`: - screenshots / diff images / browser captures taken as run evidence - run logs, test-run output, scratch files, intermediate payloads too big for context - the per-session pipeline-state handoff JSON (`.ai_log/session--.json`) — the machine bus that carries key fields + PATHS between phases - naming: `.ai_log/--.` RULES - Hand off by PATH, never by inlining a blob into a prompt or a state file. - PROMOTE anything durable that lands in `.ai_log/` into the right `docs/` subfolder (with frontmatter + links) before relying on it — a decision or report parked only in `.ai_log/` does not exist as a record. - Reports in `docs/` may LINK to `.ai_log/` evidence, knowing it is ephemeral. --- ## §6 Adopting in a NEW project — bootstrap CHECKLIST bootstrap [ ] Create the skeleton: `docs/{prd,trd,epics,user_stories,test_cases,bugs,sessions,reports/feature-log,project_config}/` + `docs/ROADMAP.md` [ ] Write `docs/project_brief.md` (the spec) and `docs/project_config/info.md` (the project facts) [ ] Create `.ai_log/` with a tracked `.gitkeep`; git-ignore its contents (`/.ai_log/*` + `!/.ai_log/.gitkeep`) [ ] Seed `docs/reports/feature-log.md` (empty index) and `docs/roadmap.json` (empty mirror) [ ] Drop a `template_.md` into each work-item subfolder if you want enforced shapes > Nothing else is required — the model is just folders + markdown + frontmatter + relative links. --- ## The Map — load the one reference you need > This SKILL.md is a MAP. Deep detail lives in atomized `references/` notes; load only what the task > needs. Machine-readable nav: `maps/index.json` (+ `tags.json`, `links.json`, `manifest.json`). TABLE references COLUMNS: Note, Owns, Load when ROW: [[work-item-taxonomy]] | §1 detail — folder, filename pattern, owner per work item | You need a work item's folder, filename pattern, or owner ROW: [[link-graph]] | §2 detail — every relationship's semantic, direction, exact syntax | Linking two work items / checking a relationship's direction ROW: [[status-lifecycle]] | §3 detail — lifecycle values, bookend, required frontmatter fields, signature | Starting/finishing work, setting status, filling frontmatter ROW: [[test-case-template]] | The mandatory Test Case Template (all fields) | Authoring/reviewing a docs/test_cases/ file ROW: [[bug-rca-report]] | The Bug+RCA format — detection sections (Symptom/Repro/5-Whys/Preventative Action) + fix sections (Fix/diff/Resolved) | Authoring/completing a docs/bugs/ Bug file ROW: [[session-reporting]] | §4 detail — session folder layout, report schema, role sections, feature log | Bookending your run as a report; organizing a session folder ROW: [[conventions-recap]] | The non-negotiables checklist + the Knowledge Strategy | A one-glance rule check; rules for updating this skill --- ## Non-negotiables (one-glance) CHECKLIST conventions [ ] Every work item = a committed markdown file in its §1 subfolder, kebab-named, frontmatter'd [ ] Every relationship = a labelled relative-markdown link, written reciprocally in both files [ ] Status bookended at BOTH ends by editing frontmatter `status:` — never left stale [ ] Test Cases follow the template AND link their story "is tested by" [ ] Bugs are one Bug+RCA file: detection sections at filing, fix sections completed by the fixer [ ] Every run bookends a report in `docs/sessions//` + a feature-log row [ ] Durable content in `docs/` (committed); ONLY temporary evidence in `.ai_log/` (git-ignored); promote anything durable that lands in `.ai_log/` [ ] No external tracker mechanics — everything is a local `docs/` file, linked by relative paths --- ## Knowledge Strategy - Patterns to capture: recurring item shapes, link-graph edge cases, report sections that proved useful. - Update permission: agents may freely add/update files in `references/`; changes to THIS SKILL.md map require user approval. Full strategy: [[conventions-recap]]. --- Made by **HasBrains** — https://hasbrains.com/