claude-code-workflow 7.2.23 → 7.2.24

package/.codex/skills/team-issue/roles/reviewer/role.md

@@ -1,86 +1,86 @@
----
-role: reviewer
-prefix: AUDIT
-inner_loop: false
-message_types: [approved, concerns, rejected, error]
----
-
-# Issue Reviewer
-
-Review solution plans for technical feasibility, risk, and completeness. Quality gate role between plan and execute phases. Provides clear verdicts: approved, rejected, or concerns.
-
-## Phase 2: Context & Solution Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
-| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
-| Bound solution | `ccw issue solutions <id> --json` | Yes |
-| wisdom meta | <session>/wisdom/.msg/meta.json | No |
-
-1. Extract issue IDs from task description via regex
-2. Load explorer context reports for each issue
-3. Load bound solutions for each issue:
-
-```
-Bash("ccw issue solutions <issueId> --json")
-```
-
-## Phase 3: Multi-Dimensional Review
-
-Review each solution across three weighted dimensions:
-
-**Technical Feasibility (40%)**:
-
-| Criterion | Check |
-|-----------|-------|
-| File Coverage | Solution covers all affected files from explorer context |
-| Dependency Awareness | Considers dependency cascade effects |
-| API Compatibility | Maintains backward compatibility |
-| Pattern Conformance | Follows existing code patterns (ACE semantic validation) |
-
-**Risk Assessment (30%)**:
-
-| Criterion | Check |
-|-----------|-------|
-| Scope Creep | Solution stays within issue boundary (task_count <= 10) |
-| Breaking Changes | No destructive modifications |
-| Side Effects | No unforeseen side effects |
-| Rollback Path | Can rollback if issues occur |
-
-**Completeness (30%)**:
-
-| Criterion | Check |
-|-----------|-------|
-| All Tasks Defined | Task decomposition is complete (count > 0) |
-| Test Coverage | Includes test plan |
-| Edge Cases | Considers boundary conditions |
-
-**Score calculation**:
-
-```
-total_score = round(
-  technical_feasibility.score * 0.4 +
-  risk_assessment.score * 0.3 +
-  completeness.score * 0.3
-)
-```
-
-**Verdict rules**:
-
-| Score | Verdict | Message Type |
-|-------|---------|-------------|
-| >= 80 | approved | `approved` |
-| 60-79 | concerns | `concerns` |
-| < 60 | rejected | `rejected` |
-
-## Phase 4: Compile Audit Report
-
-1. Write audit report to `<session>/audits/audit-report.json`:
-   - Per-issue: issueId, solutionId, total_score, verdict, per-dimension scores and findings
-   - Overall verdict (any rejected -> overall rejected)
-
-2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
-   - Read existing -> merge `{ "reviewer": { overall_verdict, review_count, scores } }` -> write back
-
-3. For rejected solutions, include specific rejection reasons and actionable feedback for SOLVE-fix task creation
+---
+role: reviewer
+prefix: AUDIT
+inner_loop: false
+message_types: [approved, concerns, rejected, error]
+---
+
+# Issue Reviewer
+
+Review solution plans for technical feasibility, risk, and completeness. Quality gate role between plan and execute phases. Provides clear verdicts: approved, rejected, or concerns.
+
+## Phase 2: Context & Solution Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
+| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
+| Bound solution | `ccw issue solutions <id> --json` | Yes |
+| wisdom meta | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract issue IDs from task description via regex
+2. Load explorer context reports for each issue
+3. Load bound solutions for each issue:
+
+```
+Bash("ccw issue solutions <issueId> --json")
+```
+
+## Phase 3: Multi-Dimensional Review
+
+Review each solution across three weighted dimensions:
+
+**Technical Feasibility (40%)**:
+
+| Criterion | Check |
+|-----------|-------|
+| File Coverage | Solution covers all affected files from explorer context |
+| Dependency Awareness | Considers dependency cascade effects |
+| API Compatibility | Maintains backward compatibility |
+| Pattern Conformance | Follows existing code patterns (ACE semantic validation) |
+
+**Risk Assessment (30%)**:
+
+| Criterion | Check |
+|-----------|-------|
+| Scope Creep | Solution stays within issue boundary (task_count <= 10) |
+| Breaking Changes | No destructive modifications |
+| Side Effects | No unforeseen side effects |
+| Rollback Path | Can rollback if issues occur |
+
+**Completeness (30%)**:
+
+| Criterion | Check |
+|-----------|-------|
+| All Tasks Defined | Task decomposition is complete (count > 0) |
+| Test Coverage | Includes test plan |
+| Edge Cases | Considers boundary conditions |
+
+**Score calculation**:
+
+```
+total_score = round(
+  technical_feasibility.score * 0.4 +
+  risk_assessment.score * 0.3 +
+  completeness.score * 0.3
+)
+```
+
+**Verdict rules**:
+
+| Score | Verdict | Message Type |
+|-------|---------|-------------|
+| >= 80 | approved | `approved` |
+| 60-79 | concerns | `concerns` |
+| < 60 | rejected | `rejected` |
+
+## Phase 4: Compile Audit Report
+
+1. Write audit report to `<session>/audits/audit-report.json`:
+   - Per-issue: issueId, solutionId, total_score, verdict, per-dimension scores and findings
+   - Overall verdict (any rejected -> overall rejected)
+
+2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
+   - Read existing -> merge `{ "reviewer": { overall_verdict, review_count, scores } }` -> write back
+
+3. For rejected solutions, include specific rejection reasons and actionable feedback for SOLVE-fix task creation

package/.codex/skills/team-issue/specs/pipelines.md

@@ -1,124 +1,124 @@
-# Pipeline Definitions — team-issue
-
-## Available Pipelines
-
-### Quick Pipeline (4 beats, strictly serial)
-
-```
-EXPLORE-001 → SOLVE-001 → MARSHAL-001 → BUILD-001
-[explorer]    [planner]   [integrator]  [implementer]
-```
-
-Use when: 1-2 simple issues, no high-priority (priority < 4).
-
-### Full Pipeline (5 beats, with review gate)
-
-```
-EXPLORE-001 → SOLVE-001 → AUDIT-001 ─┬─(approved/concerns)→ MARSHAL-001 → BUILD-001
-[explorer]    [planner]   [reviewer]  │
-                                      └─(rejected, round<2)→ SOLVE-fix-001 → AUDIT-002 → MARSHAL-001 → BUILD-001
-```
-
-Use when: 1-4 issues with high-priority, or 3-4 issues regardless of priority.
-
-### Batch Pipeline (parallel windows)
-
-```
-[EXPLORE-001..N](parallel, max 5) → [SOLVE-001..N](sequential) → AUDIT-001 → MARSHAL-001 → [BUILD-001..M](parallel, max 3, deferred)
-```
-
-Use when: 5+ issues.
-
-Note: BUILD tasks are created dynamically after MARSHAL completes and execution-queue.json is available.
-
-## Task Metadata Registry
-
-| Task ID | Role | Phase | Dependencies | Description |
-|---------|------|-------|-------------|-------------|
-| EXPLORE-001 | explorer | explore | (none) | Context analysis and impact assessment |
-| EXPLORE-002..N | explorer | explore | (none) | Parallel exploration (Batch mode only, max 5) |
-| SOLVE-001 | planner | plan | EXPLORE-001 (or all EXPLORE-*) | Solution design and task decomposition |
-| SOLVE-002..N | planner | plan | all EXPLORE-* | Parallel solution design (Batch mode only) |
-| AUDIT-001 | reviewer | review | SOLVE-001 (or all SOLVE-*) | Technical feasibility and risk review (Full/Batch) |
-| SOLVE-fix-001 | planner | fix | AUDIT-001 | Revised solution addressing reviewer feedback |
-| AUDIT-002 | reviewer | re-review | SOLVE-fix-001 | Re-review of revised solution |
-| MARSHAL-001 | integrator | integrate | AUDIT-001 (or last SOLVE-* in quick) | Conflict detection and queue orchestration |
-| BUILD-001 | implementer | implement | MARSHAL-001 | Code implementation and result submission |
-| BUILD-002..M | implementer | implement | MARSHAL-001 | Parallel implementation (Batch, deferred creation) |
-
-## Mode Auto-Detection
-
-| Condition | Mode |
-|-----------|------|
-| User specifies `--mode=<M>` | Use specified mode |
-| Issue count <= 2 AND no high-priority (priority < 4) | `quick` |
-| Issue count <= 2 AND has high-priority (priority >= 4) | `full` |
-| 3-4 issues | `full` |
-| Issue count >= 5 | `batch` |
-
-## Checkpoints
-
-| Trigger | Location | Behavior |
-|---------|----------|----------|
-| Review gate | After AUDIT-* | approved/concerns → MARSHAL; rejected → SOLVE-fix (max 2 rounds) |
-| Review loop limit | fix_cycles >= 2 | Force proceed to MARSHAL with warnings |
-| Deferred BUILD creation | After MARSHAL-* (batch) | Read execution-queue.json, create BUILD tasks |
-| Pipeline stall | No ready + no running | Check missing tasks, report to user |
-
-## Completion Conditions
-
-| Mode | Completion Condition |
-|------|---------------------|
-| quick | All 4 tasks completed |
-| full | All 5 tasks (+ any fix cycle tasks) completed |
-| batch | All N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + M BUILD (+ any fix cycle tasks) completed |
-
-## Parallel Spawn Rules
-
-| Pipeline | Stage | Max Parallel |
-|----------|-------|-------------|
-| Batch | EXPLORE-001..N | min(N, 5) |
-| Batch | BUILD-001..M | min(M, 3) |
-| All | All other stages | 1 |
-
-## Shared State (meta.json)
-
-| Role | State Key |
-|------|-----------| 
-| explorer | `explorer` (issue_id, complexity, impact_scope, file_count) |
-| planner | `planner` (issue_id, solution_id, task_count, is_revision) |
-| reviewer | `reviewer` (overall_verdict, review_count, scores) |
-| integrator | `integrator` (queue_size, parallel_groups, conflict_count) |
-| implementer | `implementer` (issue_id, executor, test_status, review_status) |
-
-## Message Types
-
-| Role | Types |
-|------|-------|
-| coordinator | `pipeline_selected`, `review_result`, `fix_required`, `task_unblocked`, `error`, `shutdown` |
-| explorer | `context_ready`, `error` |
-| planner | `solution_ready`, `multi_solution`, `error` |
-| reviewer | `approved`, `concerns`, `rejected`, `error` |
-| integrator | `queue_ready`, `conflict_found`, `error` |
-| implementer | `impl_complete`, `impl_failed`, `error` |
-
-## Review-Fix Cycle
-
-```
-AUDIT verdict: rejected
-    │
-    ├─ fix_cycles < 2 → create SOLVE-fix-<N> + AUDIT-<N+1> → spawn planner → wait
-    │                       ↑
-    │                   (repeat if rejected again)
-    │
-    └─ fix_cycles >= 2 → force proceed to MARSHAL with rejection warning logged
-```
-
-## Deferred BUILD Creation (Batch Mode)
-
-BUILD tasks are not created during initial dispatch. After MARSHAL-001 completes:
-1. Read `.workflow/issues/queue/execution-queue.json`
-2. Parse `parallel_groups` to determine M
-3. Create BUILD-001..M tasks with `addBlockedBy: ["MARSHAL-001"]`
-4. Assign owners: M <= 2 → "implementer"; M > 2 → "implementer-1".."implementer-M" (max 3)
-5. Spawn implementer workers via handleSpawnNext
+# Pipeline Definitions — team-issue
+
+## Available Pipelines
+
+### Quick Pipeline (4 beats, strictly serial)
+
+```
+EXPLORE-001 → SOLVE-001 → MARSHAL-001 → BUILD-001
+[explorer]    [planner]   [integrator]  [implementer]
+```
+
+Use when: 1-2 simple issues, no high-priority (priority < 4).
+
+### Full Pipeline (5 beats, with review gate)
+
+```
+EXPLORE-001 → SOLVE-001 → AUDIT-001 ─┬─(approved/concerns)→ MARSHAL-001 → BUILD-001
+[explorer]    [planner]   [reviewer]  │
+                                      └─(rejected, round<2)→ SOLVE-fix-001 → AUDIT-002 → MARSHAL-001 → BUILD-001
+```
+
+Use when: 1-4 issues with high-priority, or 3-4 issues regardless of priority.
+
+### Batch Pipeline (parallel windows)
+
+```
+[EXPLORE-001..N](parallel, max 5) → [SOLVE-001..N](sequential) → AUDIT-001 → MARSHAL-001 → [BUILD-001..M](parallel, max 3, deferred)
+```
+
+Use when: 5+ issues.
+
+Note: BUILD tasks are created dynamically after MARSHAL completes and execution-queue.json is available.
+
+## Task Metadata Registry
+
+| Task ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| EXPLORE-001 | explorer | explore | (none) | Context analysis and impact assessment |
+| EXPLORE-002..N | explorer | explore | (none) | Parallel exploration (Batch mode only, max 5) |
+| SOLVE-001 | planner | plan | EXPLORE-001 (or all EXPLORE-*) | Solution design and task decomposition |
+| SOLVE-002..N | planner | plan | all EXPLORE-* | Parallel solution design (Batch mode only) |
+| AUDIT-001 | reviewer | review | SOLVE-001 (or all SOLVE-*) | Technical feasibility and risk review (Full/Batch) |
+| SOLVE-fix-001 | planner | fix | AUDIT-001 | Revised solution addressing reviewer feedback |
+| AUDIT-002 | reviewer | re-review | SOLVE-fix-001 | Re-review of revised solution |
+| MARSHAL-001 | integrator | integrate | AUDIT-001 (or last SOLVE-* in quick) | Conflict detection and queue orchestration |
+| BUILD-001 | implementer | implement | MARSHAL-001 | Code implementation and result submission |
+| BUILD-002..M | implementer | implement | MARSHAL-001 | Parallel implementation (Batch, deferred creation) |
+
+## Mode Auto-Detection
+
+| Condition | Mode |
+|-----------|------|
+| User specifies `--mode=<M>` | Use specified mode |
+| Issue count <= 2 AND no high-priority (priority < 4) | `quick` |
+| Issue count <= 2 AND has high-priority (priority >= 4) | `full` |
+| 3-4 issues | `full` |
+| Issue count >= 5 | `batch` |
+
+## Checkpoints
+
+| Trigger | Location | Behavior |
+|---------|----------|----------|
+| Review gate | After AUDIT-* | approved/concerns → MARSHAL; rejected → SOLVE-fix (max 2 rounds) |
+| Review loop limit | fix_cycles >= 2 | Force proceed to MARSHAL with warnings |
+| Deferred BUILD creation | After MARSHAL-* (batch) | Read execution-queue.json, create BUILD tasks |
+| Pipeline stall | No ready + no running | Check missing tasks, report to user |
+
+## Completion Conditions
+
+| Mode | Completion Condition |
+|------|---------------------|
+| quick | All 4 tasks completed |
+| full | All 5 tasks (+ any fix cycle tasks) completed |
+| batch | All N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + M BUILD (+ any fix cycle tasks) completed |
+
+## Parallel Spawn Rules
+
+| Pipeline | Stage | Max Parallel |
+|----------|-------|-------------|
+| Batch | EXPLORE-001..N | min(N, 5) |
+| Batch | BUILD-001..M | min(M, 3) |
+| All | All other stages | 1 |
+
+## Shared State (meta.json)
+
+| Role | State Key |
+|------|-----------| 
+| explorer | `explorer` (issue_id, complexity, impact_scope, file_count) |
+| planner | `planner` (issue_id, solution_id, task_count, is_revision) |
+| reviewer | `reviewer` (overall_verdict, review_count, scores) |
+| integrator | `integrator` (queue_size, parallel_groups, conflict_count) |
+| implementer | `implementer` (issue_id, executor, test_status, review_status) |
+
+## Message Types
+
+| Role | Types |
+|------|-------|
+| coordinator | `pipeline_selected`, `review_result`, `fix_required`, `task_unblocked`, `error`, `shutdown` |
+| explorer | `context_ready`, `error` |
+| planner | `solution_ready`, `multi_solution`, `error` |
+| reviewer | `approved`, `concerns`, `rejected`, `error` |
+| integrator | `queue_ready`, `conflict_found`, `error` |
+| implementer | `impl_complete`, `impl_failed`, `error` |
+
+## Review-Fix Cycle
+
+```
+AUDIT verdict: rejected
+    │
+    ├─ fix_cycles < 2 → create SOLVE-fix-<N> + AUDIT-<N+1> → spawn planner → wait
+    │                       ↑
+    │                   (repeat if rejected again)
+    │
+    └─ fix_cycles >= 2 → force proceed to MARSHAL with rejection warning logged
+```
+
+## Deferred BUILD Creation (Batch Mode)
+
+BUILD tasks are not created during initial dispatch. After MARSHAL-001 completes:
+1. Read `.workflow/issues/queue/execution-queue.json`
+2. Parse `parallel_groups` to determine M
+3. Create BUILD-001..M tasks with `addBlockedBy: ["MARSHAL-001"]`
+4. Assign owners: M <= 2 → "implementer"; M > 2 → "implementer-1".."implementer-M" (max 3)
+5. Spawn implementer workers via handleSpawnNext

package/.codex/skills/team-iterdev/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-iterdev
 description: Unified team skill for iterative development team. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Generator-Critic loops (developer<->reviewer, max 3 rounds). Triggers on "team iterdev".
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
 ---
 
 # Team IterDev
@@ -54,7 +54,8 @@ Before calling ANY tool, apply this check:
 
 | Tool Call | Verdict | Reason |
 |-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_input` | ALLOWED | Orchestration |
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `list_agents` | ALLOWED | Agent health check |
 | `request_user_input` | ALLOWED | User interaction |
 | `mcp__ccw-tools__team_msg` | ALLOWED | Message bus |
 | `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
@@ -84,6 +85,8 @@ Coordinator spawns workers using this template:
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -107,7 +110,19 @@ pipeline_phase: <pipeline-phase>` },
 })
 ```
 
-After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
+After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
+
+
+### Model Selection Guide
+
+Iterative development uses Generator-Critic loops. Developer and reviewer need high reasoning for code generation and review quality.
+
+| Role | reasoning_effort | Rationale |
+|------|-------------------|-----------|
+| architect | high | Design decisions require careful tradeoff analysis |
+| developer | high | Code generation needs precision, inner loop role |
+| tester | medium | Test execution follows defined verification plan |
+| reviewer | high | Critical review quality drives GC loop effectiveness |
 
 ## User Commands
 
@@ -145,6 +160,52 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 
 - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Queue supplementary info (don't interrupt) | `send_message` | Send design context to running developer |
+| Assign GC iteration round | `assign_task` | Assign revision to developer after reviewer feedback |
+| Check running agents | `list_agents` | Verify agent health during resume |
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with task-ledger.json active tasks
+// Reset orphaned tasks (in_progress but agent gone) to pending
+```
+
+### Named Agent Targeting
+
+Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
+- `send_message({ target: "DEV-001", items: [...] })` -- send design context to developer
+- `assign_task({ target: "DEV-001", items: [...] })` -- assign revision after reviewer feedback
+- `close_agent({ target: "REVIEW-001" })` -- cleanup after GC loop completes
+
+### Generator-Critic Loop via assign_task (Deep Interaction Pattern)
+
+The developer-reviewer GC loop uses `assign_task` for iteration rounds:
+```
+// Round N: Reviewer found issues -> coordinator assigns revision to developer
+assign_task({
+  target: "DEV-001",
+  items: [
+    { type: "text", text: `## GC Revision Round ${N}
+review_feedback: <reviewer findings from REVIEW-001>
+iteration: ${N}/3
+instruction: Address reviewer feedback. Focus on: <specific issues>.` }
+  ]
+})
+```
+
+After developer completes revision, coordinator spawns/assigns reviewer for next round. Max 3 rounds per GC cycle.
+
 ## Error Handling
 
 | Scenario | Resolution |

package/.codex/skills/team-iterdev/roles/architect/role.md

@@ -1,65 +1,65 @@
----
-role: architect
-prefix: DESIGN
-inner_loop: false
-message_types:
-  success: design_ready
-  revision: design_revision
-  error: error
----
-
-# Architect
-
-Technical design, task decomposition, and architecture decision records for iterative development.
-
-## Phase 2: Context Loading + Codebase Exploration
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | No |
-| Wisdom files | <session>/wisdom/ | No |
-
-1. Extract session path and requirement from task description
-2. Read .msg/meta.json for shared context (architecture_decisions, implementation_context)
-3. Read wisdom files if available (learnings.md, decisions.md, conventions.md)
-4. Explore codebase for existing patterns, module structure, dependencies:
-   - Use mcp__ace-tool__search_context for semantic discovery
-   - Identify similar implementations and integration points
-
-## Phase 3: Technical Design + Task Decomposition
-
-**Design strategy selection**:
-
-| Condition | Strategy |
-|-----------|----------|
-| Single module change | Direct inline design |
-| Cross-module change | Multi-component design with integration points |
-| Large refactoring | Phased approach with milestones |
-
-**Outputs**:
-
-1. **Design Document** (`<session>/design/design-<num>.md`):
-   - Architecture decision: approach, rationale, alternatives
-   - Component design: responsibility, dependencies, files, complexity
-   - Task breakdown: files, estimated complexity, dependencies, acceptance criteria
-   - Integration points and risks with mitigations
-
-2. **Task Breakdown JSON** (`<session>/design/task-breakdown.json`):
-   - Array of tasks with id, title, files, complexity, dependencies, acceptance_criteria
-   - Execution order for developer to follow
-
-## Phase 4: Design Validation
-
-| Check | Method | Pass Criteria |
-|-------|--------|---------------|
-| Components defined | Verify component list | At least 1 component |
-| Task breakdown exists | Verify task list | At least 1 task |
-| Dependencies mapped | All components have dependencies field | All present (can be empty) |
-| Integration points | Verify integration section | Key integrations documented |
-
-1. Run validation checks above
-2. Write architecture_decisions entry to .msg/meta.json:
-   - design_id, approach, rationale, components, task_count
-3. Write discoveries to wisdom/decisions.md and wisdom/conventions.md
+---
+role: architect
+prefix: DESIGN
+inner_loop: false
+message_types:
+  success: design_ready
+  revision: design_revision
+  error: error
+---
+
+# Architect
+
+Technical design, task decomposition, and architecture decision records for iterative development.
+
+## Phase 2: Context Loading + Codebase Exploration
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+| Wisdom files | <session>/wisdom/ | No |
+
+1. Extract session path and requirement from task description
+2. Read .msg/meta.json for shared context (architecture_decisions, implementation_context)
+3. Read wisdom files if available (learnings.md, decisions.md, conventions.md)
+4. Explore codebase for existing patterns, module structure, dependencies:
+   - Use mcp__ace-tool__search_context for semantic discovery
+   - Identify similar implementations and integration points
+
+## Phase 3: Technical Design + Task Decomposition
+
+**Design strategy selection**:
+
+| Condition | Strategy |
+|-----------|----------|
+| Single module change | Direct inline design |
+| Cross-module change | Multi-component design with integration points |
+| Large refactoring | Phased approach with milestones |
+
+**Outputs**:
+
+1. **Design Document** (`<session>/design/design-<num>.md`):
+   - Architecture decision: approach, rationale, alternatives
+   - Component design: responsibility, dependencies, files, complexity
+   - Task breakdown: files, estimated complexity, dependencies, acceptance criteria
+   - Integration points and risks with mitigations
+
+2. **Task Breakdown JSON** (`<session>/design/task-breakdown.json`):
+   - Array of tasks with id, title, files, complexity, dependencies, acceptance_criteria
+   - Execution order for developer to follow
+
+## Phase 4: Design Validation
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Components defined | Verify component list | At least 1 component |
+| Task breakdown exists | Verify task list | At least 1 task |
+| Dependencies mapped | All components have dependencies field | All present (can be empty) |
+| Integration points | Verify integration section | Key integrations documented |
+
+1. Run validation checks above
+2. Write architecture_decisions entry to .msg/meta.json:
+   - design_id, approach, rationale, components, task_count
+3. Write discoveries to wisdom/decisions.md and wisdom/conventions.md