meto-cli 0.7.6 → 0.9.0

package/templates/.claude/agents/epic-agent.md

@@ -0,0 +1,63 @@
+---
+name: meto-epic-{{EPIC_ID}}
+description: Use to implement tasks belonging to {{EPIC_NAME}} ({{EPIC_ID}}). Owns {{EPIC_DOMAIN}}. Picks tasks tagged {{EPIC_ID}} from tasks-todo.md and runs independent tasks in parallel. Reports checkpoint status to SWARM_AWARENESS.md every 3 completed tasks. Do NOT use for tasks belonging to other epics.
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Epic Agent — {{EPIC_NAME}} ({{EPIC_ID}})
+
+## Domain Ownership
+- **My files:** `{{EPIC_DOMAIN}}`
+- **Shared files (READ ONLY):** `ai/swarm/SWARM_AWARENESS.md`, `ai/swarm/domain-map.md`
+- **Board files I touch:** `tasks-todo.md`, `tasks-in-progress.md`, `tasks-in-testing.md`
+
+## Session Start
+1. Read `CLAUDE.md`
+2. Read `ai/swarm/domain-map.md` — confirm my domain, check for conflicts
+3. Read `ai/swarm/SWARM_AWARENESS.md` — check what other epic agents are doing
+4. Read `.claude/agent-memory/meto-epic-{{EPIC_ID}}/MEMORY.md`
+5. Proceed with task pickup
+
+## Session End
+1. Write checkpoint to `ai/swarm/SWARM_AWARENESS.md`
+2. Update `.claude/agent-memory/meto-epic-{{EPIC_ID}}/MEMORY.md`
+
+## Task Pickup Protocol
+
+**Parallelism first:** Read all tasks tagged `{{EPIC_ID}}` in `tasks-todo.md`. Check dependency chains. Launch independent tasks in parallel (background agents or worktrees). Only run tasks sequentially when one depends on another's output.
+
+For each task:
+1. Check `ai/swarm/domain-map.md` — confirm no file conflicts with active epic agents
+2. Copy full task block to `tasks-in-progress.md`, add `Started: [date] | Agent: meto-epic-{{EPIC_ID}}`
+3. Delete from `tasks-todo.md`
+4. Implement against acceptance criteria
+5. Run self-check
+6. Copy full task block to `tasks-in-testing.md`, add `Completed: [date] | Files changed: [list]`
+7. Delete from `tasks-in-progress.md`
+8. Commit: `feat({{EPIC_ID}}): description [epic-{{EPIC_ID}}]`
+9. Increment completed task counter — at 3, write checkpoint
+
+## Self-Check Before Moving to Testing
+- [ ] All acceptance criteria implemented
+- [ ] TypeScript compiles — no errors
+- [ ] No `any` types
+- [ ] No `console.log`
+- [ ] No commented-out code
+- [ ] Error states handled
+- [ ] No hardcoded secrets
+- [ ] Only touched files within `{{EPIC_DOMAIN}}`
+
+## Checkpoint Protocol (every 3 completed tasks)
+Update `ai/swarm/SWARM_AWARENESS.md` under my epic section:
+```
+{{EPIC_ID}} | [date] | Completed: [n] tasks | Status: [on-track/blocked] | Blocker: [none or description]
+```
+Then pause and surface status to user before continuing.
+
+## NEVER DO
+- Touch files outside `{{EPIC_DOMAIN}}` without checking domain-map first
+- Pick tasks tagged for a different epic
+- Write to `ai/swarm/domain-map.md`
+- Run dependent tasks in parallel — check dependency chains first
+- Skip the domain conflict check
+- Continue past 3 tasks without writing a checkpoint

package/templates/CLAUDE.md

@@ -9,17 +9,7 @@
 
 ---
 
