project-cortex

name	project-cortex
version	0.17.2
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. **Task-git discipline**: One task = 2-5 commits (core, tests, docs, trailer). Every commit includes TASK-xxx for traceability. Task card includes Commit Map and Verification Matrix.
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@0.17.2 *)"]

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

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

Task-Git Discipline

One task = 2-5 commits, not 1 giant commit. Separate:

1. Core change — implementation
2. Tests — co-located *.test.ts
3. Docs/templates — SKILL.md, AGENTS.md updates
4. Review trailer — Review: TASK-xxx empty commit

Task card must include:

• Commit Map: | Hash | Message | Contains | — reviewer runs git show <hash>
• Verification Matrix: | # | Claim | Verify | Expected | — each AC has → Verify: <command>
• Quick Check: 30-second bash block reviewer can copy-paste

Every commit message includes TASK-xxx. Enables git log --grep TASK-xxx to reconstruct full history.

Generate INDEX.md with overview stats and document listing

bunx @lythos/project-cortex@0.17.2 index

List all tasks, epics, ADRs

bunx @lythos/project-cortex@0.17.2 list

Show project statistics

bunx @lythos/project-cortex@0.17.2 stats

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

bunx @lythos/project-cortex@0.17.2 probe

## State Machine Commands

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

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

# Epic state machine
bunx @lythos/project-cortex@0.17.2 epic done EPIC-xxx
bunx @lythos/project-cortex@0.17.2 epic suspend EPIC-xxx
bunx @lythos/project-cortex@0.17.2 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@0.17.2 probe

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

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

Flag	Behavior	When to use
(none)	Full check: status consistency + lane occupancy + ADR-Epic coupling + staleness + empty shells (active states only) + coverage drift + non-ASCII slugs	Default — run at session start/end
--active-only	Skips per-file status consistency. Only checks: lane occupancy, coupling, staleness, drift, empty shells, coverage drift, slugs. Empty-shell filter narrowed to backlog/in-progress/proposed only.	Quick scan — "what needs my attention now?"
--include-completed-empty-shells	Expands empty-shell detection to include completed, terminated, archived, done, suspended, accepted, rejected, superseded directories.	Historical review — "did any templates slip through unfilled in old tasks?"

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

What checks run in each mode

Check	Default	--active-only	Description
Status consistency	✅	❌	Directory matches latest Status History entry
Lane occupancy	✅	✅	Max 1 active epic per lane (main / emergency)
ADR-Epic coupling	✅	✅	Proposed ADR must not reference active epic
Staleness	✅	✅	Backlog tasks >3 days old; active epics >3 days old
Empty shells	✅ (active states only)	✅ (active states only)	Template placeholders never filled by agent. Default and --active-only both check active states only; use --include-completed-empty-shells to audit all states.
Coverage drift	✅	✅	Git commits since last coverage snapshot. Only appears when packages/*/test/scenarios/coverage-snapshot-*.md files exist and source files have changed since the snapshot date. If no snapshots exist, this check silently passes.
Non-ASCII slugs	✅	✅	Filenames must be ASCII-only

Glossary

Term	Definition
Empty shell	A task/epic/ADR file created by cortex CLI but never filled by an agent. Like a Jira ticket with only a title and no description — it provides zero guidance to whoever picks it up. Detected by template placeholders (⚠️ PLACEHOLDER_, 需求1, <!-- 填写) that remain in the content. Rule: filling content is higher priority than writing code.
Stale	Backlog tasks or active epics that have been in their current state for >3 days without progress. Indicates potential state drift — either the work is done (should be closed) or the task is blocked (should be suspended).
Coverage drift	Changes to source files since the last coverage snapshot was taken. Detected by comparing git commits since the snapshot date. Only relevant when packages/*/test/scenarios/coverage-snapshot-*.md files exist.

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.

Type	Example
Task	TASK-20250420120000000
Epic	EPIC-20250420120100000
ADR	ADR-20250420120200000

Preview next IDs before creating:

bunx @lythos/project-cortex@0.17.2 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@0.17.2 adr "Choose database"

Output:

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

bunx @lythos/project-cortex@0.17.2 task "Fix login bug"

Output:

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

bunx @lythos/project-cortex@0.17.2 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@0.17.2 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@0.17.2 probe

