mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-11 17:21:03 +08:00
Add unit tests for various components and stores in the terminal dashboard
- 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.
This commit is contained in:
catlog22
645
.codex/skills/team-roadmap-dev/SKILL.md
Normal file
645
.codex/skills/team-roadmap-dev/SKILL.md
Normal file
@@ -0,0 +1,645 @@
|
||||
---
|
||||
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
|
||||
176
.codex/skills/team-roadmap-dev/agents/roadmap-discusser.md
Normal file
176
.codex/skills/team-roadmap-dev/agents/roadmap-discusser.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# Roadmap Discusser Agent
|
||||
|
||||
Interactive agent for discussing roadmap with user and generating phase plan with requirements and success criteria.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Role File**: `~/.codex/agents/roadmap-discusser.md`
|
||||
- **Responsibility**: Roadmap discussion and phase planning
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Produce structured output following template
|
||||
- Interact with user via AskUserQuestion
|
||||
- Generate roadmap.md with phase definitions
|
||||
- Include requirements (REQ-IDs) and success criteria per phase
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Produce unstructured output
|
||||
- Execute implementation tasks
|
||||
- Skip user interaction
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `AskUserQuestion` | Human interaction | Clarify requirements, propose phase breakdown |
|
||||
| `Read` | File I/O | Load project context |
|
||||
| `Write` | File I/O | Generate roadmap.md |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Requirement Analysis
|
||||
|
||||
**Objective**: Analyze task description and understand scope.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Task description | Yes | User's task description from arguments |
|
||||
| .workflow/project-tech.json | No | Project context if available |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read task description from spawn message
|
||||
2. Load project context if available
|
||||
3. Identify key requirements and scope
|
||||
4. Detect complexity signals (multi-module, cross-cutting, integration)
|
||||
|
||||
**Output**: Requirement analysis summary
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Phase Breakdown Proposal
|
||||
|
||||
**Objective**: Propose logical phase breakdown to user.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Requirement analysis | Yes | From Phase 1 |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Analyze requirements to identify logical phases
|
||||
2. Propose phase breakdown (typically 2-5 phases)
|
||||
3. For each phase, draft:
|
||||
- Phase goal (one sentence)
|
||||
- Key requirements (REQ-IDs)
|
||||
- Success criteria (measurable)
|
||||
4. Present to user via AskUserQuestion:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Proposed phase breakdown:\n\nPhase 1: [goal]\n- REQ-001: [requirement]\n- Success: [criteria]\n\nPhase 2: [goal]\n...\n\nApprove or request changes?",
|
||||
header: "Roadmap Discussion",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Approve", description: "Proceed with this breakdown" },
|
||||
{ label: "Modify", description: "Request changes to phases" },
|
||||
{ label: "Cancel", description: "Abort workflow" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
5. If user requests modifications, iterate on phase breakdown
|
||||
|
||||
**Output**: User-approved phase breakdown
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Roadmap Generation
|
||||
|
||||
**Objective**: Generate roadmap.md with structured phase definitions.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Approved phase breakdown | Yes | From Phase 2 |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Format roadmap.md with structure:
|
||||
```markdown
|
||||
# Roadmap: [Task Title]
|
||||
|
||||
## Overview
|
||||
[Task description and scope]
|
||||
|
||||
## Phase 1: [Phase Goal]
|
||||
|
||||
### Requirements
|
||||
- REQ-101: [Requirement description]
|
||||
- REQ-102: [Requirement description]
|
||||
|
||||
### Success Criteria
|
||||
- [Measurable criterion 1]
|
||||
- [Measurable criterion 2]
|
||||
|
||||
## Phase 2: [Phase Goal]
|
||||
...
|
||||
```
|
||||
2. Write roadmap.md to session directory
|
||||
3. Prepare output JSON with roadmap path and phase count
|
||||
|
||||
**Output**: roadmap.md file + JSON result
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- Generated roadmap with [N] phases for [task description]
|
||||
|
||||
## Findings
|
||||
- Phase breakdown approved by user
|
||||
- [N] phases defined with requirements and success criteria
|
||||
- Roadmap written to: [path]
|
||||
|
||||
## Deliverables
|
||||
- File: [session]/roadmap.md
|
||||
Content: Phase definitions with REQ-IDs and success criteria
|
||||
|
||||
## Output JSON
|
||||
{
|
||||
"roadmap_path": "[session]/roadmap.md",
|
||||
"phase_count": [N],
|
||||
"summary": "Generated roadmap with [N] phases"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| User cancels | Output partial roadmap, mark as cancelled |
|
||||
| Project context not found | Continue without project context, note in findings |
|
||||
| User requests too many phases (>10) | Warn about complexity, suggest consolidation |
|
||||
| Ambiguous requirements | Ask clarifying questions via AskUserQuestion |
|
||||
194
.codex/skills/team-roadmap-dev/agents/roadmap-planner.md
Normal file
194
.codex/skills/team-roadmap-dev/agents/roadmap-planner.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# Roadmap Planner Agent
|
||||
|
||||
Interactive agent for research and plan creation per roadmap phase. Gathers codebase context via CLI exploration, then generates wave-based execution plans.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Role File**: `~/.codex/agents/roadmap-planner.md`
|
||||
- **Responsibility**: Phase planning and task decomposition
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Produce structured output following template
|
||||
- Use CLI tools for codebase exploration
|
||||
- Generate IMPL_PLAN.md and task JSON files
|
||||
- Define convergence criteria per task
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Execute implementation tasks
|
||||
- Skip CLI exploration step
|
||||
- Generate tasks without convergence criteria
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `Bash` | CLI execution | Run ccw cli for exploration and planning |
|
||||
| `Read` | File I/O | Load roadmap, context, prior summaries |
|
||||
| `Write` | File I/O | Generate plan artifacts |
|
||||
| `Glob` | File search | Find relevant files |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Context Loading
|
||||
|
||||
**Objective**: Load phase requirements and prior context.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| roadmap.md | Yes | Phase definitions from session |
|
||||
| config.json | Yes | Session configuration |
|
||||
| Prior summaries | No | Previous phase results |
|
||||
| discoveries.ndjson | No | Shared exploration findings |
|
||||
|
||||
**Steps**:
|
||||
|
||||
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")
|
||||
|
||||
**Output**: Phase context loaded
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Codebase Exploration
|
||||
|
||||
**Objective**: Explore codebase to understand implementation context.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Phase requirements | Yes | From Phase 1 |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Launch CLI exploration with phase requirements:
|
||||
```bash
|
||||
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
|
||||
```
|
||||
2. Wait for CLI completion (run_in_background: false)
|
||||
3. Parse exploration results
|
||||
4. Write context.md combining roadmap requirements + exploration results
|
||||
|
||||
**Output**: context.md with exploration findings
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Plan Generation
|
||||
|
||||
**Objective**: Generate wave-based execution plan with task breakdown.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| context.md | Yes | From Phase 2 |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Load context.md
|
||||
2. Create output directory: phase-{N}/.task/
|
||||
3. Delegate to CLI planning tool:
|
||||
```bash
|
||||
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. Wait for CLI completion
|
||||
5. CLI tool produces: IMPL_PLAN.md, .task/IMPL-*.json, TODO_LIST.md
|
||||
6. If gap closure: only create tasks for gaps, starting from next available ID
|
||||
|
||||
**Output**: IMPL_PLAN.md + task JSON files
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Self-Validation
|
||||
|
||||
**Objective**: Validate generated plan for completeness and correctness.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| IMPL_PLAN.md | Yes | From Phase 3 |
|
||||
| .task/IMPL-*.json | Yes | Task definitions |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Check task JSON files exist (>= 1 IMPL-*.json found)
|
||||
2. Validate required fields: id, title, description, files, implementation, convergence
|
||||
3. Check convergence criteria (each task has >= 1 criterion)
|
||||
4. Validate no self-dependency (task.id not in task.depends_on)
|
||||
5. Validate all deps valid (every depends_on ID exists)
|
||||
6. Check IMPL_PLAN.md exists (generate minimal version if missing)
|
||||
7. Compute wave structure from dependency graph for reporting
|
||||
|
||||
**Output**: Validation report + wave structure
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- Generated implementation plan for phase {phase} with {N} tasks across {M} waves
|
||||
|
||||
## Findings
|
||||
- Exploration identified {X} files needing modification
|
||||
- Key patterns: [pattern list]
|
||||
- Risks: [risk list]
|
||||
- Task breakdown validated with no circular dependencies
|
||||
|
||||
## Deliverables
|
||||
- File: phase-{N}/IMPL_PLAN.md
|
||||
Content: Wave-based execution plan
|
||||
- File: phase-{N}/.task/IMPL-*.json
|
||||
Content: Task definitions with convergence criteria
|
||||
- File: phase-{N}/TODO_LIST.md
|
||||
Content: Task checklist
|
||||
|
||||
## Output JSON
|
||||
{
|
||||
"plan_path": "phase-{N}/IMPL_PLAN.md",
|
||||
"task_count": {N},
|
||||
"wave_count": {M},
|
||||
"files_affected": [file list],
|
||||
"summary": "Generated plan with {N} tasks"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| CLI exploration fails | Use fallback file search, note limitation |
|
||||
| CLI planning fails | Generate minimal plan manually, warn user |
|
||||
| Circular dependency detected | Remove cycle, log warning |
|
||||
| No convergence criteria | Add default criteria, log warning |
|
||||
| Task count exceeds 10 | Consolidate tasks, warn about complexity |
|
||||
221
.codex/skills/team-roadmap-dev/agents/roadmap-verifier.md
Normal file
221
.codex/skills/team-roadmap-dev/agents/roadmap-verifier.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# Roadmap Verifier Agent
|
||||
|
||||
Interactive agent for testing and validating phase implementation against success criteria. Identifies gaps and triggers gap closure if needed.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Role File**: `~/.codex/agents/roadmap-verifier.md`
|
||||
- **Responsibility**: Phase verification and gap detection
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Produce structured output following template
|
||||
- Test implementation against success criteria
|
||||
- Identify gaps with specific remediation steps
|
||||
- Limit gap closure iterations to 3 per phase
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Execute implementation tasks
|
||||
- Skip testing step
|
||||
- Approve phase with unmet success criteria without documenting gaps
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `Bash` | CLI execution | Run tests, linters, build commands |
|
||||
| `Read` | File I/O | Load implementation, success criteria |
|
||||
| `Write` | File I/O | Generate verification report |
|
||||
| `Glob` | File search | Find test files |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Context Loading
|
||||
|
||||
**Objective**: Load phase implementation and success criteria.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| roadmap.md | Yes | Phase success criteria |
|
||||
| Execution task findings | Yes | From prev_context |
|
||||
| discoveries.ndjson | No | Shared exploration findings |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read roadmap.md, extract phase success criteria
|
||||
2. Load execution task findings from prev_context
|
||||
3. Read discoveries.ndjson for implementation notes
|
||||
4. Identify files modified during execution
|
||||
|
||||
**Output**: Verification context loaded
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Testing Execution
|
||||
|
||||
**Objective**: Run tests and validation checks.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Modified files | Yes | From Phase 1 |
|
||||
| Test files | No | Discovered via Glob |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Identify test files related to modified code
|
||||
2. Run relevant tests:
|
||||
```bash
|
||||
npm test -- [test-pattern]
|
||||
```
|
||||
3. Run linter/type checker:
|
||||
```bash
|
||||
npm run lint
|
||||
npm run type-check
|
||||
```
|
||||
4. Check build succeeds:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
5. Collect test results, errors, warnings
|
||||
|
||||
**Output**: Test execution results
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Gap Analysis
|
||||
|
||||
**Objective**: Compare implementation against success criteria and identify gaps.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Success criteria | Yes | From roadmap.md |
|
||||
| Test results | Yes | From Phase 2 |
|
||||
| Implementation findings | Yes | From execution tasks |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. For each success criterion:
|
||||
- Check if met by implementation
|
||||
- Check if validated by tests
|
||||
- Document status: met / partial / unmet
|
||||
2. Identify gaps:
|
||||
- Missing functionality
|
||||
- Failing tests
|
||||
- Unmet success criteria
|
||||
3. For each gap, define:
|
||||
- Gap description
|
||||
- Severity (critical / high / medium / low)
|
||||
- Remediation steps
|
||||
4. Check gap closure iteration count (max 3)
|
||||
|
||||
**Output**: Gap analysis with remediation steps
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Verification Report
|
||||
|
||||
**Objective**: Generate verification report and output results.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Gap analysis | Yes | From Phase 3 |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Generate verification.md:
|
||||
```markdown
|
||||
# Phase {N} Verification
|
||||
|
||||
## Success Criteria Status
|
||||
- [✓] Criterion 1: Met
|
||||
- [✗] Criterion 2: Unmet - [gap description]
|
||||
|
||||
## Test Results
|
||||
- Tests passed: {X}/{Y}
|
||||
- Build status: [success/failed]
|
||||
- Linter warnings: {Z}
|
||||
|
||||
## Gaps Identified
|
||||
### Gap 1: [Description]
|
||||
- Severity: [critical/high/medium/low]
|
||||
- Remediation: [steps]
|
||||
|
||||
## Recommendation
|
||||
[Approve / Gap Closure Required]
|
||||
```
|
||||
2. Write verification.md to phase directory
|
||||
3. Prepare output JSON with gap list
|
||||
|
||||
**Output**: verification.md + JSON result
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- Phase {phase} verification complete: {X}/{Y} success criteria met
|
||||
|
||||
## Findings
|
||||
- Tests passed: {X}/{Y}
|
||||
- Build status: [success/failed]
|
||||
- Gaps identified: {N} ([critical/high/medium/low] breakdown)
|
||||
|
||||
## Gaps
|
||||
- Gap 1: [description] (severity: [level])
|
||||
Remediation: [steps]
|
||||
- Gap 2: [description] (severity: [level])
|
||||
Remediation: [steps]
|
||||
|
||||
## Deliverables
|
||||
- File: phase-{N}/verification.md
|
||||
Content: Verification report with gap analysis
|
||||
|
||||
## Output JSON
|
||||
{
|
||||
"verification_path": "phase-{N}/verification.md",
|
||||
"criteria_met": {X},
|
||||
"criteria_total": {Y},
|
||||
"gaps": [
|
||||
{
|
||||
"description": "[gap description]",
|
||||
"severity": "[critical/high/medium/low]",
|
||||
"remediation": "[steps]"
|
||||
}
|
||||
],
|
||||
"recommendation": "approve" | "gap_closure_required",
|
||||
"summary": "Phase {phase} verification: {X}/{Y} criteria met"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Tests fail to run | Document as gap, continue verification |
|
||||
| Build fails | Mark as critical gap, recommend gap closure |
|
||||
| No test files found | Note in findings, continue with manual verification |
|
||||
| Gap closure iterations exceed 3 | Report to user, recommend manual intervention |
|
||||
| Success criteria ambiguous | Document interpretation, ask for clarification |
|
||||
@@ -0,0 +1,55 @@
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS
|
||||
1. Read shared discoveries: {session_folder}/discoveries.ndjson (if exists, skip if not)
|
||||
2. Read project context: .workflow/project-tech.json (if exists)
|
||||
3. Read implementation plan: {session_folder}/phase-{phase}/IMPL_PLAN.md
|
||||
4. Read task details: {session_folder}/phase-{phase}/.task/{id}.json (if exists)
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
**Task ID**: {id}
|
||||
**Title**: {title}
|
||||
**Description**: {description}
|
||||
**Phase**: {phase}
|
||||
**Role**: {role}
|
||||
|
||||
### Previous Tasks' Findings (Context)
|
||||
{prev_context}
|
||||
|
||||
---
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
1. **Read discoveries**: Load {session_folder}/discoveries.ndjson for shared exploration findings
|
||||
2. **Use context**: Apply previous tasks' findings from prev_context above
|
||||
3. **Execute**: Implement the task following the implementation plan and task details
|
||||
- Read target files listed in description
|
||||
- Apply changes following project conventions
|
||||
- Validate changes compile/lint correctly
|
||||
- Run relevant tests if available
|
||||
4. **Share discoveries**: Append exploration findings to shared board:
|
||||
```bash
|
||||
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> {session_folder}/discoveries.ndjson
|
||||
```
|
||||
5. **Report result**: Return JSON via report_agent_job_result
|
||||
|
||||
### Discovery Types to Share
|
||||
- `file_pattern`: `{pattern, files[], description}` — Code patterns discovered
|
||||
- `dependency`: `{from, to, type}` — Module dependencies identified
|
||||
- `risk`: `{description, severity, mitigation}` — Implementation risks
|
||||
- `test_gap`: `{area, description, priority}` — Testing gaps identified
|
||||
|
||||
---
|
||||
|
||||
## Output (report_agent_job_result)
|
||||
|
||||
Return JSON:
|
||||
{
|
||||
"id": "{id}",
|
||||
"status": "completed" | "failed",
|
||||
"findings": "Key discoveries and implementation notes (max 500 chars)",
|
||||
"error": ""
|
||||
}
|
||||
144
.codex/skills/team-roadmap-dev/schemas/tasks-schema.md
Normal file
144
.codex/skills/team-roadmap-dev/schemas/tasks-schema.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Roadmap-Driven Development — CSV Schema
|
||||
|
||||
## Master CSV: tasks.csv
|
||||
|
||||
### Column Definitions
|
||||
|
||||
#### Input Columns (Set by Decomposer)
|
||||
|
||||
| Column | Type | Required | Description | Example |
|
||||
|--------|------|----------|-------------|---------|
|
||||
| `id` | string | Yes | Unique task identifier | `"PLAN-101"` |
|
||||
| `title` | string | Yes | Short task title | `"Phase 1 Planning"` |
|
||||
| `description` | string | Yes | Detailed task description (self-contained) | `"Research and plan for authentication module..."` |
|
||||
| `deps` | string | No | Semicolon-separated dependency task IDs | `"PLAN-101"` |
|
||||
| `context_from` | string | No | Semicolon-separated task IDs for context | `"PLAN-101"` |
|
||||
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
|
||||
| `phase` | integer | Yes | Phase number (1-based) | `1` |
|
||||
| `role` | enum | Yes | Role name: `planner`, `executor`, `verifier` | `"executor"` |
|
||||
|
||||
#### Computed Columns (Set by Wave Engine)
|
||||
|
||||
| Column | Type | Description | Example |
|
||||
|--------|------|-------------|---------|
|
||||
| `wave` | integer | Wave number (1-based, from topological sort) | `2` |
|
||||
| `prev_context` | string | Aggregated findings from context_from tasks (per-wave CSV only) | `"[PLAN-101] Created implementation plan..."` |
|
||||
|
||||
#### Output Columns (Set by Agent)
|
||||
|
||||
| Column | Type | Description | Example |
|
||||
|--------|------|-------------|---------|
|
||||
| `status` | enum | `pending` → `completed` / `failed` / `skipped` | `"completed"` |
|
||||
| `findings` | string | Key discoveries (max 500 chars) | `"Implemented JWT middleware in src/middleware/auth.ts..."` |
|
||||
| `error` | string | Error message if failed | `""` |
|
||||
|
||||
---
|
||||
|
||||
### exec_mode Values
|
||||
|
||||
| Value | Mechanism | Description |
|
||||
|-------|-----------|-------------|
|
||||
| `csv-wave` | `spawn_agents_on_csv` | One-shot batch execution within wave |
|
||||
| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round individual execution |
|
||||
|
||||
Interactive tasks appear in master CSV for dependency tracking but are NOT included in wave-{N}.csv files.
|
||||
|
||||
---
|
||||
|
||||
### Example Data
|
||||
|
||||
```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,"",""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Column Lifecycle
|
||||
|
||||
```
|
||||
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
|
||||
───────────────────── ──────────────────── ─────────────────
|
||||
id ───────────► id ──────────► id
|
||||
title ───────────► title ──────────► (reads)
|
||||
description ───────────► description ──────────► (reads)
|
||||
deps ───────────► deps ──────────► (reads)
|
||||
context_from───────────► context_from──────────► (reads)
|
||||
exec_mode ───────────► exec_mode ──────────► (reads)
|
||||
phase ───────────► phase ──────────► (reads)
|
||||
role ───────────► role ──────────► (reads)
|
||||
wave ──────────► (reads)
|
||||
prev_context ──────────► (reads)
|
||||
status
|
||||
findings
|
||||
error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Schema (JSON)
|
||||
|
||||
Agent output via `report_agent_job_result` (csv-wave tasks):
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "EXEC-101",
|
||||
"status": "completed",
|
||||
"findings": "Implemented authentication routes in src/routes/auth.ts with login, logout, and register endpoints. Added input validation and error handling.",
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
|
||||
|
||||
---
|
||||
|
||||
## Discovery Types
|
||||
|
||||
| Type | Dedup Key | Data Schema | Description |
|
||||
|------|-----------|-------------|-------------|
|
||||
| `file_pattern` | `pattern` | `{pattern, files[], description}` | Code patterns discovered during exploration |
|
||||
| `dependency` | `from+to` | `{from, to, type}` | Module dependencies identified |
|
||||
| `risk` | `description` | `{description, severity, mitigation}` | Implementation risks and concerns |
|
||||
| `test_gap` | `area` | `{area, description, priority}` | Testing gaps identified during verification |
|
||||
|
||||
### Discovery NDJSON Format
|
||||
|
||||
```jsonl
|
||||
{"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"}}
|
||||
{"ts":"2026-03-08T14:35:10Z","worker":"EXEC-102","type":"dependency","data":{"from":"auth.ts","to":"jwt.ts","type":"import"}}
|
||||
{"ts":"2026-03-08T15:20:45Z","worker":"VERIFY-101","type":"test_gap","data":{"area":"token refresh","description":"No tests for token refresh flow","priority":"high"}}
|
||||
```
|
||||
|
||||
> Both csv-wave and interactive agents read/write the same discoveries.ndjson file.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Mechanism Context Flow
|
||||
|
||||
| Source | Target | Mechanism |
|
||||
|--------|--------|-----------|
|
||||
| CSV task findings | Interactive task | Injected via spawn message or send_input |
|
||||
| Interactive task result | CSV task prev_context | Read from interactive/{id}-result.json |
|
||||
| Any agent discovery | Any agent | Shared via discoveries.ndjson |
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
| Rule | Check | Error |
|
||||
|------|-------|-------|
|
||||
| Unique IDs | No duplicate `id` values | "Duplicate task ID: {id}" |
|
||||
| Valid deps | All dep IDs exist in tasks | "Unknown dependency: {dep_id}" |
|
||||
| No self-deps | Task cannot depend on itself | "Self-dependency: {id}" |
|
||||
| No circular deps | Topological sort completes | "Circular dependency detected involving: {ids}" |
|
||||
| context_from valid | All context IDs exist and in earlier waves | "Invalid context_from: {id}" |
|
||||
| exec_mode valid | Value is `csv-wave` or `interactive` | "Invalid exec_mode: {value}" |
|
||||
| Description non-empty | Every task has description | "Empty description for task: {id}" |
|
||||
| Status enum | status ∈ {pending, completed, failed, skipped} | "Invalid status: {status}" |
|
||||
| Cross-mechanism deps | Interactive→CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |
|
||||
| Role valid | role ∈ {planner, executor, verifier} | "Invalid role: {role}" |
|
||||
| Phase valid | phase >= 1 | "Invalid phase: {phase}" |
|
||||
Reference in New Issue
Block a user