lythoskill-project-cortex

Files (16)

• SKILL.md
• command-output.md · references/
• example-workflow.md · references/
• milestone-protocol.md · references/
• session-handoff.md · references/
• state-machines.md · references/
• template-guide.md · references/
• wiki-workflow.md · references/
• writing-guide.md · references/
• zk-review.md · references/
• adr.sh · scripts/
• epic.sh · scripts/
• index.sh · scripts/
• init.sh · scripts/
• probe.sh · scripts/
• task.sh · scripts/

SKILL.md (first lines)

# 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

From lythos-labs/lythoskill, MIT.

More from lythos-labs/lythoskill