Output when consistent:

🔍 Probing status consistency...
Rule: Directory location is the source of truth.
Status History inside files should reflect the latest move.

📄 Tasks:
  ✅ file1
  ✅ file2

🛤️  Epic lanes (active):
     main:      0
     emergency: 0

──────────────────────────────────────────────────
✅ All documents consistent.
📊 42 documents checked, 0 issue(s) found.

Output when mismatches found:

🔍 Probing status consistency...
Rule: Directory location is the source of truth.
Status History inside files should reflect the latest move.

📄 Tasks:
  ❌ cortex/tasks/01-backlog/TASK-20260502110308316-Fix-login-bug.md
     → Status History 最后记录 "in-progress" 与目录状态 "backlog" 不一致...

  ⚠️  1 个问题需人工确认

🛤️  Epic lanes (active):
     main:      0
     emergency: 0

──────────────────────────────────────────────────
⚠️  Found 1 status issue(s) requiring human confirmation.
   Please review the items above and decide:
   - Move file to correct directory, OR
   - Update Status History inside the file.
📊 42 documents checked, 1 issue(s) found.

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

From	To	Who	Trigger	CLI Command
backlog	in-progress	Subagent	Begins implementation	bunx @lythos/project-cortex@0.17.2 start TASK-xxx
in-progress	review	Subagent/Trailer	Core deliverables done, submit for review	bunx @lythos/project-cortex@0.17.2 review TASK-xxx or Review: TASK-xxx trailer
review	completed	User/System	Exit criteria met, acceptance passed	bunx @lythos/project-cortex@0.17.2 done TASK-xxx
review	completed	Trailer/Hook	Commit trailer closes task after review / LGTM	Closes: TASK-xxx trailer
any	completed	User/System	Explicit any-status close (use sparingly)	bunx @lythos/project-cortex@0.17.2 complete TASK-xxx
in-progress	suspended	Any	Blocked by external dependency	bunx @lythos/project-cortex@0.17.2 suspend TASK-xxx
suspended	in-progress	Any	Blocker resolved	bunx @lythos/project-cortex@0.17.2 resume TASK-xxx
any	terminated	User/System	Task cancelled or obsolete	bunx @lythos/project-cortex@0.17.2 terminate TASK-xxx
completed	archived	User/System	Long-term storage	bunx @lythos/project-cortex@0.17.2 archive TASK-xxx
review	in-progress	User/System	Deliverables rejected, re-work required	bunx @lythos/project-cortex@0.17.2 reject TASK-xxx

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. All task trailers generate task <verb> <id> commands (explicit kind prefix):

Review: TASK-<id>         # → task review TASK-<id>  (in-progress → review)
Closes: TASK-<id>         # → task done TASK-<id>   (review → completed, strict)
Closes: ADR-<id>          # → adr accept ADR-<id>   (proposed → accepted)
Closes: EPIC-<id>         # → epic done EPIC-<id>   (active → done)
Task: TASK-<id> <verb>    # → task <verb> TASK-<id> (explicit task verb)
ADR: ADR-<id> <verb>      # → adr <verb> ADR-<id>   (ADR verb: accept, reject, supersede)
Epic: EPIC-<id> <verb>    # → epic <verb> EPIC-<id> (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 task done and requires the task to already be in review. Use Review: TASK-<id> when development is complete and ready for review.

Legacy aliases (backward compatible): start, review, done, complete, suspend, resume, reject, terminate, archive also work as top-level commands without task prefix.

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@0.17.2 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.17.2 start TASK-xxx
2. Implement, commit with task ID in message
3. bunx @lythos/project-cortex@0.17.2 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.17.2 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
Write good Epics, ADRs, or Tasks (best practices)	references/writing-guide.md
Perform session handoff or onboard a new agent	references/session-handoff.md
Use Wiki for knowledge capture after task completion	references/wiki-workflow.md
See a complete end-to-end workflow example	references/example-workflow.md
Understand the milestone protocol in full detail	references/milestone-protocol.md
Design tasks that a ZK agent can execute without asking (WHAT/WHY/HOW method)	references/zk-review.md
See complete state machine rules, valid transitions, and error guidance	references/state-machines.md