project-cortex

name: project-cortex version: {{PACKAGE_VERSION}} description: | Register tasks BEFORE fixing bugs. Close epics when work is done. Always use CLI for state transitions — never mv files by hand. CLI moves update Status History; manual mv causes probe mismatches. Never leave state drift for the next agent to discover via git log. GTD-style governance: ADR, Epic, Task, Wiki. Numeric-prefixed directories enforce workflow order. Timestamp IDs prevent collision. ZK task review (WHAT/WHY/HOW) ensures subagent-readable requirements before assignment. probe detects stale backlog, epic drift, and history mismatches. when_to_use: | Create a task, create an epic, create an ADR, architecture decision, project management, track requirements, delegate to subagent, ZK review task cards before assignment, 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 "登记" / "记录一下" / "记下来" / "别忘了"
• User says "ZK review this task" / "零知识审查" / "review this task" / "任务能看懂吗" — ZK Review the card before assignment
• Before assigning a task to executor agent — ZK Review the card (WHAT/WHY/HOW, prerequisites, contracts, baselines, scope)
• 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)

CRITICAL — trigger proactively, do NOT wait for user to ask: - Finished a batch of fixes and pushed — verify tasks moved, epic status matches reality - User says "确认epic/task都正常流转" or "还在途的epic是什么" — probe for state drift - Session ending, writing handoff — run cortex list and close stale epics, don't leave them for next agent - Notice an epic marked active but its tasks are all done — it's state drift, close it immediately - Commit message includes Closes:/Task: trailers — verify post-commit dispatch worked, tasks actually moved - ABSOLUTELY FORBIDDEN: mv/cp/rename task or epic files by hand. ALWAYS use CLI: cortex start/done/complete/suspend <id>. Manual moves skip Status History update and create probe noise. allowed-tools: - Bash(bunx @lythos/project-cortex@{{PACKAGE_VERSION}} *)

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.

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

# Create documents (CLI assigns timestamp ID, generates from template)
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} task "Fix login bug"
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} epic "User auth system" --lane main|emergency
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} adr "Choose database"
# Create a Wiki entry (dated, for knowledge capture)
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} wiki "Your insight" --category pattern|faq|lesson
# Initialize cortex/ directory structure in current project
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} init
# Process commit trailers (used by post-commit hook)
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} dispatch-trailers

⚠️ MANDATORY: CLI create is Step 1/3. Step 2/3 is IMMEDIATE EDIT. After cortex task/epic/adr creates the file, you MUST edit it right away to fill Background, Requirements, and Acceptance Criteria. The CLI prints Step 2/3 NOW: Edit the file... — follow it. Empty templates will be REJECTED by pre-commit probe.

English-only slugs are MANDATORY. Task/epic titles must be ASCII-only. Filenames like TASK-xxx-<slug>.md must contain no Chinese or other non-ASCII characters. Use English titles so paths are portable across agents and CLIs.

Agent 不需要自己拼路径或生成 ID。 CLI 会自动处理：timestamp ID、模板填充、目录放置。Agent 只需执行命令，然后从输出中读取返回的完整路径和 ID，然后立即编辑填充内容。标题请用英文，确保 slug 只含 ASCII 字符。

Generate INDEX.md with overview stats and document listing

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} index

List all tasks, epics, ADRs

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} list

Show project statistics

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} stats

Probe: check if file location matches internal status record + epic lane counts

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} probe

## State Machine Commands

```bash
# Task state machine
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} start TASK-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} review TASK-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} done TASK-xxx        # review → completed only
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} complete TASK-xxx    # any status → completed (trailer-driven)
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} suspend TASK-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} resume TASK-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} terminate TASK-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} archive TASK-xxx

# ADR state machine
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} adr accept ADR-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} adr reject ADR-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} adr supersede ADR-xxx --by ADR-yyy

# Epic state machine
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} epic done EPIC-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} epic suspend EPIC-xxx
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} 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 Flags & Modes

# Default mode — full consistency check (all directories, all checks)
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} probe

# Active-only mode — skip status consistency, focus on actionable items only
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} probe --active-only

# Include completed/terminated tasks in empty-shell detection
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} probe --include-completed-empty-shells

Backward compatibility: --suspicious is accepted as a deprecated alias for --active-only and prints a warning to stderr.

What checks run in each mode

Probe Validation Loop

flowchart TD
    A[Run probe] --> B{Dir matches<br/>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<br/>manually or regenerate]
    E -->|History is correct| G[cortex move to<br/>correct directory]
    F --> A
    G --> A

Directory Structure

cortex/
├── INDEX.md
├── adr/
│   ├── 01-proposed/
│   ├── 02-accepted/
│   ├── 03-rejected/
│   └── 04-superseded/
├── epics/
│   ├── 01-active/
│   ├── 99-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.

Preview next IDs before creating:

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} 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

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} adr "Choose database"

Output:

✅ Created: cortex/adr/01-proposed/ADR-20260502110308316-Choose-database.md
🏛️  ADR ID: ADR-20260502110308316

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} task "Fix login bug"

Output:

✅ Created: cortex/tasks/01-backlog/TASK-20260502110308316-Fix-login-bug.md
📝 Task ID: TASK-20260502110308316

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} epic "User auth system"

Output:

✅ Created: cortex/epics/01-active/EPIC-20260502110308316-User-auth-system.md
🎯 Epic ID: EPIC-20260502110308316

Project statistics

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} 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)

bunx @lythos/project-cortex@{{PACKAGE_VERSION}} 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.

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

ADR State Machine

stateDiagram-v2
    [*] --> proposed : create
    proposed --> accepted : accept
    proposed --> rejected : reject
    proposed --> superseded : supersede
    accepted --> superseded : supersede
    rejected --> [*]
    superseded --> [*]

Epic State Machine

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:

Review: TASK-<id>         # in-progress → review (dev complete, submit for review / internal PR)
Closes: TASK-<id>         # review → completed (reviewed and approved / LGTM)
Closes: ADR-<id>          # proposed → accepted
Closes: EPIC-<id>         # active → done
Task: TASK-<id> <verb>    # Explicit task verb
ADR: ADR-<id> <verb>      # ADR verb: accept, reject, supersede
Epic: EPIC-<id> <verb>    # Epic verb: done, suspend, resume

Review: and Closes: are intent aliases for the two most common kanban transitions. Closes: TASK-<id> is strict: it resolves to done and requires the task to already be in review. Use Review: TASK-<id> when development is complete and ready for review.

Example:

git commit -m "feat(api): add endpoint

Review: TASK-20260503010227902"

The post-commit hook auto-dispatches to cortex CLI and creates a follow-up commit with the state changes. Malformed trailers or illegal FSM transitions print warnings but do not block.

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\nReview: TASK-xxx"
    G->>H: trigger hook
    H->>C: dispatch-trailers
    C->>C: parse trailers
    C->>C: move TASK-xxx → review
    C->>G: git add + git commit
    Note over C,G: Follow-up commit with<br/>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 "<reason>" 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.

# 1. Create the epic (generates the file)
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} 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

Subagent workflow (delegate with: "Execute TASK-xxx"):

1. bunx @lythos/project-cortex@{{PACKAGE_VERSION}} start TASK-xxx
2. Implement, commit with task ID in message
3. bunx @lythos/project-cortex@{{PACKAGE_VERSION}} 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@{{PACKAGE_VERSION}} index after any status change. Manual edits will be overwritten.

Supporting References

Read these only when the specific topic arises: