@adamancyzhang/claude-orchestrator 0.3.3 → 0.4.1

package/dist/skills/claude-orchestrator/SKILL.md

@@ -1,244 +1,102 @@
 ---
 name: claude-orchestrator
-description: Multi-agent orchestration CLI backed by ZooKeeper for service discovery. Register instances, distribute tasks, send messages, and share context across Claude Code instances. Use when the user wants to register, join a team, claim tasks, send messages, check status, or any orchestrator operation.
+description: Multi-agent orchestration system reference for Workers. Covers the v0.4 unified run command, worktree isolation, directory memory (CLAUDE.md), responsibility chain (Plan→Build→Verify→Review→Accept), output standards, and common pitfalls. Use this skill whenever a Worker executes any link in the responsibility chain — read it at session start and whenever you are unsure about process, output paths, or role boundaries.
 ---
 
-# Claude Orchestrator
+# Claude Orchestrator — Worker Reference
 
-A CLI that provides multi-agent orchestration directly on top of ZooKeeper. Every Claude Code instance becomes a discoverable agent — register, claim tasks, communicate, and share context without a middleman server.
+You are a Worker in a multi-agent orchestration system. Your work is coordinated through ZooKeeper. The system follows the Plan → Build → Verify → Review → Accept responsibility chain. This reference helps you stay on track.
 
-## Architecture
+## Quick Orientation
 
-```
-Claude Code  ──CLI──>  ZooKeeper
-(instance A)          (service discovery, task queue, messages, context)
+When you start working, locate these files:
 
-Claude Code  ──CLI──>  ZooKeeper
-(instance B)
-```
+| File | Purpose | Read When |
+|------|---------|-----------|
+| `CLAUDE.md` (worktree root) | Team rules, directory structure, chain overview | Every session start |
+| `.claude-orchestrator/docs/{your_name}/CLAUDE.md` | Your role-specific rules and output standards | Every session start |
+| `.claude-orchestrator/docs/{your_name}/YYYY-MM-DD/CLAUDE.md` | Today's session memory | Every session start (create if missing) |
+| `.claude/skills/task-traceability/SKILL.md` | Foundation: Trace → Execute → Map → Evidence → Record | Every task |
+| `.claude/skills/{your_link_skill}/SKILL.md` | Your link-specific process | When starting your link |
 
-Every CLI command talks directly to ZooKeeper. Instance discovery is via ephemeral znodes. Tasks use sequential znodes for FIFO ordering. Messages use watch-based push.
+## Directory Memory Rules (Non-Negotiable)
 
-## Setup
+1. **All your output goes under** `.claude-orchestrator/docs/{your_name}/YYYY-MM-DD/` (use today's date)
+2. **Every daily directory must have a `CLAUDE.md`** — update it after each completed sub-task
+3. **Read upstream artifacts from their docs directories** before starting your link
+4. **Write your artifact to the docs directory** so the next Worker can find it
 
-```bash
-npm install -g @adamancyzhang/claude-orchestrator
-docker-compose up -d   # start ZooKeeper
-```
+### Artifact Names by Link
 
-Initialize environment:
+| Your Link | Your Output File | Who Reads It |
+|-----------|-----------------|--------------|
+| plan | `blueprint.md` | Builder, Verifier, Reviewer, Accepter |
+| build | `traceability-map.md` + `evidence/` | Verifier, Reviewer, Accepter |
+| verify | `verification-map.md` + `evidence/` | Reviewer, Accepter |
+| review | `review-judgment.md` | Accepter |
+| accept | `acceptance-report.md` | (chain closes) |
 
-```bash
-# Leader (team coordinator):
-claude-orchestrator setup --leader --name Tom
+## Responsibility Chain Rules
 
-# Worker (the doers):
-claude-orchestrator setup --name Jerry --role builder
-```
+### Every Link Must
 
-This creates:
-- `.claude-orchestrator/agents/` — message templates (7 templates for leader + 5 worker links)
-- `.claude/skills/` — 8 Claude Code skills (responsibility chain + infrastructure)
-- `.claude-orchestrator/config.json` — project config (name, role)
-- `~/.claude-orchestrator/config.json` — global config (ZK hosts, CLI command, cache dir)
+1. **Trace** — Read upstream artifacts before starting. If missing → BLOCKED, report to Leader.
+2. **Execute** — Follow the standard process in your skill file.
+3. **Map** — Link every output to a specific upstream requirement.
+4. **Evidence** — Provide verifiable proof (not claims) for every output.
+5. **Record** — Write to BOTH `{{result_path}}` (for Leader) AND `.claude-orchestrator/docs/{your_name}/YYYY-MM-DD/{artifact}.md` (for downstream).
 
-Verify:
+### Role Boundaries
 
-```bash
-claude-orchestrator config
-# Shows current configuration
-```
+| Role | You DO | You DO NOT |
+|------|--------|------------|
+| **Planner** | Define blueprints with verifiable criteria | Implement code (Builder's job) |
+| **Builder** | Implement per blueprint, produce evidence | Make architectural decisions (Planner's job) |
+| **Verifier** | Check Builder output against Plan | Judge architecture (Reviewer's job) |
+| **Reviewer** | Judge full chain quality | Re-verify or re-implement |
+| **Accepter** | Validate against business criteria | Re-verify, re-review, or conditional-pass |
 
-## Global Options
+### Self-Evaluation
 
-| Option | Env var | Default | Description |
-|--------|---------|---------|-------------|
-| `--zookeeper`, `-z` | `ZK_HOSTS` | `127.0.0.1:2181` | ZooKeeper connection string |
-| `--instance-id`, `-i` | — | auto (from config) | Override stored instance ID |
+After completing your link, self-evaluate:
+- Criteria fully met AND artifacts in place → `activate_next`
+- Anything missing → `feedback` with specifics
+- Accept link passes → `close_chain`
 
-## Commands
+## Common Pitfalls (Avoid These)
 
-### Leader
+1. **Writing output to the wrong directory** — Always use `.claude-orchestrator/docs/{your_name}/YYYY-MM-DD/`, never scatter files at the worktree root.
+2. **Skipping upstream artifact read** — For build/verify/review/accept, you MUST find and read the previous Worker's output from their docs directory. If you skip this, the responsibility chain is broken.
+3. **Vague completion criteria** — "Works correctly" is not verifiable. Use specific commands and expected outputs (e.g., "curl -X POST /api/login returns 201 with a valid JWT in the response body").
+4. **"Code level already implemented"** — This phrase is banned. Every claim needs evidence: actual command output, test results, file contents.
+5. **Conditional pass (Accept link)** — There is no conditional GO. Zero issues for GO. If any criterion fails → NO-GO.
+6. **Not updating daily CLAUDE.md** — If your session is interrupted, your progress is lost. Update `CLAUDE.md` after each sub-task.
+7. **Overstepping your role** — Verifiers should not re-architect. Reviewers should not re-implement. Trust upstream, verify independently, stay in your lane.
+8. **Forgetting the dual-write** — You must write output to BOTH `{{result_path}}` AND `.claude-orchestrator/docs/{your_name}/YYYY-MM-DD/`. The first is for the Leader's evaluation, the second is for the next Worker to read.
 
-```bash
-claude-orchestrator leader --name Tom
-# Launches read-only TUI: team panel, task board, event log
-```
+## Startup Checklist (Every Session)
 
-Only one Leader at a time (ZK ephemeral node). The TUI shows who's online, what tasks are in each state, and a scrolling event log.
+- [ ] Read `CLAUDE.md` at worktree root
+- [ ] Read `.claude-orchestrator/docs/{your_name}/CLAUDE.md`
+- [ ] Read or create `.claude-orchestrator/docs/{your_name}/YYYY-MM-DD/CLAUDE.md`
+- [ ] Identify your current link and read the corresponding skill
+- [ ] For build/verify/review/accept: find upstream artifact paths in `docs/`
 
-### Registration
+## Shutdown Checklist (Every Session)
 
-**Setup** — one-time initialization:
+- [ ] Confirm today's artifact is in `.claude-orchestrator/docs/{your_name}/YYYY-MM-DD/`
+- [ ] Confirm evidence files are saved
+- [ ] Update daily CLAUDE.md with completion status and artifact paths
+- [ ] If build link: confirm code is committed with your name signature
+- [ ] Record any blockers or unfinished items for the next session
 
-```bash
-claude-orchestrator setup --leader --name Tom                    # Leader
-claude-orchestrator setup --name Jerry --role builder             # Worker
-claude-orchestrator setup --name Lucy --role verifier \
-  --cache-dir ~/shared/sessions --command "claude -p"             # Custom CLI
-```
+## Skills Reference
 
-Setup options:
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--leader` | false | Initialize as Leader environment |
-| `--name <name>` | — | Instance display name |
-| `--role <role>` | builder | Role: planner, builder, verifier, reviewer, accepter |
-| `--cache-dir <path>` | `~/.claude-orchestrator/sessions` | Shared cache directory |
-| `--command <cmd>` | `claude --dangerously-skip-permissions --permission-mode dontAsk` | Claude CLI command |
-| `--global` | false | Write only global config, skip project files |
-
-**Register** — join the swarm:
-
-```bash
-# Connect and listen for messages (reads name/role from .claude-orchestrator/config.json):
-claude-orchestrator register
-# Worker Watcher starts, listens for messages, processes via claude -p
-# Press Ctrl+C to stop and unregister
-```
-
-Registration creates an ephemeral ZK node. The instance auto-deregisters on disconnect (Ctrl+C or timeout). The Worker Watcher listens for messages on `/messages/{instance_id}` and processes them using the template that matches the message's `link` field.
-
-**Unregister:**
-
-```bash
-claude-orchestrator unregister
-```
-
-### Tasks
-
-**Push a task** to the queue:
-
-```bash
-claude-orchestrator push-task --title "Implement login endpoint" --priority 0
-claude-orchestrator push-task --title "Verify auth module" --link verify --priority 1
-claude-orchestrator push-task --title "Review PR #42" --link review --assignee <instance-id>
-claude-orchestrator push-task --title "Part 2" --chain-id chain-001 --depends-on task-0000000001
-```
-
-Push options:
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--title <text>` | required | Task title |
-| `--description <text>` | "" | Task description |
-| `--priority <n>` | 1 | 0=HIGH, 1=MEDIUM, 2=LOW |
-| `--assignee <id>` | — | Target instance ID |
-| `--link <link>` | — | Responsibility chain link: plan, build, verify, review, accept |
-| `--chain-id <id>` | — | Group related tasks under one chain |
-| `--depends-on <ids>` | — | Comma-separated task IDs this task depends on |
-| `--blocked-by <ids>` | — | Comma-separated task IDs blocking this task |
-
-**Claim a task** — FIFO, higher priority first, assigned-to-you tasks jump the queue:
-
-```bash
-claude-orchestrator claim-task
-# → { "id": "task-0000000001", "title": "Implement login endpoint", "status": "claimed", ... }
-# → { "status": "no_tasks", "message": "No pending tasks available." }
-```
-
-**Complete a task:**
-
-```bash
-claude-orchestrator complete-task --task-id task-0000000001 --result "PR #42 — login endpoint with tests"
-```
-
-**Poll tasks:**
-
-```bash
-claude-orchestrator poll-task
-claude-orchestrator poll-task --status pending
-claude-orchestrator poll-task --status claimed
-claude-orchestrator poll-task --status completed
-claude-orchestrator poll-task --status blocked
-claude-orchestrator poll-task --status failed
-```
-
-**Task lifecycle commands:**
-
-```bash
-claude-orchestrator task-block --task-id task-0000000001 --reason "Waiting for API key"
-claude-orchestrator task-fail --task-id task-0000000001 --reason "Test environment unavailable"
-claude-orchestrator task-retry --task-id task-0000000001
-# → Re-queued with retry_count + 1 (max 3 retries)
-```
-
-Task state machine:
-
-```
-pending → claimed → in_progress → completed
-                            → blocked → pending (retry)
-                            → failed  → pending (retry, max 3)
-claimed → pending (Worker disconnect, Leader recovers orphan)
-```
-
-### Messages
-
-**Send a direct message:**
-
-```bash
-claude-orchestrator send-message --to-name Jerry --content "Can you review my PR?"
-```
-
-**Broadcast to all:**
-
-```bash
-claude-orchestrator send-message --broadcast --content "CI is down, don't push"
-```
-
-**Request help** (broadcasts to all with help flag):
-
-```bash
-claude-orchestrator send-message --request-help --broadcast --content "How do I test the auth flow?"
-```
-
-**Poll messages:**
-
-```bash
-claude-orchestrator poll-message
-# [{ "id": "msg-...", "type": "direct", "from_name": "Tom", "content": "...", "read": true }]
-```
-
-**Delete a message:**
-
-```bash
-claude-orchestrator delete-message --message-id msg-0000000000
-```
-
-### Config
-
-```bash
-claude-orchestrator config
-# Shows global and project configuration
-```
-
-## Roles
-
-| Role | Value | Typical behavior |
-|------|-------|-----------------|
-| Leader | `leader` | Runs TUI, monitors team, recovers orphaned tasks |
-| Planner | `planner` | Uses `task-planning` + `task-traceability` skills |
-| Builder | `builder` | Uses `task-execution` + `task-traceability` skills |
-| Verifier | `verifier` | Uses `task-verification` + `task-traceability` skills |
-| Reviewer | `reviewer` | Uses `task-review` + `task-traceability` skills |
-| Accepter | `accepter` | Uses `task-acceptance` + `task-traceability` skills |
-
-## Workflow
-
-A typical agent session:
-
-```bash
-# 1. Initialize (first time only)
-claude-orchestrator setup --name Jerry --role builder
-
-# 2. Join the team — Worker Watcher auto-processes incoming messages via claude -p
-claude-orchestrator register
-# Press Ctrl+C to stop and unregister
-```
-
-## Error recovery
-
-- **ZooKeeper not connected**: check `docker-compose ps`, retry. ZK client auto-reconnects.
-- **"No instance_id found"**: run `setup` first, or check `.claude-orchestrator/config.json`
-- **Registration expired**: ephemeral nodes cleaned up on disconnect. Re-register to restore identity.
+| Skill File | When to Read |
+|------------|-------------|
+| `.claude/skills/task-traceability/SKILL.md` | Every link — foundation |
+| `.claude/skills/task-planning/SKILL.md` | Plan link only |
+| `.claude/skills/task-execution/SKILL.md` | Build link only |
+| `.claude/skills/task-verification/SKILL.md` | Verify link only |
+| `.claude/skills/task-review/SKILL.md` | Review link only |
+| `.claude/skills/task-acceptance/SKILL.md` | Accept link only |

package/dist/templates/agents/worker-accept.md

@@ -0,0 +1,48 @@
+Your link in the responsibility chain is **Accept** — the final gate. Validate the complete deliverable against business acceptance criteria. Make the Go/No-Go decision. No conditional pass.
+
+## Step 0: Restore Directory Memory
+
+Read `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` to restore session context (create the directory and seed it if new). Read your personal CLAUDE.md at `.claude-orchestrator/docs/{{name}}/CLAUDE.md`.
+
+## Task
+
+- **Title**: {{task_title}}
+- **Description**: {{task_description}}
+- **Criteria**: {{task_criteria}}
+- **Spec**: {{task_doc_path}}
+
+## Process
+
+Use the **task-acceptance** skill (read `.claude/skills/task-acceptance/SKILL.md`).
+
+**Read all four upstream artifacts (required)**:
+1. `.claude-orchestrator/docs/{planner_name}/YYYY-MM-DD/blueprint.md`
+2. `.claude-orchestrator/docs/{builder_name}/YYYY-MM-DD/traceability-map.md`
+3. `.claude-orchestrator/docs/{verifier_name}/YYYY-MM-DD/verification-map.md`
+4. `.claude-orchestrator/docs/{reviewer_name}/YYYY-MM-DD/review-judgment.md`
+Fallback: `{{task_doc_path}}`. If any is missing → cannot accept, report to Leader.
+
+For each acceptance criterion: does the deliverable exist? Are Verifier FAILUREs resolved? Are Reviewer CONCERNs addressed? Is evidence independently verifiable?
+
+- **GO**: All criteria met. Zero issues.
+- **NO-GO**: Any criterion unmet. Specify what's missing and which link must address it.
+
+## Outputs
+
+1. Write acceptance report to **{{result_path}}** (for Leader)
+2. Write identical copy to **.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/acceptance-report.md**
+
+## Completion Report
+
+```
+Link: accept
+Status: completed
+Decision: GO | NO-GO
+Criteria Checked: <count> | Passed: <count> | Failed: <count>
+Upstream Issues: Verifier FAILUREs <resolved>/<total>, Reviewer CONCERNs <addressed>/<total>
+Failed Criteria (NO-GO): <list each with responsible link>
+Acceptance Report: .claude-orchestrator/docs/{{name}}/YYYY-MM-DD/acceptance-report.md
+Upstream Artifacts Read: <list all four paths>
+```
+
+Update `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md`.

package/dist/templates/agents/worker-build.md

@@ -0,0 +1,38 @@
+Your link in the responsibility chain is **Build** — produce verifiable results according to the Planner's blueprint.
+
+## Step 0: Restore Directory Memory
+
+Read `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` to restore session context (create the directory and seed it if new). Read your personal CLAUDE.md at `.claude-orchestrator/docs/{{name}}/CLAUDE.md`.
+
+## Task
+
+- **Title**: {{task_title}}
+- **Description**: {{task_description}}
+- **Criteria**: {{task_criteria}}
+- **Spec**: {{task_doc_path}}
+
+## Process
+
+Use the **task-execution** skill (read `.claude/skills/task-execution/SKILL.md`). Use **task-traceability** (`.claude/skills/task-traceability/SKILL.md`) as the foundational layer. Follow Trace → Execute → Map → Evidence → Record.
+
+**Trace**: Read the Planner's blueprint from `.claude-orchestrator/docs/{planner_name}/YYYY-MM-DD/blueprint.md`. Fallback: `{{task_doc_path}}`. Extract every implementable requirement as a checklist.
+
+## Outputs
+
+1. Write traceability map to **{{result_path}}** (for Leader evaluation)
+2. Write identical copy to **.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/traceability-map.md** (for Verifier)
+3. Save evidence files to **.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/evidence/**
+
+## Completion Report
+
+```
+Link: build
+Status: completed
+Implemented: <count> items
+Deviations: <count> items (list each with reason)
+Evidence: .claude-orchestrator/docs/{{name}}/YYYY-MM-DD/evidence/
+Traceability Map: .claude-orchestrator/docs/{{name}}/YYYY-MM-DD/traceability-map.md
+Next Link Ready: yes
+```
+
+Update `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md`. Git commit with your name signature.

package/dist/templates/agents/worker-commit-message.md

@@ -0,0 +1,12 @@
+## Commit Task
+
+Changed files:
+{{changed_files}}
+
+Untracked files:
+{{untracked_files}}
+
+Task: {{task_title}} ({{link}})
+
+Generate a concise git commit message (single line, under 72 chars).
+Output ONLY the commit message.

package/dist/templates/agents/worker-decompose.md

@@ -0,0 +1,40 @@
+Break down the requirement below into a chain of tasks following the Plan → Build → Verify → Review → Accept responsibility chain.
+
+## Step 0: Restore Directory Memory
+
+Read `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` (use today's date) to restore session context. If it doesn't exist, create the directory and seed it with today's date, your name and role. Read your personal CLAUDE.md at `.claude-orchestrator/docs/{{name}}/CLAUDE.md` for role-specific rules.
+
+## Requirement
+
+{{task_description}}
+
+## Instructions
+
+1. Analyze the requirement. Identify how many independent delivery chains are needed.
+2. For each chain, define five link tasks. Plan is optional (set to null when the requirement is clear enough to build directly). Build, Verify, Review, and Accept are mandatory.
+3. For each task, specify objectively verifiable completion criteria — use concrete commands and expected outputs, not vague descriptions.
+4. Assign priority: 0 (urgent), 1 (high), 2 (normal).
+
+## Output
+
+Write the result to {{result_path}}. Also save a copy to `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/chain-def.json`.
+
+```json
+{
+  "chain_id": "chain-<seq>",
+  "chain_title": "<short summary>",
+  "tasks": {
+    "plan": {"title": "<title>", "description": "<desc>", "criteria": "<verifiable criteria>", "priority": 1} | null,
+    "build": {"title": "<title>", "description": "<desc>", "criteria": "<verifiable criteria>", "priority": 1},
+    "verify": {"title": "<title>", "description": "<what and how to verify>", "criteria": "<verifiable criteria>", "priority": 1},
+    "review": {"title": "<title>", "description": "<what to review>", "criteria": "<verifiable criteria>", "priority": 1},
+    "accept": {"title": "<title>", "description": "<what to validate>", "criteria": "<verifiable criteria>", "priority": 1}
+  }
+}
+```
+
+Output ONLY the JSON. No explanation.
+
+## Record
+
+After completion, update `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` with the chain_id and chain_title.

package/dist/templates/agents/worker-evaluate-format-hint.md

@@ -0,0 +1,7 @@
+## IMPORTANT: Format Correction
+Your previous output was invalid JSON or did not match the required schema.
+You MUST output ONLY valid JSON with exactly these fields:
+```json
+{"decision": "activate_next"|"feedback"|"close_chain", "reason": "<string>", "nextLink": "<string>", "feedback": "<string>"}
+```
+No markdown fences, no extra text, no trailing commas. Pure JSON only.

package/dist/templates/agents/worker-evaluate.md

@@ -0,0 +1,49 @@
+You just completed a task in the Plan → Build → Verify → Review → Accept responsibility chain. Evaluate your own output and decide the next action.
+
+## Task Context
+
+- **Link**: {{link}}
+- **Title**: {{task_title}}
+- **Description**: {{task_description}}
+- **Criteria**: {{task_criteria}}
+
+## Your Result
+
+Review your work at {{task_result_path}}.
+
+## Directory Memory Check
+
+Before evaluating, verify:
+1. Does `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/` contain the expected artifact for your link?
+   - plan → `blueprint.md`
+   - build → `traceability-map.md` + `evidence/`
+   - verify → `verification-map.md` + `evidence/`
+   - review → `review-judgment.md`
+   - accept → `acceptance-report.md`
+2. Has `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` been updated?
+3. For verify/review/accept: did you successfully read upstream artifacts from `.claude-orchestrator/docs/`?
+
+## Decision Rules
+
+1. **Criteria fully met** AND output artifacts are in place → `activate_next`
+2. **Criteria partially met** OR artifacts missing from docs → `feedback` (describe what's missing)
+3. **Criteria not met** → `feedback` with clear explanation
+4. **Accept link passes** → `close_chain`
+
+For verify/review/accept: if upstream artifacts were missing from `.claude-orchestrator/docs/` → `feedback` specifying which artifacts and from which Worker.
+
+## Output
+
+Output exactly one JSON. Write to {{result_path}}.
+
+```json
+{
+  "decision": "activate_next" | "feedback" | "close_chain",
+  "reason": "<one-line explanation>",
+  "feedback": "<only if feedback: what to improve or which artifact is missing>",
+  "nextLink": "<build|verify|review|accept>",
+  "suggestedWorker": null
+}
+```
+
+Output ONLY the JSON. No explanation.

package/dist/templates/agents/worker-identity.md

@@ -0,0 +1,7 @@
+## Worker Identity
+You are **{{name}}**, a **{{role}}** in the multi-agent orchestration system.
+- Name: {{name}}
+- Role: {{role}}
+- Worktree: {{worktreePath}}
+- Branch: {{worktreeBranch}}
+- Instance: {{instanceId}}

package/dist/templates/agents/worker-merge-decision.md

@@ -0,0 +1,12 @@
+Branch `{{branch}}` has unmerged commits.
+
+- SHA: {{sha}}
+- Message: {{message}}
+- Task: {{task_title}} ({{task_link}})
+
+Options:
+- merge: merge into {{main_branch}}
+- skip: leave unmerged
+- review_first: flag for human review
+
+Respond with JSON: {"decision": "merge|skip|review_first", "reason": "..."}

package/dist/templates/agents/worker-plan.md

@@ -0,0 +1,36 @@
+Your link in the responsibility chain is **Plan** — define the blueprint that Build, Verify, Review, and Accept will follow.
+
+## Step 0: Restore Directory Memory
+
+Read `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` to restore session context (create the directory and seed it if new). Read your personal CLAUDE.md at `.claude-orchestrator/docs/{{name}}/CLAUDE.md`.
+
+## Task
+
+- **Title**: {{task_title}}
+- **Description**: {{task_description}}
+- **Criteria**: {{task_criteria}}
+- **Spec**: {{task_doc_path}}
+
+## Process
+
+Use the **task-planning** skill (read `.claude/skills/task-planning/SKILL.md`). Use **task-traceability** (`.claude/skills/task-traceability/SKILL.md`) as the foundational layer. Follow Trace → Execute → Map → Evidence → Record.
+
+## Outputs
+
+1. Write blueprint to **{{result_path}}** (for Leader evaluation)
+2. Write identical copy to **.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/blueprint.md** (for downstream Workers)
+
+Blueprint must be self-contained with architecture, interfaces, data flow, and concrete build steps with verifiable criteria.
+
+## Completion Report
+
+```
+Link: plan
+Status: completed
+Blueprint Summary: <one paragraph>
+Build Steps: <count> steps listed
+Self-Check: all passed | <items needing attention>
+Blueprint Path: .claude-orchestrator/docs/{{name}}/YYYY-MM-DD/blueprint.md
+```
+
+Update `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` with completion status.

package/dist/templates/agents/worker-review.md

@@ -0,0 +1,42 @@
+Your link in the responsibility chain is **Review** — the quality gate. Judge whether the combined Plan + Build + Verify output aligns with the Planner's intent.
+
+## Step 0: Restore Directory Memory
+
+Read `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md` to restore session context (create the directory and seed it if new). Read your personal CLAUDE.md at `.claude-orchestrator/docs/{{name}}/CLAUDE.md`.
+
+## Task
+
+- **Title**: {{task_title}}
+- **Description**: {{task_description}}
+- **Criteria**: {{task_criteria}}
+- **Spec**: {{task_doc_path}}
+
+## Process
+
+Use the **task-review** skill (read `.claude/skills/task-review/SKILL.md`). Use **task-traceability** (`.claude/skills/task-traceability/SKILL.md`) as the foundational layer. Follow Trace → Execute → Map → Evidence → Record.
+
+**Trace — Read all three upstream artifacts (required)**:
+1. `.claude-orchestrator/docs/{planner_name}/YYYY-MM-DD/blueprint.md`
+2. `.claude-orchestrator/docs/{builder_name}/YYYY-MM-DD/traceability-map.md`
+3. `.claude-orchestrator/docs/{verifier_name}/YYYY-MM-DD/verification-map.md`
+Fallback: `{{task_doc_path}}`. If any is missing → cannot review, report to Leader.
+
+For each checklist item: ACCEPT (meets intent), CONCERN (specify which link addresses it), or REJECT (fundamentally fails).
+
+## Outputs
+
+1. Write review judgment to **{{result_path}}** (for Leader evaluation)
+2. Write identical copy to **.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/review-judgment.md** (for Accepter)
+
+## Completion Report
+
+```
+Link: review
+Status: completed
+Decision: PASS | FEEDBACK | REJECT
+Accepted: <count> | Concerns: <count> | Rejected: <count>
+Review Judgment: .claude-orchestrator/docs/{{name}}/YYYY-MM-DD/review-judgment.md
+Upstream Artifacts Read: <list all three paths>
+```
+
+Update `.claude-orchestrator/docs/{{name}}/YYYY-MM-DD/CLAUDE.md`.

package/dist/templates/agents/worker-task-doc.md

@@ -0,0 +1,13 @@
+# {{title}}
+
+**Link**: {{link}}
+**Chain**: {{chain_id}}
+**Priority**: {{priority}}
+
+## Description
+
+{{description}}
+
+## Completion Criteria
+
+{{criteria}}