mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-11 17:21:03 +08:00
62d8aa3623
- Implement tests for AssociationHighlight, DashboardToolbar, QueuePanel, SessionGroupTree, and TerminalDashboardPage to ensure proper functionality and state management. - Create tests for cliSessionStore, issueQueueIntegrationStore, queueExecutionStore, queueSchedulerStore, sessionManagerStore, and terminalGridStore to validate state resets and workspace scoping. - Mock necessary dependencies and state management hooks to isolate tests and ensure accurate behavior.
646 lines
25 KiB
Markdown
646 lines
25 KiB
Markdown
---
|
|
name: team-roadmap-dev
|
|
description: Roadmap-driven development with phased execution pipeline. Coordinator discusses roadmap with user, then executes plan->execute->verify cycles per phase using CSV wave execution.
|
|
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<task-description>\""
|
|
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
---
|
|
|
|
## Auto Mode
|
|
|
|
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
|
|
|
|
# Roadmap-Driven Development
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
$team-roadmap-dev "Build authentication module with JWT tokens"
|
|
$team-roadmap-dev -c 4 "Refactor payment processing to support multiple gateways"
|
|
$team-roadmap-dev -y "Add real-time notifications feature"
|
|
$team-roadmap-dev --continue "RD-auth-module-2026-03-08"
|
|
```
|
|
|
|
**Flags**:
|
|
- `-y, --yes`: Skip all confirmations (auto mode)
|
|
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
|
|
- `--continue`: Resume existing session
|
|
|
|
**Output Directory**: `.workflow/.csv-wave/{session-id}/`
|
|
**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Roadmap-driven development workflow that breaks down complex development tasks into phases, with each phase following a plan->execute->verify cycle. The coordinator discusses the roadmap with the user to establish phases and requirements, then executes each phase systematically using CSV wave execution for parallel task processing.
|
|
|
|
**Execution Model**: Hybrid — CSV wave pipeline (primary) + individual agent spawn (secondary)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ ROADMAP-DRIVEN DEVELOPMENT WORKFLOW │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Phase 0: Roadmap Discussion (Interactive) │
|
|
│ ├─ Discuss requirements and scope with user │
|
|
│ ├─ Break down into logical phases │
|
|
│ ├─ Define success criteria per phase │
|
|
│ └─ Output: roadmap.md with phase definitions │
|
|
│ │
|
|
│ Phase 1: Requirement → CSV + Classification │
|
|
│ ├─ For each roadmap phase: generate plan->execute->verify tasks │
|
|
│ ├─ Classify tasks: csv-wave (execution) | interactive (planning) │
|
|
│ ├─ Compute dependency waves (topological sort → depth grouping) │
|
|
│ ├─ Generate tasks.csv with wave + exec_mode columns │
|
|
│ └─ User validates task breakdown (skip if -y) │
|
|
│ │
|
|
│ Phase 2: Wave Execution Engine (Extended) │
|
|
│ ├─ For each wave (1..N): │
|
|
│ │ ├─ Execute pre-wave interactive tasks (planning) │
|
|
│ │ ├─ Build wave CSV (filter csv-wave tasks for this wave) │
|
|
│ │ ├─ Inject previous findings into prev_context column │
|
|
│ │ ├─ spawn_agents_on_csv(wave CSV) │
|
|
│ │ ├─ Execute post-wave interactive tasks (verification) │
|
|
│ │ ├─ Merge all results into master tasks.csv │
|
|
│ │ └─ Check: any failed? → skip dependents │
|
|
│ └─ discoveries.ndjson shared across all modes (append-only) │
|
|
│ │
|
|
│ Phase 3: Results Aggregation │
|
|
│ ├─ Export final results.csv │
|
|
│ ├─ Generate context.md with all findings │
|
|
│ ├─ Display summary: completed/failed/skipped per wave │
|
|
│ └─ Offer: view results | retry failed | done │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Task Classification Rules
|
|
|
|
Each task is classified by `exec_mode`:
|
|
|
|
| exec_mode | Mechanism | Criteria |
|
|
|-----------|-----------|----------|
|
|
| `csv-wave` | `spawn_agents_on_csv` | One-shot, structured I/O, no multi-round interaction |
|
|
| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round, clarification, inline utility |
|
|
|
|
**Classification Decision**:
|
|
|
|
| Task Property | Classification |
|
|
|---------------|---------------|
|
|
| Planning tasks (research, exploration, plan generation) | `interactive` |
|
|
| Execution tasks (code implementation, file modifications) | `csv-wave` |
|
|
| Verification tasks (testing, validation, gap detection) | `interactive` |
|
|
| Gap closure tasks (re-planning based on verification) | `interactive` |
|
|
|
|
---
|
|
|
|
## CSV Schema
|
|
|
|
### tasks.csv (Master State)
|
|
|
|
```csv
|
|
id,title,description,deps,context_from,exec_mode,phase,role,wave,status,findings,error
|
|
PLAN-101,Phase 1 Planning,Research and plan for authentication module,,,"interactive",1,planner,1,pending,"",""
|
|
EXEC-101,Implement auth routes,Create Express routes for login/logout/register,PLAN-101,PLAN-101,"csv-wave",1,executor,2,pending,"",""
|
|
EXEC-102,Implement JWT middleware,Create JWT token generation and validation,PLAN-101,PLAN-101,"csv-wave",1,executor,2,pending,"",""
|
|
VERIFY-101,Verify Phase 1,Test and validate phase 1 implementation,"EXEC-101;EXEC-102","EXEC-101;EXEC-102","interactive",1,verifier,3,pending,"",""
|
|
```
|
|
|
|
**Columns**:
|
|
|
|
| Column | Phase | Description |
|
|
|--------|-------|-------------|
|
|
| `id` | Input | Unique task identifier (string) |
|
|
| `title` | Input | Short task title |
|
|
| `description` | Input | Detailed task description |
|
|
| `deps` | Input | Semicolon-separated dependency task IDs |
|
|
| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
|
|
| `exec_mode` | Input | `csv-wave` or `interactive` |
|
|
| `phase` | Input | Phase number (1-based) |
|
|
| `role` | Input | Role name: planner, executor, verifier |
|
|
| `wave` | Computed | Wave number (computed by topological sort, 1-based) |
|
|
| `status` | Output | `pending` → `completed` / `failed` / `skipped` |
|
|
| `findings` | Output | Key discoveries or implementation notes (max 500 chars) |
|
|
| `error` | Output | Error message if failed (empty if success) |
|
|
|
|
### Per-Wave CSV (Temporary)
|
|
|
|
Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only).
|
|
|
|
---
|
|
|
|
## Agent Registry (Interactive Agents)
|
|
|
|
| Agent | Role File | Pattern | Responsibility | Position |
|
|
|-------|-----------|---------|----------------|----------|
|
|
| roadmap-discusser | ~/.codex/agents/roadmap-discusser.md | 2.3 | Discuss roadmap with user, generate phase plan | pre-wave (Phase 0) |
|
|
| planner | ~/.codex/agents/roadmap-planner.md | 2.4 | Research and plan creation per phase | pre-wave (per phase) |
|
|
| verifier | ~/.codex/agents/roadmap-verifier.md | 2.4 | Test and validate phase implementation | post-wave (per phase) |
|
|
|
|
> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.
|
|
|
|
---
|
|
|
|
## Output Artifacts
|
|
|
|
| File | Purpose | Lifecycle |
|
|
|------|---------|-----------|
|
|
| `tasks.csv` | Master state — all tasks with status/findings | Updated after each wave |
|
|
| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after |
|
|
| `results.csv` | Final export of all task results | Created in Phase 3 |
|
|
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
|
|
| `context.md` | Human-readable execution report | Created in Phase 3 |
|
|
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
|
|
| `agents/registry.json` | Active interactive agent tracking | Updated on spawn/close |
|
|
| `roadmap.md` | Phase definitions and requirements | Created in Phase 0 |
|
|
| `phase-{N}/IMPL_PLAN.md` | Implementation plan per phase | Created by planner |
|
|
| `phase-{N}/verification.md` | Verification results per phase | Created by verifier |
|
|
|
|
---
|
|
|
|
## Session Structure
|
|
|
|
```
|
|
.workflow/.csv-wave/{session-id}/
|
|
├── tasks.csv # Master state (all tasks, both modes)
|
|
├── results.csv # Final results export
|
|
├── discoveries.ndjson # Shared discovery board (all agents)
|
|
├── context.md # Human-readable report
|
|
├── roadmap.md # Phase definitions
|
|
├── wave-{N}.csv # Temporary per-wave input (csv-wave only)
|
|
├── interactive/ # Interactive task artifacts
|
|
│ ├── {id}-result.json # Per-task results
|
|
│ └── cache-index.json # Shared exploration cache
|
|
├── agents/
|
|
│ └── registry.json # Active interactive agent tracking
|
|
└── phase-{N}/ # Per-phase artifacts
|
|
├── IMPL_PLAN.md
|
|
├── TODO_LIST.md
|
|
├── .task/IMPL-*.json
|
|
└── verification.md
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation
|
|
|
|
### Session Initialization
|
|
|
|
```javascript
|
|
// Parse arguments
|
|
const args = parseArguments($ARGUMENTS)
|
|
const autoYes = args.yes || args.y
|
|
const concurrency = args.concurrency || args.c || 3
|
|
const continueMode = args.continue
|
|
const taskDescription = args._[0]
|
|
|
|
// Generate session ID
|
|
const slug = taskDescription.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
|
|
const date = new Date().toISOString().split('T')[0]
|
|
const sessionId = `RD-${slug}-${date}`
|
|
const sessionDir = `.workflow/.csv-wave/${sessionId}`
|
|
|
|
// Create session structure
|
|
Bash(`mkdir -p "${sessionDir}/interactive" "${sessionDir}/agents" "${sessionDir}/phase-1"`)
|
|
|
|
// Initialize registry
|
|
Write(`${sessionDir}/agents/registry.json`, JSON.stringify({
|
|
active: [],
|
|
closed: [],
|
|
created_at: new Date().toISOString()
|
|
}, null, 2))
|
|
|
|
// Initialize discoveries
|
|
Write(`${sessionDir}/discoveries.ndjson`, '')
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 0: Roadmap Discussion (Interactive)
|
|
|
|
**Objective**: Discuss roadmap with user and generate phase plan with requirements and success criteria.
|
|
|
|
```javascript
|
|
// Spawn roadmap discusser
|
|
const discusser = spawn_agent({
|
|
message: `### MANDATORY FIRST STEPS
|
|
1. Read: ~/.codex/agents/roadmap-discusser.md
|
|
|
|
---
|
|
|
|
## Task Assignment
|
|
|
|
**Goal**: Discuss roadmap with user and generate phase plan
|
|
|
|
**Task Description**: ${taskDescription}
|
|
|
|
**Session Directory**: ${sessionDir}
|
|
|
|
**Deliverables**:
|
|
- roadmap.md with phase definitions, requirements, and success criteria
|
|
- Each phase should have: phase number, goal, requirements (REQ-IDs), success criteria
|
|
|
|
**Instructions**:
|
|
1. Analyze task description to understand scope
|
|
2. Propose phase breakdown to user via AskUserQuestion
|
|
3. For each phase, clarify requirements and success criteria
|
|
4. Generate roadmap.md with structured phase definitions
|
|
5. Output result as JSON with roadmap_path and phase_count`
|
|
})
|
|
|
|
// Wait for completion
|
|
const result = wait({ ids: [discusser], timeout_ms: 600000 })
|
|
|
|
if (result.timed_out) {
|
|
send_input({ id: discusser, message: "Please finalize roadmap and output current plan." })
|
|
const retry = wait({ ids: [discusser], timeout_ms: 120000 })
|
|
}
|
|
|
|
// Store result
|
|
const discusserOutput = JSON.parse(result.output)
|
|
Write(`${sessionDir}/interactive/DISCUSS-001-result.json`, JSON.stringify({
|
|
task_id: "DISCUSS-001",
|
|
status: "completed",
|
|
findings: discusserOutput.summary,
|
|
roadmap_path: discusserOutput.roadmap_path,
|
|
phase_count: discusserOutput.phase_count,
|
|
timestamp: new Date().toISOString()
|
|
}, null, 2))
|
|
|
|
close_agent({ id: discusser })
|
|
|
|
// Load roadmap
|
|
const roadmap = Read(discusserOutput.roadmap_path)
|
|
const phases = parsePhases(roadmap)
|
|
```
|
|
|
|
**Success Criteria**:
|
|
- roadmap.md created with phase definitions
|
|
- Each phase has clear requirements and success criteria
|
|
- User approved phase breakdown
|
|
|
|
---
|
|
|
|
### Phase 1: Requirement → CSV + Classification
|
|
|
|
**Objective**: Generate task breakdown from roadmap phases, classify by exec_mode, compute waves.
|
|
|
|
```javascript
|
|
// Read roadmap
|
|
const roadmapContent = Read(`${sessionDir}/roadmap.md`)
|
|
const phases = parseRoadmapPhases(roadmapContent)
|
|
|
|
// Generate tasks for all phases
|
|
const allTasks = []
|
|
let taskCounter = 1
|
|
|
|
for (const phase of phases) {
|
|
const phaseNum = phase.number
|
|
|
|
// Planning task (interactive, pre-wave)
|
|
allTasks.push({
|
|
id: `PLAN-${phaseNum}01`,
|
|
title: `Phase ${phaseNum} Planning`,
|
|
description: `Research and plan for: ${phase.goal}\n\nRequirements:\n${phase.requirements.join('\n')}\n\nSuccess Criteria:\n${phase.success_criteria.join('\n')}`,
|
|
deps: phaseNum > 1 ? `VERIFY-${phaseNum-1}01` : "",
|
|
context_from: phaseNum > 1 ? `VERIFY-${phaseNum-1}01` : "",
|
|
exec_mode: "interactive",
|
|
phase: phaseNum,
|
|
role: "planner",
|
|
wave: 0, // Computed later
|
|
status: "pending",
|
|
findings: "",
|
|
error: ""
|
|
})
|
|
|
|
// Execution tasks (csv-wave) - will be generated by planner
|
|
// Placeholder: planner will create EXEC-{phaseNum}01, EXEC-{phaseNum}02, etc.
|
|
|
|
// Verification task (interactive, post-wave)
|
|
allTasks.push({
|
|
id: `VERIFY-${phaseNum}01`,
|
|
title: `Phase ${phaseNum} Verification`,
|
|
description: `Test and validate phase ${phaseNum} implementation against success criteria:\n${phase.success_criteria.join('\n')}`,
|
|
deps: `PLAN-${phaseNum}01`, // Will be updated after execution tasks created
|
|
context_from: `PLAN-${phaseNum}01`, // Will be updated
|
|
exec_mode: "interactive",
|
|
phase: phaseNum,
|
|
role: "verifier",
|
|
wave: 0, // Computed later
|
|
status: "pending",
|
|
findings: "",
|
|
error: ""
|
|
})
|
|
}
|
|
|
|
// Compute waves via topological sort
|
|
const tasksWithWaves = computeWaves(allTasks)
|
|
|
|
// Write master CSV
|
|
writeMasterCSV(`${sessionDir}/tasks.csv`, tasksWithWaves)
|
|
|
|
// User validation (skip if autoYes)
|
|
if (!autoYes) {
|
|
const approval = AskUserQuestion({
|
|
questions: [{
|
|
question: `Generated ${tasksWithWaves.length} tasks across ${phases.length} phases. Proceed?`,
|
|
header: "Task Breakdown Validation",
|
|
multiSelect: false,
|
|
options: [
|
|
{ label: "Proceed", description: "Start execution" },
|
|
{ label: "Cancel", description: "Abort workflow" }
|
|
]
|
|
}]
|
|
})
|
|
|
|
if (approval.answers[0] !== "Proceed") {
|
|
throw new Error("User cancelled workflow")
|
|
}
|
|
}
|
|
```
|
|
|
|
**Success Criteria**:
|
|
- tasks.csv created with valid schema, wave, and exec_mode assignments
|
|
- No circular dependencies
|
|
- User approved (or AUTO_YES)
|
|
|
|
---
|
|
|
|
### Phase 2: Wave Execution Engine (Extended)
|
|
|
|
**Objective**: Execute tasks wave-by-wave with hybrid mechanism support and cross-wave context propagation.
|
|
|
|
```javascript
|
|
// Load master CSV
|
|
const masterCSV = readMasterCSV(`${sessionDir}/tasks.csv`)
|
|
const maxWave = Math.max(...masterCSV.map(t => t.wave))
|
|
|
|
for (let waveNum = 1; waveNum <= maxWave; waveNum++) {
|
|
console.log(`\n=== Executing Wave ${waveNum} ===\n`)
|
|
|
|
// Get tasks for this wave
|
|
const waveTasks = masterCSV.filter(t => t.wave === waveNum && t.status === 'pending')
|
|
|
|
// Separate by exec_mode
|
|
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
|
|
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
|
|
|
|
// Execute pre-wave interactive tasks (planners)
|
|
for (const task of interactiveTasks.filter(t => t.role === 'planner')) {
|
|
const agent = spawn_agent({
|
|
message: buildPlannerPrompt(task, sessionDir)
|
|
})
|
|
|
|
const result = wait({ ids: [agent], timeout_ms: 600000 })
|
|
|
|
if (result.timed_out) {
|
|
send_input({ id: agent, message: "Please finalize plan and output current results." })
|
|
const retry = wait({ ids: [agent], timeout_ms: 120000 })
|
|
}
|
|
|
|
// Store result
|
|
Write(`${sessionDir}/interactive/${task.id}-result.json`, JSON.stringify({
|
|
task_id: task.id,
|
|
status: "completed",
|
|
findings: parseFindings(result),
|
|
timestamp: new Date().toISOString()
|
|
}, null, 2))
|
|
|
|
close_agent({ id: agent })
|
|
|
|
// Update master CSV
|
|
updateTaskStatus(masterCSV, task.id, "completed", parseFindings(result))
|
|
|
|
// Planner generates execution tasks - read and add to master CSV
|
|
const planTasks = readPlanTasks(`${sessionDir}/phase-${task.phase}/.task/`)
|
|
for (const planTask of planTasks) {
|
|
masterCSV.push({
|
|
id: planTask.id,
|
|
title: planTask.title,
|
|
description: planTask.description,
|
|
deps: task.id,
|
|
context_from: task.id,
|
|
exec_mode: "csv-wave",
|
|
phase: task.phase,
|
|
role: "executor",
|
|
wave: waveNum + 1, // Next wave
|
|
status: "pending",
|
|
findings: "",
|
|
error: ""
|
|
})
|
|
}
|
|
}
|
|
|
|
// Build wave CSV for csv-wave tasks
|
|
if (csvTasks.length > 0) {
|
|
const waveCSV = buildWaveCSV(csvTasks, masterCSV, sessionDir)
|
|
const waveCSVPath = `${sessionDir}/wave-${waveNum}.csv`
|
|
writeWaveCSV(waveCSVPath, waveCSV)
|
|
|
|
// Execute CSV wave
|
|
spawn_agents_on_csv({
|
|
csv_file_path: waveCSVPath,
|
|
instruction_file_path: `${sessionDir}/../instructions/executor-instruction.md`,
|
|
concurrency: concurrency
|
|
})
|
|
|
|
// Merge results back to master CSV
|
|
const waveResults = readWaveCSV(waveCSVPath)
|
|
for (const result of waveResults) {
|
|
updateTaskStatus(masterCSV, result.id, result.status, result.findings, result.error)
|
|
}
|
|
|
|
// Cleanup temp wave CSV
|
|
Bash(`rm "${waveCSVPath}"`)
|
|
}
|
|
|
|
// Execute post-wave interactive tasks (verifiers)
|
|
for (const task of interactiveTasks.filter(t => t.role === 'verifier')) {
|
|
const agent = spawn_agent({
|
|
message: buildVerifierPrompt(task, sessionDir, masterCSV)
|
|
})
|
|
|
|
const result = wait({ ids: [agent], timeout_ms: 600000 })
|
|
|
|
if (result.timed_out) {
|
|
send_input({ id: agent, message: "Please finalize verification and output current results." })
|
|
const retry = wait({ ids: [agent], timeout_ms: 120000 })
|
|
}
|
|
|
|
// Store result
|
|
const verificationResult = JSON.parse(result.output)
|
|
Write(`${sessionDir}/interactive/${task.id}-result.json`, JSON.stringify({
|
|
task_id: task.id,
|
|
status: "completed",
|
|
findings: verificationResult.summary,
|
|
gaps_found: verificationResult.gaps || [],
|
|
timestamp: new Date().toISOString()
|
|
}, null, 2))
|
|
|
|
close_agent({ id: agent })
|
|
|
|
// Update master CSV
|
|
updateTaskStatus(masterCSV, task.id, "completed", verificationResult.summary)
|
|
|
|
// Handle gaps (max 3 iterations)
|
|
if (verificationResult.gaps && verificationResult.gaps.length > 0) {
|
|
const gapIteration = countGapIterations(masterCSV, task.phase)
|
|
if (gapIteration < 3) {
|
|
// Create gap closure tasks
|
|
const gapTasks = createGapClosureTasks(verificationResult.gaps, task.phase, gapIteration)
|
|
masterCSV.push(...gapTasks)
|
|
} else {
|
|
console.log(`[WARNING] Max gap iterations (3) reached for phase ${task.phase}`)
|
|
}
|
|
}
|
|
}
|
|
|
|
// Write updated master CSV
|
|
writeMasterCSV(`${sessionDir}/tasks.csv`, masterCSV)
|
|
|
|
// Check for failures and skip dependents
|
|
const failedTasks = waveTasks.filter(t => t.status === 'failed')
|
|
if (failedTasks.length > 0) {
|
|
skipDependentTasks(masterCSV, failedTasks.map(t => t.id))
|
|
}
|
|
}
|
|
```
|
|
|
|
**Success Criteria**:
|
|
- All waves executed in order
|
|
- Both csv-wave and interactive tasks handled per wave
|
|
- Each wave's results merged into master CSV before next wave starts
|
|
- Dependent tasks skipped when predecessor failed
|
|
- discoveries.ndjson accumulated across all waves and mechanisms
|
|
- Interactive agent lifecycle tracked in registry.json
|
|
|
|
---
|
|
|
|
### Phase 3: Results Aggregation
|
|
|
|
**Objective**: Generate final results and human-readable report.
|
|
|
|
```javascript
|
|
// Load final master CSV
|
|
const finalCSV = readMasterCSV(`${sessionDir}/tasks.csv`)
|
|
|
|
// Export results.csv
|
|
writeFinalResults(`${sessionDir}/results.csv`, finalCSV)
|
|
|
|
// Generate context.md
|
|
const contextMd = generateContextReport(finalCSV, sessionDir)
|
|
Write(`${sessionDir}/context.md`, contextMd)
|
|
|
|
// Cleanup active agents
|
|
const registry = JSON.parse(Read(`${sessionDir}/agents/registry.json`))
|
|
for (const agent of registry.active) {
|
|
close_agent({ id: agent.id })
|
|
}
|
|
registry.active = []
|
|
Write(`${sessionDir}/agents/registry.json`, JSON.stringify(registry, null, 2))
|
|
|
|
// Display summary
|
|
const completed = finalCSV.filter(t => t.status === 'completed').length
|
|
const failed = finalCSV.filter(t => t.status === 'failed').length
|
|
const skipped = finalCSV.filter(t => t.status === 'skipped').length
|
|
|
|
console.log(`\n=== Roadmap Development Complete ===`)
|
|
console.log(`Completed: ${completed}`)
|
|
console.log(`Failed: ${failed}`)
|
|
console.log(`Skipped: ${skipped}`)
|
|
console.log(`\nResults: ${sessionDir}/results.csv`)
|
|
console.log(`Report: ${sessionDir}/context.md`)
|
|
|
|
// Offer next steps
|
|
const nextStep = AskUserQuestion({
|
|
questions: [{
|
|
question: "Roadmap Dev pipeline complete. What would you like to do?",
|
|
header: "Completion",
|
|
multiSelect: false,
|
|
options: [
|
|
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
|
|
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
|
|
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
|
|
]
|
|
}]
|
|
})
|
|
|
|
if (nextStep.answers[0] === "Archive & Clean (Recommended)") {
|
|
Bash(`tar -czf "${sessionDir}.tar.gz" "${sessionDir}" && rm -rf "${sessionDir}"`)
|
|
console.log(`Session archived to ${sessionDir}.tar.gz`)
|
|
}
|
|
```
|
|
|
|
**Success Criteria**:
|
|
- results.csv exported (all tasks, both modes)
|
|
- context.md generated
|
|
- All interactive agents closed (registry.json cleanup)
|
|
- Summary displayed to user
|
|
|
|
---
|
|
|
|
## Shared Discovery Board Protocol
|
|
|
|
All agents (both csv-wave and interactive) share a single `discoveries.ndjson` file for exploration findings.
|
|
|
|
**Discovery Types**:
|
|
|
|
| Type | Dedup Key | Data Schema | Description |
|
|
|------|-----------|-------------|-------------|
|
|
| `file_pattern` | `pattern` | `{pattern, files[], description}` | Code patterns discovered |
|
|
| `dependency` | `from+to` | `{from, to, type}` | Module dependencies |
|
|
| `risk` | `description` | `{description, severity, mitigation}` | Implementation risks |
|
|
| `test_gap` | `area` | `{area, description, priority}` | Testing gaps |
|
|
|
|
**Write Protocol**:
|
|
|
|
```bash
|
|
echo '{"ts":"2026-03-08T14:30:22Z","worker":"EXEC-101","type":"file_pattern","data":{"pattern":"auth middleware","files":["src/middleware/auth.ts"],"description":"JWT validation pattern"}}' >> ${sessionDir}/discoveries.ndjson
|
|
```
|
|
|
|
**Read Protocol**:
|
|
|
|
```javascript
|
|
const discoveries = Read(`${sessionDir}/discoveries.ndjson`)
|
|
.split('\n')
|
|
.filter(line => line.trim())
|
|
.map(line => JSON.parse(line))
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
| Error | Resolution |
|
|
|-------|------------|
|
|
| Circular dependency | Detect in wave computation, abort with error message |
|
|
| CSV agent timeout | Mark as failed in results, continue with wave |
|
|
| CSV agent failed | Mark as failed, skip dependent tasks in later waves |
|
|
| Interactive agent timeout | Urge convergence via send_input, then close if still timed out |
|
|
| Interactive agent failed | Mark as failed, skip dependents |
|
|
| Pre-wave interactive failed | Skip dependent csv-wave tasks in same wave |
|
|
| All agents in wave failed | Log error, offer retry or abort |
|
|
| CSV parse error | Validate CSV format before execution, show line number |
|
|
| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries |
|
|
| Lifecycle leak | Cleanup all active agents via registry.json at end |
|
|
| Continue mode: no session found | List available sessions, prompt user to select |
|
|
| project-tech.json missing | Invoke workflow:init skill |
|
|
| Verifier gaps persist (>3 iterations) | Report to user, ask for manual intervention |
|
|
|
|
---
|
|
|
|
## Core Rules
|
|
|
|
1. **Start Immediately**: First action is session initialization, then Phase 0
|
|
2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged
|
|
3. **CSV is Source of Truth**: Master tasks.csv holds all state (both csv-wave and interactive)
|
|
4. **CSV First**: Default to csv-wave for tasks; only use interactive when interaction pattern requires it
|
|
5. **Context Propagation**: prev_context built from master CSV, not from memory
|
|
6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson — both mechanisms share it
|
|
7. **Skip on Failure**: If a dependency failed, skip the dependent task (regardless of mechanism)
|
|
8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent (tracked in registry.json)
|
|
9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
|
|
10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
|