-## Agents
-
-Human orchestrator reads the board and calls the right agent.
-
-| Agent | Owns |
-|---|---|
-| `@meto-pm` | `/ai/backlog/`, `tasks-backlog.md`, `tasks-todo.md` |
-| `@meto-developer` | `/src/`, `tasks-in-progress.md`, `tasks-in-testing.md` |
-| `@meto-tester` | `tasks-in-testing.md` → done or back to todo |
-
-Each agent has a memory file in `.claude/agent-memory/` — read at session start, update at session end.
+{{WORKFLOW_AGENTS_SECTION}}
 
 ---
 

package/templates/ai/swarm/SWARM_AWARENESS.md

@@ -0,0 +1,62 @@
+# SWARM_AWARENESS — {{PROJECT_NAME}}
+
+> **READ ONLY for epic agents. Only `@meto-pm` and checkpoint protocol may write here.**
+> Parsed by `npx meto-cli status` — keep section headers and format exact.
+
+---
+
+## [swarm:meta]
+- **Project:** {{PROJECT_NAME}}
+- **Mode:** swarm
+- **Started:** *(date)*
+- **Total epics:** *(n)*
+- **Total tasks:** *(n)*
+- **Acceptance criteria:** 0 / 0 passed
+
+---
+
+## [swarm:epics]
+
+| Epic ID | Name | Agent | Status | Tasks Done | Blocker |
+|---|---|---|---|---|---|
+| *(populated at swarm init by @meto-pm)* | | | not-started | 0 | none |
+
+Status values: `not-started` · `on-track` · `blocked` · `complete`
+
+---
+
+## [swarm:domains]
+
+See full ownership rules in `ai/swarm/domain-map.md`.
+
+| Epic ID | Owns |
+|---|---|
+| *(populated at swarm init by @meto-pm)* | |
+
+---
+
+## [swarm:checkpoints]
+
+Append only. Never delete entries. One line per checkpoint.
+
+```
+[ISO date] | [EPIC_ID] | done:[n] | status:[on-track/blocked] | blocker:[none or description]
+```
+
+---
+
+## [swarm:conflicts]
+
+```
+[ISO date] | CONFLICT | file:[path] | agents:[e1] vs [e2] | resolution:[pending/resolved]
+```
+
+---
+
+## [swarm:log]
+
+Free text. Epic agents append observations, decisions, or notes here.
+
+```
+[ISO date] | [EPIC_ID] | [note]
+```

package/templates/ai/swarm/domain-map.md

@@ -0,0 +1,46 @@
+# Domain Map — {{PROJECT_NAME}}
+
+> Generated by `@meto-pm` at swarm init. **READ ONLY after generation.**
+> Epic agents use this to check for file conflicts before picking up a task.
+
+---
+
+## Ownership Rules
+
+1. Each epic agent owns its declared domain exclusively
+2. Before touching any file, check it is within your domain
+3. If a task requires a file outside your domain — STOP, log conflict in `SWARM_AWARENESS.md`, wait for user
+4. Shared config files (e.g. `package.json`, `tsconfig.json`) require user coordination before editing
+
+---
+
+## Epic Domains
+
+*(Populated by @meto-pm during swarm init based on confirmed epics)*
+
+| Epic ID | Epic Name | Owns | Shared With |
+|---|---|---|---|
+| E1 | *(name)* | *(paths)* | none |
+| E2 | *(name)* | *(paths)* | none |
+
+---
+
+## Shared Files (requires coordination)
+
+Files that multiple epics may need to touch. Epic agents must flag before editing.
+
+| File | Reason shared | Protocol |
+|---|---|---|
+| `package.json` | All epics may add deps | Flag in SWARM_AWARENESS, user approves |
+| `tsconfig.json` | Compiler config affects all | Flag in SWARM_AWARENESS, user approves |
+| `CLAUDE.md` | Project-wide context | Only @meto-pm writes |
+
+---
+
+## Conflict Resolution Protocol
+
+1. Epic agent detects file outside its domain is needed
+2. Agent logs conflict in `SWARM_AWARENESS.md`
+3. Agent pauses — does NOT proceed
+4. User reviews and assigns ownership or approves shared edit
+5. Agent continues only after user confirmation

package/templates/ai/workflows/swarm-workflow.md

@@ -0,0 +1,97 @@
+# Swarm Workflow — {{PROJECT_NAME}}
+
+## What is Swarm Mode
+
+Each epic runs its own agent in parallel. Epic agents are scoped to their domain and cannot touch files owned by other epics. They report status every 3 completed tasks. The user stays in control at every checkpoint.
+
+---
+
+## Swarm vs Sprint
+
+| | Sprint | Swarm |
+|---|---|---|
+| Tasks | One at a time, sequential | Parallel per epic |
+| Agents | meto-developer (generic) | meto-epic-[id] (scoped) |
+| Speed | Careful, deliberate | Faster on independent epics |
+| Risk | Low | Medium — requires domain discipline |
+| Best for | Solo, small scope, tight control | Multiple epics, independent domains |
+
+---
+
+## Starting a Swarm
+
+1. `@meto-pm` confirms all epics are defined in `epics.md`
+2. `@meto-pm` generates `ai/swarm/domain-map.md` — one domain per epic
+3. `@meto-pm` generates one `epic-agent.md` per epic in `.claude/agents/`
+4. `@meto-pm` initialises `ai/swarm/SWARM_AWARENESS.md` with active epic table
+5. User launches epic agents — one per epic, in separate Claude Code sessions
+
+---
+
+## Checkpoint Rhythm
+
+```
+Epic agent reads todo -> identifies independent tasks -> launches in parallel
+Each task: implement -> self-check -> move to testing
+After 3 tasks complete (parallel or sequential):
+-> Write checkpoint to SWARM_AWARENESS.md
+-> Surface status to user
+-> User runs: npx meto-cli status
+-> User reviews: continue / intervene / reassign
+-> Repeat
+```
+
+**Parallelism within an epic:** Independent tasks (no dependency chain) run in parallel using background agents or worktrees. Only tasks that depend on another's output run sequentially.
+
+A checkpoint is NOT a blocker — if status is `on-track` the agent continues automatically. Only `blocked` status requires user intervention.
+
+---
+
+## npx meto-cli status
+
+Reads `ai/swarm/SWARM_AWARENESS.md` and prints a formatted terminal report:
+
+```
+Last Swarm Checkpoint
+
+Project: {{PROJECT_NAME}}
+Duration: [start] – [latest checkpoint]
+
+Epics Active:
+- E1 · [name]   [n] tasks done
+- E2 · [name]   [n] tasks in progress
+- E3 · [name]   blocked — [reason]
+- E4 · [name]   not started
+
+Acceptance Criteria: [n] of [n] passed
+
+Blockers:
+- [EPIC_ID]: [description]
+
+Next: [instruction to user]
+```
+
+Run at any time — not only at checkpoints. Gives a live read of the swarm state.
+
+---
+
+## Conflict Resolution Protocol
+
+1. Epic agent detects it needs a file outside its domain
+2. Agent logs conflict in `SWARM_AWARENESS.md` under Shared File Conflicts
+3. Agent sets its status to `blocked`
+4. Agent pauses — does NOT proceed
+5. User runs `npx meto-cli status` — sees the blocker
+6. User resolves: assigns ownership or approves shared edit
+7. Agent continues only after user confirmation
+
+---
+
+## Ending a Swarm
+
+A swarm ends when all epics reach 0 tasks in `tasks-todo.md` tagged to them and `@meto-tester` has signed off all items in `tasks-done.md`.
+
+`@meto-pm` writes final swarm summary to `SWARM_AWARENESS.md`:
+```
+SWARM COMPLETE | [date] | [n] epics | [n] tasks | [n/n] AC passed
+```