lythoskill-project-cortex · {{PACKAGE_VERSION}} · 2026-09-09 · sha256 6b93dcbb9b1c15ee
lythoskill-project-cortex {{PACKAGE_VERSION}}A
Immutable. This exact content is served forever at /api/v1/blob/6b93dcbb9b1c15ee.
---
name: lythoskill-project-cortex
version: {{PACKAGE_VERSION}}
description: |
Register tasks BEFORE fixing bugs. Close epics when work is done.
Always move state through the CLI — never mv files by hand: CLI moves
write Status History, manual moves create probe mismatches. Never leave
state drift for the next agent to discover via git log. GTD (Getting
Things Done)-style governance across ADR (architecture decision record)
/ Epic / Task / Wiki. Zero-knowledge (ZK) review = a fresh-agent pass
over a task card (WHAT/WHY/HOW) before assignment, so an executor with
no conversation context can still run it. `cortex probe` = drift
detector: stale backlog, drifted epics, history mismatches vs git
reality. **Task-git discipline**: one task = 2-5 commits (core, tests,
docs, trailer); every commit carries its full TASK-id (see ID Format —
truncated IDs are not addressable).
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. User says "登记" (register) / "记录一下"
(record it) / "创建任务" (create task) / "完成" (done) / "推进" (advance)
/ "状态" (status) / "零知识审查" (zero-knowledge review) / "任务能看懂吗"
(can an executor understand this task). Proactive: just finished a fix
batch and pushed; about to commit with a trailer; writing daily notes;
epic marked active but all its tasks are done; about to mv a task file
by hand (forbidden — always use the CLI). Full trigger list: body §Also
Trigger When.
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.
| 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.
## 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
```bash
# 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|research|lesson|ssot
# 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.
>
> **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/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
```bash
# 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
```
| 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 that remain in the content (`⚠️ PLACEHOLDER_`, `需求1` — the Chinese template's "requirement 1" filler, `<!-- 填写` — "fill in"). **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
```mermaid
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
├── 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 and 02-research share prefix 02 — historical numbering drift; config matches disk, renumbering would break references.)
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` |
**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/project-cortex@{{PACKAGE_VERSION}} 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](./references/command-output.md).
## Task State Machine (FSM)
Directory location is the source of truth. Status History mirrors the directory.
### Transition Table
| From | To | Who | Trigger | CLI Command |
|------|----|-----|---------|-------------|
| backlog | in-progress | Subagent | Begins implementation | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} start TASK-xxx` |
| in-progress | review | Subagent/Trailer | Core deliverables done, submit for review | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} review TASK-xxx` or `Review: TASK-xxx` trailer |
| review | completed | User/System | Exit criteria met, acceptance passed | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} 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@{{PACKAGE_VERSION}} complete TASK-xxx` |
| in-progress | suspended | Any | Blocked by external dependency | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} suspend TASK-xxx` |
| suspended | in-progress | Any | Blocker resolved | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} resume TASK-xxx` |
| any | terminated | User/System | Task cancelled or obsolete | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} terminate TASK-xxx` |
| completed | archived | User/System | Long-term storage | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} archive TASK-xxx` |
| review | in-progress | User/System | Deliverables rejected, re-work required | `bunx @lythos/project-cortex@{{PACKAGE_VERSION}} reject TASK-xxx` |
### 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:
```bash
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.
```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\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.
```bash
# 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
| 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@{{PACKAGE_VERSION}} 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/project-cortex@{{PACKAGE_VERSION}} review TASK-xxx`
5. **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**:
| 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) |
| Design tasks that a ZK agent can execute without asking (WHAT/WHY/HOW method) | [references/zk-review.md](./references/zk-review.md) |
| See complete state machine rules, valid transitions, and error guidance | [references/state-machines.md](./references/state-machines.md) |