mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-28 20:01:17 +08:00
feat: migrate all codex team skills from spawn_agents_on_csv to spawn_agent + wait_agent architecture
- Delete 21 old team skill directories using CSV-wave pipeline pattern (~100+ files) - Delete old team-lifecycle (v3) and team-planex-v2 - Create generic team-worker.toml and team-supervisor.toml (replacing tlv4-specific TOMLs) - Convert 19 team skills from Claude Code format (Agent/SendMessage/TaskCreate) to Codex format (spawn_agent/wait_agent/tasks.json/request_user_input) - Update team-lifecycle-v4 to use generic agent types (team_worker/team_supervisor) - Convert all coordinator role files: dispatch.md, monitor.md, role.md - Convert all worker role files: remove run_in_background, fix Bash syntax - Convert all specs/pipelines.md references - Final state: 20 team skills, 217 .md files, zero Claude Code API residuals Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -0,0 +1,61 @@
|
||||
# Analyze Task
|
||||
|
||||
Parse user task description for roadmap-dev domain signals. Detect phase count, depth preference, gate configuration, and pipeline mode.
|
||||
|
||||
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
|
||||
|
||||
## Signal Detection
|
||||
|
||||
### Phase Count
|
||||
|
||||
| Keywords | Inferred Phase Count |
|
||||
|----------|---------------------|
|
||||
| "phase 1", "phase 2", ... | Explicit phase count from numbers |
|
||||
| "milestone", "milestone 1/2/3" | Count milestones |
|
||||
| "first ... then ... finally" | 3 phases |
|
||||
| "step 1/2/3" | Count steps |
|
||||
| No phase keywords | Default: 1 phase |
|
||||
|
||||
### Depth Setting
|
||||
|
||||
| Keywords | Depth |
|
||||
|----------|-------|
|
||||
| "quick", "fast", "simple", "minimal" | quick |
|
||||
| "thorough", "comprehensive", "complete", "full" | comprehensive |
|
||||
| default | standard |
|
||||
|
||||
### Gate Configuration
|
||||
|
||||
| Keywords | Gate |
|
||||
|----------|------|
|
||||
| "review each plan", "approve plan", "check before execute" | plan_check: true |
|
||||
| "review each phase", "approve phase", "check between phases" | phase_check: true |
|
||||
| "auto", "automated", "no review", "fully automated" | all gates: false |
|
||||
| default | plan_check: false, phase_check: false |
|
||||
|
||||
### Pipeline Mode
|
||||
|
||||
| Keywords | Mode |
|
||||
|----------|------|
|
||||
| "interactive", "step by step", "with approval" | interactive |
|
||||
| default | auto |
|
||||
|
||||
## Output
|
||||
|
||||
Write coordinator state to memory (not a file). Structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"pipeline_mode": "auto | interactive",
|
||||
"phase_count": 1,
|
||||
"depth": "quick | standard | comprehensive",
|
||||
"gates": {
|
||||
"plan_check": false,
|
||||
"phase_check": false
|
||||
},
|
||||
"task_description": "<original task text>",
|
||||
"notes": ["<any detected constraints or special requirements>"]
|
||||
}
|
||||
```
|
||||
|
||||
This state is passed to `commands/dispatch.md` and written to `config.json` in the session directory.
|
||||
@@ -0,0 +1,241 @@
|
||||
# Command: dispatch
|
||||
|
||||
Create task chain for a specific phase. Each phase gets a PLAN -> EXEC -> VERIFY pipeline with dependency ordering.
|
||||
|
||||
## Purpose
|
||||
|
||||
Read the roadmap and create a linked task chain (PLAN -> EXEC -> VERIFY) for a given phase number. Tasks are assigned to the appropriate worker roles and linked via blockedBy dependencies. All tasks are stored in `<session>/tasks.json`.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Source | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `phaseNumber` | From coordinator | Phase to dispatch (1-based) |
|
||||
| `sessionFolder` | From coordinator | Session artifact directory |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Read Roadmap and Extract Phase Requirements
|
||||
|
||||
```javascript
|
||||
const roadmap = Read(`${sessionFolder}/roadmap.md`)
|
||||
const config = JSON.parse(Read(`${sessionFolder}/config.json`))
|
||||
|
||||
// Parse phase section from roadmap
|
||||
// Extract: goal, requirements (REQ-IDs), success criteria
|
||||
const phaseGoal = extractPhaseGoal(roadmap, phaseNumber)
|
||||
const phaseRequirements = extractPhaseRequirements(roadmap, phaseNumber)
|
||||
const phaseSuccessCriteria = extractPhaseSuccessCriteria(roadmap, phaseNumber)
|
||||
```
|
||||
|
||||
### Step 2: Create Phase Directory
|
||||
|
||||
```javascript
|
||||
Bash(`mkdir -p "${sessionFolder}/phase-${phaseNumber}"`)
|
||||
```
|
||||
|
||||
### Step 3: Load or Initialize tasks.json
|
||||
|
||||
```javascript
|
||||
let tasks = []
|
||||
try {
|
||||
tasks = JSON.parse(Read(`${sessionFolder}/tasks.json`))
|
||||
} catch {
|
||||
tasks = []
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Create PLAN Task (Assigned to Planner)
|
||||
|
||||
```javascript
|
||||
const planTaskId = `PLAN-${phaseNumber}01`
|
||||
|
||||
tasks.push({
|
||||
id: planTaskId,
|
||||
subject: `PLAN-${phaseNumber}01: Plan phase ${phaseNumber} - ${phaseGoal}`,
|
||||
status: "pending",
|
||||
owner: "planner",
|
||||
blockedBy: [],
|
||||
activeForm: `Planning phase ${phaseNumber}`,
|
||||
description: `[coordinator] Plan creation for phase ${phaseNumber}.
|
||||
|
||||
## Session
|
||||
- Folder: ${sessionFolder}
|
||||
- Phase: ${phaseNumber}
|
||||
- Depth: ${config.depth}
|
||||
|
||||
## Phase Goal
|
||||
${phaseGoal}
|
||||
|
||||
## Requirements
|
||||
${phaseRequirements.map(r => `- ${r}`).join('\n')}
|
||||
|
||||
## Success Criteria
|
||||
${phaseSuccessCriteria.map(c => `- ${c}`).join('\n')}
|
||||
|
||||
## Deliverables
|
||||
- ${sessionFolder}/phase-${phaseNumber}/context.md (research context)
|
||||
- ${sessionFolder}/phase-${phaseNumber}/plan-01.md (execution plan with waves and must_haves)
|
||||
|
||||
## Instructions
|
||||
1. Invoke Skill(skill="team-roadmap-dev", args="--role=planner")
|
||||
2. Follow planner role.md research + create-plans commands
|
||||
3. Use roadmap requirements as input for plan generation
|
||||
4. Update this task to completed when plan is written`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 5: Create EXEC Task (Assigned to Executor, Blocked by PLAN)
|
||||
|
||||
```javascript
|
||||
const execTaskId = `EXEC-${phaseNumber}01`
|
||||
|
||||
tasks.push({
|
||||
id: execTaskId,
|
||||
subject: `EXEC-${phaseNumber}01: Execute phase ${phaseNumber} - ${phaseGoal}`,
|
||||
status: "pending",
|
||||
owner: "executor",
|
||||
blockedBy: [planTaskId],
|
||||
activeForm: `Executing phase ${phaseNumber}`,
|
||||
description: `[coordinator] Execute plans for phase ${phaseNumber}.
|
||||
|
||||
## Session
|
||||
- Folder: ${sessionFolder}
|
||||
- Phase: ${phaseNumber}
|
||||
|
||||
## Phase Goal
|
||||
${phaseGoal}
|
||||
|
||||
## Plan Reference
|
||||
- ${sessionFolder}/phase-${phaseNumber}/plan-01.md (and any additional plans)
|
||||
|
||||
## Instructions
|
||||
1. Invoke Skill(skill="team-roadmap-dev", args="--role=executor")
|
||||
2. Follow executor role.md implement command
|
||||
3. Execute all plans in wave order
|
||||
4. Write summary to ${sessionFolder}/phase-${phaseNumber}/summary-01.md
|
||||
5. Update this task to completed when all plans executed`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 6: Create VERIFY Task (Assigned to Verifier, Blocked by EXEC)
|
||||
|
||||
```javascript
|
||||
const verifyTaskId = `VERIFY-${phaseNumber}01`
|
||||
|
||||
tasks.push({
|
||||
id: verifyTaskId,
|
||||
subject: `VERIFY-${phaseNumber}01: Verify phase ${phaseNumber} - ${phaseGoal}`,
|
||||
status: "pending",
|
||||
owner: "verifier",
|
||||
blockedBy: [execTaskId],
|
||||
activeForm: `Verifying phase ${phaseNumber}`,
|
||||
description: `[coordinator] Verify phase ${phaseNumber} against success criteria.
|
||||
|
||||
## Session
|
||||
- Folder: ${sessionFolder}
|
||||
- Phase: ${phaseNumber}
|
||||
|
||||
## Phase Goal
|
||||
${phaseGoal}
|
||||
|
||||
## Success Criteria (from roadmap)
|
||||
${phaseSuccessCriteria.map(c => `- ${c}`).join('\n')}
|
||||
|
||||
## References
|
||||
- Roadmap: ${sessionFolder}/roadmap.md
|
||||
- Plans: ${sessionFolder}/phase-${phaseNumber}/plan-*.md
|
||||
- Summaries: ${sessionFolder}/phase-${phaseNumber}/summary-*.md
|
||||
|
||||
## Instructions
|
||||
1. Invoke Skill(skill="team-roadmap-dev", args="--role=verifier")
|
||||
2. Follow verifier role.md verify command
|
||||
3. Check each success criterion against actual implementation
|
||||
4. Write verification to ${sessionFolder}/phase-${phaseNumber}/verification.md
|
||||
5. If gaps found: list them with gap IDs in verification.md
|
||||
6. Update this task to completed with result (passed/gaps_found)`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 7: Write tasks.json
|
||||
|
||||
```javascript
|
||||
Write(`${sessionFolder}/tasks.json`, JSON.stringify(tasks, null, 2))
|
||||
```
|
||||
|
||||
### Step 8: Update state.md
|
||||
|
||||
```javascript
|
||||
Edit(`${sessionFolder}/state.md`, {
|
||||
old_string: `- Phase: ${phaseNumber}\n- Status: ready_to_dispatch`,
|
||||
new_string: `- Phase: ${phaseNumber}\n- Status: in_progress\n- Tasks: PLAN-${phaseNumber}01 -> EXEC-${phaseNumber}01 -> VERIFY-${phaseNumber}01`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 9: Log Dispatch Message
|
||||
|
||||
```javascript
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "coordinator", to: "all",
|
||||
type: "phase_started",
|
||||
data: { ref: `${sessionFolder}/roadmap.md` }
|
||||
})
|
||||
```
|
||||
|
||||
## Task Description Format
|
||||
|
||||
All dispatched tasks follow this structure:
|
||||
|
||||
```
|
||||
[coordinator] {action} for phase {N}.
|
||||
|
||||
## Session
|
||||
- Folder: {sessionFolder}
|
||||
- Phase: {N}
|
||||
- Depth: {config.depth} (PLAN only)
|
||||
|
||||
## Phase Goal
|
||||
{goal from roadmap}
|
||||
|
||||
## Requirements / Success Criteria
|
||||
{from roadmap}
|
||||
|
||||
## Deliverables
|
||||
{expected output files}
|
||||
|
||||
## Instructions
|
||||
{step-by-step for the worker role}
|
||||
```
|
||||
|
||||
## Task Naming Convention
|
||||
|
||||
| Task | Name Pattern | Example |
|
||||
|------|-------------|---------|
|
||||
| Plan | `PLAN-{phase}01` | PLAN-101 |
|
||||
| Execute | `EXEC-{phase}01` | EXEC-101 |
|
||||
| Verify | `VERIFY-{phase}01` | VERIFY-101 |
|
||||
| Gap Plan | `PLAN-{phase}02` | PLAN-102 (gap closure iteration 1) |
|
||||
| Gap Execute | `EXEC-{phase}02` | EXEC-102 |
|
||||
| Gap Verify | `VERIFY-{phase}02` | VERIFY-102 |
|
||||
|
||||
## Dependency Chain
|
||||
|
||||
```
|
||||
PLAN-{N}01 <-- EXEC-{N}01 <-- VERIFY-{N}01
|
||||
(planner) (executor) (verifier)
|
||||
```
|
||||
|
||||
Each task is blocked by its predecessor. Workers pick up tasks only when their blockedBy list is empty.
|
||||
|
||||
## Output
|
||||
|
||||
Returns the three task IDs as a structured result:
|
||||
|
||||
```javascript
|
||||
{
|
||||
planTaskId: planTaskId,
|
||||
execTaskId: execTaskId,
|
||||
verifyTaskId: verifyTaskId
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,468 @@
|
||||
# Command: Monitor
|
||||
|
||||
Handle all coordinator monitoring events for the roadmap-dev pipeline using the async Spawn-and-Stop pattern. Multi-phase execution with gap closure expressed as event-driven state machine transitions. One operation per invocation, then STOP and wait for the next callback.
|
||||
|
||||
## Constants
|
||||
|
||||
| Key | Value | Description |
|
||||
|-----|-------|-------------|
|
||||
| SPAWN_MODE | background | All workers spawned via `spawn_agent()` |
|
||||
| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
|
||||
| WORKER_AGENT | team_worker | All workers spawned as team_worker agents |
|
||||
| MAX_GAP_ITERATIONS | 3 | Maximum gap closure re-plan/exec/verify cycles per phase |
|
||||
|
||||
### Role-Worker Map
|
||||
|
||||
| Prefix | Role | Role Spec | inner_loop |
|
||||
|--------|------|-----------|------------|
|
||||
| PLAN | planner | `~ or <project>/.codex/skills/team-roadmap-dev/roles/planner/role.md` | true (cli_tools: gemini --mode analysis) |
|
||||
| EXEC | executor | `~ or <project>/.codex/skills/team-roadmap-dev/roles/executor/role.md` | true (cli_tools: gemini --mode write) |
|
||||
| VERIFY | verifier | `~ or <project>/.codex/skills/team-roadmap-dev/roles/verifier/role.md` | true |
|
||||
|
||||
### Pipeline Structure
|
||||
|
||||
Per-phase task chain: `PLAN-{phase}01 -> EXEC-{phase}01 -> VERIFY-{phase}01`
|
||||
|
||||
Gap closure creates: `PLAN-{phase}0N -> EXEC-{phase}0N -> VERIFY-{phase}0N` (N = iteration + 1)
|
||||
|
||||
Multi-phase: Phases execute sequentially. Each phase completes its full PLAN/EXEC/VERIFY cycle (including gap closure) before the next phase is dispatched.
|
||||
|
||||
### State Machine Coordinates
|
||||
|
||||
The coordinator tracks its position using these state variables in `meta.json`:
|
||||
|
||||
```
|
||||
session.coordinates = {
|
||||
current_phase: <number>, // Active phase (1-based)
|
||||
total_phases: <number>, // Total phases from roadmap
|
||||
gap_iteration: <number>, // Current gap closure iteration within phase (0 = initial)
|
||||
step: <string>, // Current step: "plan" | "exec" | "verify" | "gap_closure" | "transition"
|
||||
status: <string> // "running" | "paused" | "complete"
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session file | `<session-folder>/.msg/meta.json` | Yes |
|
||||
| Task list | `<session>/tasks.json` | Yes |
|
||||
| Active workers | session.active_workers[] | Yes |
|
||||
| Coordinates | session.coordinates | Yes |
|
||||
| Config | `<session-folder>/config.json` | Yes |
|
||||
| State | `<session-folder>/state.md` | Yes |
|
||||
|
||||
```
|
||||
Load session state:
|
||||
1. Read <session-folder>/.msg/meta.json -> session
|
||||
2. Read <session-folder>/config.json -> config
|
||||
3. Read <session>/tasks.json -> allTasks
|
||||
4. Extract coordinates from session (current_phase, gap_iteration, step)
|
||||
5. Extract active_workers[] from session (default: [])
|
||||
6. Parse $ARGUMENTS to determine trigger event
|
||||
```
|
||||
|
||||
## Phase 3: Event Handlers
|
||||
|
||||
### Wake-up Source Detection
|
||||
|
||||
Parse `$ARGUMENTS` to determine handler:
|
||||
|
||||
| Priority | Condition | Handler |
|
||||
|----------|-----------|---------|
|
||||
| 1 | Message contains `[planner]`, `[executor]`, or `[verifier]` | handleCallback |
|
||||
| 2 | Contains "check" or "status" | handleCheck |
|
||||
| 3 | Contains "resume", "continue", or "next" | handleResume |
|
||||
| 4 | Pipeline detected as complete (all phases done) | handleComplete |
|
||||
| 5 | None of the above (initial spawn after dispatch) | handleSpawnNext |
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCallback
|
||||
|
||||
Worker completed a task. Determine which step completed via prefix, apply pipeline logic, advance.
|
||||
|
||||
```
|
||||
Receive callback from [<role>]
|
||||
+- Find matching active worker by role tag
|
||||
+- Is this a progress update (not final)? (Inner Loop intermediate)
|
||||
| +- YES -> Update session state -> STOP
|
||||
+- Task status = completed?
|
||||
| +- YES -> remove from active_workers -> update session
|
||||
| | +- Update task in tasks.json: set status = "completed"
|
||||
| | +- Determine completed step from task prefix:
|
||||
| | |
|
||||
| | +- PLAN-* completed:
|
||||
| | | +- Update coordinates.step = "plan_done"
|
||||
| | | +- Is this initial plan (gap_iteration === 0)?
|
||||
| | | | +- YES + config.gates.plan_check?
|
||||
| | | | | +- request_user_input:
|
||||
| | | | | prompt: "Phase <N> plan ready. Proceed with execution?
|
||||
| | | | | Options:
|
||||
| | | | | 1. Proceed - Continue to execution
|
||||
| | | | | 2. Revise - Create new PLAN task with incremented suffix
|
||||
| | | | | 3. Skip phase - Delete all phase tasks"
|
||||
| | | | | -> "Proceed": -> handleSpawnNext (spawns EXEC)
|
||||
| | | | | -> "Revise": Create new PLAN task in tasks.json
|
||||
| | | | | blockedBy: [] (immediate), -> handleSpawnNext
|
||||
| | | | | -> "Skip phase": Remove all phase tasks from tasks.json
|
||||
| | | | | -> advanceToNextPhase
|
||||
| | | | +- NO (gap closure plan) -> handleSpawnNext (spawns EXEC)
|
||||
| | | +- -> handleSpawnNext
|
||||
| | |
|
||||
| | +- EXEC-* completed:
|
||||
| | | +- Update coordinates.step = "exec_done"
|
||||
| | | +- -> handleSpawnNext (spawns VERIFY)
|
||||
| | |
|
||||
| | +- VERIFY-* completed:
|
||||
| | +- Update coordinates.step = "verify_done"
|
||||
| | +- Read verification result from:
|
||||
| | | <session-folder>/phase-<N>/verification.md
|
||||
| | +- Parse gaps from verification
|
||||
| | +- Gaps found?
|
||||
| | +- NO -> Phase passed
|
||||
| | | +- -> advanceToNextPhase
|
||||
| | +- YES + gap_iteration < MAX_GAP_ITERATIONS?
|
||||
| | | +- -> triggerGapClosure
|
||||
| | +- YES + gap_iteration >= MAX_GAP_ITERATIONS?
|
||||
| | +- request_user_input:
|
||||
| | prompt: "Phase <N> still has <count> gaps after <max> attempts.
|
||||
| | Options:
|
||||
| | 1. Continue anyway - Accept and advance to next phase
|
||||
| | 2. Retry once more - Increment max and try again
|
||||
| | 3. Stop - Pause session"
|
||||
| | -> "Continue anyway": Accept, -> advanceToNextPhase
|
||||
| | -> "Retry once more": Increment max, -> triggerGapClosure
|
||||
| | -> "Stop": -> pauseSession
|
||||
| |
|
||||
| +- NO -> progress message -> STOP
|
||||
+- No matching worker found
|
||||
+- Scan all active workers for completed tasks
|
||||
+- Found completed -> process each (same logic above) -> handleSpawnNext
|
||||
+- None completed -> STOP
|
||||
```
|
||||
|
||||
**Sub-procedure: advanceToNextPhase**
|
||||
|
||||
```
|
||||
advanceToNextPhase:
|
||||
+- Update state.md: mark current phase completed
|
||||
+- current_phase < total_phases?
|
||||
| +- YES:
|
||||
| | +- config.mode === "interactive"?
|
||||
| | | +- request_user_input:
|
||||
| | | prompt: "Phase <N> complete. Proceed to phase <N+1>?
|
||||
| | | Options:
|
||||
| | | 1. Proceed - Dispatch next phase tasks
|
||||
| | | 2. Review results - Output phase summary, re-ask
|
||||
| | | 3. Stop - Pause session"
|
||||
| | | -> "Proceed": Dispatch next phase tasks, -> handleSpawnNext
|
||||
| | | -> "Review results": Output phase summary, re-ask
|
||||
| | | -> "Stop": -> pauseSession
|
||||
| | +- Auto mode: Dispatch next phase tasks directly
|
||||
| | +- Update coordinates:
|
||||
| | current_phase++, gap_iteration=0, step="plan"
|
||||
| | +- Dispatch new phase tasks (PLAN/EXEC/VERIFY with blockedBy) to tasks.json
|
||||
| | +- -> handleSpawnNext
|
||||
| +- NO -> All phases done -> handleComplete
|
||||
```
|
||||
|
||||
**Sub-procedure: triggerGapClosure**
|
||||
|
||||
```
|
||||
triggerGapClosure:
|
||||
+- Increment coordinates.gap_iteration
|
||||
+- suffix = "0" + (gap_iteration + 1)
|
||||
+- phase = coordinates.current_phase
|
||||
+- Read gaps from verification.md
|
||||
+- Log: team_msg gap_closure
|
||||
+- Create gap closure task chain in tasks.json:
|
||||
|
|
||||
| Add to tasks.json: {
|
||||
| id: "PLAN-{phase}{suffix}",
|
||||
| subject: "PLAN-{phase}{suffix}: Gap closure for phase {phase} (iteration {gap_iteration})",
|
||||
| status: "pending",
|
||||
| owner: "planner",
|
||||
| blockedBy: [],
|
||||
| description: includes gap list, references to previous verification
|
||||
| }
|
||||
|
|
||||
| Add to tasks.json: {
|
||||
| id: "EXEC-{phase}{suffix}",
|
||||
| subject: "EXEC-{phase}{suffix}: Execute gap fixes for phase {phase}",
|
||||
| status: "pending",
|
||||
| owner: "executor",
|
||||
| blockedBy: ["PLAN-{phase}{suffix}"]
|
||||
| }
|
||||
|
|
||||
| Add to tasks.json: {
|
||||
| id: "VERIFY-{phase}{suffix}",
|
||||
| subject: "VERIFY-{phase}{suffix}: Verify gap closure for phase {phase}",
|
||||
| status: "pending",
|
||||
| owner: "verifier",
|
||||
| blockedBy: ["EXEC-{phase}{suffix}"]
|
||||
| }
|
||||
|
|
||||
| Write updated tasks.json
|
||||
|
|
||||
+- Update coordinates.step = "gap_closure"
|
||||
+- -> handleSpawnNext (picks up the new PLAN task)
|
||||
```
|
||||
|
||||
**Sub-procedure: pauseSession**
|
||||
|
||||
```
|
||||
pauseSession:
|
||||
+- Save coordinates to meta.json (phase, step, gap_iteration)
|
||||
+- Update coordinates.status = "paused"
|
||||
+- Update state.md with pause marker
|
||||
+- team_msg log -> session_paused
|
||||
+- Output: "Session paused at phase <N>, step <step>. Resume with 'resume'."
|
||||
+- STOP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleSpawnNext
|
||||
|
||||
Find all ready tasks, spawn team_worker agent, update session, STOP.
|
||||
|
||||
```
|
||||
Read tasks from <session>/tasks.json
|
||||
+- completedSubjects: status = completed
|
||||
+- inProgressSubjects: status = in_progress
|
||||
+- readySubjects: status = pending
|
||||
AND (no blockedBy OR all blockedBy in completedSubjects)
|
||||
|
||||
Ready tasks found?
|
||||
+- NONE + work in progress -> report waiting -> STOP
|
||||
+- NONE + nothing in progress:
|
||||
| +- More phases to dispatch? -> advanceToNextPhase
|
||||
| +- No more phases -> handleComplete
|
||||
+- HAS ready tasks -> take first ready task:
|
||||
+- Is task owner an Inner Loop role AND that role already has active_worker?
|
||||
| +- YES -> SKIP spawn (existing worker picks it up via inner loop)
|
||||
| +- NO -> normal spawn below
|
||||
+- Determine role from prefix:
|
||||
| PLAN-* -> planner
|
||||
| EXEC-* -> executor
|
||||
| VERIFY-* -> verifier
|
||||
+- Update task status to "in_progress" in tasks.json
|
||||
+- team_msg log -> task_unblocked (team_session_id=<session-id>)
|
||||
+- Spawn team_worker (see spawn call below)
|
||||
+- Add to session.active_workers
|
||||
+- Update session file
|
||||
+- Output: "[coordinator] Spawned <role> for <subject>"
|
||||
+- STOP
|
||||
```
|
||||
|
||||
**Spawn worker call** (one per ready task):
|
||||
|
||||
```
|
||||
spawn_agent({
|
||||
agent_type: "team_worker",
|
||||
items: [{
|
||||
description: "Spawn <role> worker for <subject>",
|
||||
team_name: "roadmap-dev",
|
||||
name: "<role>",
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: ~ or <project>/.codex/skills/team-roadmap-dev/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: roadmap-dev
|
||||
requirement: <task-description>
|
||||
inner_loop: true
|
||||
|
||||
## Current Task
|
||||
- Task ID: <task-id>
|
||||
- Task: <subject>
|
||||
- Phase: <current_phase>
|
||||
- Gap Iteration: <gap_iteration>
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
Workers report results via `report_agent_job_result()`. Coordinator receives results via `wait_agent({ ids })`.
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCheck
|
||||
|
||||
Read-only status report. No pipeline advancement.
|
||||
|
||||
**Output format**:
|
||||
|
||||
```
|
||||
[coordinator] Roadmap Pipeline Status
|
||||
[coordinator] Phase: <current>/<total> | Gap Iteration: <N>/<max>
|
||||
[coordinator] Progress: <completed>/<total tasks> (<percent>%)
|
||||
|
||||
[coordinator] Current Phase <N> Graph:
|
||||
PLAN-{N}01: <status-icon> <summary>
|
||||
EXEC-{N}01: <status-icon> <summary>
|
||||
VERIFY-{N}01: <status-icon> <summary>
|
||||
[PLAN-{N}02: <status-icon> (gap closure #1)]
|
||||
[EXEC-{N}02: <status-icon>]
|
||||
[VERIFY-{N}02:<status-icon>]
|
||||
|
||||
done=completed >>>=running o=pending x=deleted .=not created
|
||||
|
||||
[coordinator] Phase Summary:
|
||||
Phase 1: completed
|
||||
Phase 2: in_progress (step: exec)
|
||||
Phase 3: not started
|
||||
|
||||
[coordinator] Active Workers:
|
||||
> <subject> (<role>) - running [inner-loop: N/M tasks done]
|
||||
|
||||
[coordinator] Ready to spawn: <subjects>
|
||||
[coordinator] Coordinates: phase=<N> step=<step> gap=<iteration>
|
||||
[coordinator] Commands: 'resume' to advance | 'check' to refresh
|
||||
```
|
||||
|
||||
Then STOP.
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleResume
|
||||
|
||||
Check active worker completion, process results, advance pipeline. Also handles resume from paused state.
|
||||
|
||||
```
|
||||
Check coordinates.status:
|
||||
+- "paused" -> Restore coordinates, resume from saved position
|
||||
| Reset coordinates.status = "running"
|
||||
| -> handleSpawnNext (picks up where it left off)
|
||||
+- "running" -> Normal resume:
|
||||
Load active_workers from session
|
||||
+- No active workers -> handleSpawnNext
|
||||
+- Has active workers -> check each:
|
||||
+- status = completed -> mark done, remove from active_workers, log
|
||||
+- status = in_progress -> still running, log
|
||||
+- other status -> worker failure -> reset to pending
|
||||
After processing:
|
||||
+- Some completed -> handleSpawnNext
|
||||
+- All still running -> report status -> STOP
|
||||
+- All failed -> handleSpawnNext (retry)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleComplete
|
||||
|
||||
All phases done. Generate final project summary and finalize session.
|
||||
|
||||
```
|
||||
All phases completed (no pending, no in_progress across all phases)
|
||||
+- Generate project-level summary:
|
||||
| - Roadmap overview (phases completed)
|
||||
| - Per-phase results:
|
||||
| - Gap closure iterations used
|
||||
| - Verification status
|
||||
| - Key deliverables
|
||||
| - Overall stats (tasks completed, phases, total gap iterations)
|
||||
|
|
||||
+- Update session:
|
||||
| coordinates.status = "complete"
|
||||
| session.completed_at = <timestamp>
|
||||
| Write meta.json
|
||||
|
|
||||
+- Update state.md: mark all phases completed
|
||||
+- team_msg log -> project_complete
|
||||
+- Output summary to user
|
||||
+- STOP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Worker Failure Handling
|
||||
|
||||
When a worker has unexpected status (not completed, not in_progress):
|
||||
|
||||
1. Reset task -> pending in tasks.json
|
||||
2. Remove from active_workers
|
||||
3. Log via team_msg (type: error)
|
||||
4. Report to user: task reset, will retry on next resume
|
||||
|
||||
## Phase 4: State Persistence
|
||||
|
||||
After every handler action, before STOP:
|
||||
|
||||
| Check | Action |
|
||||
|-------|--------|
|
||||
| Coordinates updated | current_phase, step, gap_iteration reflect actual state |
|
||||
| Session state consistent | active_workers matches tasks.json in_progress tasks |
|
||||
| No orphaned tasks | Every in_progress task has an active_worker entry |
|
||||
| Meta.json updated | Write updated session state and coordinates |
|
||||
| State.md updated | Phase progress reflects actual completion |
|
||||
| Completion detection | All phases done + no pending + no in_progress -> handleComplete |
|
||||
|
||||
```
|
||||
Persist:
|
||||
1. Update coordinates in meta.json
|
||||
2. Reconcile active_workers with actual tasks.json states
|
||||
3. Remove entries for completed/deleted tasks
|
||||
4. Write updated meta.json
|
||||
5. Update state.md if phase status changed
|
||||
6. Verify consistency
|
||||
7. STOP (wait for next callback)
|
||||
```
|
||||
|
||||
## State Machine Diagram
|
||||
|
||||
```
|
||||
[dispatch] -> PLAN-{N}01 spawned
|
||||
|
|
||||
[planner callback]
|
||||
|
|
||||
plan_check gate? --YES--> request_user_input --> "Revise" --> new PLAN task --> [spawn]
|
||||
| "Skip" --> advanceToNextPhase
|
||||
| "Proceed" / no gate
|
||||
v
|
||||
EXEC-{N}01 spawned
|
||||
|
|
||||
[executor callback]
|
||||
|
|
||||
v
|
||||
VERIFY-{N}01 spawned
|
||||
|
|
||||
[verifier callback]
|
||||
|
|
||||
gaps found? --NO--> advanceToNextPhase
|
||||
|
|
||||
YES + iteration < MAX
|
||||
|
|
||||
v
|
||||
triggerGapClosure:
|
||||
PLAN-{N}02 -> EXEC-{N}02 -> VERIFY-{N}02
|
||||
|
|
||||
[repeat verify check]
|
||||
|
|
||||
gaps found? --NO--> advanceToNextPhase
|
||||
|
|
||||
YES + iteration >= MAX
|
||||
|
|
||||
v
|
||||
request_user_input: "Continue anyway" / "Retry" / "Stop"
|
||||
|
||||
advanceToNextPhase:
|
||||
+- phase < total? --YES--> interactive gate? --> dispatch phase+1 --> [spawn PLAN]
|
||||
+- phase = total? --> handleComplete
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Session file not found | Error, suggest re-initialization |
|
||||
| Worker callback from unknown role | Log info, scan for other completions |
|
||||
| All workers still running on resume | Report status, suggest check later |
|
||||
| Pipeline stall (no ready, no running, has pending) | Check blockedBy chains, report to user |
|
||||
| Verification file missing | Treat as gap -- verifier may have crashed, re-spawn |
|
||||
| Phase dispatch fails | Check roadmap integrity, report to user |
|
||||
| Max gap iterations exceeded | Ask user: continue / retry / stop |
|
||||
| User chooses "Stop" at any gate | Pause session with coordinates, exit cleanly |
|
||||
@@ -0,0 +1,90 @@
|
||||
# Command: pause
|
||||
|
||||
Save session state and exit cleanly. Allows resumption later via resume command.
|
||||
|
||||
## Purpose
|
||||
|
||||
Persist the current execution state (phase, step, pending tasks) to state.md so the session can be resumed from exactly where it stopped. This is the coordinator's mechanism for handling user "Stop" requests at phase boundaries or gap closure gates.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User selects "Stop" at any interactive gate in monitor.md
|
||||
- User requests pause during roadmap discussion
|
||||
- External interruption requires graceful shutdown
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Source | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `sessionFolder` | From coordinator | Session artifact directory |
|
||||
| `currentPhase` | From monitor loop | Phase number at pause time |
|
||||
| `currentStep` | From monitor loop | Step within phase (plan/exec/verify/gap_closure) |
|
||||
| `gapIteration` | From monitor loop | Current gap closure iteration (0 = none) |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Capture Current State
|
||||
|
||||
```javascript
|
||||
const state = Read(`${sessionFolder}/state.md`)
|
||||
const timestamp = new Date().toISOString().slice(0, 19)
|
||||
|
||||
// Capture pending task states from tasks.json
|
||||
const allTasks = JSON.parse(Read(`${sessionFolder}/tasks.json`))
|
||||
const pendingTasks = allTasks.filter(t =>
|
||||
t.status === 'pending' || t.status === 'in_progress'
|
||||
)
|
||||
```
|
||||
|
||||
### Step 2: Update state.md with Pause Marker
|
||||
|
||||
```javascript
|
||||
// Find the current phase status line and update it
|
||||
Edit(`${sessionFolder}/state.md`, {
|
||||
old_string: `- Status: in_progress`,
|
||||
new_string: `- Status: paused
|
||||
- Paused At: ${timestamp}
|
||||
- Paused Phase: ${currentPhase}
|
||||
- Paused Step: ${currentStep}
|
||||
- Gap Iteration: ${gapIteration}
|
||||
- Pending Tasks: ${pendingTasks.map(t => t.subject).join(', ')}`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 3: Log Pause Event
|
||||
|
||||
```javascript
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "coordinator", to: "all",
|
||||
type: "phase_paused",
|
||||
data: { ref: `${sessionFolder}/state.md` }
|
||||
})
|
||||
```
|
||||
|
||||
### Step 4: Report to User
|
||||
|
||||
```javascript
|
||||
// Output pause summary
|
||||
const summary = `[coordinator] Session paused.
|
||||
- Phase: ${currentPhase}
|
||||
- Step: ${currentStep}
|
||||
- Gap Iteration: ${gapIteration}
|
||||
- Pending Tasks: ${pendingTasks.length}
|
||||
|
||||
To resume: Skill(skill="team-roadmap-dev", args="--resume ${sessionFolder}")
|
||||
`
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
| Artifact | Path | Description |
|
||||
|----------|------|-------------|
|
||||
| state.md | `{sessionFolder}/state.md` | Updated with paused status and resume coordinates |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| state.md edit fails | Write full state.md from scratch with pause info |
|
||||
| Task list unavailable | Record phase/step only, skip task listing |
|
||||
@@ -0,0 +1,137 @@
|
||||
# Command: resume
|
||||
|
||||
Resume a paused roadmap-dev session from its saved state. Reads pause coordinates from state.md and re-enters the monitor loop at the exact phase and step where execution was paused.
|
||||
|
||||
## Purpose
|
||||
|
||||
Restore execution context from a paused session and continue the monitor loop. This is the coordinator's mechanism for resuming long-running projects across sessions.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User invokes `Skill(skill="team-roadmap-dev", args="--resume {sessionFolder}")`
|
||||
- Coordinator detects a paused session during init
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Source | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `sessionFolder` | From --resume argument | Session artifact directory to resume |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Validate Session State
|
||||
|
||||
```javascript
|
||||
const stateContent = Read(`${sessionFolder}/state.md`)
|
||||
|
||||
// Check for paused status
|
||||
if (!stateContent.includes('Status: paused')) {
|
||||
// Session is not paused — check if it's in_progress or completed
|
||||
if (stateContent.includes('Status: completed')) {
|
||||
// Session already finished
|
||||
return { error: "Session already completed", sessionFolder }
|
||||
}
|
||||
// Not paused, not completed — treat as fresh continue
|
||||
}
|
||||
|
||||
// Parse resume coordinates
|
||||
const pausedPhase = parseInt(stateContent.match(/Paused Phase: (\d+)/)?.[1] || '1')
|
||||
const pausedStep = stateContent.match(/Paused Step: (\w+)/)?.[1] || 'plan'
|
||||
const gapIteration = parseInt(stateContent.match(/Gap Iteration: (\d+)/)?.[1] || '0')
|
||||
```
|
||||
|
||||
### Step 2: Load Session Context
|
||||
|
||||
```javascript
|
||||
const roadmap = Read(`${sessionFolder}/roadmap.md`)
|
||||
const config = JSON.parse(Read(`${sessionFolder}/config.json`))
|
||||
|
||||
// Load project context
|
||||
const projectTech = JSON.parse(Read('.workflow/project-tech.json'))
|
||||
```
|
||||
|
||||
### Step 3: Update State to In-Progress
|
||||
|
||||
```javascript
|
||||
const timestamp = new Date().toISOString().slice(0, 19)
|
||||
|
||||
Edit(`${sessionFolder}/state.md`, {
|
||||
old_string: `- Status: paused`,
|
||||
new_string: `- Status: in_progress
|
||||
- Resumed At: ${timestamp}
|
||||
- Resumed From Phase: ${pausedPhase}, Step: ${pausedStep}`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 4: Log Resume Event
|
||||
|
||||
```javascript
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "coordinator", to: "all",
|
||||
type: "phase_started",
|
||||
data: { ref: `${sessionFolder}/state.md` }
|
||||
})
|
||||
```
|
||||
|
||||
### Step 5: Re-enter Monitor Loop
|
||||
|
||||
```javascript
|
||||
// Delegate to monitor.md with resume context
|
||||
// monitor.md receives:
|
||||
// - startPhase: pausedPhase (instead of 1)
|
||||
// - startStep: pausedStep (plan/exec/verify/gap_closure)
|
||||
// - gapIteration: gapIteration (for gap closure continuity)
|
||||
|
||||
Read("commands/monitor.md")
|
||||
// Monitor will:
|
||||
// 1. Skip phases before pausedPhase
|
||||
// 2. Within pausedPhase, skip steps before pausedStep
|
||||
// 3. Continue normal execution from that point
|
||||
```
|
||||
|
||||
### Step 6: Determine Resume Entry Point
|
||||
|
||||
```javascript
|
||||
// Map pausedStep to monitor entry point
|
||||
switch (pausedStep) {
|
||||
case 'plan':
|
||||
// Re-dispatch planner for current phase
|
||||
// Check if PLAN task exists and is pending/incomplete
|
||||
break
|
||||
|
||||
case 'exec':
|
||||
// Re-dispatch executor for current phase
|
||||
// Check if EXEC task exists and is pending/incomplete
|
||||
break
|
||||
|
||||
case 'verify':
|
||||
// Re-dispatch verifier for current phase
|
||||
break
|
||||
|
||||
case 'gap_closure':
|
||||
// Re-enter gap closure loop at gapIteration
|
||||
break
|
||||
|
||||
case 'transition':
|
||||
// Phase was complete, proceed to next phase
|
||||
break
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
| Artifact | Path | Description |
|
||||
|----------|------|-------------|
|
||||
| state.md | `{sessionFolder}/state.md` | Updated with resumed status |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Session folder not found | Error with available session list |
|
||||
| state.md missing | Error — session may be corrupted |
|
||||
| Session not paused | Check if in_progress or completed, handle accordingly |
|
||||
| Roadmap.md missing | Error — session artifacts may be incomplete |
|
||||
| config.json missing | Use defaults (mode=interactive, depth=standard) |
|
||||
| Tasks from prior run still pending | Re-use them, don't create duplicates |
|
||||
@@ -0,0 +1,243 @@
|
||||
# Command: roadmap-discuss
|
||||
|
||||
Interactive roadmap discussion with the user. This is the KEY coordinator command -- no work begins until the roadmap is agreed upon.
|
||||
|
||||
## Purpose
|
||||
|
||||
Discuss project roadmap with the user using project-tech.json + specs/*.md as context. Elicit phases, requirements, success criteria, and execution preferences. Produces `roadmap.md` and `config.json` as session artifacts.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 2 of coordinator lifecycle (after init prerequisites, before dispatch)
|
||||
- Called exactly once per session (re-entry updates existing roadmap)
|
||||
|
||||
## Strategy
|
||||
|
||||
Direct interaction via request_user_input. No delegation to workers or CLI tools. Coordinator handles this entirely.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Source | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `sessionFolder` | From coordinator Phase 1 | Session artifact directory |
|
||||
| `taskDescription` | From coordinator Phase 1 | User's original task description |
|
||||
| `projectTech` | Loaded in Phase 1 | Parsed project-tech.json |
|
||||
| `projectGuidelines` | Loaded in Phase 1 | Parsed specs/*.md (nullable) |
|
||||
| `autoYes` | From -y/--yes flag | Skip interactive prompts, use defaults |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Load Project Context
|
||||
|
||||
```javascript
|
||||
// Already loaded by coordinator Phase 1, but verify availability
|
||||
const projectTech = JSON.parse(Read('.workflow/project-tech.json'))
|
||||
let projectGuidelines = null
|
||||
try {
|
||||
projectGuidelines = JSON.parse(Read('.workflow/specs/*.md'))
|
||||
} catch {}
|
||||
```
|
||||
|
||||
### Step 2: Present Project Overview to User
|
||||
|
||||
```javascript
|
||||
// Summarize what we know about the project
|
||||
const overview = `[coordinator] Project context loaded.
|
||||
- Project: ${projectTech.project_name}
|
||||
- Tech Stack: ${projectTech.tech_stack?.join(', ')}
|
||||
- Task: ${taskDescription}
|
||||
${projectGuidelines ? `- Guidelines: ${projectGuidelines.conventions?.length || 0} conventions loaded` : '- Guidelines: not configured'}`
|
||||
|
||||
// Display overview (via direct output, not request_user_input)
|
||||
```
|
||||
|
||||
### Step 3: Confirm Project Goal and Scope
|
||||
|
||||
```javascript
|
||||
// Skip if taskDescription is already detailed enough, or autoYes
|
||||
if (!autoYes && !taskDescription) {
|
||||
request_user_input({
|
||||
prompt: "What is the project goal and scope for this session?"
|
||||
})
|
||||
}
|
||||
// Store response as `projectGoal`
|
||||
const projectGoal = taskDescription || userResponse
|
||||
```
|
||||
|
||||
### Step 4: Ask Execution Mode
|
||||
|
||||
```javascript
|
||||
if (!autoYes) {
|
||||
request_user_input({
|
||||
prompt: "How should phase transitions be handled?\n\nOptions:\n1. interactive - Ask for confirmation at each phase transition\n2. yolo - Auto-execute all phases without stopping\n3. custom - Choose which gates require confirmation"
|
||||
})
|
||||
} else {
|
||||
mode = "yolo"
|
||||
}
|
||||
|
||||
// If "custom" selected, follow up with gate selection:
|
||||
if (mode === "custom") {
|
||||
request_user_input({
|
||||
prompt: "Which gates should require confirmation? (select multiple)\n\n1. plan_check - Review plan before execution\n2. verifier - Review verification results before next phase\n3. gap_closure - Confirm gap closure before re-execution"
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Ask Analysis Depth
|
||||
|
||||
```javascript
|
||||
if (!autoYes) {
|
||||
request_user_input({
|
||||
prompt: "How thorough should the analysis be?\n\nOptions:\n1. quick - Fast scan, minimal context gathering (small tasks)\n2. standard - Balanced analysis with key context (default)\n3. comprehensive - Deep analysis, full codebase exploration (large refactors)"
|
||||
})
|
||||
} else {
|
||||
depth = "standard"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 6: Analyze Codebase and Generate Phased Roadmap
|
||||
|
||||
```javascript
|
||||
// Use Gemini CLI (or CLI exploration tool) to analyze the codebase
|
||||
// and generate a phased breakdown based on goal + project context
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Analyze codebase and generate phased execution roadmap for: ${projectGoal}
|
||||
TASK: \
|
||||
- Scan project structure and identify affected modules \
|
||||
- Break goal into sequential phases (max 5) \
|
||||
- Each phase: goal, requirements (REQ-IDs), success criteria (2-5 testable behaviors) \
|
||||
- Order phases by dependency (foundational first)
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Tech stack: ${projectTech.tech_stack?.join(', ')}
|
||||
EXPECTED: Phased roadmap in markdown with REQ-IDs and testable success criteria
|
||||
CONSTRAINTS: Max 5 phases | Each phase independently verifiable | No implementation details" \
|
||||
--tool gemini --mode analysis --rule planning-breakdown-task-steps`,
|
||||
timeout: 300000
|
||||
})
|
||||
|
||||
// Parse the CLI output into structured phases
|
||||
```
|
||||
|
||||
### Step 7: Present Roadmap Draft for Confirmation
|
||||
|
||||
```javascript
|
||||
// Display the generated roadmap to user
|
||||
// Output the roadmap content directly, then ask for adjustments
|
||||
|
||||
request_user_input({
|
||||
prompt: "Review the roadmap above. Any adjustments needed?\n\nOptions:\n1. Looks good, proceed - Accept roadmap as-is\n2. Adjust phases - I want to modify the phase breakdown\n3. Add requirements - I want to add missing requirements\n4. Change scope - Narrow or expand the scope"
|
||||
})
|
||||
|
||||
// If user requests adjustments, incorporate feedback and re-present
|
||||
// Loop until user confirms "Looks good, proceed"
|
||||
```
|
||||
|
||||
### Step 8: Generate Session Artifacts
|
||||
|
||||
#### roadmap.md
|
||||
|
||||
```javascript
|
||||
Write(`${sessionFolder}/roadmap.md`, roadmapContent)
|
||||
```
|
||||
|
||||
**roadmap.md format**:
|
||||
|
||||
```markdown
|
||||
# Roadmap: {projectGoal}
|
||||
|
||||
Generated: {date}
|
||||
Session: {sessionFolder}
|
||||
Depth: {depth}
|
||||
|
||||
## Phase 1: {phase title}
|
||||
|
||||
**Goal**: {one-line goal}
|
||||
|
||||
**Requirements**:
|
||||
- REQ-101: {requirement description}
|
||||
- REQ-102: {requirement description}
|
||||
|
||||
**Success Criteria**:
|
||||
- [ ] {testable behavior 1}
|
||||
- [ ] {testable behavior 2}
|
||||
- [ ] {testable behavior 3}
|
||||
|
||||
**Plan Count**: TBD
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: {phase title}
|
||||
|
||||
**Goal**: {one-line goal}
|
||||
|
||||
**Requirements**:
|
||||
- REQ-201: {requirement description}
|
||||
|
||||
**Success Criteria**:
|
||||
- [ ] {testable behavior 1}
|
||||
- [ ] {testable behavior 2}
|
||||
|
||||
**Plan Count**: TBD
|
||||
|
||||
---
|
||||
|
||||
(... additional phases ...)
|
||||
```
|
||||
|
||||
**REQ-ID Convention**: `REQ-{phase}{seq}` (e.g., REQ-101 = Phase 1, requirement 1)
|
||||
|
||||
#### config.json
|
||||
|
||||
```javascript
|
||||
Write(`${sessionFolder}/config.json`, JSON.stringify({
|
||||
mode: mode, // "interactive" | "yolo" | "custom"
|
||||
depth: depth, // "quick" | "standard" | "comprehensive"
|
||||
auto_advance: mode === "yolo",
|
||||
gates: {
|
||||
plan_check: mode === "interactive" || (mode === "custom" && customGates.includes("plan_check")),
|
||||
verifier: mode === "interactive" || (mode === "custom" && customGates.includes("verifier")),
|
||||
gap_closure: mode === "interactive" || (mode === "custom" && customGates.includes("gap_closure"))
|
||||
}
|
||||
}, null, 2))
|
||||
```
|
||||
|
||||
**config.json format**:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "interactive",
|
||||
"depth": "standard",
|
||||
"auto_advance": false,
|
||||
"gates": {
|
||||
"plan_check": true,
|
||||
"verifier": true,
|
||||
"gap_closure": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 9: Update state.md
|
||||
|
||||
```javascript
|
||||
Edit(`${sessionFolder}/state.md`, {
|
||||
old_string: "- Phase: 0 (Roadmap Discussion)\n- Status: initializing",
|
||||
new_string: `- Phase: 1\n- Status: ready_to_dispatch\n- Roadmap: confirmed (${phaseCount} phases)\n- Mode: ${mode}\n- Depth: ${depth}`
|
||||
})
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
| Artifact | Path | Description |
|
||||
|----------|------|-------------|
|
||||
| roadmap.md | `{sessionFolder}/roadmap.md` | Phased plan with REQ-IDs and success criteria |
|
||||
| config.json | `{sessionFolder}/config.json` | Execution preferences |
|
||||
| state.md | `{sessionFolder}/state.md` | Updated with phase transition |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| User provides no goal | Re-prompt with examples |
|
||||
| CLI analysis fails | Retry with simpler prompt, or ask user to describe phases manually |
|
||||
| User keeps adjusting roadmap | Max 5 adjustment rounds, then proceed with latest version |
|
||||
| autoYes flag set | Skip all request_user_input calls, use defaults: mode=yolo, depth=standard |
|
||||
303
.codex/skills/team-roadmap-dev/roles/coordinator/role.md
Normal file
303
.codex/skills/team-roadmap-dev/roles/coordinator/role.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# Coordinator Role
|
||||
|
||||
Orchestrate the roadmap-driven development workflow: init prerequisites -> roadmap discussion with user -> phase dispatch -> monitoring -> transitions -> completion. Coordinator is the ONLY role that interacts with humans.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
||||
- **Responsibility**: Orchestration (parse requirements -> discuss roadmap -> create team -> dispatch tasks -> monitor progress -> report results)
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- All outputs must carry `[coordinator]` prefix
|
||||
- Handle ALL human interaction (request_user_input) -- workers never interact with user
|
||||
- Ensure init prerequisites before starting (project-tech.json)
|
||||
- Discuss roadmap with user before dispatching work
|
||||
- Manage state.md updates at every phase transition
|
||||
- Route verifier gap results to planner for closure
|
||||
- Parse user requirements and clarify ambiguous inputs via request_user_input
|
||||
- Create team and spawn worker team members in background
|
||||
- Dispatch tasks with proper dependency chains
|
||||
- Monitor progress via worker callbacks and route messages
|
||||
- Maintain session state persistence
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute any business tasks (code, analysis, testing, verification)
|
||||
- Call CLI tools for code generation, exploration, or planning
|
||||
- Modify source code or generate implementation artifacts
|
||||
- Bypass worker roles to do work directly
|
||||
- Skip roadmap discussion phase
|
||||
- Modify task outputs (workers own their deliverables)
|
||||
- Skip dependency validation when creating task chains
|
||||
|
||||
> **Core principle**: coordinator is the orchestrator, not the executor. All actual work must be delegated to worker roles via tasks.json entries.
|
||||
|
||||
---
|
||||
|
||||
## Command Execution Protocol
|
||||
|
||||
When coordinator needs to execute a command (dispatch, monitor, pause, resume):
|
||||
|
||||
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
|
||||
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
|
||||
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
|
||||
4. **Execute synchronously** -- complete the command workflow before proceeding
|
||||
|
||||
Example:
|
||||
```
|
||||
Phase 3 needs task dispatch
|
||||
-> Read roles/coordinator/commands/dispatch.md
|
||||
-> Execute Phase 2 (Context Loading)
|
||||
-> Execute Phase 3 (Task Chain Creation)
|
||||
-> Execute Phase 4 (Validation)
|
||||
-> Continue to Phase 4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entry Router
|
||||
|
||||
When coordinator is invoked, detect invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains role tag [planner], [executor], [verifier] | -> handleCallback |
|
||||
| Resume mode | Arguments contain `--resume` | -> @commands/resume.md: load session, re-enter monitor |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
|
||||
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
|
||||
| Interrupted session | Active/paused session exists | -> Phase 0 (Session Resume Check) |
|
||||
| New session | None of above | -> Phase 1 (Init Prerequisites) |
|
||||
|
||||
For callback/check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
|
||||
|
||||
### Router Implementation
|
||||
|
||||
1. **Load session context** (if exists):
|
||||
- Scan `.workflow/.team/RD-*/.msg/meta.json` for active/paused sessions
|
||||
- If found, extract session folder path, status, and pipeline mode
|
||||
|
||||
2. **Parse $ARGUMENTS** for detection keywords:
|
||||
- Check for role name tags in message content
|
||||
- Check for "check", "status", "resume", "continue", "--resume" keywords
|
||||
|
||||
3. **Route to handler**:
|
||||
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
|
||||
- For --resume: Read `@commands/resume.md`, execute resume flow
|
||||
- For Phase 0: Execute Session Resume Check
|
||||
- For Phase 1: Execute Init Prerequisites below
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | File | Phase | Description |
|
||||
|---------|------|-------|-------------|
|
||||
| `analyze` | [commands/analyze.md](commands/analyze.md) | Phase 1 | Detect depth/phase-count/gate signals from task description |
|
||||
| `roadmap-discuss` | [commands/roadmap-discuss.md](commands/roadmap-discuss.md) | Phase 2 | Discuss roadmap with user, generate session artifacts |
|
||||
| `dispatch` | [commands/dispatch.md](commands/dispatch.md) | Phase 3 | Create task chain per phase |
|
||||
| `monitor` | [commands/monitor.md](commands/monitor.md) | Phase 4 | Stop-Wait phase execution loop |
|
||||
| `pause` | [commands/pause.md](commands/pause.md) | Any | Save state and exit cleanly |
|
||||
| `resume` | [commands/resume.md](commands/resume.md) | Any | Resume from paused session |
|
||||
|
||||
### Tool Capabilities
|
||||
|
||||
| Tool | Type | Used By | Purpose |
|
||||
|------|------|---------|---------|
|
||||
| `request_user_input` | Human interaction | coordinator | Clarify requirements, roadmap discussion |
|
||||
| Session folder ops | Team management | coordinator | Create roadmap-dev session folder |
|
||||
| `tasks.json` | Task dispatch | coordinator | Create PLAN-*, EXEC-*, VERIFY-* tasks in tasks.json |
|
||||
| `wait_agent` | Worker communication | coordinator | Receive worker results |
|
||||
| `report_agent_job_result` | Worker communication | workers | Report results to coordinator |
|
||||
| `mcp__ccw-tools__team_msg` | Message bus | coordinator | Log all communications |
|
||||
| `Read/Write` | File operations | coordinator | Session state management |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `phase_started` | coordinator -> workers | Phase dispatch | New phase initiated |
|
||||
| `phase_complete` | coordinator -> user | All phase tasks done | Phase results summary |
|
||||
| `gap_closure` | coordinator -> planner | Verifier found gaps | Trigger re-plan for gaps |
|
||||
| `project_complete` | coordinator -> user | All phases done | Final report |
|
||||
| `error` | coordinator -> user | Critical failure | Error report |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every message exchange, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "coordinator",
|
||||
to: <target-role>,
|
||||
type: <message-type>,
|
||||
data: { ref: <artifact-path> }
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --session-id <session-id> --from coordinator --type <type> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Init Prerequisites + Requirement Parsing
|
||||
|
||||
**Objective**: Ensure prerequisites and parse user requirements.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Parse arguments for flags: `--resume`, `--yes`, task description
|
||||
2. If `--resume` present -> load @commands/resume.md and execute resume flow
|
||||
3. Ensure project-tech.json exists:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| `.workflow/project-tech.json` exists | Continue to step 4 |
|
||||
| File not found | Invoke `Skill(skill="workflow:init")` |
|
||||
|
||||
4. Load project context from project-tech.json
|
||||
5. Create session directory: `.workflow/.team/RD-<slug>-<date>/`
|
||||
6. Initialize state.md with project reference, current position, task description
|
||||
|
||||
**Success**: Session directory created, state.md initialized.
|
||||
|
||||
### Phase 2: Roadmap Discussion (via command)
|
||||
|
||||
**Objective**: Discuss roadmap with user and generate phase plan.
|
||||
|
||||
Delegate to `@commands/roadmap-discuss.md`:
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Load commands/roadmap-discuss.md |
|
||||
| 2 | Execute interactive discussion with user |
|
||||
| 3 | Produce roadmap.md with phase requirements |
|
||||
| 4 | Produce config.json with session settings |
|
||||
| 5 | Update state.md with roadmap reference |
|
||||
|
||||
**Produces**: `<session>/roadmap.md`, `<session>/config.json`
|
||||
|
||||
**Command**: [commands/roadmap-discuss.md](commands/roadmap-discuss.md)
|
||||
|
||||
### Phase 3: Create Team + Dispatch First Phase
|
||||
|
||||
**Objective**: Initialize team and dispatch first phase task.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Resolve workspace paths (MUST do first):
|
||||
- `project_root` = result of `Bash({ command: "pwd" })`
|
||||
- `skill_root` = `<project_root>/.claude/skills/team-roadmap-dev`
|
||||
|
||||
2. Create session folder: `.workflow/.team/RD-<slug>-<date>/`
|
||||
|
||||
3. Initialize meta.json with pipeline metadata:
|
||||
```typescript
|
||||
// Use team_msg to write pipeline metadata to .msg/meta.json
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: "<session-id>",
|
||||
from: "coordinator",
|
||||
type: "state_update",
|
||||
summary: "Session initialized",
|
||||
data: {
|
||||
pipeline_mode: "roadmap-driven",
|
||||
pipeline_stages: ["planner", "executor", "verifier"],
|
||||
roles: ["coordinator", "planner", "executor", "verifier"],
|
||||
team_name: "roadmap-dev"
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
4. Spawn worker roles (see SKILL.md Coordinator Spawn Template)
|
||||
5. Load `@commands/dispatch.md` for task chain creation
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Read roadmap.md for phase definitions |
|
||||
| 2 | Create PLAN-101 task entry in tasks.json for first phase |
|
||||
| 3 | Set proper owner and blockedBy dependencies in tasks.json |
|
||||
| 4 | Include `Session: <session-folder>` in task description |
|
||||
|
||||
**Produces**: PLAN-101 task created, workers spawned
|
||||
|
||||
**Command**: [commands/dispatch.md](commands/dispatch.md)
|
||||
|
||||
### Phase 4: Coordination Loop (Stop-Wait per phase)
|
||||
|
||||
**Objective**: Monitor phase execution, handle callbacks, advance pipeline.
|
||||
|
||||
**Design**: Spawn-and-Stop + Callback pattern.
|
||||
- Spawn workers with `spawn_agent()` -> immediately return
|
||||
- Worker completes -> report_agent_job_result() -> coordinator receives via wait_agent() -> auto-advance
|
||||
- User can use "check" / "resume" to manually advance
|
||||
- Coordinator does one operation per invocation, then STOPS
|
||||
|
||||
Delegate to `@commands/monitor.md`:
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Load commands/monitor.md |
|
||||
| 2 | Find tasks with: status=pending, blockedBy all resolved |
|
||||
| 3 | For each ready task -> spawn worker (see SKILL.md Spawn Template) |
|
||||
| 4 | Handle worker callbacks -> advance pipeline |
|
||||
| 5 | Phase complete -> transition to next phase or gap closure |
|
||||
| 6 | STOP after each operation |
|
||||
|
||||
**Pipeline advancement** driven by three wake sources:
|
||||
- Worker callback (automatic) -> handleCallback
|
||||
- User "check" -> handleCheck (status only)
|
||||
- User "resume" -> handleContinue (advance)
|
||||
|
||||
**Command**: [commands/monitor.md](commands/monitor.md)
|
||||
|
||||
### Phase 5: Report + Persist
|
||||
|
||||
**Objective**: Completion report and follow-up options.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Load session state -> count completed tasks, duration |
|
||||
| 2 | List deliverables with output paths |
|
||||
| 3 | Update state.md status -> "completed" |
|
||||
| 4 | Offer next steps via request_user_input |
|
||||
|
||||
**Next step options**:
|
||||
- Submit code (git add + commit)
|
||||
- Continue next milestone (new roadmap discussion)
|
||||
- Complete (end session)
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| project-tech.json missing | Invoke /workflow:spec:setup automatically |
|
||||
| User cancels roadmap discussion | Save session state, exit gracefully |
|
||||
| Planner fails | Retry once, then ask user for guidance |
|
||||
| Executor fails on plan | Mark plan as failed, continue with next |
|
||||
| Verifier finds gaps (<=3 iterations) | Trigger gap closure: re-plan -> re-execute -> re-verify |
|
||||
| Verifier gaps persist (>3 iterations) | Report to user, ask for manual intervention |
|
||||
| Worker timeout | Kill worker, report partial results |
|
||||
| Task timeout | Log, mark failed, ask user to retry or skip |
|
||||
| Worker crash | Respawn worker, reassign task |
|
||||
| Dependency cycle | Detect, report to user, halt |
|
||||
| Invalid mode | Reject with error, ask to clarify |
|
||||
| Session corruption | Attempt recovery, fallback to manual reconciliation |
|
||||
71
.codex/skills/team-roadmap-dev/roles/executor/role.md
Normal file
71
.codex/skills/team-roadmap-dev/roles/executor/role.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
role: executor
|
||||
prefix: EXEC
|
||||
inner_loop: true
|
||||
cli_tools:
|
||||
- gemini --mode write
|
||||
message_types:
|
||||
success: exec_complete
|
||||
progress: exec_progress
|
||||
error: error
|
||||
---
|
||||
|
||||
# Executor
|
||||
|
||||
Wave-based code implementation per phase. Reads IMPL-*.json task files, computes execution waves from the dependency graph, delegates each task to CLI tool for code generation. Produces summary-{IMPL-ID}.md per task.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes |
|
||||
| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
|
||||
| Wisdom | <session>/wisdom/ | No |
|
||||
|
||||
1. Glob `<session>/phase-{N}/.task/IMPL-*.json`, error if none found
|
||||
2. Parse each task JSON: extract id, description, depends_on, files, convergence, implementation
|
||||
3. Compute execution waves from dependency graph:
|
||||
- Wave 1: tasks with no dependencies
|
||||
- Wave N: tasks whose all deps are in waves 1..N-1
|
||||
- Force-assign if circular (break at lowest-numbered task)
|
||||
4. Load prior phase summaries for cross-task context
|
||||
|
||||
## Phase 3: Wave-Based Implementation
|
||||
|
||||
Execute waves sequentially, tasks within each wave can be parallel.
|
||||
|
||||
**Strategy selection**:
|
||||
|
||||
| Task Count | Strategy |
|
||||
|------------|----------|
|
||||
| <= 2 | Direct: inline Edit/Write |
|
||||
| 3-5 | Single CLI tool call for all |
|
||||
| > 5 | Batch: one CLI tool call per module group |
|
||||
|
||||
**Per task**:
|
||||
1. Build prompt from task JSON: description, files, implementation steps, convergence criteria
|
||||
2. Include prior summaries and wisdom as context
|
||||
3. Delegate to CLI tool:
|
||||
```
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Implement task ${taskId}: ${description}
|
||||
TASK: ${implementationSteps}
|
||||
MODE: write
|
||||
CONTEXT: @${files.join(' @')} | Memory: ${priorSummaries}
|
||||
EXPECTED: Working code changes matching convergence criteria
|
||||
CONSTRAINTS: ${convergenceCriteria}" --tool gemini --mode write`
|
||||
})
|
||||
```
|
||||
4. Write `<session>/phase-{N}/summary-{IMPL-ID}.md` with: task ID, affected files, changes made, status
|
||||
|
||||
**Between waves**: report wave progress via team_msg (type: exec_progress)
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| Affected files exist | `test -f <path>` for each file in summary | All present |
|
||||
| TypeScript syntax | `npx tsc --noEmit` (if tsconfig.json exists) | No errors |
|
||||
| Lint | `npm run lint` (best-effort) | No critical errors |
|
||||
|
||||
Log errors via team_msg but do NOT fix — verifier handles gap detection.
|
||||
76
.codex/skills/team-roadmap-dev/roles/planner/role.md
Normal file
76
.codex/skills/team-roadmap-dev/roles/planner/role.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
role: planner
|
||||
prefix: PLAN
|
||||
inner_loop: true
|
||||
cli_tools:
|
||||
- gemini --mode analysis
|
||||
message_types:
|
||||
success: plan_ready
|
||||
progress: plan_progress
|
||||
error: error
|
||||
---
|
||||
|
||||
# Planner
|
||||
|
||||
Research and plan creation per roadmap phase. Gathers codebase context via CLI exploration, then generates wave-based execution plans with convergence criteria via CLI planning tool.
|
||||
|
||||
## Phase 2: Context Loading + Research
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| roadmap.md | <session>/roadmap.md | Yes |
|
||||
| config.json | <session>/config.json | Yes |
|
||||
| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
|
||||
| Wisdom | <session>/wisdom/ | No |
|
||||
|
||||
1. Read roadmap.md, extract phase goal, requirements (REQ-IDs), success criteria
|
||||
2. Read config.json for depth setting (quick/standard/comprehensive)
|
||||
3. Load prior phase summaries for dependency context
|
||||
4. Detect gap closure mode (task description contains "Gap closure")
|
||||
5. Launch CLI exploration with phase requirements as exploration query:
|
||||
```
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Explore codebase for phase requirements
|
||||
TASK: • Identify files needing modification • Map patterns and dependencies • Assess test infrastructure • Identify risks
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Phase goal: ${phaseGoal}
|
||||
EXPECTED: Structured exploration results with file lists, patterns, risks
|
||||
CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis`
|
||||
})
|
||||
```
|
||||
- Target: files needing modification, patterns, dependencies, test infrastructure, risks
|
||||
6. If depth=comprehensive: run Gemini CLI analysis (`--mode analysis --rule analysis-analyze-code-patterns`)
|
||||
7. Write `<session>/phase-{N}/context.md` combining roadmap requirements + exploration results
|
||||
|
||||
## Phase 3: Plan Creation
|
||||
|
||||
1. Load context.md from Phase 2
|
||||
2. Create output directory: `<session>/phase-{N}/.task/`
|
||||
3. Delegate to CLI planning tool with:
|
||||
```
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Generate wave-based execution plan for phase ${phaseNum}
|
||||
TASK: • Break down requirements into tasks • Define convergence criteria • Build dependency graph • Assign waves
|
||||
MODE: write
|
||||
CONTEXT: @${contextMd} | Memory: ${priorSummaries}
|
||||
EXPECTED: IMPL_PLAN.md + IMPL-*.json files + TODO_LIST.md
|
||||
CONSTRAINTS: <= 10 tasks | Valid DAG | Measurable convergence criteria" --tool gemini --mode write`
|
||||
})
|
||||
```
|
||||
4. CLI tool produces: `IMPL_PLAN.md`, `.task/IMPL-*.json`, `TODO_LIST.md`
|
||||
5. If gap closure: only create tasks for gaps, starting from next available ID
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
| Check | Pass Criteria | Action on Failure |
|
||||
|-------|---------------|-------------------|
|
||||
| Task JSON files exist | >= 1 IMPL-*.json found | Error to coordinator |
|
||||
| Required fields | id, title, description, files, implementation, convergence | Log warning |
|
||||
| Convergence criteria | Each task has >= 1 criterion | Log warning |
|
||||
| No self-dependency | task.id not in task.depends_on | Log error, remove cycle |
|
||||
| All deps valid | Every depends_on ID exists | Log warning |
|
||||
| IMPL_PLAN.md exists | File present | Generate minimal version from task JSONs |
|
||||
|
||||
After validation, compute wave structure from dependency graph for reporting:
|
||||
- Wave count = topological layers of DAG
|
||||
- Report: task count, wave count, file list
|
||||
74
.codex/skills/team-roadmap-dev/roles/verifier/role.md
Normal file
74
.codex/skills/team-roadmap-dev/roles/verifier/role.md
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
role: verifier
|
||||
prefix: VERIFY
|
||||
inner_loop: true
|
||||
cli_tools:
|
||||
- gemini --mode analysis
|
||||
message_types:
|
||||
success: verify_passed
|
||||
failure: gaps_found
|
||||
error: error
|
||||
---
|
||||
|
||||
# Verifier
|
||||
|
||||
Goal-backward verification per phase. Reads convergence criteria from IMPL-*.json task files and checks against actual codebase state. Read-only — never modifies code. Produces verification.md with pass/fail and structured gap lists.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes |
|
||||
| Summaries | <session>/phase-{N}/summary-*.md | Yes |
|
||||
| Wisdom | <session>/wisdom/ | No |
|
||||
|
||||
1. Glob IMPL-*.json files, extract convergence criteria from each task
|
||||
2. Glob summary-*.md files, parse frontmatter (task, affects, provides)
|
||||
3. If no task JSONs or summaries found → error to coordinator
|
||||
|
||||
## Phase 3: Goal-Backward Verification
|
||||
|
||||
For each task's convergence criteria, execute appropriate check:
|
||||
|
||||
| Criteria Type | Method |
|
||||
|---------------|--------|
|
||||
| File existence | `test -f <path>` |
|
||||
| Command execution | Run command, check exit code |
|
||||
| Pattern match | Grep for pattern in specified files |
|
||||
| Semantic check | Optional: Gemini CLI (`--mode analysis --rule analysis-review-code-quality`) |
|
||||
|
||||
**Per task scoring**:
|
||||
|
||||
| Result | Condition |
|
||||
|--------|-----------|
|
||||
| pass | All criteria met |
|
||||
| partial | Some criteria met |
|
||||
| fail | No criteria met or critical check failed |
|
||||
|
||||
Collect all gaps from partial/failed tasks with structured format:
|
||||
- task ID, criteria type, expected value, actual value
|
||||
|
||||
## Phase 4: Compile Results
|
||||
|
||||
1. Aggregate per-task results: count passed, partial, failed
|
||||
2. Determine overall status:
|
||||
- `passed` if gaps.length === 0
|
||||
- `gaps_found` otherwise
|
||||
3. Write `<session>/phase-{N}/verification.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
phase: <N>
|
||||
status: passed | gaps_found
|
||||
tasks_checked: <count>
|
||||
tasks_passed: <count>
|
||||
gaps:
|
||||
- task: "<task-id>"
|
||||
type: "<criteria-type>"
|
||||
item: "<description>"
|
||||
expected: "<expected>"
|
||||
actual: "<actual>"
|
||||
---
|
||||
```
|
||||
|
||||
4. Update .msg/meta.json with verification summary
|
||||
Reference in New Issue
Block a user