| 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:
- 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.
- 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).
- 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-<kebab-title>.md
ROW: Test Case | docs/test_cases/ | A verification script for ONE behavior — numbered navigate→action→expected steps; filename tc-NNN-<kebab-behavior>.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_<type>.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:
— <agent-name> v<version> (<passport-id>).
§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]].
- The orchestrator (or the first agent of a run) CREATES the session folder
docs/sessions/<YYYY-MM-DD>-<slug>/ with a README.md manifest (request, plan, a
phase→agent→status→report table) and passes session_dir to every worker.
- EVERY agent bookends its run there —
<session_dir>/<phase-N>-<agent>.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.
- Each agent ALSO appends a run-row to its feature's log
docs/reports/feature-log/<slug>.md
(indexed by the lean docs/reports/feature-log.md).
- 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-<id>-<name>.json) — the machine
bus that carries key fields + PATHS between phases
- naming:
.ai_log/<phase-N>-<agent>-<artifact>.<ext>
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_<type>.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/<session>/ + 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]].
