--- name: project-cortex version: 0.9.48 type: standard description: | GTD-style project governance with ADR, Epic, Task, and Wiki. Numeric-prefixed directories (01-backlog, 02-in-progress, etc.) ensure GTD workflow ordering. Timestamp IDs avoid collision without a central database. CLI creates documents, generates indexes, and probes for status inconsistencies. when_to_use: | Create a task, create an epic, create an ADR, architecture decision, project management, track requirements, delegate to subagent, task status, project index, what needs to be done, backlog, milestone, project governance, generate index, probe status. ALSO trigger when: - About to commit and need to write a trailer (Closes: TASK-xxx, Task: TASK-xxx review, ADR: ADR-xxx accept) - Just finished a task and need to move it to review/completed - Need to check active tasks/epics before starting new work - Found a bug or vulnerability — register it as a task BEFORE fixing - Discovered a systemic issue that needs an ADR - QA sweep found findings that need tracking - Need to register a lesson learned or pitfall - User says "登记" / "记录一下" / "记下来" / "别忘了" - See a TASK-xxx or EPIC-xxx reference and need context - User says "登记" (register), "创建任务" (create task), "完成" (done), "推进" (advance), "状态" (status) - Doing session handoff or writing daily notes - husky post-commit trailer processing (Closes:/Task:/ADR: trailers auto-create follow-up commits) allowed-tools: - Bash(bunx @lythos/project-cortex@0.9.48 *) --- # Project Cortex: ADR + Epic + Task + Wiki > Automation over memory. Use CLI for IDs and templates. Use index for discovery. ## Three Systems ``` Epic (WHY) ADR (HOW) Task (WHAT) requirement origin technical decision executable work derives tasks guides tasks links to epic/adr ``` **OS analogy**: Think of the governance system like an operating memory model. | Component | OS Analogy | Role | |-----------|-----------|------| | **Epic** | Memory segment (heap) | Stores the full context — background, requirement tree, zoom-in map. **Workflowy-style**, not a todo list. | | **ADR** | Code segment (text) | Stores ratified decisions — options considered, consequences, follow-ups. Immutable once accepted. | | **Wiki** | Shared library | Reusable knowledge extracted after tasks complete. Patterns, FAQs, lessons. | | **Task** | **Pointer / Reference** | A task card is a `pointer` to epic/adr context plus executable instructions. It does **not** inline the full epic or ADR body — that would be "pass by value" and create drift. | **Pass by reference, not by value**: A task card should contain precise pointers (`Refs: EPIC-xxx`, `See ADR-yyy §Decision`, `Modify: src/path.ts`) so a subagent can navigate to source of truth. The card is a **map**, not a warehouse. A new team member reading only AGENTS.md + the task card should be able to find everything needed without asking for clarification. ## CLI Commands ```bash # Create documents (CLI assigns timestamp ID, generates from template) bunx @lythos/project-cortex@0.9.48 task "Fix login bug" bunx @lythos/project-cortex@0.9.48 epic "User auth system" --lane main|emergency bunx @lythos/project-cortex@0.9.48 adr "Choose database" # Create a Wiki entry (dated, for knowledge capture) bunx @lythos/project-cortex@0.9.48 wiki "Your insight" --category pattern|faq|lesson # Initialize cortex/ directory structure in current project bunx @lythos/project-cortex@0.9.48 init # Process commit trailers (used by post-commit hook) bunx @lythos/project-cortex@0.9.48 dispatch-trailers ``` > **Agent 不需要自己拼路径或生成 ID。** CLI 会自动处理：timestamp ID、模板填充、目录放置。Agent 只需执行命令，然后从输出中读取返回的完整路径和 ID。 # Generate INDEX.md with overview stats and document listing bunx @lythos/project-cortex@0.9.48 index # List all tasks, epics, ADRs bunx @lythos/project-cortex@0.9.48 list # Show project statistics bunx @lythos/project-cortex@0.9.48 stats # Probe: check if file location matches internal status record + epic lane counts bunx @lythos/project-cortex@0.9.48 probe ``` ## State Machine Commands ```bash # Task state machine bunx @lythos/project-cortex@0.9.48 start TASK-xxx bunx @lythos/project-cortex@0.9.48 review TASK-xxx bunx @lythos/project-cortex@0.9.48 done TASK-xxx # review → completed only bunx @lythos/project-cortex@0.9.48 complete TASK-xxx # any status → completed (trailer-driven) bunx @lythos/project-cortex@0.9.48 suspend TASK-xxx bunx @lythos/project-cortex@0.9.48 resume TASK-xxx bunx @lythos/project-cortex@0.9.48 terminate TASK-xxx bunx @lythos/project-cortex@0.9.48 archive TASK-xxx # ADR state machine bunx @lythos/project-cortex@0.9.48 adr accept ADR-xxx bunx @lythos/project-cortex@0.9.48 adr reject ADR-xxx bunx @lythos/project-cortex@0.9.48 adr supersede ADR-xxx --by ADR-yyy # Epic state machine bunx @lythos/project-cortex@0.9.48 epic done EPIC-xxx bunx @lythos/project-cortex@0.9.48 epic suspend EPIC-xxx bunx @lythos/project-cortex@0.9.48 epic resume EPIC-xxx ``` `probe` is a read-only consistency check. It compares each document's directory (source of truth) against its internal Status History table. Mismatches are flagged for human review — probe never auto-fixes. ### Probe Validation Loop ```mermaid flowchart TD A[Run probe] --> B{Dir matches
Status History?} B -->|Yes| C[✅ All consistent] B -->|No| D[⚠️ Mismatch found] D --> E{Which is truth?} E -->|Dir is correct| F[Update Status History
manually or regenerate] E -->|History is correct| G[cortex move to
correct directory] F --> A G --> A ``` ## Directory Structure ``` cortex/ ├── INDEX.md ├── adr/ │ ├── 01-proposed/ │ ├── 02-accepted/ │ ├── 03-rejected/ │ └── 04-superseded/ ├── epics/ │ ├── 01-active/ │ ├── 02-done/ │ ├── 03-suspended/ │ └── 04-archived/ ├── tasks/ │ ├── 01-backlog/ ← Capture + Clarify │ ├── 02-in-progress/ ← Engage │ ├── 03-review/ ← Pending acceptance │ ├── 04-completed/ ← Normal completion │ ├── 05-suspended/ ← Blocked (recoverable) │ ├── 06-terminated/ ← Cancelled (abnormal end) │ └── 07-archived/ ← Final archive └── wiki/ ├── 01-patterns/ ← Reusable solutions ├── 02-faq/ ← Common questions ├── 03-lessons/ ← Retrospectives └── 04-legacy/ ← Outdated but historically valuable ``` Numeric prefixes ensure GTD workflow ordering in `ls` output. ## ID Format `PREFIX-yyyyMMddHHmmssSSS` (17 digits). Collision-free, self-sorting, no registry. | Type | Example | |------|---------| | Task | `TASK-20250420120000000` | | Epic | `EPIC-20250420120100000` | | ADR | `ADR-20250420120200000` | **Preview next IDs before creating:** ```bash bunx @lythos/project-cortex@0.9.48 next-id ``` Output: ``` 📋 Timestamp ID Format: Task: TASK-20260502110420008 Epic: EPIC-20260502110420009 ADR: ADR-20260502110420009 Format: PREFIX-yyyyMMddHHmmssSSS (17 digits) ``` ## Command Output Examples Agents should expect the following output patterns when invoking CLI commands. ### Creating a document ```bash bunx @lythos/project-cortex@0.9.48 adr "Choose database" ``` Output: ``` ✅ Created: cortex/adr/01-proposed/ADR-20260502110308316-Choose-database.md 🏛️ ADR ID: ADR-20260502110308316 ``` ```bash bunx @lythos/project-cortex@0.9.48 task "Fix login bug" ``` Output: ``` ✅ Created: cortex/tasks/01-backlog/TASK-20260502110308316-Fix-login-bug.md 📝 Task ID: TASK-20260502110308316 ``` ```bash bunx @lythos/project-cortex@0.9.48 epic "User auth system" ``` Output: ``` ✅ Created: cortex/epics/01-active/EPIC-20260502110308316-User-auth-system.md 🎯 Epic ID: EPIC-20260502110308316 ``` ### Project statistics ```bash bunx @lythos/project-cortex@0.9.48 stats ``` Output: ``` 📊 Project Statistics: Tasks: Backlog : 3 In Progress : 1 Review : 0 Completed : 5 Suspended : 0 Terminated : 0 Archived : 2 Epics: Active : 1 Archived : 0 ADRs: Proposed : 2 Accepted : 1 Rejected : 0 Superseded : 0 Wiki: Patterns : 4 FAQ : 1 Lessons : 0 ``` ### Consistency probe (read-only) ```bash bunx @lythos/project-cortex@0.9.48 probe ``` Output when consistent: ``` 🔍 Probing cortex consistency... ✅ All documents consistent. ``` Output when mismatches found: ``` 🔍 Probing cortex consistency... ⚠️ 1 inconsistency found: cortex/tasks/01-backlog/TASK-20260502110308316-Fix-login-bug.md Status History claims: 02-in-progress Actual directory: 01-backlog → File location does not match latest status record ``` ## Task State Machine (FSM) Directory location is the source of truth. Status History mirrors the directory. ```mermaid stateDiagram-v2 [*] --> backlog : create backlog --> in_progress : start in_progress --> review : review review --> completed : done in_progress --> suspended : suspend suspended --> in_progress : resume review --> in_progress : reject backlog --> terminated : terminate in_progress --> terminated : terminate review --> terminated : terminate suspended --> terminated : terminate completed --> archived : archive completed --> [*] terminated --> [*] archived --> [*] note right of review done: review → completed only complete: any → completed (trailer-driven) end note ``` ### Transition Table | From | To | Who | Trigger | CLI Command | |------|----|-----|---------|-------------| | backlog | in-progress | Subagent | Begins implementation | `bunx @lythos/project-cortex@0.9.48 start TASK-xxx` | | in-progress | review | Subagent | Core deliverables done, committed with task ID | `bunx @lythos/project-cortex@0.9.48 review TASK-xxx` | | review | completed | User/System | Exit criteria met, acceptance passed | `bunx @lythos/project-cortex@0.9.48 done TASK-xxx` | | any | completed | Trailer/Hook | Commit trailer closes task | `bunx @lythos/project-cortex@0.9.48 complete TASK-xxx` | | in-progress | suspended | Any | Blocked by external dependency | `bunx @lythos/project-cortex@0.9.48 suspend TASK-xxx` | | suspended | in-progress | Any | Blocker resolved | `bunx @lythos/project-cortex@0.9.48 resume TASK-xxx` | | any | terminated | User/System | Task cancelled or obsolete | `bunx @lythos/project-cortex@0.9.48 terminate TASK-xxx` | | completed | archived | User/System | Long-term storage | `bunx @lythos/project-cortex@0.9.48 archive TASK-xxx` | | review | in-progress | User/System | Deliverables rejected, re-work required | `bunx @lythos/project-cortex@0.9.48 reject TASK-xxx` | ### ADR State Machine ```mermaid stateDiagram-v2 [*] --> proposed : create proposed --> accepted : accept proposed --> rejected : reject proposed --> superseded : supersede accepted --> superseded : supersede rejected --> [*] superseded --> [*] ``` ### Epic State Machine ```mermaid stateDiagram-v2 [*] --> active : create active --> done : done active --> suspended : suspend suspended --> active : resume done --> archived : archive active --> [*] suspended --> [*] done --> [*] archived --> [*] ``` ## Commit Trailer Integration Cortex governance is **commit-driven** via git trailers parsed by `.husky/post-commit`: ``` Closes: TASK- # Any status → completed (task), proposed → accepted (ADR), active → done (epic) Task: TASK- # Explicit task verb ADR: ADR- # ADR verb: accept, reject, supersede Epic: EPIC- # Epic verb: done, suspend, resume ``` Example: ```bash git commit -m "feat(api): add endpoint Closes: TASK-20260503010227902" ``` The post-commit hook auto-dispatches to `cortex` CLI and creates a follow-up commit with the state changes. Malformed trailers print warnings but do not block. ```mermaid sequenceDiagram participant A as Agent/User participant G as Git Commit participant H as post-commit Hook participant C as cortex CLI A->>G: git commit -m "feat: ...\n\nCloses: TASK-xxx" G->>H: trigger hook H->>C: dispatch-trailers C->>C: parse trailers C->>C: move TASK-xxx → completed C->>G: git add + git commit Note over C,G: Follow-up commit with
state change appended ``` ## Epic Lane Discipline - **Dual-track lanes**: `lane: main` (current iteration focus, max 1 active) and `lane: emergency` (unavoidable urgent insert, max 1 active). - **5-question checklist** at creation: outcome clear? / closable in 1-3 weeks? / fits 1-3 week size? / not a task? / not an ADR? - Lane-full = rejection unless `--override ""` is provided. - `cortex probe` warns when >1 active epic per lane. ## Epic-ADR Coupling When an epic is created to implement a proposed ADR, **accept the ADR immediately**. An epic in `01-active/` means the decision is ratified and work is underway — a proposed ADR must not lag behind its implementation epic. **Let pre-commit handle it.** The `.husky/pre-commit` hook scans staged epic files in `cortex/epics/01-active/`. If an epic's corresponding ADR is still in `01-proposed/` (detected via the ADR's `Related → Epic:` field), the hook **auto-accepts** the ADR and stages the move — before the commit even finishes. ```bash # 1. Create the epic (generates the file) bunx @lythos/project-cortex@0.9.48 epic "Implement kanban flow" --lane main # 2. Commit the epic — pre-commit auto-accepts the linked ADR # (ADR must reference the epic in its ## Related section: "Epic: EPIC-xxx") git add cortex/epics/01-active/EPIC-xxx-Implement-kanban-flow.md git commit -m "epic(kanban): start kanban flow implementation" # ↑ pre-commit auto-runs: cortex adr accept ADR-yyy ``` **Probe also guards this**: `cortex probe` reports any proposed ADR that references an active epic as an **ADR-Epic coupling warning** — a proposed ADR should not reference an epic that is already underway. **Why this matters**: Agents frequently forget to `adr accept` after creating an epic. By making the accept **pre-commit automated** (plus probe as a read-only safety net), the ADR state stays in sync with the epic lifecycle without relying on working memory. ## Git Integration (Critical) Commits **must** include task ID in the message title: ✅ `git commit -m "feat(api): add endpoint (TASK-20250422143321029)"` ❌ `git commit -m "feat(api): add endpoint"` This enables: traceability (code ↔ task), audit (`git log --grep TASK-`), rollback by task scope, automation parsing. After user says "LGTM": `git tag -a v0.X.0 -m "feat: description"` ## Role Separation | Role | Can do | Operates on | |------|--------|-------------| | **User/System** | Create epics/ADRs, archive, final review, mark done | epics/, adr/, tasks/04-completed/ | | **Subagent** | Execute tasks, drive status forward | tasks/01-backlog/ → 02-in-progress/ → 03-review/ | **Subagent workflow** (delegate with: "Execute TASK-xxx"): 1. `bunx @lythos/project-cortex@0.9.48 start TASK-xxx` 2. Implement, commit with task ID in message 3. `bunx @lythos/project-cortex@0.9.48 review TASK-xxx` 4. **Stop here.** Never use `done` — that requires user acceptance. ## Milestone Protocol (Prevents Fake Completion) Every task must define at creation: - **Exit criteria**: one sentence defining "done enough" - **Deliverables table**: what was produced + how to verify - **Explicitly not delivering**: scope excluded from this milestone - **Exit reason**: why stop now (links to exit criteria) **Anti-patterns that cause real failures:** | Anti-pattern | Example | Consequence | |-------------|---------|-------------| | Checklist = done | 5 deliverables planned, 1 built, all boxes checked | Fake completion | | No "not delivering" | "Let me research more", "Let me polish" | Endless refinement | | Vague exit criteria | "Good enough" | Agent decides own standard, drift | | Deliverables in tmp/ | Report written to tmp/, never archived | Lost in next session | ✅ Mark completed when: core deliverables exist, exit reason stated, not-delivering declared. ❌ Do not mark completed when: only checkboxes ticked, exit criteria is "roughly done", undeclared TODOs remain. **Always use CLI commands to move tasks.** Never `mv` files manually or edit Status History by hand. The CLI enforces valid FSM transitions, appends Status History, and regenerates INDEX.md automatically. ## Gotchas **Always use CLI for all state changes.** Creating documents, moving tasks, archiving — everything goes through CLI. Never `mv` or edit files manually. Manual changes bypass FSM validation and cause probe mismatches. The CLI handles template alignment, correct timestamp IDs, and initial directory placement. Manual creation risks ID collision and template drift. **probe does not auto-fix.** It only surfaces inconsistencies between file location and internal status. Human decides whether to move the file or update the record. This is deliberate — status ambiguity requires human judgment. **Templates in assets/, not in SKILL.md.** If you need to see the template format, read `${CLAUDE_SKILL_DIR}/assets/TASK-TEMPLATE.md` (or ADR/EPIC). Or look at existing files in cortex/ — the playground examples are real CLI output. **INDEX.md is generated, not hand-edited.** Run `bunx @lythos/project-cortex@0.9.48 index` after any status change. Manual edits will be overwritten. ## Supporting References Read these **only when the specific topic arises**: | When you need to… | Read | |--------------------|------| | Understand ADR/Epic/Task template fields in detail | [references/template-guide.md](./references/template-guide.md) | | Write good Epics, ADRs, or Tasks (best practices) | [references/writing-guide.md](./references/writing-guide.md) | | Perform session handoff or onboard a new agent | [references/session-handoff.md](./references/session-handoff.md) | | Use Wiki for knowledge capture after task completion | [references/wiki-workflow.md](./references/wiki-workflow.md) | | See a complete end-to-end workflow example | [references/example-workflow.md](./references/example-workflow.md) | | Understand the milestone protocol in full detail | [references/milestone-protocol.md](./references/milestone-protocol.md) | | See complete state machine rules, valid transitions, and error guidance | [references/state-machines.md](./references/state-machines.md) |