Project Cortex: ADR + Epic + Task + Wiki

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.

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 "登记" / "记录一下" / "记下来" / "别忘了"
• Before assigning a task to an executor agent — ZK Review the card (WHAT/​WHY/​HOW, prerequisites, contracts, baselines, scope)
• See a TASK-xxx or EPIC-xxx reference and need context
• husky post-commit trailer processing (trailers auto-create follow-up commits)

CRITICAL — trigger proactively, do NOT wait for the user to ask:

• Finished a batch of fixes and pushed — verify tasks moved, epic status matches reality
• Writing or updating daily notes (save discipline — after ANY commit batch) — run cortex list and close stale epics, don't leave them for the 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.

CLI Commands

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

The agent never hand-assembles paths or generates IDs. The CLI handles timestamp IDs, template filling, and directory placement. The agent runs the command, reads the full path and ID from its output, and immediately edits the file to fill in content. Write titles in English so the slug stays ASCII-only.

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/​[email protected] index

List all tasks, epics, ADRs

bunx @lythos/​[email protected] list

Show project statistics

bunx @lythos/​[email protected] stats

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

bunx @lythos/​[email protected] probe

## State Machine Commands

```bash
# Task state machine
bunx @lythos/​[email protected] start TASK-xxx
bunx @lythos/​[email protected] review TASK-xxx
bunx @lythos/​[email protected] done TASK-xxx        # review → completed only
bunx @lythos/​[email protected] complete TASK-xxx    # any status → completed (trailer-driven)
bunx @lythos/​[email protected] suspend TASK-xxx
bunx @lythos/​[email protected] resume TASK-xxx
bunx @lythos/​[email protected] terminate TASK-xxx
bunx @lythos/​[email protected] archive TASK-xxx

# ADR state machine
bunx @lythos/​[email protected] adr accept ADR-xxx
bunx @lythos/​[email protected] adr reject ADR-xxx
bunx @lythos/​[email protected] adr supersede ADR-xxx --by ADR-yyy

# Epic state machine
bunx @lythos/​[email protected] epic done EPIC-xxx
bunx @lythos/​[email protected] epic suspend EPIC-xxx
bunx @lythos/​[email protected] 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/​[email protected] probe

# Active-only mode — skip status consistency, focus on actionable items only
bunx @lythos/​[email protected] probe --active-only

# Include completed/​terminated tasks in empty-shell detection
bunx @lythos/​[email protected] 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

Glossary

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-research/      ← Research notes and investigations
    ├── 03-lessons/       ← Retrospectives
    ├── 04-ssot/          ← Single source of truth (conventions, decisions)
    └── 05-archived/      ← Outdated but historically valuable

(02-faq retired 2026-09-09: guided tour → 01-patterns/​level-gated-onboarding-ladder, player prerequisites → 04-ssot/​player-prerequisites.) Numeric prefixes ensure GTD workflow ordering in ls output.

ID Format

PREFIX-yyyyMMddHHmmssSSS (17 digits). Collision-free, self-sorting, no registry.

Always spell IDs in full — truncation is not addressable. …402-style abbreviations cannot be resolved by a zero-context reader: the date prefix IS the lookup key, and a 3-digit suffix matches nothing. Applies everywhere an ID is written for another agent to follow: daily handoffs, ADRs, wiki, task cards, commit trailers. The reader must jump to the carrier with zero re-derivation (same contract as scribe's "no raw ref → no item").

Preview next IDs before creating: bunx @lythos/​[email protected] next-id (prints the next Task/​Epic/​ADR timestamp IDs in the PREFIX-yyyyMMddHHmmssSSS format).

Command Output Examples

Agents should expect stable output patterns when invoking CLI commands. Sample outputs (create / stats / probe, consistent and mismatch cases): references/​command-output.md.

Task State Machine (FSM)

Directory location is the source of truth. Status History mirrors the directory.

Transition Table

ADR State Machine

Epic State Machine

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/​[email protected] 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/​[email protected] start TASK-xxx
2. Implement, commit with task ID in message
3. ZK-review your own work before requesting review: spawn a fresh zero-knowledge reviewer (pass-by-reference: task card path + git log --grep TASK-xxx commits). Skeptical, severity-rated findings on two questions: are the checked acceptance boxes honestly supported, and does the evidence support the conclusions. Verify its P1 claims yourself (reviewers are sensors, not oracles), then fix or register follow-ups. Self-review has a structural blind spot (knowledge curse, self-graded homework) — 2026-07-17: a ZK reviewer caught an A/​B report headline that misread its own primary evidence.
4. bunx @lythos/​[email protected] review TASK-xxx
5. Stop here. Never use done — that requires user acceptance.

Reporting Discipline (review & status reports)

How you report a task's completion is part of the review surface — the owner accepts or rejects based on what you wrote, so the report carries the same burden as the work. Two rules, both from AGENTS.md §3:

Structure: 5W1H, not private shorthand. Answer What (what was produced), Why (which problem it closes), Where (carrier — file:line, TASK-/​ADR-/​EPIC-id, commit hash), When (date the claim was verified), Who (who verified it, by what method), How (the check that proves it). Take the 3-5 that apply — never fewer than the owner needs to verify without asking a follow-up. A verdict word (score, gate, severity, "P1", "pass") must define its criteria in the same report: an undefined scale cannot be disagreed with, so it is not a review.

Posture: you report, the owner decides. Never assign the owner a task, never pre-authorize their decision ("just nod and it's done"), never write agreement as the default path. A pending decision is options + consequence ("A or B — here is what each costs"), fully formed, with the choice left open. This is the mirror of ZK agents are sensors, not bosses: that rule stops a reviewer from commanding an executor; this one stops an executor from commanding the owner. Pre-framing consent is a default-value play against this project's anti-default discipline.

Scribe's What + Why + Done + Raw ref handoff contract is the same rule at handoff scope — one convention, two carriers.

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/​[email protected] index after any status change. Manual edits will be overwritten.

Supporting References

Read these only when the specific topic arises: