catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-25 19:48:33 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: migrate all codex team skills from spawn_agents_on_csv to spawn_agent + wait_agent architecture

Browse Source 
- 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
2026-03-24 16:54:48 +08:00
parent 54283e5dbb
commit 1e560ab8e8
334 changed files with 28996 additions and 35516 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
.codex/agents/team-supervisor.toml Normal file
View File

@@ -0,0 +1,39 @@
name = "team_supervisor"
description = "Resident pipeline supervisor. Spawned once, woken via send_input for checkpoint verification. Read-only."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
You are a resident pipeline supervisor (message-driven lifecycle).
## Lifecycle
Init -> idle -> [wake -> execute checkpoint -> idle]* -> shutdown
Unlike team_worker (task-driven), you are message-driven:
- Spawned once at session start
- Woken by coordinator via send_input with checkpoint requests
- Stay alive across checkpoints, maintaining context continuity
## Boot Protocol
1. Parse role assignment from items (role_spec, session, session_id, requirement)
2. Read role_spec to load checkpoint definitions
3. Load baseline context (all role states, session state)
4. Report ready via report_agent_job_result
5. Wait for checkpoint requests via send_input
## Per Checkpoint
1. Parse checkpoint request from send_input items (task_id, scope)
2. Read artifacts specified in checkpoint scope
3. Load incremental context (new data since last wake)
4. Verify cross-artifact consistency per role.md definitions
5. Issue verdict: pass (>= 0.8), warn (0.5-0.79), block (< 0.5)
6. Write report to discoveries/{checkpoint_id}.json
7. Report findings via report_agent_job_result
## Constraints
- Read-only: never modify source artifacts
- Never issue pass when critical inconsistencies exist
- Never block for minor style issues
- Only communicate with coordinator
"""

46
.codex/agents/team-worker.toml Normal file
View File

@@ -0,0 +1,46 @@
name = "team_worker"
description = "Generic team worker agent. Role-specific behavior loaded from role.md at spawn time via items parameter."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
You are a team worker agent. You execute a specific role within a team pipeline.
## Boot Protocol
1. Parse role assignment from items (role, role_spec path, session, session_id, requirement)
2. Read role_spec file to load Phase 2-4 domain instructions
3. Read session state from session path
4. Execute built-in Phase 1 (task discovery from tasks.json)
5. Execute role-specific Phase 2-4 defined in role.md
6. Write deliverables to session artifacts directory
7. Write findings to discoveries/{task_id}.json
8. Report via report_agent_job_result
## Task State
- tasks.json is source of truth (NOT CSV)
- Filter tasks by your role prefix + status=pending + no blocked deps
- Update task status in tasks.json (pending -> in_progress -> completed)
## Inner Loop
If inner_loop=true, process ALL same-prefix tasks sequentially:
Phase 1 -> Phase 2-4 -> Phase 5-L (loop) -> repeat
Until no more same-prefix pending tasks -> Phase 5-F (final report)
## Output Schema
{
"id": "<task_id>",
"status": "completed | failed",
"role": "<role_name>",
"findings": "<max 500 chars>",
"artifact": "<artifact_path>",
"files_modified": [],
"error": ""
}
## Constraints
- Only process tasks matching your role prefix
- Never modify tasks outside your scope
- Report to coordinator only (not other workers)
- Use CLI tools (ccw cli) or direct tools for exploration
"""

793
.codex/skills/team-arch-opt/SKILL.md
View File

@@ -1,698 +1,151 @@
---
name: team-arch-opt
description: Architecture optimization team skill. Analyzes codebase architecture, designs refactoring plans, implements changes, validates improvements, and reviews code quality via CSV wave pipeline with interactive review-fix cycles.
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"architecture optimization task description\""
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
description: Unified team skill for architecture optimization. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team arch-opt".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
# Team Architecture Optimization
## Usage
Orchestrate multi-agent architecture optimization: analyze codebase -> design refactoring plan -> implement changes -> validate improvements -> review code quality.
```bash
$team-arch-opt "Refactor the auth module to reduce coupling and eliminate circular dependencies"
$team-arch-opt -c 4 "Analyze and fix God Classes across the service layer"
$team-arch-opt -y "Remove dead code and clean up barrel exports in src/utils"
$team-arch-opt --continue "tao-refactor-auth-20260308"
```
**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
Orchestrate multi-agent architecture optimization: analyze codebase structure, design refactoring plan, implement changes, validate improvements, review code quality. The pipeline has five domain roles (analyzer, designer, refactorer, validator, reviewer) mapped to CSV wave stages with an interactive review-fix cycle.
**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
## Architecture
```
+-------------------------------------------------------------------+
| TEAM ARCHITECTURE OPTIMIZATION WORKFLOW |
+-------------------------------------------------------------------+
| |
| Phase 0: Pre-Wave Interactive (Requirement Clarification) |
| +- Parse user task description |
| +- Detect scope: targeted module vs full architecture |
| +- Clarify ambiguous requirements (request_user_input) |
| +- Output: refined requirements for decomposition |
| |
| Phase 1: Requirement -> CSV + Classification |
| +- Identify architecture issues to target |
| +- Build 5-stage pipeline (analyze->design->refactor->validate |
| | +review) |
| +- Classify tasks: csv-wave | interactive (exec_mode) |
| +- Compute dependency waves (topological sort) |
| +- 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 (if any) |
| | +- 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 (if any) |
| | +- Merge all results into master tasks.csv |
| | +- Check: any failed? -> skip dependents |
| +- discoveries.ndjson shared across all modes (append-only) |
| +- Review-fix cycle: max 3 iterations per branch |
| |
| Phase 3: Post-Wave Interactive (Completion Action) |
| +- Pipeline completion report with improvement metrics |
| +- Interactive completion choice (Archive/Keep/Export) |
| +- Final aggregation / report |
| |
| Phase 4: 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 |
| |
+-------------------------------------------------------------------+
Skill(skill="team-arch-opt", args="task description")
|
SKILL.md (this file) = Router
|
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-- analyze -> dispatch -> spawn workers -> STOP
|
+-------+-------+-------+-------+
v v v v v
[analyzer][designer][refactorer][validator][reviewer]
```
---
## Role Registry
## Pipeline Definition
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false |
| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
| refactorer | [roles/refactorer/role.md](roles/refactorer/role.md) | REFACTOR-*, FIX-* | true |
| validator | [roles/validator/role.md](roles/validator/role.md) | VALIDATE-* | false |
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-* | false |
## Role Router
Parse `$ARGUMENTS`:
- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` -> `roles/coordinator/role.md`, execute entry router
## Shared Constants
- **Session prefix**: `TAO`
- **Session path**: `.workflow/.team/TAO-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
## Worker Spawn Template
Coordinator spawns workers using this template:
```
Stage 1 Stage 2 Stage 3 Stage 4
ANALYZE-001 --> DESIGN-001 --> REFACTOR-001 --> VALIDATE-001
[analyzer] [designer] [refactorer] [validator]
^ |
+<-- FIX-001 ----+
| REVIEW-001
+<--------> [reviewer]
(max 3 iterations)
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
---
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
## Task Classification Rules
**Inner Loop roles** (refactorer): Set `inner_loop: true`.
**Single-task roles** (analyzer, designer, validator, reviewer): Set `inner_loop: false`.
Each task is classified by `exec_mode`:
## User Commands
| 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, revision cycles, user checkpoints |
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph (branch-grouped), no advancement |
| `resume` / `continue` | Check worker states, advance next step |
| `revise <TASK-ID> [feedback]` | Revise specific task + cascade downstream |
| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
| `recheck` | Re-run quality check |
| `improve [dimension]` | Auto-improve weakest dimension |
**Classification Decision**:
| Task Property | Classification |
|---------------|---------------|
| Architecture analysis (single-pass scan) | `csv-wave` |
| Refactoring plan design (single-pass) | `csv-wave` |
| Code refactoring implementation | `csv-wave` |
| Validation (build, test, metrics) | `csv-wave` |
| Code review (single-pass) | `csv-wave` |
| Review-fix cycle (iterative revision) | `interactive` |
| User checkpoint (plan approval) | `interactive` |
| Discussion round (DISCUSS-REFACTOR, DISCUSS-REVIEW) | `interactive` |
---
## CSV Schema
### tasks.csv (Master State)
```csv
id,title,description,role,issue_type,priority,target_files,deps,context_from,exec_mode,wave,status,findings,verdict,artifacts_produced,error
"ANALYZE-001","Analyze architecture","Analyze codebase architecture to identify structural issues: cycles, coupling, cohesion, God Classes, dead code, API bloat. Produce baseline metrics and ranked report.","analyzer","","","","","","csv-wave","1","pending","","","",""
"DESIGN-001","Design refactoring plan","Analyze architecture report to design prioritized refactoring plan with strategies, expected improvements, and risk assessments.","designer","","","","ANALYZE-001","ANALYZE-001","csv-wave","2","pending","","","",""
"REFACTOR-001","Implement refactorings","Implement architecture refactoring changes following design plan in priority order (P0 first).","refactorer","","","","DESIGN-001","DESIGN-001","csv-wave","3","pending","","","",""
"VALIDATE-001","Validate changes","Validate refactoring: build checks, test suite, dependency metrics, API compatibility.","validator","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","PASS","",""
"REVIEW-001","Review refactoring code","Review refactoring changes for correctness, patterns, completeness, migration safety, best practices.","reviewer","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","APPROVE","",""
```
**Columns**:
| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (PREFIX-NNN format) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description (self-contained) |
| `role` | Input | Worker role: analyzer, designer, refactorer, validator, reviewer |
| `issue_type` | Input | Architecture issue category: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT |
| `priority` | Input | P0 (Critical), P1 (High), P2 (Medium), P3 (Low) |
| `target_files` | Input | Semicolon-separated file paths to focus on |
| `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` |
| `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) |
| `verdict` | Output | Validation/review verdict: PASS, WARN, FAIL, APPROVE, REVISE, REJECT |
| `artifacts_produced` | Output | Semicolon-separated paths of produced artifacts |
| `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 |
|-------|-----------|---------|----------------|----------|
| Plan Reviewer | agents/plan-reviewer.md | 2.3 (send_input cycle) | Review architecture report or refactoring plan at user checkpoint | pre-wave |
| Fix Cycle Handler | agents/fix-cycle-handler.md | 2.3 (send_input cycle) | Manage review-fix iteration cycle (max 3 rounds) | post-wave |
| Completion Handler | agents/completion-handler.md | 2.3 (send_input cycle) | Handle pipeline completion action (Archive/Keep/Export) | standalone |
> **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 4 |
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
| `context.md` | Human-readable execution report | Created in Phase 4 |
| `task-analysis.json` | Phase 1 output: scope, issues, pipeline config | Created in Phase 1 |
| `artifacts/architecture-baseline.json` | Analyzer: pre-refactoring metrics | Created by analyzer |
| `artifacts/architecture-report.md` | Analyzer: ranked structural issue findings | Created by analyzer |
| `artifacts/refactoring-plan.md` | Designer: prioritized refactoring plan | Created by designer |
| `artifacts/validation-results.json` | Validator: post-refactoring validation | Created by validator |
| `artifacts/review-report.md` | Reviewer: code review findings | Created by reviewer |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
---
## Session Structure
## Session Directory
```
.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
+-- task-analysis.json # Phase 1 analysis output
+-- wave-{N}.csv # Temporary per-wave input (csv-wave only)
+-- artifacts/
| +-- architecture-baseline.json # Analyzer output
| +-- architecture-report.md # Analyzer output
| +-- refactoring-plan.md # Designer output
| +-- validation-results.json # Validator output
| +-- review-report.md # Reviewer output
+-- interactive/ # Interactive task artifacts
| +-- {id}-result.json
+-- wisdom/
+-- patterns.md # Discovered patterns and conventions
.workflow/.team/TAO-<slug>-<date>/
├── session.json # Session metadata + status + parallel_mode
├── task-analysis.json # Coordinator analyze output
├── artifacts/
│ ├── architecture-baseline.json # Analyzer: pre-refactoring metrics
│ ├── architecture-report.md # Analyzer: ranked structural issue findings
│ ├── refactoring-plan.md # Designer: prioritized refactoring plan
│ ├── validation-results.json # Validator: post-refactoring validation
│ ├── review-report.md # Reviewer: code review findings
│ ├── aggregate-results.json # Fan-out/independent: aggregated results
│ ├── branches/ # Fan-out mode branch artifacts
│ │ └── B{NN}/
│ │ ├── refactoring-detail.md
│ │ ├── validation-results.json
│ │ └── review-report.md
│ └── pipelines/ # Independent mode pipeline artifacts
│ └── {P}/
│ └── ...
├── explorations/
│ ├── cache-index.json # Shared explore cache
│ └── <hash>.md
├── wisdom/
│ └── patterns.md # Discovered patterns and conventions
├── discussions/
│ ├── DISCUSS-REFACTOR.md
│ └── DISCUSS-REVIEW.md
└── .msg/
├── messages.jsonl # Message bus log
└── meta.json # Session state + cross-role state
```
---
## Specs Reference
## Implementation
### Session Initialization
```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
const requirement = $ARGUMENTS
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
.trim()
const slug = requirement.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = `tao-${slug}-${dateStr}`
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
Bash(`mkdir -p ${sessionFolder}/artifacts ${sessionFolder}/interactive ${sessionFolder}/wisdom`)
// Initialize discoveries.ndjson
Write(`${sessionFolder}/discoveries.ndjson`, '')
// Initialize wisdom
Write(`${sessionFolder}/wisdom/patterns.md`, '# Patterns & Conventions\n')
```
---
### Phase 0: Pre-Wave Interactive (Requirement Clarification)
**Objective**: Parse user task, detect architecture scope, clarify ambiguities, prepare for decomposition.
**Workflow**:
1. **Parse user task description** from $ARGUMENTS
2. **Check for existing sessions** (continue mode):
- Scan `.workflow/.csv-wave/tao-*/tasks.csv` for sessions with pending tasks
- If `--continue`: resume the specified or most recent session, skip to Phase 2
- If active session found: ask user whether to resume or start new
3. **Identify architecture optimization target**:
| Signal | Target |
|--------|--------|
| Specific file/module mentioned | Scoped refactoring |
| "coupling", "dependency", "structure", generic | Full architecture analysis |
| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
4. **Clarify if ambiguous** (skip if AUTO_YES):
```javascript
request_user_input({
questions: [{
question: "Please confirm the architecture optimization scope.",
header: "Scope",
id: "arch_scope",
options: [
{ label: "Proceed (Recommended)", description: "Scope is clear, start analysis" },
{ label: "Narrow scope", description: "Specify modules/files to focus on" },
{ label: "Add constraints", description: "Exclude areas, set priorities" }
]
}]
})
```
5. **Output**: Refined requirement string for Phase 1
**Success Criteria**:
- Refined requirements available for Phase 1 decomposition
- Existing session detected and handled if applicable
---
### Phase 1: Requirement -> CSV + Classification
**Objective**: Decompose architecture optimization task into the 5-stage pipeline tasks, assign waves, generate tasks.csv.
**Decomposition Rules**:
1. **Stage mapping** -- architecture optimization always follows this pipeline:
| Stage | Role | Task Prefix | Wave | Description |
|-------|------|-------------|------|-------------|
| 1 | analyzer | ANALYZE | 1 | Scan codebase, identify structural issues, produce baseline metrics |
| 2 | designer | DESIGN | 2 | Design refactoring plan from architecture report |
| 3 | refactorer | REFACTOR | 3 | Implement refactorings per plan priority |
| 4a | validator | VALIDATE | 4 | Validate build, tests, metrics, API compatibility |
| 4b | reviewer | REVIEW | 4 | Review refactoring code for correctness and patterns |
2. **Single-pipeline decomposition**: Generate one task per stage with sequential dependencies:
- ANALYZE-001 (wave 1, no deps)
- DESIGN-001 (wave 2, deps: ANALYZE-001)
- REFACTOR-001 (wave 3, deps: DESIGN-001)
- VALIDATE-001 (wave 4, deps: REFACTOR-001)
- REVIEW-001 (wave 4, deps: REFACTOR-001)
3. **Description enrichment**: Each task description must be self-contained with:
- Clear goal statement
- Input artifacts to read
- Output artifacts to produce
- Success criteria
- Session folder path
**Classification Rules**:
| Task Property | exec_mode |
|---------------|-----------|
| ANALYZE, DESIGN, REFACTOR, VALIDATE, REVIEW (initial pass) | `csv-wave` |
| FIX tasks (review-fix cycle) | `interactive` (handled by fix-cycle-handler agent) |
**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
**Success Criteria**:
- tasks.csv created with valid schema, wave, and exec_mode assignments
- task-analysis.json written with scope and pipeline config
- 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
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
const maxWave = Math.max(...tasks.map(t => t.wave))
for (let wave = 1; wave <= maxWave; wave++) {
console.log(`\nWave ${wave}/${maxWave}`)
// 1. Separate tasks by exec_mode
const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
// 2. Check dependencies -- skip tasks whose deps failed
for (const task of waveTasks) {
const depIds = (task.deps || '').split(';').filter(Boolean)
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
task.status = 'skipped'
task.error = `Dependency failed: ${depIds.filter((id, i) =>
['failed','skipped'].includes(depStatuses[i])).join(', ')}`
}
}
// 3. Execute pre-wave interactive tasks (if any)
for (const task of interactiveTasks.filter(t => t.status === 'pending')) {
// Determine agent file based on task type
const agentFile = task.id.startsWith('FIX') ? 'agents/fix-cycle-handler.md' : 'agents/plan-reviewer.md'
Read(agentFile)
const agent = spawn_agent({
message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: ${agentFile}\n2. Read: ${sessionFolder}/discoveries.ndjson\n3. Read: .workflow/project-tech.json (if exists)\n\n---\n\nGoal: ${task.description}\nScope: ${task.title}\nSession: ${sessionFolder}\n\n### Previous Context\n${buildPrevContext(task, tasks)}`
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
if (result.timed_out) {
send_input({ id: agent, message: "Please finalize and output current findings." })
wait({ ids: [agent], timeout_ms: 120000 })
}
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
task_id: task.id, status: "completed", findings: parseFindings(result),
timestamp: getUtc8ISOString()
}))
close_agent({ id: agent })
task.status = 'completed'
task.findings = parseFindings(result)
}
// 4. Build prev_context for csv-wave tasks
const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
for (const task of pendingCsvTasks) {
task.prev_context = buildPrevContext(task, tasks)
}
if (pendingCsvTasks.length > 0) {
// 5. Write wave CSV
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))
// 6. Determine instruction -- read from instructions/agent-instruction.md
Read('instructions/agent-instruction.md')
// 7. Execute wave via spawn_agents_on_csv
spawn_agents_on_csv({
csv_path: `${sessionFolder}/wave-${wave}.csv`,
id_column: "id",
instruction: archOptInstruction, // from instructions/agent-instruction.md
max_concurrency: maxConcurrency,
max_runtime_seconds: 900,
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
verdict: { type: "string" },
artifacts_produced: { type: "string" },
error: { type: "string" }
}
}
})
// 8. Merge results into master CSV
const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
for (const r of results) {
const t = tasks.find(t => t.id === r.id)
if (t) Object.assign(t, r)
}
}
// 9. Update master CSV
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
// 10. Cleanup temp files
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
// 11. Post-wave: check for review-fix cycle
const validateTask = tasks.find(t => t.id.startsWith('VALIDATE') && t.wave === wave)
const reviewTask = tasks.find(t => t.id.startsWith('REVIEW') && t.wave === wave)
if ((validateTask?.verdict === 'FAIL' || reviewTask?.verdict === 'REVISE' || reviewTask?.verdict === 'REJECT')) {
const fixCycleCount = tasks.filter(t => t.id.startsWith('FIX')).length
if (fixCycleCount < 3) {
// Create FIX task, add to tasks, re-run refactor -> validate+review cycle
const fixId = `FIX-${String(fixCycleCount + 1).padStart(3, '0')}`
const feedback = [validateTask?.error, reviewTask?.findings].filter(Boolean).join('\n')
tasks.push({
id: fixId, title: `Fix issues from review/validation cycle ${fixCycleCount + 1}`,
description: `Fix issues found:\n${feedback}`,
role: 'refactorer', issue_type: '', priority: 'P0', target_files: '',
deps: '', context_from: '', exec_mode: 'interactive',
wave: wave + 1, status: 'pending', findings: '', verdict: '',
artifacts_produced: '', error: ''
})
}
}
// 12. Display wave summary
const completed = waveTasks.filter(t => t.status === 'completed').length
const failed = waveTasks.filter(t => t.status === 'failed').length
const skipped = waveTasks.filter(t => t.status === 'skipped').length
console.log(`Wave ${wave} Complete: ${completed} completed, ${failed} failed, ${skipped} skipped`)
}
```
**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
- Review-fix cycle handled with max 3 iterations
- discoveries.ndjson accumulated across all waves and mechanisms
---
### Phase 3: Post-Wave Interactive (Completion Action)
**Objective**: Pipeline completion report with architecture improvement metrics and interactive completion choice.
```javascript
// 1. Generate pipeline summary
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
const completed = tasks.filter(t => t.status === 'completed')
const failed = tasks.filter(t => t.status === 'failed')
// 2. Load improvement metrics from validation results
let improvements = ''
try {
const validation = JSON.parse(Read(`${sessionFolder}/artifacts/validation-results.json`))
improvements = `Architecture Improvements:\n${validation.dimensions.map(d =>
` ${d.name}: ${d.baseline} -> ${d.current} (${d.improvement})`).join('\n')}`
} catch {}
console.log(`
============================================
ARCHITECTURE OPTIMIZATION COMPLETE
Deliverables:
- Architecture Baseline: artifacts/architecture-baseline.json
- Architecture Report: artifacts/architecture-report.md
- Refactoring Plan: artifacts/refactoring-plan.md
- Validation Results: artifacts/validation-results.json
- Review Report: artifacts/review-report.md
${improvements}
Pipeline: ${completed.length}/${tasks.length} tasks
Session: ${sessionFolder}
============================================
`)
// 3. Completion action
if (!AUTO_YES) {
request_user_input({
questions: [{
question: "Architecture optimization complete. Choose next action.",
header: "Done",
id: "completion",
options: [
{ label: "Archive (Recommended)", description: "Archive session, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Retry Failed", description: "Re-run failed tasks" }
]
}]
})
}
```
**Success Criteria**:
- Post-wave interactive processing complete
- User informed of results and improvement metrics
---
### Phase 4: Results Aggregation
**Objective**: Generate final results and human-readable report.
```javascript
// 1. Export results.csv
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
// 2. Generate context.md
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
let contextMd = `# Architecture Optimization Report\n\n`
contextMd += `**Session**: ${sessionId}\n`
contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n\n`
contextMd += `## Summary\n`
contextMd += `| Status | Count |\n|--------|-------|\n`
contextMd += `| Completed | ${tasks.filter(t => t.status === 'completed').length} |\n`
contextMd += `| Failed | ${tasks.filter(t => t.status === 'failed').length} |\n`
contextMd += `| Skipped | ${tasks.filter(t => t.status === 'skipped').length} |\n\n`
contextMd += `## Deliverables\n\n`
contextMd += `| Artifact | Path |\n|----------|------|\n`
contextMd += `| Architecture Baseline | artifacts/architecture-baseline.json |\n`
contextMd += `| Architecture Report | artifacts/architecture-report.md |\n`
contextMd += `| Refactoring Plan | artifacts/refactoring-plan.md |\n`
contextMd += `| Validation Results | artifacts/validation-results.json |\n`
contextMd += `| Review Report | artifacts/review-report.md |\n\n`
const maxWave = Math.max(...tasks.map(t => t.wave))
contextMd += `## Wave Execution\n\n`
for (let w = 1; w <= maxWave; w++) {
const waveTasks = tasks.filter(t => t.wave === w)
contextMd += `### Wave ${w}\n\n`
for (const t of waveTasks) {
const icon = t.status === 'completed' ? '[DONE]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
contextMd += `${icon} **${t.title}** [${t.role}] ${t.verdict ? `(${t.verdict})` : ''} ${t.findings || ''}\n\n`
}
}
Write(`${sessionFolder}/context.md`, contextMd)
console.log(`Results exported to: ${sessionFolder}/results.csv`)
console.log(`Report generated at: ${sessionFolder}/context.md`)
```
**Success Criteria**:
- results.csv exported (all tasks, both modes)
- context.md generated with deliverables list
- Summary displayed to user
---
## Shared Discovery Board Protocol
All agents (csv-wave and interactive) share a single `discoveries.ndjson` file for cross-task knowledge exchange.
**Format**: One JSON object per line (NDJSON):
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"ANALYZE-001","type":"cycle_found","data":{"modules":["auth","user"],"depth":2,"description":"Circular dependency between auth and user modules"}}
{"ts":"2026-03-08T10:05:00Z","worker":"REFACTOR-001","type":"file_modified","data":{"file":"src/auth/index.ts","change":"Extracted interface to break cycle","lines_added":15}}
```
**Discovery Types**:
| Type | Data Schema | Description |
|------|-------------|-------------|
| `cycle_found` | `{modules, depth, description}` | Circular dependency detected |
| `god_class_found` | `{file, loc, methods, description}` | God Class/Module identified |
| `coupling_issue` | `{module, fan_in, fan_out, description}` | High coupling detected |
| `dead_code_found` | `{file, type, description}` | Dead code or dead export found |
| `file_modified` | `{file, change, lines_added}` | File change recorded |
| `pattern_found` | `{pattern_name, location, description}` | Code pattern identified |
| `metric_measured` | `{metric, value, unit, module}` | Architecture metric measured |
| `artifact_produced` | `{name, path, producer, type}` | Deliverable created |
**Protocol**:
1. Agents MUST read discoveries.ndjson at start of execution
2. Agents MUST append relevant discoveries during execution
3. Agents MUST NOT modify or delete existing entries
4. Deduplication by `{type, data.file}` or `{type, data.modules}` key
---
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task registry, parallel modes
## Error Handling
| Error | Resolution |
|-------|------------|
| Circular dependency in tasks | 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 |
| 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 |
| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues |
| Validation fails on build | Create FIX task with compilation error details |
| Architecture baseline unavailable | Fall back to static analysis estimates |
| Continue mode: no session found | List available sessions, prompt user to select |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 0/1
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. **Max 3 Fix Cycles**: Review-fix cycle capped at 3 iterations; escalate to user after
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
---
## Coordinator Role Constraints (Main Agent)
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
| consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline |
| Branch fix cycle >= 3 | Escalate only that branch to user, others continue |
| max_branches exceeded | Coordinator truncates to top N at CP-2.5 |

138
.codex/skills/team-arch-opt/agents/completion-handler.md
View File

@@ -1,138 +0,0 @@
# Completion Handler Agent
Handle pipeline completion action for architecture optimization: present results summary, offer Archive/Keep/Export options, execute chosen action.
## Identity
- **Type**: `interactive`
- **Responsibility**: Pipeline completion and session lifecycle management
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Present complete pipeline summary with improvement metrics
- Offer completion action choices
- Execute chosen action (archive, keep, export)
- Produce structured output
### MUST NOT
- Skip presenting results summary
- Execute destructive actions without confirmation
- Modify source code
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load result artifacts |
| `Write` | builtin | Write export files |
| `Bash` | builtin | Archive/cleanup operations |
| `request_user_input` | builtin | Present completion choices |
---
## Execution
### Phase 1: Results Collection
**Objective**: Gather all pipeline results for summary.
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| tasks.csv | Yes | Master task state |
| Architecture baseline | Yes | Pre-refactoring metrics |
| Validation results | Yes | Post-refactoring metrics |
| Review report | Yes | Code review findings |
**Steps**:
1. Read tasks.csv -- count completed/failed/skipped
2. Read architecture-baseline.json -- extract before metrics
3. Read validation-results.json -- extract after metrics, compute improvements
4. Read review-report.md -- extract final verdict
**Output**: Compiled results summary
---
### Phase 2: Present and Choose
**Objective**: Display results and get user's completion choice.
**Steps**:
1. Display pipeline summary with improvement metrics
2. Present completion action:
```javascript
request_user_input({
questions: [{
question: "Architecture optimization complete. What would you like to do?",
header: "Completion",
id: "completion_action",
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location" }
]
}]
})
```
**Output**: User's choice
---
### Phase 3: Execute Action
**Objective**: Execute the chosen completion action.
| Choice | Action |
|--------|--------|
| Archive & Clean | Copy results.csv and context.md to archive, mark session completed |
| Keep Active | Mark session as paused, leave all artifacts in place |
| Export Results | Copy key deliverables to user-specified location |
---
## Structured Output Template
```
## Pipeline Summary
- Tasks: X completed, Y failed, Z skipped
- Duration: estimated from timestamps
## Architecture Improvements
- Metric 1: before -> after (improvement %)
- Metric 2: before -> after (improvement %)
## Deliverables
- Architecture Report: path
- Refactoring Plan: path
- Validation Results: path
- Review Report: path
## Action Taken
- Choice: Archive & Clean / Keep Active / Export Results
- Status: completed
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Result artifacts missing | Report partial summary with available data |
| Archive operation fails | Default to Keep Active |
| Export path invalid | Ask user for valid path |
| Timeout approaching | Default to Keep Active |

146
.codex/skills/team-arch-opt/agents/fix-cycle-handler.md
View File

@@ -1,146 +0,0 @@
# Fix Cycle Handler Agent
Manage the review-fix iteration cycle for architecture refactoring. Reads validation/review feedback, applies targeted fixes, re-validates, up to 3 iterations.
## Identity
- **Type**: `interactive`
- **Responsibility**: Iterative fix-verify cycle for refactoring issues
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read validation results and review report to understand failures
- Apply targeted fixes addressing specific feedback items
- Re-validate after each fix attempt
- Track iteration count (max 3)
- Produce structured output with fix summary
### MUST NOT
- Skip reading feedback before attempting fixes
- Apply broad changes unrelated to feedback
- Exceed 3 fix iterations
- Modify code outside the scope of reported issues
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load feedback artifacts and source files |
| `Edit` | builtin | Apply targeted code fixes |
| `Write` | builtin | Write updated artifacts |
| `Bash` | builtin | Run build/test validation |
| `Grep` | builtin | Search for patterns |
| `Glob` | builtin | Find files |
---
## Execution
### Phase 1: Feedback Loading
**Objective**: Load and parse validation/review feedback.
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Validation results | Yes (if validation failed) | From artifacts/validation-results.json |
| Review report | Yes (if review issued REVISE/REJECT) | From artifacts/review-report.md |
| Refactoring plan | Yes | Original plan for reference |
| Discoveries | No | Shared findings |
**Steps**:
1. Read validation-results.json -- identify failed dimensions (build, test, metrics, API)
2. Read review-report.md -- identify Critical/High findings with file:line references
3. Categorize issues by type and priority
**Output**: Prioritized list of issues to fix
---
### Phase 2: Fix Implementation (Iterative)
**Objective**: Apply fixes and re-validate, up to 3 rounds.
**Steps**:
For each iteration (1..3):
1. **Apply fixes**:
- Address highest-severity issues first
- Make minimal, targeted changes at reported file:line locations
- Update imports if structural changes are needed
- Preserve existing behavior
2. **Self-validate**:
- Run build check (no new compilation errors)
- Run test suite (no new test failures)
- Verify fix addresses the specific concern raised
3. **Check convergence**:
| Validation Result | Action |
|-------------------|--------|
| All checks pass | Exit loop, report success |
| Some checks still fail, iteration < 3 | Continue to next iteration |
| Still failing at iteration 3 | Report remaining issues for escalation |
**Output**: Fix results per iteration
---
### Phase 3: Result Reporting
**Objective**: Produce final fix cycle summary.
**Steps**:
1. Update validation-results.json with post-fix metrics
2. Append fix discoveries to discoveries.ndjson
3. Report final status
---
## Structured Output Template
```
## Summary
- Fix cycle completed: N iterations, M issues resolved, K remaining
## Iterations
### Iteration 1
- Fixed: [list of fixes applied with file:line]
- Validation: [pass/fail per dimension]
### Iteration 2 (if needed)
- Fixed: [list of fixes]
- Validation: [pass/fail]
## Final Status
- verdict: PASS | PARTIAL | ESCALATE
- Remaining issues (if any): [list]
## Artifacts Updated
- artifacts/validation-results.json (updated metrics)
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Fix introduces new errors | Revert fix, try alternative approach |
| Cannot reproduce reported issue | Log as resolved-by-environment, continue |
| Fix scope exceeds current files | Report scope expansion needed, escalate |
| Timeout approaching | Output partial results with iteration count |
| 3 iterations exhausted | Report remaining issues for user escalation |

150
.codex/skills/team-arch-opt/agents/plan-reviewer.md
View File

@@ -1,150 +0,0 @@
# Plan Reviewer Agent
Review architecture report or refactoring plan at user checkpoints, providing interactive approval or revision requests.
## Identity
- **Type**: `interactive`
- **Responsibility**: Review and approve/revise plans before execution proceeds
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read the architecture report or refactoring plan being reviewed
- Produce structured output with clear APPROVE/REVISE verdict
- Include specific file:line references in findings
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Modify source code directly
- Produce unstructured output
- Approve without actually reading the plan
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load plan artifacts and project files |
| `Grep` | builtin | Search for patterns in codebase |
| `Glob` | builtin | Find files by pattern |
| `Bash` | builtin | Run build/test commands |
### Tool Usage Patterns
**Read Pattern**: Load context files before review
```
Read("{session_folder}/artifacts/architecture-report.md")
Read("{session_folder}/artifacts/refactoring-plan.md")
Read("{session_folder}/discoveries.ndjson")
```
---
## Execution
### Phase 1: Context Loading
**Objective**: Load the plan or report to review.
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Architecture report | Yes (if reviewing analysis) | Ranked issue list from analyzer |
| Refactoring plan | Yes (if reviewing design) | Prioritized plan from designer |
| Discoveries | No | Shared findings from prior stages |
**Steps**:
1. Read the artifact being reviewed from session artifacts folder
2. Read discoveries.ndjson for additional context
3. Identify which checkpoint this review corresponds to (CP-1 for analysis, CP-2 for design)
**Output**: Loaded plan context for review
---
### Phase 2: Plan Review
**Objective**: Evaluate plan quality, completeness, and feasibility.
**Steps**:
1. **For architecture report review (CP-1)**:
- Verify all issue categories are covered (cycles, coupling, cohesion, God Classes, dead code, API bloat)
- Check that severity rankings are justified with evidence
- Validate baseline metrics are quantified and reproducible
- Check scope coverage matches original requirement
2. **For refactoring plan review (CP-2)**:
- Verify each refactoring has unique REFACTOR-ID and self-contained detail
- Check priority assignments follow impact/effort matrix
- Validate target files are non-overlapping between refactorings
- Verify success criteria are measurable
- Check that implementation guidance is actionable
- Assess risk levels and mitigation strategies
3. **Issue classification**:
| Finding Severity | Condition | Impact |
|------------------|-----------|--------|
| Critical | Missing key analysis area or infeasible plan | REVISE required |
| High | Unclear criteria or overlapping targets | REVISE recommended |
| Medium | Minor gaps in coverage or detail | Note for improvement |
| Low | Style or formatting issues | Informational |
**Output**: Review findings with severity classifications
---
### Phase 3: Verdict
**Objective**: Issue APPROVE or REVISE verdict.
| Verdict | Condition | Action |
|---------|-----------|--------|
| APPROVE | No Critical or High findings | Plan is ready for next stage |
| REVISE | Has Critical or High findings | Return specific feedback for revision |
**Output**: Verdict with detailed feedback
---
## Structured Output Template
```
## Summary
- One-sentence verdict: APPROVE or REVISE with rationale
## Findings
- Finding 1: [severity] description with artifact reference
- Finding 2: [severity] description with specific section reference
## Verdict
- APPROVE: Plan is ready for execution
OR
- REVISE: Specific items requiring revision
1. Issue description + suggested fix
2. Issue description + suggested fix
## Recommendations
- Optional improvement suggestions (non-blocking)
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Artifact file not found | Report in findings, request re-generation |
| Plan structure invalid | Report as Critical finding, REVISE verdict |
| Scope mismatch | Report in findings, note for coordinator |
| Timeout approaching | Output current findings with "PARTIAL" status |

114
.codex/skills/team-arch-opt/instructions/agent-instruction.md
View File

@@ -1,114 +0,0 @@
## 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 task schema: ~ or <project>/.codex/skills/team-arch-opt/schemas/tasks-schema.md
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Description**: {description}
**Role**: {role}
**Issue Type**: {issue_type}
**Priority**: {priority}
**Target Files**: {target_files}
### 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 by role**:
**If role = analyzer**:
- Scan codebase for architecture issues within target scope
- Build import/require graph, detect circular dependencies
- Identify God Classes (>500 LOC, >10 public methods)
- Calculate coupling (fan-in/fan-out) and cohesion metrics
- Detect dead code, dead exports, layering violations
- Collect quantified baseline metrics
- Rank top 3-7 issues by severity (Critical/High/Medium)
- Write `{session_folder}/artifacts/architecture-baseline.json` (metrics)
- Write `{session_folder}/artifacts/architecture-report.md` (ranked issues)
**If role = designer**:
- Read architecture report and baseline from {session_folder}/artifacts/
- For each issue, select refactoring strategy by type:
- CYCLE: interface extraction, dependency inversion, mediator
- GOD_CLASS: SRP decomposition, extract class/module
- COUPLING: introduce interface/abstraction, DI, events
- DUPLICATION: extract shared utility/base class
- LAYER_VIOLATION: move to correct layer, add facade
- DEAD_CODE: safe removal with reference verification
- API_BLOAT: privatize internals, barrel file cleanup
- Prioritize by impact/effort: P0 (high impact+low effort) to P3 (low impact or high effort)
- Assign unique REFACTOR-IDs (REFACTOR-001, 002, ...) with non-overlapping file targets
- Write `{session_folder}/artifacts/refactoring-plan.md`
**If role = refactorer**:
- Read refactoring plan from {session_folder}/artifacts/refactoring-plan.md
- Apply refactorings in priority order (P0 first)
- Preserve existing behavior -- refactoring must not change functionality
- Update ALL import references when moving/renaming modules
- Update ALL test files referencing moved/renamed symbols
- Verify no dangling imports after module moves
**If role = validator**:
- Read baseline from {session_folder}/artifacts/architecture-baseline.json
- Read plan from {session_folder}/artifacts/refactoring-plan.md
- Build validation: compile/type-check, zero new errors
- Test validation: run test suite, no new failures
- Metric validation: coupling improved or neutral, no new cycles
- API validation: public signatures preserved, no dangling references
- Write `{session_folder}/artifacts/validation-results.json`
- Set verdict: PASS / WARN / FAIL
**If role = reviewer**:
- Read plan from {session_folder}/artifacts/refactoring-plan.md
- Review changed files across 5 dimensions:
- Correctness: no behavior changes, all references updated
- Pattern consistency: follows existing conventions
- Completeness: imports, tests, configs all updated
- Migration safety: no dangling refs, backward compatible
- Best practices: SOLID, appropriate abstraction
- Write `{session_folder}/artifacts/review-report.md`
- Set verdict: APPROVE / REVISE / REJECT
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
- `cycle_found`: `{modules, depth, description}` -- Circular dependency detected
- `god_class_found`: `{file, loc, methods, description}` -- God Class identified
- `coupling_issue`: `{module, fan_in, fan_out, description}` -- High coupling
- `dead_code_found`: `{file, type, description}` -- Dead code found
- `layer_violation`: `{from, to, description}` -- Layering violation
- `file_modified`: `{file, change, lines_added}` -- File change recorded
- `pattern_found`: `{pattern_name, location, description}` -- Pattern identified
- `metric_measured`: `{metric, value, unit, module}` -- Metric measured
- `artifact_produced`: `{name, path, producer, type}` -- Deliverable created
---
## Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key discoveries and implementation notes (max 500 chars)",
"verdict": "PASS|WARN|FAIL|APPROVE|REVISE|REJECT or empty",
"artifacts_produced": "semicolon-separated artifact paths",
"error": ""
}

78
.codex/skills/team-arch-opt/roles/analyzer/role.md Normal file
View File

@@ -0,0 +1,78 @@
---
role: analyzer
prefix: ANALYZE
inner_loop: false
message_types: [state_update]
---
# Architecture Analyzer
Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report.
## Phase 2: Context & Environment Detection
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
1. Extract session path and target scope from task description
2. Detect project type by scanning for framework markers:
| Signal File | Project Type | Analysis Focus |
|-------------|-------------|----------------|
| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports |
| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns |
| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection |
| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts |
| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
| No detection | Generic | All architecture dimensions |
3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope
4. Detect available analysis tools (linters, dependency analyzers, build tools)
## Phase 3: Architecture Analysis
Execute analysis based on detected project type:
**Dependency analysis**:
- Build import/require graph across modules
- Detect circular dependencies (direct and transitive cycles)
- Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)
**Structural analysis**:
- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
- Calculate coupling metrics (afferent/efferent coupling per module)
- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
- Detect code duplication (repeated logic blocks, copy-paste patterns)
- Identify missing abstractions (repeated conditionals, switch-on-type patterns)
**API surface analysis**:
- Count exported symbols per module (export bloat detection)
- Identify dead exports (exported but never imported elsewhere)
- Detect dead code (unreachable functions, unused variables, orphan files)
- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)
**All project types**:
- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
- Rank top 3-7 architecture issues by severity (Critical / High / Medium)
- Record evidence: file paths, line numbers, measured values
## Phase 4: Report Generation
1. Write architecture baseline to `<session>/artifacts/architecture-baseline.json`:
- Module count, dependency count, cycle count, average coupling, average cohesion
- God Class candidates with LOC and method count
- Dead code file count, dead export count
- Timestamp and project type details
2. Write architecture report to `<session>/artifacts/architecture-report.md`:
- Ranked list of architecture issues with severity, location (file:line or module), measured impact
- Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
- Evidence summary per issue
- Detected project type and analysis methods used
3. Update `<session>/wisdom/.msg/meta.json` under `analyzer` namespace:
- Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back

57
.codex/skills/team-arch-opt/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,57 @@
# Analyze Task
Parse user task -> detect architecture capabilities -> build dependency graph -> design roles.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Prefix |
|----------|------------|--------|
| analyze, scan, audit, map, identify | analyzer | ANALYZE |
| design, plan, strategy, refactoring-plan | designer | DESIGN |
| refactor, implement, fix, apply | refactorer | REFACTOR |
| validate, build, test, verify, compile | validator | VALIDATE |
| review, audit-code, quality, check-code | reviewer | REVIEW |
## Dependency Graph
Natural ordering tiers:
- Tier 0: analyzer (knowledge gathering -- no dependencies)
- Tier 1: designer (requires analyzer output)
- Tier 2: refactorer (requires designer output)
- Tier 3: validator, reviewer (validation requires refactored artifacts, can run in parallel)
## Complexity Scoring
| Factor | Points |
|--------|--------|
| Per capability | +1 |
| Cross-domain refactoring | +2 |
| Parallel branches requested | +1 per branch |
| Serial depth > 3 | +1 |
| Multiple targets (independent mode) | +2 |
Results: 1-3 Low, 4-6 Medium, 7+ High
## Role Minimization
- Cap at 5 roles
- Merge overlapping capabilities
- Absorb trivial single-step roles
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<single|fan-out|independent|auto>",
"capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
"dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"parallel_mode": "<auto|single|fan-out|independent>",
"max_branches": 5
}
```

287
.codex/skills/team-arch-opt/roles/coordinator/commands/dispatch.md Normal file
View File

@@ -0,0 +1,287 @@
# Command: Dispatch
Create the architecture optimization task chain with correct dependencies and structured task descriptions. Supports single, fan-out, independent, and auto parallel modes.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| User requirement | From coordinator Phase 1 | Yes |
| Session folder | From coordinator Phase 2 | Yes |
| Pipeline definition | From SKILL.md Pipeline Definitions | Yes |
| Parallel mode | From tasks.json `parallel_mode` | Yes |
| Max branches | From tasks.json `max_branches` | Yes |
| Independent targets | From tasks.json `independent_targets` (independent mode only) | Conditional |
1. Load user requirement and refactoring scope from tasks.json
2. Load pipeline stage definitions from SKILL.md Task Metadata Registry
3. Read `parallel_mode` and `max_branches` from tasks.json
4. For `independent` mode: read `independent_targets` array from tasks.json
## Phase 3: Task Chain Creation (Mode-Branched)
### Task Entry Template
Every task in tasks.json `tasks` object uses structured format:
```json
{
"<TASK-ID>": {
"title": "<concise title>",
"description": "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>\nTASK:\n - <step 1: specific action>\n - <step 2: specific action>\n - <step 3: specific action>\nCONTEXT:\n - Session: <session-folder>\n - Scope: <refactoring-scope>\n - Branch: <branch-id or 'none'>\n - Upstream artifacts: <artifact-1>, <artifact-2>\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits, focus areas>\n---\nInnerLoop: <true|false>\nBranchId: <B01|A|none>",
"role": "<role-name>",
"prefix": "<PREFIX>",
"deps": ["<upstream-task-id>"],
"status": "pending",
"findings": null,
"error": null
}
}
```
### Mode Router
| Mode | Action |
|------|--------|
| `single` | Create 5 tasks (ANALYZE -> DESIGN -> REFACTOR -> VALIDATE + REVIEW) -- unchanged from linear pipeline |
| `auto` | Create ANALYZE-001 + DESIGN-001 only. **Defer branch creation to CP-2.5** after design completes |
| `fan-out` | Create ANALYZE-001 + DESIGN-001 only. **Defer branch creation to CP-2.5** after design completes |
| `independent` | Create M complete pipelines immediately (one per target) |
---
### Single Mode Task Chain
Create tasks in dependency order (backward compatible, unchanged):
**ANALYZE-001** (analyzer, Stage 1):
```json
{
"ANALYZE-001": {
"title": "Analyze codebase architecture",
"description": "PURPOSE: Analyze codebase architecture to identify structural issues | Success: Baseline metrics captured, top 3-7 issues ranked by severity\nTASK:\n - Detect project type and available analysis tools\n - Execute analysis across relevant dimensions (dependencies, coupling, cohesion, layering, duplication, dead code)\n - Collect baseline metrics and rank architecture issues by severity\nCONTEXT:\n - Session: <session-folder>\n - Scope: <refactoring-scope>\n - Branch: none\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/architecture-baseline.json + <session>/artifacts/architecture-report.md | Quantified metrics with evidence\nCONSTRAINTS: Focus on <refactoring-scope> | Analyze before any changes\n---\nInnerLoop: false",
"role": "analyzer",
"prefix": "ANALYZE",
"deps": [],
"status": "pending",
"findings": null,
"error": null
}
}
```
**DESIGN-001** (designer, Stage 2):
```json
{
"DESIGN-001": {
"title": "Design prioritized refactoring plan",
"description": "PURPOSE: Design prioritized refactoring plan from architecture analysis | Success: Actionable plan with measurable success criteria per refactoring\nTASK:\n - Analyze architecture report and baseline metrics\n - Select refactoring strategies per issue type\n - Prioritize by impact/effort ratio, define success criteria\n - Each refactoring MUST have a unique REFACTOR-ID (REFACTOR-001, REFACTOR-002, ...) with non-overlapping target files\nCONTEXT:\n - Session: <session-folder>\n - Scope: <refactoring-scope>\n - Branch: none\n - Upstream artifacts: architecture-baseline.json, architecture-report.md\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/refactoring-plan.md | Priority-ordered with structural improvement targets, discrete REFACTOR-IDs\nCONSTRAINTS: Focus on highest-impact refactorings | Risk assessment required | Non-overlapping file targets per REFACTOR-ID\n---\nInnerLoop: false",
"role": "designer",
"prefix": "DESIGN",
"deps": ["ANALYZE-001"],
"status": "pending",
"findings": null,
"error": null
}
}
```
**REFACTOR-001** (refactorer, Stage 3):
```json
{
"REFACTOR-001": {
"title": "Implement refactoring changes per design plan",
"description": "PURPOSE: Implement refactoring changes per design plan | Success: All planned refactorings applied, code compiles, existing tests pass\nTASK:\n - Load refactoring plan and identify target files\n - Apply refactorings in priority order (P0 first)\n - Update all import references for moved/renamed modules\n - Validate changes compile and pass existing tests\nCONTEXT:\n - Session: <session-folder>\n - Scope: <refactoring-scope>\n - Branch: none\n - Upstream artifacts: refactoring-plan.md\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: Modified source files + validation passing | Refactorings applied without regressions\nCONSTRAINTS: Preserve existing behavior | Update all references | Follow code conventions\n---\nInnerLoop: true",
"role": "refactorer",
"prefix": "REFACTOR",
"deps": ["DESIGN-001"],
"status": "pending",
"findings": null,
"error": null
}
}
```
**VALIDATE-001** (validator, Stage 4 - parallel):
```json
{
"VALIDATE-001": {
"title": "Validate refactoring results against baseline",
"description": "PURPOSE: Validate refactoring results against baseline | Success: Build passes, tests pass, no metric regressions, API compatible\nTASK:\n - Load architecture baseline and plan success criteria\n - Run build validation (compilation, type checking)\n - Run test validation (existing test suite)\n - Compare dependency metrics against baseline\n - Verify API compatibility (no dangling references)\nCONTEXT:\n - Session: <session-folder>\n - Scope: <refactoring-scope>\n - Branch: none\n - Upstream artifacts: architecture-baseline.json, refactoring-plan.md\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/validation-results.json | Per-dimension validation with verdicts\nCONSTRAINTS: Must compare against baseline | Flag any regressions or broken imports\n---\nInnerLoop: false",
"role": "validator",
"prefix": "VALIDATE",
"deps": ["REFACTOR-001"],
"status": "pending",
"findings": null,
"error": null
}
}
```
**REVIEW-001** (reviewer, Stage 4 - parallel):
```json
{
"REVIEW-001": {
"title": "Review refactoring code for correctness and quality",
"description": "PURPOSE: Review refactoring code for correctness, pattern consistency, and migration safety | Success: All dimensions reviewed, verdict issued\nTASK:\n - Load modified files and refactoring plan\n - Review across 5 dimensions: correctness, pattern consistency, completeness, migration safety, best practices\n - Issue verdict: APPROVE, REVISE, or REJECT with actionable feedback\nCONTEXT:\n - Session: <session-folder>\n - Scope: <refactoring-scope>\n - Branch: none\n - Upstream artifacts: refactoring-plan.md, validation-results.json (if available)\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/review-report.md | Per-dimension findings with severity\nCONSTRAINTS: Focus on refactoring changes only | Provide specific file:line references\n---\nInnerLoop: false",
"role": "reviewer",
"prefix": "REVIEW",
"deps": ["REFACTOR-001"],
"status": "pending",
"findings": null,
"error": null
}
}
```
---
### Auto / Fan-out Mode Task Chain (Deferred Branching)
For `auto` and `fan-out` modes, create only shared stages now. Branch tasks are created at **CP-2.5** after DESIGN-001 completes.
Create ANALYZE-001 and DESIGN-001 with same templates as single mode above.
**Do NOT create REFACTOR/VALIDATE/REVIEW tasks yet.** They are created by the CP-2.5 Branch Creation subroutine in monitor.md.
---
### Independent Mode Task Chain
For `independent` mode, create M complete pipelines -- one per target in `independent_targets` array.
Pipeline prefix chars: `A, B, C, D, E, F, G, H, I, J` (from config `pipeline_prefix_chars`).
For each target index `i` (0-based), with prefix char `P = pipeline_prefix_chars[i]`:
```javascript
// Create session subdirectory for this pipeline
Bash("mkdir -p <session>/artifacts/pipelines/<P>")
// Add pipeline tasks to tasks.json:
state.tasks["ANALYZE-<P>01"] = { title: "...", role: "analyzer", prefix: "ANALYZE", deps: [], ... }
state.tasks["DESIGN-<P>01"] = { title: "...", role: "designer", prefix: "DESIGN", deps: ["ANALYZE-<P>01"], ... }
state.tasks["REFACTOR-<P>01"] = { title: "...", role: "refactorer", prefix: "REFACTOR", deps: ["DESIGN-<P>01"], ... }
state.tasks["VALIDATE-<P>01"] = { title: "...", role: "validator", prefix: "VALIDATE", deps: ["REFACTOR-<P>01"], ... }
state.tasks["REVIEW-<P>01"] = { title: "...", role: "reviewer", prefix: "REVIEW", deps: ["REFACTOR-<P>01"], ... }
```
Task descriptions follow same template as single mode, with additions:
- `Pipeline: <P>` in CONTEXT
- Artifact paths use `<session>/artifacts/pipelines/<P>/` instead of `<session>/artifacts/`
- Meta.json namespace uses `<role>.<P>` (e.g., `analyzer.A`, `refactorer.B`)
- Each pipeline's scope is its specific target from `independent_targets[i]`
Example for pipeline A with target "refactor auth module":
```json
{
"ANALYZE-A01": {
"title": "Analyze auth module architecture",
"description": "PURPOSE: Analyze auth module architecture | Success: Auth module structural issues identified\nTASK:\n - Detect project type and available analysis tools\n - Execute architecture analysis focused on auth module\n - Collect baseline metrics and rank auth module issues\nCONTEXT:\n - Session: <session-folder>\n - Scope: refactor auth module\n - Pipeline: A\n - Shared memory: <session>/wisdom/.msg/meta.json (namespace: analyzer.A)\nEXPECTED: <session>/artifacts/pipelines/A/architecture-baseline.json + architecture-report.md\nCONSTRAINTS: Focus on auth module scope\n---\nInnerLoop: false\nPipelineId: A",
"role": "analyzer",
"prefix": "ANALYZE",
"deps": [],
"status": "pending",
"findings": null,
"error": null
}
}
```
---
### CP-2.5: Branch Creation Subroutine
**Triggered by**: monitor.md handleSpawnNext when DESIGN-001 completes in `auto` or `fan-out` mode.
**Procedure**:
1. Read `<session>/artifacts/refactoring-plan.md` to count REFACTOR-IDs
2. Read `.msg/meta.json` -> `designer.refactoring_count`
3. **Auto mode decision**:
| Refactoring Count | Decision |
|-------------------|----------|
| count <= 2 | Switch to `single` mode -- add REFACTOR-001, VALIDATE-001, REVIEW-001 to tasks.json (standard single pipeline) |
| count >= 3 | Switch to `fan-out` mode -- add branch tasks below |
4. Update tasks.json with resolved `parallel_mode` (auto -> single or fan-out)
5. **Fan-out branch creation** (when count >= 3 or forced fan-out):
- Truncate to `max_branches` if `refactoring_count > max_branches` (keep top N by priority)
- For each refactoring `i` (1-indexed), branch ID = `B{NN}` where NN = zero-padded i:
```javascript
// Create branch artifact directory
Bash("mkdir -p <session>/artifacts/branches/B{NN}")
// Extract single REFACTOR detail to branch
Write("<session>/artifacts/branches/B{NN}/refactoring-detail.md",
extracted REFACTOR-{NNN} block from refactoring-plan.md)
```
6. Add branch tasks to tasks.json for each branch B{NN}:
```json
{
"REFACTOR-B{NN}": {
"title": "Implement refactoring REFACTOR-{NNN}",
"description": "PURPOSE: Implement refactoring REFACTOR-{NNN} | Success: Single refactoring applied, compiles, tests pass\nTASK:\n - Load refactoring detail from branches/B{NN}/refactoring-detail.md\n - Apply this single refactoring to target files\n - Update all import references for moved/renamed modules\n - Validate changes compile and pass existing tests\nCONTEXT:\n - Session: <session-folder>\n - Branch: B{NN}\n - Upstream artifacts: branches/B{NN}/refactoring-detail.md\n - Shared memory: <session>/wisdom/.msg/meta.json (namespace: refactorer.B{NN})\nEXPECTED: Modified source files for REFACTOR-{NNN} only\nCONSTRAINTS: Only implement this branch's refactoring | Do not touch files outside REFACTOR-{NNN} scope\n---\nInnerLoop: false\nBranchId: B{NN}",
"role": "refactorer",
"prefix": "REFACTOR",
"deps": ["DESIGN-001"],
"status": "pending",
"findings": null,
"error": null
},
"VALIDATE-B{NN}": {
"title": "Validate branch B{NN} refactoring",
"description": "PURPOSE: Validate branch B{NN} refactoring | Success: REFACTOR-{NNN} passes build, tests, and metric checks\nTASK:\n - Load architecture baseline and REFACTOR-{NNN} success criteria\n - Validate build, tests, dependency metrics, and API compatibility\n - Compare against baseline, check for regressions\nCONTEXT:\n - Session: <session-folder>\n - Branch: B{NN}\n - Upstream artifacts: architecture-baseline.json, branches/B{NN}/refactoring-detail.md\n - Shared memory: <session>/wisdom/.msg/meta.json (namespace: validator.B{NN})\nEXPECTED: <session>/artifacts/branches/B{NN}/validation-results.json\nCONSTRAINTS: Only validate this branch's changes\n---\nInnerLoop: false\nBranchId: B{NN}",
"role": "validator",
"prefix": "VALIDATE",
"deps": ["REFACTOR-B{NN}"],
"status": "pending",
"findings": null,
"error": null
},
"REVIEW-B{NN}": {
"title": "Review branch B{NN} refactoring code",
"description": "PURPOSE: Review branch B{NN} refactoring code | Success: Code quality verified for REFACTOR-{NNN}\nTASK:\n - Load modified files from refactorer.B{NN} namespace in .msg/meta.json\n - Review across 5 dimensions for this branch's changes only\n - Issue verdict: APPROVE, REVISE, or REJECT\nCONTEXT:\n - Session: <session-folder>\n - Branch: B{NN}\n - Upstream artifacts: branches/B{NN}/refactoring-detail.md\n - Shared memory: <session>/wisdom/.msg/meta.json (namespace: reviewer.B{NN})\nEXPECTED: <session>/artifacts/branches/B{NN}/review-report.md\nCONSTRAINTS: Only review this branch's changes\n---\nInnerLoop: false\nBranchId: B{NN}",
"role": "reviewer",
"prefix": "REVIEW",
"deps": ["REFACTOR-B{NN}"],
"status": "pending",
"findings": null,
"error": null
}
}
```
7. Update tasks.json:
- `branches`: array of branch IDs (["B01", "B02", ...])
- `fix_cycles`: object keyed by branch ID, all initialized to 0
---
## Phase 4: Validation
Verify task chain integrity:
| Check | Method | Expected |
|-------|--------|----------|
| Task count correct | tasks.json task count | single: 5, auto/fan-out: 2 (pre-CP-2.5), independent: 5*M |
| Dependencies correct | Trace dependency graph | Acyclic, correct deps |
| No circular dependencies | Trace dependency graph | Acyclic |
| Task IDs use correct prefixes | Pattern check | Match naming rules per mode |
| Structured descriptions complete | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
| Branch/Pipeline IDs consistent | Cross-check with tasks.json | Match |
### Naming Rules Summary
| Mode | Stage 3 | Stage 4 | Fix |
|------|---------|---------|-----|
| Single | REFACTOR-001 | VALIDATE-001, REVIEW-001 | FIX-001, FIX-002 |
| Fan-out | REFACTOR-B01 | VALIDATE-B01, REVIEW-B01 | FIX-B01-1, FIX-B01-2 |
| Independent | REFACTOR-A01 | VALIDATE-A01, REVIEW-A01 | FIX-A01-1, FIX-A01-2 |
If validation fails, fix the specific task and re-validate.

204
.codex/skills/team-arch-opt/roles/coordinator/commands/monitor.md Normal file
View File

@@ -0,0 +1,204 @@
# Monitor Pipeline
Synchronous pipeline coordination using spawn_agent + wait_agent.
## Constants
- WORKER_AGENT: team_worker
- ONE_STEP_PER_INVOCATION: false (synchronous wait loop)
- FAST_ADVANCE_AWARE: true
## Handler Router
| Source | Handler |
|--------|---------|
| Message contains branch tag [refactorer-B01], etc. | handleSpawnNext (branch-aware) |
| Message contains pipeline tag [analyzer-A], etc. | handleSpawnNext (pipeline-aware) |
| "consensus_blocked" | handleConsensus |
| "capability_gap" | handleAdapt |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
## handleCheck
Read-only status report from tasks.json, then STOP.
1. Read tasks.json
2. Count tasks by status (pending, in_progress, completed, failed)
Output (single mode):
```
[coordinator] Pipeline Status
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active agents: <list from active_agents>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
Fan-out mode adds per-branch grouping. Independent mode adds per-pipeline grouping.
## handleResume
1. Read tasks.json, check active_agents
2. No active agents -> handleSpawnNext
3. Has active agents -> check each status
4. Proceed to handleSpawnNext
## handleSpawnNext
Find ready tasks, spawn workers, wait for completion, process results.
1. Read tasks.json
2. Collect: completedTasks, inProgressTasks, readyTasks (pending + all deps completed)
3. No ready + nothing in progress -> handleComplete
4. No ready + work in progress -> report waiting, STOP
5. Has ready -> for each:
a. Check if inner loop role with active worker -> skip (worker picks up)
b. Update task status in tasks.json -> in_progress
c. team_msg log -> task_unblocked
d. **CP-2.5 check** (auto/fan-out mode only):
- If completed task is DESIGN-001 AND parallel_mode is `auto` or `fan-out`:
- Execute CP-2.5 Branch Creation from dispatch.md
- After branch creation, re-collect readyTasks (spawns all REFACTOR-B* in parallel)
### Spawn Workers
For each ready task:
```javascript
// 1) Update status in tasks.json
state.tasks[taskId].status = 'in_progress'
// 2) Spawn worker
const agentId = spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: ${task.role}
role_spec: ${skillRoot}/roles/${task.role}/role.md
session: ${sessionFolder}
session_id: ${sessionId}
team_name: arch-opt
requirement: ${task.description}
inner_loop: ${task.role === 'refactorer'}` },
{ type: "text", text: `Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` },
{ type: "text", text: `## Task Context
task_id: ${taskId}
title: ${task.title}
description: ${task.description}` },
{ type: "text", text: `## Upstream Context\n${prevContext}` }
]
})
// 3) Track agent
state.active_agents[taskId] = { agentId, role: task.role, started_at: now }
```
6. Parallel spawn rules by mode:
| Mode | Scenario | Spawn Behavior |
|------|----------|---------------|
| Single | Stage 4 ready | Spawn VALIDATE-001 + REVIEW-001 in parallel |
| Fan-out (CP-2.5 done) | All REFACTOR-B* unblocked | Spawn ALL REFACTOR-B* in parallel |
| Fan-out (REFACTOR-B{NN} done) | VALIDATE + REVIEW ready | Spawn both for that branch in parallel |
| Independent | Any unblocked task | Spawn all ready tasks across all pipelines in parallel |
### Wait and Process Results
After spawning all ready tasks:
```javascript
// 4) Batch wait for all spawned workers
const agentIds = Object.values(state.active_agents).map(a => a.agentId)
wait_agent({ ids: agentIds, timeout_ms: 900000 })
// 5) Collect results
for (const [taskId, agent] of Object.entries(state.active_agents)) {
state.tasks[taskId].status = 'completed'
close_agent({ id: agent.agentId })
delete state.active_agents[taskId]
}
```
### Persist and Loop
After processing all results:
1. Write updated tasks.json
2. Check stage checkpoints (CP-1, CP-2, CP-2.5, CP-3)
3. Check if more tasks are now ready (deps newly resolved)
4. If yes -> loop back to step 1 of handleSpawnNext
5. If no more ready and all done -> handleComplete
6. If no more ready but some still blocked -> report status, STOP
## Review-Fix Cycle (CP-3)
**Per-branch/pipeline scoping**: Each branch/pipeline has its own independent fix cycle.
When both VALIDATE-* and REVIEW-* are completed for a branch/pipeline:
1. Read validation verdict from scoped meta.json namespace
2. Read review verdict from scoped meta.json namespace
| Validate Verdict | Review Verdict | Action |
|-----------------|----------------|--------|
| PASS | APPROVE | -> handleComplete check |
| PASS | REVISE | Create FIX task in tasks.json with review feedback |
| FAIL | APPROVE | Create FIX task in tasks.json with validation feedback |
| FAIL | REVISE/REJECT | Create FIX task in tasks.json with combined feedback |
| Any | REJECT | Create FIX task in tasks.json + flag for designer re-evaluation |
Fix cycle tracking per branch in tasks.json `fix_cycles`:
- < 3: Add FIX task to tasks.json, increment cycle count
- >= 3: Escalate THIS branch to user. Other branches continue
## handleComplete
Pipeline done. Generate report and completion action.
Completion check by mode:
| Mode | Completion Condition |
|------|---------------------|
| Single | All 5 tasks (+ any FIX/retry tasks) completed |
| Fan-out | ALL branches have VALIDATE + REVIEW completed (or escalated), shared stages done |
| Independent | ALL pipelines have VALIDATE + REVIEW completed (or escalated) |
1. For fan-out/independent: aggregate per-branch/pipeline results to `<session>/artifacts/aggregate-results.json`
2. If any tasks not completed, return to handleSpawnNext
3. If all completed -> transition to coordinator Phase 5
4. Execute completion action per tasks.json completion_action:
- interactive -> request_user_input (Archive/Keep/Export)
- auto_archive -> Archive & Clean (rm -rf session folder)
- auto_keep -> Keep Active (status=paused)
## handleConsensus
Handle consensus_blocked signals from discuss rounds.
| Severity | Action |
|----------|--------|
| HIGH | Pause pipeline (or branch), notify user with findings summary |
| MEDIUM | Add revision task to tasks.json for the blocked role (scoped to branch if applicable) |
| LOW | Log finding, continue pipeline |
## handleAdapt
Capability gap reported mid-pipeline.
1. Parse gap description
2. Check if existing role covers it -> redirect
3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/
4. Add new task to tasks.json, spawn worker via spawn_agent + wait_agent
5. Role count >= 5 -> merge or pause
## Fast-Advance Reconciliation
On every coordinator wake:
1. Read team_msg entries with type="fast_advance"
2. Sync active_agents with spawned successors
3. No duplicate spawns

162
.codex/skills/team-arch-opt/roles/coordinator/role.md Normal file
View File

@@ -0,0 +1,162 @@
# Coordinator
Orchestrate team-arch-opt: analyze -> dispatch -> spawn -> monitor -> report.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Spawn workers via `spawn_agent({ agent_type: "team_worker" })` and wait via `wait_agent`
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (deps)
- Handle review-fix cycles with max 3 iterations
- Execute completion action in Phase 5
### MUST NOT
- Implement domain logic (analyzing, refactoring, reviewing) -- workers handle this
- Spawn workers without creating tasks first
- Skip checkpoints when configured
- Force-advance pipeline past failed review/validation
- Modify source code directly -- delegate to refactorer worker
## Command Execution Protocol
When coordinator needs to execute a specific phase:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active session in .workflow/.team/TAO-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
1. Scan `.workflow/.team/TAO-*/tasks.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile:
a. Read tasks.json, reset in_progress -> pending
b. Rebuild active_agents map
c. Kick first ready task via handleSpawnNext
4. Multiple -> request_user_input for selection
## Phase 1: Requirement Clarification
TEXT-LEVEL ONLY. No source code reading.
1. Parse task description from $ARGUMENTS
2. Parse parallel mode flags:
| Flag | Value | Default |
|------|-------|---------|
| `--parallel-mode` | `single`, `fan-out`, `independent`, `auto` | `auto` |
| `--max-branches` | integer 1-10 | 5 |
3. Identify architecture optimization target:
| Signal | Target |
|--------|--------|
| Specific file/module mentioned | Scoped refactoring |
| "coupling", "dependency", "structure", generic | Full architecture analysis |
| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
| Multiple quoted targets (independent mode) | Per-target scoped refactoring |
4. If target is unclear, request_user_input for scope clarification
5. Record requirement with scope, target issues, parallel_mode, max_branches
## Phase 2: Create Session + Initialize
1. Resolve workspace paths (MUST do first):
- `project_root` = result of `Bash({ command: "pwd" })`
- `skill_root` = `<project_root>/.codex/skills/team-arch-opt`
2. Generate session ID: `TAO-<slug>-<date>`
3. Create session folder structure:
```bash
mkdir -p .workflow/.team/${SESSION_ID}/{artifacts,artifacts/branches,artifacts/pipelines,wisdom,wisdom/.msg}
```
4. Initialize meta.json via team_msg state_update:
```
mcp__ccw-tools__team_msg({
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: { pipeline_mode: "<mode>", pipeline_stages: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
})
```
5. Write initial tasks.json:
```json
{
"session_id": "<id>",
"pipeline": "<parallel_mode>",
"requirement": "<original requirement>",
"created_at": "<ISO timestamp>",
"parallel_mode": "<single|fan-out|independent|auto>",
"max_branches": 5,
"branches": [],
"independent_targets": [],
"fix_cycles": {},
"completed_waves": [],
"active_agents": {},
"tasks": {}
}
```
## Phase 3: Create Task Chain
Delegate to @commands/dispatch.md:
1. Read dependency graph and parallel mode from tasks.json
2. Topological sort tasks
3. Write tasks to tasks.json with deps arrays
4. Update tasks.json metadata (total count)
## Phase 4: Spawn-and-Wait
Delegate to @commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + deps resolved)
2. Spawn team_worker agents via spawn_agent
3. Wait for completion via wait_agent
4. Process results, advance pipeline
5. Repeat until all waves complete or pipeline blocked
## Phase 5: Report + Completion Action
1. Load session state -> count completed tasks, calculate duration
2. List deliverables:
| Deliverable | Path |
|-------------|------|
| Architecture Baseline | <session>/artifacts/architecture-baseline.json |
| Architecture Report | <session>/artifacts/architecture-report.md |
| Refactoring Plan | <session>/artifacts/refactoring-plan.md |
| Validation Results | <session>/artifacts/validation-results.json |
| Review Report | <session>/artifacts/review-report.md |
3. Include discussion summaries if discuss rounds were used
4. Output pipeline summary: task count, duration, improvement metrics
5. Execute completion action per tasks.json completion_action:
- interactive -> request_user_input (Archive/Keep/Export)
- auto_archive -> Archive & Clean (rm -rf session folder)
- auto_keep -> Keep Active (status=paused)
## Error Handling
| Error | Resolution |
|-------|------------|
| Task too vague | request_user_input for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
| Dependency cycle | Detect in analysis, halt |
| Role limit exceeded | Merge overlapping roles |

115
.codex/skills/team-arch-opt/roles/designer/role.md Normal file
View File

@@ -0,0 +1,115 @@
---
role: designer
prefix: DESIGN
inner_loop: false
message_types: [state_update]
---
# Refactoring Designer
Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.
## Phase 2: Analysis Loading
| Input | Source | Required |
|-------|--------|----------|
| Architecture report | <session>/artifacts/architecture-report.md | Yes |
| Architecture baseline | <session>/artifacts/architecture-baseline.json | Yes |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
| Wisdom files | <session>/wisdom/patterns.md | No |
1. Extract session path from task description
2. Read architecture report -- extract ranked issue list with severities and categories
3. Read architecture baseline -- extract current structural metrics
4. Load .msg/meta.json for analyzer findings (project_type, scope)
5. Assess overall refactoring complexity:
| Issue Count | Severity Mix | Complexity |
|-------------|-------------|------------|
| 1-2 | All Medium | Low |
| 2-3 | Mix of High/Medium | Medium |
| 3+ or any Critical | Any Critical present | High |
## Phase 3: Strategy Formulation
For each architecture issue, select refactoring approach by type:
| Issue Type | Strategies | Risk Level |
|------------|-----------|------------|
| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High |
| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High |
| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium |
| Code duplication | Extract shared utility/base class, template method pattern | Low |
| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium |
| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low |
| Dead code | Safe removal with reference verification | Low |
| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium |
Prioritize refactorings by impact/effort ratio:
| Priority | Criteria |
|----------|----------|
| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) |
| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) |
| P2 (Medium) | Medium impact + Low effort (duplication extraction) |
| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) |
If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
Define measurable success criteria per refactoring (target metric improvement or structural change).
## Phase 4: Plan Output
1. Write refactoring plan to `<session>/artifacts/refactoring-plan.md`:
Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:
```markdown
### REFACTOR-001: <title>
- Priority: P0
- Target issue: <issue from report>
- Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
- Target files: <file-list>
- Strategy: <selected approach>
- Expected improvement: <metric> by <description>
- Risk level: <Low/Medium/High>
- Success criteria: <specific structural change to verify>
- Implementation guidance:
1. <step 1>
2. <step 2>
3. <step 3>
### REFACTOR-002: <title>
...
```
Requirements:
- Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
- Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
- Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others
2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
- Read existing -> merge -> write back:
```json
{
"designer": {
"complexity": "<Low|Medium|High>",
"refactoring_count": 4,
"priorities": ["P0", "P0", "P1", "P2"],
"discuss_used": false,
"refactorings": [
{
"id": "REFACTOR-001",
"title": "<title>",
"issue_type": "<CYCLE|COUPLING|...>",
"priority": "P0",
"target_files": ["src/a.ts", "src/b.ts"],
"expected_improvement": "<metric> by <description>",
"success_criteria": "<threshold>"
}
]
}
}
```
3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md`

102
.codex/skills/team-arch-opt/roles/refactorer/role.md Normal file
View File

@@ -0,0 +1,102 @@
---
role: refactorer
prefix: REFACTOR
inner_loop: true
message_types: [state_update]
---
# Code Refactorer
Implement architecture refactoring changes following the design plan. For FIX tasks, apply targeted corrections based on review/validation feedback.
## Modes
| Mode | Task Prefix | Trigger | Focus |
|------|-------------|---------|-------|
| Refactor | REFACTOR | Design plan ready | Apply refactorings per plan priority |
| Fix | FIX | Review/validation feedback | Targeted fixes for identified issues |
## Phase 2: Plan & Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Refactoring plan | <session>/artifacts/refactoring-plan.md | Yes (REFACTOR, no branch) |
| Branch refactoring detail | <session>/artifacts/branches/B{NN}/refactoring-detail.md | Yes (REFACTOR with branch) |
| Pipeline refactoring plan | <session>/artifacts/pipelines/{P}/refactoring-plan.md | Yes (REFACTOR with pipeline) |
| Review/validation feedback | From task description | Yes (FIX) |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
| Wisdom files | <session>/wisdom/patterns.md | No |
| Context accumulator | From prior REFACTOR/FIX tasks | Yes (inner loop) |
1. Extract session path and task mode (REFACTOR or FIX) from task description
2. **Detect branch/pipeline context** from task description:
| Task Description Field | Value | Context |
|----------------------|-------|---------|
| `BranchId: B{NN}` | Present | Fan-out branch -- load single refactoring detail |
| `PipelineId: {P}` | Present | Independent pipeline -- load pipeline-scoped plan |
| Neither present | - | Single mode -- load full refactoring plan |
3. **Load refactoring context by mode**:
- **Single mode (no branch)**: Read `<session>/artifacts/refactoring-plan.md` -- extract ALL priority-ordered changes
- **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- extract ONLY this branch's refactoring (single REFACTOR-ID)
- **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md` -- extract this pipeline's plan
4. For FIX: parse review/validation feedback for specific issues to address
5. Use `explore` CLI tool to load implementation context for target files
6. For inner loop (single mode only): load context_accumulator from prior REFACTOR/FIX tasks
**Meta.json namespace**:
- Single: write to `refactorer` namespace
- Fan-out: write to `refactorer.B{NN}` namespace
- Independent: write to `refactorer.{P}` namespace
## Phase 3: Code Implementation
Implementation backend selection:
| Backend | Condition | Method |
|---------|-----------|--------|
| CLI | Multi-file refactoring with clear plan | ccw cli --tool gemini --mode write |
| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools |
For REFACTOR tasks:
- **Single mode**: Apply refactorings in plan priority order (P0 first, then P1, etc.)
- **Fan-out branch**: Apply ONLY this branch's single refactoring (from refactoring-detail.md)
- **Independent pipeline**: Apply this pipeline's refactorings in priority order
- Follow implementation guidance from plan (target files, patterns)
- **Preserve existing behavior -- refactoring must not change functionality**
- **Update ALL import references** when moving/renaming modules
- **Update ALL test files** that reference moved/renamed symbols
For FIX tasks:
- Read specific issues from review/validation feedback
- Apply targeted corrections to flagged code locations
- Verify the fix addresses the exact concern raised
General rules:
- Make minimal, focused changes per refactoring
- Add comments only where refactoring logic is non-obvious
- Preserve existing code style and conventions
- Verify no dangling imports after module moves
## Phase 4: Self-Validation
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Syntax | IDE diagnostics or build check | No new errors |
| File integrity | Verify all planned files exist and are modified | All present |
| Import integrity | Verify no broken imports after moves | All imports resolve |
| Acceptance | Match refactoring plan success criteria | All structural changes applied |
| No regression | Run existing tests if available | No new failures |
If validation fails, attempt auto-fix (max 2 attempts) before reporting error.
Append to context_accumulator for next REFACTOR/FIX task (single/inner-loop mode only):
- Files modified, refactorings applied, validation results
- Any discovered patterns or caveats for subsequent iterations
**Branch output paths**:
- Single: write artifacts to `<session>/artifacts/`
- Fan-out: write artifacts to `<session>/artifacts/branches/B{NN}/`
- Independent: write artifacts to `<session>/artifacts/pipelines/{P}/`

111
.codex/skills/team-arch-opt/roles/reviewer/role.md Normal file
View File

@@ -0,0 +1,111 @@
---
role: reviewer
prefix: REVIEW
inner_loop: false
message_types: [state_update]
---
# Architecture Reviewer
Review refactoring code changes for correctness, pattern consistency, completeness, migration safety, and adherence to best practices. Provide structured verdicts with actionable feedback.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Refactoring code changes | From REFACTOR task artifacts / git diff | Yes |
| Refactoring plan / detail | Varies by mode (see below) | Yes |
| Validation results | Varies by mode (see below) | No |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
1. Extract session path from task description
2. **Detect branch/pipeline context** from task description:
| Task Description Field | Value | Context |
|----------------------|-------|---------|
| `BranchId: B{NN}` | Present | Fan-out branch -- review only this branch's changes |
| `PipelineId: {P}` | Present | Independent pipeline -- review pipeline-scoped changes |
| Neither present | - | Single mode -- review all refactoring changes |
3. **Load refactoring context by mode**:
- Single: Read `<session>/artifacts/refactoring-plan.md`
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md`
- Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
4. Load .msg/meta.json for scoped refactorer namespace:
- Single: `refactorer` namespace
- Fan-out: `refactorer.B{NN}` namespace
- Independent: `refactorer.{P}` namespace
5. Identify changed files from refactorer context -- read ONLY files modified by this branch/pipeline
6. If validation results available, read from scoped path:
- Single: `<session>/artifacts/validation-results.json`
- Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
- Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
## Phase 3: Multi-Dimension Review
Analyze refactoring changes across five dimensions:
| Dimension | Focus | Severity |
|-----------|-------|----------|
| Correctness | No behavior changes, all references updated, no dangling imports | Critical |
| Pattern consistency | Follows existing patterns, naming consistent, language-idiomatic | High |
| Completeness | All related code updated (imports, tests, config, documentation) | High |
| Migration safety | No dangling references, backward compatible, public API preserved | Critical |
| Best practices | Clean Architecture / SOLID principles, appropriate abstraction level | Medium |
Per-dimension review process:
- Scan modified files for patterns matching each dimension
- Record findings with severity (Critical / High / Medium / Low)
- Include specific file:line references and suggested fixes
**Correctness checks**:
- Verify moved code preserves original behavior (no logic changes mixed with structural changes)
- Check all import/require statements updated to new paths
- Verify no orphaned files left behind after moves
**Pattern consistency checks**:
- New module names follow existing naming conventions
- Extracted interfaces/classes use consistent patterns with existing codebase
- File organization matches project conventions (e.g., index files, barrel exports)
**Completeness checks**:
- All test files updated for moved/renamed modules
- Configuration files updated if needed (e.g., path aliases, build configs)
- Type definitions updated for extracted interfaces
**Migration safety checks**:
- Public API surface unchanged (same exports available to consumers)
- No circular dependencies introduced by the refactoring
- Re-exports in place if module paths changed for backward compatibility
**Best practices checks**:
- Extracted modules have clear single responsibility
- Dependency direction follows layer conventions (dependencies flow inward)
- Appropriate abstraction level (not over-engineered, not under-abstracted)
If any Critical findings detected, invoke `discuss` CLI tool (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
## Phase 4: Verdict & Feedback
Classify overall verdict based on findings:
| Verdict | Condition | Action |
|---------|-----------|--------|
| APPROVE | No Critical or High findings | Send review_complete |
| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback |
| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for designer escalation |
1. Write review report to scoped output path:
- Single: `<session>/artifacts/review-report.md`
- Fan-out: `<session>/artifacts/branches/B{NN}/review-report.md`
- Independent: `<session>/artifacts/pipelines/{P}/review-report.md`
- Content: Per-dimension findings with severity, file:line, description; Overall verdict with rationale; Specific fix instructions for REVISE/REJECT verdicts
2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
- Single: merge `{ "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }`
- Fan-out: merge `{ "reviewer.B{NN}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
- Independent: merge `{ "reviewer.{P}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
3. If DISCUSS-REVIEW was triggered, record discussion summary in `<session>/discussions/DISCUSS-REVIEW.md` (or `DISCUSS-REVIEW-B{NN}.md` for branch-scoped discussions)

115
.codex/skills/team-arch-opt/roles/validator/role.md Normal file
View File

@@ -0,0 +1,115 @@
---
role: validator
prefix: VALIDATE
inner_loop: false
message_types: [state_update]
---
# Architecture Validator
Validate refactoring changes by running build checks, test suites, dependency metric comparisons, and API compatibility verification. Ensure refactoring improves architecture without breaking functionality.
## Phase 2: Environment & Baseline Loading
| Input | Source | Required |
|-------|--------|----------|
| Architecture baseline | <session>/artifacts/architecture-baseline.json (shared) | Yes |
| Refactoring plan / detail | Varies by mode (see below) | Yes |
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
1. Extract session path from task description
2. **Detect branch/pipeline context** from task description:
| Task Description Field | Value | Context |
|----------------------|-------|---------|
| `BranchId: B{NN}` | Present | Fan-out branch -- validate only this branch's changes |
| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline |
| Neither present | - | Single mode -- full validation |
3. **Load architecture baseline**:
- Single / Fan-out: Read `<session>/artifacts/architecture-baseline.json` (shared baseline)
- Independent: Read `<session>/artifacts/pipelines/{P}/architecture-baseline.json`
4. **Load refactoring context**:
- Single: Read `<session>/artifacts/refactoring-plan.md` -- all success criteria
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- only this branch's criteria
- Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
5. Load .msg/meta.json for project type and refactoring scope
6. Detect available validation tools from project:
| Signal | Validation Tool | Method |
|--------|----------------|--------|
| package.json + tsc | TypeScript compiler | Type-check entire project |
| package.json + vitest/jest | Test runner | Run existing test suite |
| package.json + eslint | Linter | Run lint checks for import/export issues |
| Cargo.toml | Rust compiler | cargo check + cargo test |
| go.mod | Go tools | go build + go test |
| Makefile with test target | Custom tests | make test |
| No tooling detected | Manual validation | File existence + import grep checks |
7. Get changed files scope from .msg/meta.json:
- Single: `refactorer` namespace
- Fan-out: `refactorer.B{NN}` namespace
- Independent: `refactorer.{P}` namespace
## Phase 3: Validation Execution
Run validations across four dimensions:
**Build validation**:
- Compile/type-check the project -- zero new errors allowed
- Verify all moved/renamed files are correctly referenced
- Check for missing imports or unresolved modules
**Test validation**:
- Run existing test suite -- all previously passing tests must still pass
- Identify any tests that need updating due to module moves (update, don't skip)
- Check for test file imports that reference old paths
**Dependency metric validation**:
- Recalculate architecture metrics post-refactoring
- Compare coupling scores against baseline (must improve or stay neutral)
- Verify no new circular dependencies introduced
- Check cohesion metrics for affected modules
**API compatibility validation**:
- Verify public API signatures are preserved (exported function/class/type names)
- Check for dangling references (imports pointing to removed/moved files)
- Verify no new dead exports introduced by the refactoring
- Check that re-exports maintain backward compatibility where needed
**Branch-scoped validation** (fan-out mode):
- Only validate metrics relevant to this branch's refactoring (from refactoring-detail.md)
- Still check for regressions across all metrics (not just branch-specific ones)
## Phase 4: Result Analysis
Compare against baseline and plan criteria:
| Metric | Threshold | Verdict |
|--------|-----------|---------|
| Build passes | Zero compilation errors | PASS |
| All tests pass | No new test failures | PASS |
| Coupling improved or neutral | No metric degradation > 5% | PASS |
| No new cycles introduced | Cycle count <= baseline | PASS |
| All plan success criteria met | Every criterion satisfied | PASS |
| Partial improvement | Some metrics improved, none degraded | WARN |
| Build fails | Compilation errors detected | FAIL -> fix_required |
| Test failures | Previously passing tests now fail | FAIL -> fix_required |
| New cycles introduced | Cycle count > baseline | FAIL -> fix_required |
| Dangling references | Unresolved imports detected | FAIL -> fix_required |
1. Write validation results to output path:
- Single: `<session>/artifacts/validation-results.json`
- Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
- Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
- Content: Per-dimension: name, baseline value, current value, improvement/regression, verdict; Overall verdict: PASS / WARN / FAIL; Failure details (if any)
2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
- Single: merge `{ "validator": { verdict, improvements, regressions, build_pass, test_pass } }`
- Fan-out: merge `{ "validator.B{NN}": { verdict, improvements, regressions, build_pass, test_pass } }`
- Independent: merge `{ "validator.{P}": { verdict, improvements, regressions, build_pass, test_pass } }`
3. If verdict is FAIL, include detailed feedback in message for FIX task creation:
- Which validations failed, specific errors, suggested investigation areas

174
.codex/skills/team-arch-opt/schemas/tasks-schema.md
View File

@@ -1,174 +0,0 @@
# Team Architecture Optimization -- CSV Schema
## Master CSV: tasks.csv
### Column Definitions
#### Input Columns (Set by Decomposer)
| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `id` | string | Yes | Unique task identifier (PREFIX-NNN) | `"ANALYZE-001"` |
| `title` | string | Yes | Short task title | `"Analyze architecture"` |
| `description` | string | Yes | Detailed task description (self-contained) with goal, inputs, outputs, success criteria | `"Analyze codebase architecture..."` |
| `role` | enum | Yes | Worker role: `analyzer`, `designer`, `refactorer`, `validator`, `reviewer` | `"analyzer"` |
| `issue_type` | string | No | Architecture issue category: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT | `"CYCLE"` |
| `priority` | enum | No | P0 (Critical), P1 (High), P2 (Medium), P3 (Low) | `"P0"` |
| `target_files` | string | No | Semicolon-separated file paths to focus on | `"src/auth/index.ts;src/user/index.ts"` |
| `deps` | string | No | Semicolon-separated dependency task IDs | `"ANALYZE-001"` |
| `context_from` | string | No | Semicolon-separated task IDs for context | `"ANALYZE-001"` |
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
#### 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) | `"[ANALYZE-001] Found 5 architecture issues..."` |
#### Output Columns (Set by Agent)
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` |
| `findings` | string | Key discoveries (max 500 chars) | `"Found 3 circular deps, 2 God Classes..."` |
| `verdict` | string | Validation/review verdict: PASS, WARN, FAIL, APPROVE, REVISE, REJECT | `"PASS"` |
| `artifacts_produced` | string | Semicolon-separated paths of produced artifacts | `"artifacts/architecture-report.md"` |
| `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.
---
### Role Prefix Mapping
| Role | Prefix | Stage | Responsibility |
|------|--------|-------|----------------|
| analyzer | ANALYZE | 1 | Architecture analysis, baseline metrics, issue identification |
| designer | DESIGN | 2 | Refactoring plan design, strategy selection, prioritization |
| refactorer | REFACTOR / FIX | 3 | Code implementation, refactoring application, targeted fixes |
| validator | VALIDATE | 4 | Build checks, test suite, metric validation, API compatibility |
| reviewer | REVIEW | 4 | Code review for correctness, patterns, completeness, safety |
---
### Example Data
```csv
id,title,description,role,issue_type,priority,target_files,deps,context_from,exec_mode,wave,status,findings,verdict,artifacts_produced,error
"ANALYZE-001","Analyze architecture","PURPOSE: Analyze codebase architecture to identify structural issues\nTASK:\n- Build import graph, detect circular deps\n- Identify God Classes (>500 LOC, >10 methods)\n- Calculate coupling/cohesion metrics\n- Detect dead code and dead exports\nINPUT: Codebase under target scope\nOUTPUT: artifacts/architecture-baseline.json + artifacts/architecture-report.md\nSUCCESS: Ranked issue list with severity, baseline metrics collected\nSESSION: .workflow/.csv-wave/tao-example-20260308","analyzer","","","","","","csv-wave","1","pending","","","",""
"DESIGN-001","Design refactoring plan","PURPOSE: Design prioritized refactoring plan from architecture report\nTASK:\n- For each issue, select refactoring strategy\n- Prioritize by impact/effort ratio (P0-P3)\n- Define measurable success criteria per refactoring\n- Assign unique REFACTOR-IDs with non-overlapping file targets\nINPUT: artifacts/architecture-report.md + artifacts/architecture-baseline.json\nOUTPUT: artifacts/refactoring-plan.md\nSUCCESS: Prioritized plan with self-contained REFACTOR blocks\nSESSION: .workflow/.csv-wave/tao-example-20260308","designer","","","","ANALYZE-001","ANALYZE-001","csv-wave","2","pending","","","",""
"REFACTOR-001","Implement refactorings","PURPOSE: Implement architecture refactoring changes per plan\nTASK:\n- Apply refactorings in priority order (P0 first)\n- Update all import references when moving/renaming\n- Update all test files referencing moved symbols\n- Preserve existing behavior\nINPUT: artifacts/refactoring-plan.md\nOUTPUT: Modified source files\nSUCCESS: All planned structural changes applied, no dangling imports\nSESSION: .workflow/.csv-wave/tao-example-20260308","refactorer","","","","DESIGN-001","DESIGN-001","csv-wave","3","pending","","","",""
"VALIDATE-001","Validate refactoring","PURPOSE: Validate refactoring improves architecture without breaking functionality\nTASK:\n- Build check: zero new compilation errors\n- Test suite: all previously passing tests still pass\n- Metrics: coupling improved or neutral, no new cycles\n- API: public signatures preserved\nINPUT: artifacts/architecture-baseline.json + artifacts/refactoring-plan.md\nOUTPUT: artifacts/validation-results.json\nSUCCESS: All dimensions PASS\nSESSION: .workflow/.csv-wave/tao-example-20260308","validator","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","","",""
"REVIEW-001","Review refactoring code","PURPOSE: Review refactoring changes for correctness and quality\nTASK:\n- Correctness: no behavior changes, all references updated\n- Pattern consistency: follows existing conventions\n- Completeness: imports, tests, configs all updated\n- Migration safety: no dangling refs, backward compatible\n- Best practices: SOLID principles, appropriate abstraction\nINPUT: artifacts/refactoring-plan.md + changed files\nOUTPUT: artifacts/review-report.md\nSUCCESS: APPROVE verdict (no Critical/High findings)\nSESSION: .workflow/.csv-wave/tao-example-20260308","reviewer","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","","",""
```
---
### Column Lifecycle
```
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
--------------------- -------------------- -----------------
id ----------> id ----------> id
title ----------> title ----------> (reads)
description ----------> description ----------> (reads)
role ----------> role ----------> (reads)
issue_type ----------> issue_type ----------> (reads)
priority ----------> priority ----------> (reads)
target_files----------> target_files----------> (reads)
deps ----------> deps ----------> (reads)
context_from----------> context_from----------> (reads)
exec_mode ----------> exec_mode ----------> (reads)
wave ----------> (reads)
prev_context ----------> (reads)
status
findings
verdict
artifacts_produced
error
```
---
## Output Schema (JSON)
Agent output via `report_agent_job_result` (csv-wave tasks):
```json
{
"id": "ANALYZE-001",
"status": "completed",
"findings": "Found 5 architecture issues: 2 circular deps (auth<->user, service<->repo), 1 God Class (UserManager 850 LOC), 1 dead code cluster (src/legacy/), 1 API bloat (utils/ exports 45 symbols, 12 unused).",
"verdict": "",
"artifacts_produced": "artifacts/architecture-baseline.json;artifacts/architecture-report.md",
"error": ""
}
```
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
---
## Discovery Types
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `cycle_found` | `data.modules` (sorted) | `{modules, depth, description}` | Circular dependency detected |
| `god_class_found` | `data.file` | `{file, loc, methods, description}` | God Class/Module identified |
| `coupling_issue` | `data.module` | `{module, fan_in, fan_out, description}` | High coupling detected |
| `dead_code_found` | `data.file+data.type` | `{file, type, description}` | Dead code or dead export |
| `layer_violation` | `data.from+data.to` | `{from, to, description}` | Layering violation detected |
| `file_modified` | `data.file` | `{file, change, lines_added}` | File change recorded |
| `pattern_found` | `data.pattern_name+data.location` | `{pattern_name, location, description}` | Code pattern identified |
| `metric_measured` | `data.metric+data.module` | `{metric, value, unit, module}` | Architecture metric measured |
| `artifact_produced` | `data.path` | `{name, path, producer, type}` | Deliverable created |
### Discovery NDJSON Format
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"ANALYZE-001","type":"cycle_found","data":{"modules":["auth","user"],"depth":2,"description":"Circular dependency: auth imports user, user imports auth"}}
{"ts":"2026-03-08T10:01:00Z","worker":"ANALYZE-001","type":"god_class_found","data":{"file":"src/services/UserManager.ts","loc":850,"methods":15,"description":"UserManager handles auth, profile, permissions, notifications"}}
{"ts":"2026-03-08T10:05:00Z","worker":"ANALYZE-001","type":"metric_measured","data":{"metric":"coupling_score","value":0.72,"unit":"normalized","module":"src/auth/"}}
{"ts":"2026-03-08T10:20:00Z","worker":"REFACTOR-001","type":"file_modified","data":{"file":"src/auth/index.ts","change":"Extracted IAuthService interface to break cycle","lines_added":25}}
{"ts":"2026-03-08T10:25:00Z","worker":"REFACTOR-001","type":"artifact_produced","data":{"name":"refactoring-summary","path":"artifacts/refactoring-plan.md","producer":"designer","type":"markdown"}}
```
> 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 in {pending, completed, failed, skipped} | "Invalid status: {status}" |
| Role valid | role in {analyzer, designer, refactorer, validator, reviewer} | "Invalid role: {role}" |
| Verdict enum | verdict in {PASS, WARN, FAIL, APPROVE, REVISE, REJECT, ""} | "Invalid verdict: {verdict}" |
| Cross-mechanism deps | Interactive to CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |

102
.codex/skills/team-arch-opt/specs/pipelines.md Normal file
View File

@@ -0,0 +1,102 @@
# Pipeline Definitions — team-arch-opt
## Available Pipelines
### Single Mode (Linear)
```
ANALYZE-001 → DESIGN-001 → REFACTOR-001 → VALIDATE-001 + REVIEW-001
[analyzer] [designer] [refactorer] [validator] [reviewer]
^ |
+<-- FIX-001 ----+
(max 3 iterations)
```
### Fan-out Mode (Shared Stages + Parallel Branches)
```
ANALYZE-001 → DESIGN-001 --+→ REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
[analyzer] [designer] | [refactorer] [validator] [reviewer]
+→ REFACTOR-B02 → VALIDATE-B02 + REVIEW-B02
+→ REFACTOR-B0N → VALIDATE-B0N + REVIEW-B0N
|
AGGREGATE → Phase 5
```
Branch tasks created at CP-2.5 after DESIGN-001 completes.
### Independent Mode (M Complete Pipelines)
```
Pipeline A: ANALYZE-A01 → DESIGN-A01 → REFACTOR-A01 → VALIDATE-A01 + REVIEW-A01
Pipeline B: ANALYZE-B01 → DESIGN-B01 → REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
... |
AGGREGATE → Phase 5
```
### Auto Mode
Auto-detects based on refactoring count at CP-2.5:
- count <= 2 → switch to single mode
- count >= 3 → switch to fan-out mode
## Task Metadata Registry
### Single Mode
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-001 | analyzer | Stage 1 | (none) | Analyze architecture, identify structural issues |
| DESIGN-001 | designer | Stage 2 | ANALYZE-001 | Design refactoring plan from architecture report |
| REFACTOR-001 | refactorer | Stage 3 | DESIGN-001 | Implement highest-priority refactorings |
| VALIDATE-001 | validator | Stage 4 | REFACTOR-001 | Validate build, tests, metrics, API compatibility |
| REVIEW-001 | reviewer | Stage 4 | REFACTOR-001 | Review refactoring code for correctness |
| FIX-001 | refactorer | Stage 3 (cycle) | REVIEW-001 or VALIDATE-001 | Fix issues found in review/validation |
### Fan-out Mode (Branch Tasks at CP-2.5)
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-001 | analyzer | Stage 1 (shared) | (none) | Analyze architecture |
| DESIGN-001 | designer | Stage 2 (shared) | ANALYZE-001 | Design plan with discrete REFACTOR-IDs |
| REFACTOR-B{NN} | refactorer | Stage 3 (branch) | DESIGN-001 | Implement REFACTOR-{NNN} only |
| VALIDATE-B{NN} | validator | Stage 4 (branch) | REFACTOR-B{NN} | Validate branch B{NN} |
| REVIEW-B{NN} | reviewer | Stage 4 (branch) | REFACTOR-B{NN} | Review branch B{NN} |
| FIX-B{NN}-{cycle} | refactorer | Fix (branch) | (none) | Fix issues in branch B{NN} |
### Independent Mode
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| ANALYZE-{P}01 | analyzer | Stage 1 | (none) | Analyze for pipeline {P} target |
| DESIGN-{P}01 | designer | Stage 2 | ANALYZE-{P}01 | Design for pipeline {P} |
| REFACTOR-{P}01 | refactorer | Stage 3 | DESIGN-{P}01 | Implement pipeline {P} refactorings |
| VALIDATE-{P}01 | validator | Stage 4 | REFACTOR-{P}01 | Validate pipeline {P} |
| REVIEW-{P}01 | reviewer | Stage 4 | REFACTOR-{P}01 | Review pipeline {P} |
## Checkpoints
| Checkpoint | Trigger | Location | Behavior |
|------------|---------|----------|----------|
| CP-1 | ANALYZE-001 complete | After Stage 1 | User reviews architecture report, can refine scope |
| CP-2 | DESIGN-001 complete | After Stage 2 | User reviews refactoring plan, can adjust priorities |
| CP-2.5 | DESIGN-001 complete (auto/fan-out) | After Stage 2 | Auto-create N branch tasks, spawn all REFACTOR-B* in parallel |
| CP-3 | REVIEW/VALIDATE fail | Stage 4 (per-branch) | Auto-create FIX task for that branch only (max 3x per branch) |
| CP-4 | All tasks/branches complete | Phase 5 | Aggregate results, interactive completion action |
## Task Naming Rules
| Mode | Stage 3 | Stage 4 | Fix | Retry |
|------|---------|---------|-----|-------|
| Single | REFACTOR-001 | VALIDATE-001, REVIEW-001 | FIX-001 | VALIDATE-001-R1, REVIEW-001-R1 |
| Fan-out | REFACTOR-B01 | VALIDATE-B01, REVIEW-B01 | FIX-B01-1 | VALIDATE-B01-R1, REVIEW-B01-R1 |
| Independent | REFACTOR-A01 | VALIDATE-A01, REVIEW-A01 | FIX-A01-1 | VALIDATE-A01-R1, REVIEW-A01-R1 |
## Parallel Mode Invocation
```bash
Skill(skill="team-arch-opt", args="<task-description>") # auto mode
Skill(skill="team-arch-opt", args="--parallel-mode=fan-out <task-description>") # force fan-out
Skill(skill="team-arch-opt", args='--parallel-mode=independent "target1" "target2"') # independent
Skill(skill="team-arch-opt", args="--max-branches=3 <task-description>") # limit branches
```

263
.codex/skills/team-arch-opt/specs/team-config.json Normal file
View File

@@ -0,0 +1,263 @@
{
"version": "5.0.0",
"team_name": "arch-opt",
"team_display_name": "Architecture Optimization",
"skill_name": "team-arch-opt",
"skill_path": "~ or <project>/.claude/skills/team-arch-opt/",
"pipeline_type": "Linear with Review-Fix Cycle (Parallel-Capable)",
"completion_action": "interactive",
"has_inline_discuss": true,
"has_shared_explore": true,
"has_checkpoint_feedback": true,
"has_session_resume": true,
"roles": [
{
"name": "coordinator",
"type": "orchestrator",
"description": "Orchestrates architecture optimization pipeline, manages task chains, handles review-fix cycles",
"spec_path": "roles/coordinator/role.md",
"tools": ["Task", "TaskCreate", "TaskList", "TaskGet", "TaskUpdate", "TeamCreate", "TeamDelete", "SendMessage", "AskUserQuestion", "Read", "Write", "Bash", "Glob", "Grep"]
},
{
"name": "analyzer",
"type": "orchestration",
"description": "Analyzes architecture: dependency graphs, coupling/cohesion, layering violations, God Classes, dead code",
"role_spec": "roles/analyzer/role.md",
"inner_loop": false,
"frontmatter": {
"prefix": "ANALYZE",
"inner_loop": false,
"additional_prefixes": [],
"discuss_rounds": [],
"cli_tools": ["explore"],
"message_types": {
"success": "analyze_complete",
"error": "error"
}
},
"weight": 1,
"tools": ["Read", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"]
},
{
"name": "designer",
"type": "orchestration",
"description": "Designs refactoring strategies from architecture analysis, produces prioritized refactoring plan with discrete REFACTOR-IDs",
"role_spec": "roles/designer/role.md",
"inner_loop": false,
"frontmatter": {
"prefix": "DESIGN",
"inner_loop": false,
"additional_prefixes": [],
"discuss_rounds": ["DISCUSS-REFACTOR"],
"cli_tools": ["discuss"],
"message_types": {
"success": "design_complete",
"error": "error"
}
},
"weight": 2,
"tools": ["Read", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"]
},
{
"name": "refactorer",
"type": "code_generation",
"description": "Implements architecture refactoring changes following the design plan",
"role_spec": "roles/refactorer/role.md",
"inner_loop": true,
"frontmatter": {
"prefix": "REFACTOR",
"inner_loop": true,
"additional_prefixes": ["FIX"],
"discuss_rounds": [],
"cli_tools": ["explore"],
"message_types": {
"success": "refactor_complete",
"error": "error",
"fix": "fix_required"
}
},
"weight": 3,
"tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"]
},
{
"name": "validator",
"type": "validation",
"description": "Validates refactoring: build checks, test suites, dependency metrics, API compatibility",
"role_spec": "roles/validator/role.md",
"inner_loop": false,
"frontmatter": {
"prefix": "VALIDATE",
"inner_loop": false,
"additional_prefixes": [],
"discuss_rounds": [],
"cli_tools": [],
"message_types": {
"success": "validate_complete",
"error": "error",
"fix": "fix_required"
}
},
"weight": 4,
"tools": ["Read", "Bash", "Glob", "Grep", "Task"]
},
{
"name": "reviewer",
"type": "read_only_analysis",
"description": "Reviews refactoring code for correctness, pattern consistency, completeness, migration safety, and best practices",
"role_spec": "roles/reviewer/role.md",
"inner_loop": false,
"frontmatter": {
"prefix": "REVIEW",
"inner_loop": false,
"additional_prefixes": ["QUALITY"],
"discuss_rounds": ["DISCUSS-REVIEW"],
"cli_tools": ["discuss"],
"message_types": {
"success": "review_complete",
"error": "error",
"fix": "fix_required"
}
},
"weight": 4,
"tools": ["Read", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"]
}
],
"parallel_config": {
"modes": ["single", "fan-out", "independent", "auto"],
"default_mode": "auto",
"max_branches": 5,
"auto_mode_rules": {
"single": "refactoring_count <= 2",
"fan-out": "refactoring_count >= 3"
}
},
"pipeline": {
"stages": [
{
"stage": 1,
"name": "Architecture Analysis",
"roles": ["analyzer"],
"blockedBy": [],
"fast_advance": true
},
{
"stage": 2,
"name": "Refactoring Design",
"roles": ["designer"],
"blockedBy": ["ANALYZE"],
"fast_advance": true
},
{
"stage": 3,
"name": "Code Refactoring",
"roles": ["refactorer"],
"blockedBy": ["DESIGN"],
"fast_advance": false
},
{
"stage": 4,
"name": "Validate & Review",
"roles": ["validator", "reviewer"],
"blockedBy": ["REFACTOR"],
"fast_advance": false,
"parallel": true,
"review_fix_cycle": {
"trigger": "REVIEW or VALIDATE finds issues",
"target_stage": 3,
"max_iterations": 3
}
}
],
"parallel_pipelines": {
"fan-out": {
"shared_stages": [1, 2],
"branch_stages": [3, 4],
"branch_prefix": "B",
"review_fix_cycle": {
"scope": "per_branch",
"max_iterations": 3
}
},
"independent": {
"pipeline_prefix_chars": "ABCDEFGHIJ",
"review_fix_cycle": {
"scope": "per_pipeline",
"max_iterations": 3
}
}
},
"diagram": "See pipeline-diagram section"
},
"cli_tools": [
{
"name": "explore",
"implementation": "ccw cli with analysis mode",
"callable_by": ["analyzer", "refactorer"],
"purpose": "Shared codebase exploration for architecture-critical structures, dependency graphs, and module boundaries",
"has_cache": true,
"cache_domain": "explorations"
},
{
"name": "discuss",
"implementation": "ccw cli with analysis mode",
"callable_by": ["designer", "reviewer"],
"purpose": "Multi-perspective discussion for refactoring approaches and review findings",
"has_cache": false
}
],
"shared_resources": [
{
"name": "Architecture Baseline",
"path": "<session>/artifacts/architecture-baseline.json",
"usage": "Pre-refactoring architecture metrics for comparison",
"scope": "shared (fan-out) / per-pipeline (independent)"
},
{
"name": "Architecture Report",
"path": "<session>/artifacts/architecture-report.md",
"usage": "Analyzer output consumed by designer",
"scope": "shared (fan-out) / per-pipeline (independent)"
},
{
"name": "Refactoring Plan",
"path": "<session>/artifacts/refactoring-plan.md",
"usage": "Designer output consumed by refactorer",
"scope": "shared (fan-out) / per-pipeline (independent)"
},
{
"name": "Validation Results",
"path": "<session>/artifacts/validation-results.json",
"usage": "Validator output consumed by reviewer",
"scope": "per-branch (fan-out) / per-pipeline (independent)"
}
],
"shared_memory_namespacing": {
"single": {
"analyzer": "analyzer",
"designer": "designer",
"refactorer": "refactorer",
"validator": "validator",
"reviewer": "reviewer"
},
"fan-out": {
"analyzer": "analyzer",
"designer": "designer",
"refactorer": "refactorer.B{NN}",
"validator": "validator.B{NN}",
"reviewer": "reviewer.B{NN}"
},
"independent": {
"analyzer": "analyzer.{P}",
"designer": "designer.{P}",
"refactorer": "refactorer.{P}",
"validator": "validator.{P}",
"reviewer": "reviewer.{P}"
}
}
}

813
.codex/skills/team-brainstorm/SKILL.md
View File

@@ -1,724 +1,167 @@
---
name: team-brainstorm
description: Multi-agent brainstorming pipeline with Generator-Critic loop. Generates ideas, challenges assumptions, synthesizes themes, and evaluates proposals. Supports Quick, Deep, and Full pipeline modes.
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"topic description\""
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
description: Unified team skill for brainstorming team. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team brainstorm".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
# Team Brainstorm
## Usage
Orchestrate multi-agent brainstorming: generate ideas -> challenge assumptions -> synthesize -> evaluate. Supports Quick, Deep, and Full pipelines with Generator-Critic loop.
```bash
$team-brainstorm "How should we approach microservices migration?"
$team-brainstorm -c 4 "Innovation strategies for AI-powered developer tools"
$team-brainstorm -y "Quick brainstorm on naming conventions"
$team-brainstorm --continue "brs-microservices-20260308"
```
**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
Multi-agent brainstorming with Generator-Critic loop: generate ideas across multiple angles, challenge assumptions, synthesize themes, and evaluate proposals. Supports three pipeline modes (Quick/Deep/Full) with configurable depth and parallel ideation.
**Execution Model**: Hybrid — CSV wave pipeline (primary) + individual agent spawn (secondary for Generator-Critic control)
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────┐
│ TEAM BRAINSTORM WORKFLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 0: Pre-Wave Interactive │
│ ├─ Topic clarification + complexity scoring │
│ ├─ Pipeline mode selection (quick/deep/full) │
│ └─ Output: refined requirements for decomposition │
│ │
│ Phase 1: Requirement → CSV + Classification │
│ ├─ Parse topic into brainstorm tasks per selected pipeline │
│ ├─ Assign roles: ideator, challenger, synthesizer, evaluator │
│ ├─ Classify tasks: csv-wave | interactive (exec_mode) │
│ ├─ 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 (if any) │
│ │ ├─ 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 (if any) │
│ │ ├─ Merge all results into master tasks.csv │
│ │ └─ Check: any failed? → skip dependents │
│ └─ discoveries.ndjson shared across all modes (append-only) │
│ │
│ Phase 3: Post-Wave Interactive │
│ ├─ Generator-Critic (GC) loop control │
│ ├─ If critique severity >= HIGH: trigger revision wave │
│ └─ Max 2 GC rounds, then force convergence │
│ │
│ Phase 4: 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 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Skill(skill="team-brainstorm", args="topic description")
|
SKILL.md (this file) = Router
|
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-- analyze -> dispatch -> spawn workers -> STOP
|
+-------+-------+-------+
v v v v
[ideator][challenger][synthesizer][evaluator]
```
---
## Role Registry
## Task Classification Rules
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| ideator | [roles/ideator/role.md](roles/ideator/role.md) | IDEA-* | false |
| challenger | [roles/challenger/role.md](roles/challenger/role.md) | CHALLENGE-* | false |
| synthesizer | [roles/synthesizer/role.md](roles/synthesizer/role.md) | SYNTH-* | false |
| evaluator | [roles/evaluator/role.md](roles/evaluator/role.md) | EVAL-* | false |
Each task is classified by `exec_mode`:
## Role Router
| 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 |
Parse `$ARGUMENTS`:
- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` -> `roles/coordinator/role.md`, execute entry router
**Classification Decision**:
## Shared Constants
| Task Property | Classification |
|---------------|---------------|
| Idea generation (single angle) | `csv-wave` |
| Parallel ideation (Full pipeline, multiple angles) | `csv-wave` (parallel in same wave) |
| Idea revision (GC loop) | `csv-wave` |
| Critique / challenge | `csv-wave` |
| Synthesis (theme extraction) | `csv-wave` |
| Evaluation (scoring / ranking) | `csv-wave` |
| GC loop control (severity check → decide revision or convergence) | `interactive` |
| Topic clarification (Phase 0) | `interactive` |
- **Session prefix**: `BRS`
- **Session path**: `.workflow/.team/BRS-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
---
## Worker Spawn Template
## CSV Schema
### tasks.csv (Master State)
```csv
id,title,description,role,angle,gc_round,deps,context_from,exec_mode,wave,status,findings,gc_signal,severity_summary,error
"IDEA-001","Multi-angle idea generation","Generate 3+ ideas per angle with title, description, assumption, impact","ideator","Technical;Product;Innovation","0","","","csv-wave","1","pending","","","",""
"CHALLENGE-001","Critique generated ideas","Challenge each idea across assumption, feasibility, risk, competition dimensions","challenger","","0","IDEA-001","IDEA-001","csv-wave","2","pending","","","",""
"GC-CHECK-001","GC loop decision","Evaluate critique severity and decide: revision or convergence","gc-controller","","1","CHALLENGE-001","CHALLENGE-001","interactive","3","pending","","","",""
```
**Columns**:
| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (string) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description |
| `role` | Input | Worker role: ideator, challenger, synthesizer, evaluator |
| `angle` | Input | Brainstorming angle(s) for ideator tasks (semicolon-separated) |
| `gc_round` | Input | Generator-Critic round number (0 = initial, 1+ = revision) |
| `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` |
| `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) |
| `gc_signal` | Output | Generator-Critic signal: `REVISION_NEEDED` or `CONVERGED` (challenger only) |
| `severity_summary` | Output | Severity count: e.g. "CRITICAL:1 HIGH:2 MEDIUM:3 LOW:1" |
| `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 |
|-------|-----------|---------|----------------|----------|
| gc-controller | agents/gc-controller.md | 2.3 (wait-respond) | Evaluate critique severity, decide revision vs convergence | post-wave (after challenger wave) |
| topic-clarifier | agents/topic-clarifier.md | 2.3 (wait-respond) | Clarify topic, assess complexity, select pipeline mode | standalone (Phase 0) |
> **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 4 |
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
| `context.md` | Human-readable execution report | Created in Phase 4 |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
---
## Session Structure
Coordinator spawns workers using this template:
```
.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
├── wave-{N}.csv # Temporary per-wave input (csv-wave only)
└── interactive/ # Interactive task artifacts
└── {id}-result.json # Per-task results
```
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <topic-description>
inner_loop: false
---
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
## Implementation
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <topic-description>
pipeline_phase: <pipeline-phase>` },
### Session Initialization
```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
// Parse flags
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
// Clean requirement text (remove flags)
const topic = $ARGUMENTS
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
.trim()
const slug = topic.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
let sessionId = `brs-${slug}-${dateStr}`
let sessionFolder = `.workflow/.csv-wave/${sessionId}`
// Continue mode: find existing session
if (continueMode) {
const existing = Bash(`ls -t .workflow/.csv-wave/brs-* 2>/dev/null | head -1`).trim()
if (existing) {
sessionId = existing.split('/').pop()
sessionFolder = existing
// Read existing tasks.csv, find incomplete waves, resume from Phase 2
}
}
Bash(`mkdir -p ${sessionFolder}/interactive`)
```
---
### Phase 0: Pre-Wave Interactive
**Objective**: Clarify topic, assess complexity, and select pipeline mode.
**Execution**:
```javascript
const clarifier = spawn_agent({
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~ or <project>/.codex/skills/team-brainstorm/agents/topic-clarifier.md (MUST read first)
2. Read: .workflow/project-tech.json (if exists)
---
Goal: Clarify brainstorming topic and select pipeline mode
Topic: ${topic}
### Task
1. Assess topic complexity using signal detection:
- Strategic/systemic keywords (+3): strategy, architecture, system, framework, paradigm
- Multi-dimensional keywords (+2): multiple, compare, tradeoff, versus, alternative
- Innovation-focused keywords (+2): innovative, creative, novel, breakthrough
- Simple/basic keywords (-2): simple, quick, straightforward, basic
2. Score >= 4 → full, 2-3 → deep, 0-1 → quick
3. Suggest divergence angles (e.g., Technical, Product, Innovation, Risk)
4. Return structured result
`
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
const clarifierResult = wait({ ids: [clarifier], timeout_ms: 120000 })
if (clarifierResult.timed_out) {
send_input({ id: clarifier, message: "Please finalize and output current findings." })
const retry = wait({ ids: [clarifier], timeout_ms: 60000 })
}
// Parse result for pipeline_mode, angles
close_agent({ id: clarifier })
// Store result
Write(`${sessionFolder}/interactive/topic-clarifier-result.json`, JSON.stringify({
task_id: "topic-clarification",
status: "completed",
pipeline_mode: parsedMode, // "quick" | "deep" | "full"
angles: parsedAngles, // ["Technical", "Product", "Innovation", "Risk"]
complexity_score: parsedScore,
timestamp: getUtc8ISOString()
}))
```
If not AUTO_YES, present user with pipeline mode selection for confirmation:
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
```javascript
if (!AUTO_YES) {
const answer = request_user_input({
questions: [{
question: `Topic: "${topic}" — Recommended: ${pipeline_mode}. Approve or override?`,
header: "Pipeline",
id: "pipeline_select",
options: [
{ label: "Approve (Recommended)", description: `Use ${pipeline_mode} pipeline (complexity: ${complexity_score})` },
{ label: "Quick", description: "3 tasks: generate -> challenge -> synthesize" },
{ label: "Deep/Full", description: "6-7 tasks: parallel generation, GC loop, evaluation" }
]
}]
})
// Update pipeline_mode based on user choice
}
**Parallel ideator spawn** (Full pipeline with N angles):
When Full pipeline has N parallel IDEA tasks, spawn N distinct team-worker agents named `ideator-1`, `ideator-2`, etc.
```
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: ideator
role_spec: <skill_root>/roles/ideator/role.md
session: <session-folder>
session_id: <session-id>
requirement: <topic-description>
agent_name: ideator-<N>
inner_loop: false
Read role_spec file (<skill_root>/roles/ideator/role.md) to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <topic-description>
pipeline_phase: <pipeline-phase>` },
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
**Success Criteria**:
- Refined requirements available for Phase 1 decomposition
- Interactive agents closed, results stored
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
---
## User Commands
### Phase 1: Requirement → CSV + Classification
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
**Objective**: Build tasks.csv from selected pipeline mode with proper wave assignments.
## Session Directory
**Decomposition Rules**:
| Pipeline | Tasks | Wave Structure |
|----------|-------|---------------|
| quick | IDEA-001 → CHALLENGE-001 → SYNTH-001 | 3 waves, serial |
| deep | IDEA-001 → CHALLENGE-001 → IDEA-002 → CHALLENGE-002 → SYNTH-001 → EVAL-001 | 6 waves, serial with GC loop |
| full | IDEA-001,002,003 (parallel) → CHALLENGE-001 → IDEA-004 → SYNTH-001 → EVAL-001 | 5 waves, fan-out + GC |
**Classification Rules**:
All brainstorm work tasks (ideation, challenging, synthesis, evaluation) are `csv-wave`. The GC loop controller between challenger and next ideation revision is `interactive` (post-wave, spawned by orchestrator to decide the GC outcome).
**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
**Pipeline Task Definitions**:
#### Quick Pipeline (3 csv-wave tasks)
| Task ID | Role | Wave | Deps | Description |
|---------|------|------|------|-------------|
| IDEA-001 | ideator | 1 | (none) | Generate multi-angle ideas: 3+ ideas per angle with title, description, assumption, impact |
| CHALLENGE-001 | challenger | 2 | IDEA-001 | Challenge each idea across 4 dimensions (assumption, feasibility, risk, competition). Assign severity per idea. Output GC signal |
| SYNTH-001 | synthesizer | 3 | CHALLENGE-001 | Synthesize ideas and critiques into 1-3 integrated proposals with feasibility and innovation scores |
#### Deep Pipeline (6 csv-wave tasks + 1 interactive GC check)
Same as Quick plus:
| Task ID | Role | Wave | Deps | Description |
|---------|------|------|------|-------------|
| IDEA-002 | ideator | 4 | CHALLENGE-001 | Revise ideas based on critique feedback (GC Round 1). Address HIGH/CRITICAL challenges |
| CHALLENGE-002 | challenger | 5 | IDEA-002 | Validate revised ideas (GC Round 2). Re-evaluate previously challenged ideas |
| SYNTH-001 | synthesizer | 6 | CHALLENGE-002 | Synthesize all ideas and critiques |
| EVAL-001 | evaluator | 7 | SYNTH-001 | Score and rank proposals: Feasibility 30%, Innovation 25%, Impact 25%, Cost 20% |
GC-CHECK-001 (interactive) runs post-wave after CHALLENGE-001 to decide whether to proceed with revision or skip to synthesis.
#### Full Pipeline (7 csv-wave tasks + GC control)
| Task ID | Role | Wave | Deps | Description |
|---------|------|------|------|-------------|
| IDEA-001 | ideator | 1 | (none) | Generate ideas from angle 1 |
| IDEA-002 | ideator | 1 | (none) | Generate ideas from angle 2 |
| IDEA-003 | ideator | 1 | (none) | Generate ideas from angle 3 |
| CHALLENGE-001 | challenger | 2 | IDEA-001;IDEA-002;IDEA-003 | Critique all generated ideas |
| IDEA-004 | ideator | 3 | CHALLENGE-001 | Revise ideas based on critique |
| SYNTH-001 | synthesizer | 4 | IDEA-004 | Synthesize all ideas and critiques |
| EVAL-001 | evaluator | 5 | SYNTH-001 | Score and rank proposals |
**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
const failedIds = new Set()
const skippedIds = new Set()
const MAX_GC_ROUNDS = 2
let gcRound = 0
for (let wave = 1; wave <= maxWave; wave++) {
console.log(`\n## Wave ${wave}/${maxWave}\n`)
// 1. Read current master CSV
const masterCsv = parseCsv(Read(`${sessionFolder}/tasks.csv`))
// 2. Separate csv-wave and interactive tasks for this wave
const waveTasks = masterCsv.filter(row => parseInt(row.wave) === wave)
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
// 3. Skip tasks whose deps failed
const executableCsvTasks = []
for (const task of csvTasks) {
const deps = task.deps.split(';').filter(Boolean)
if (deps.some(d => failedIds.has(d) || skippedIds.has(d))) {
skippedIds.add(task.id)
updateMasterCsvRow(sessionFolder, task.id, {
status: 'skipped',
error: 'Dependency failed or skipped'
})
continue
}
executableCsvTasks.push(task)
}
// 4. Build prev_context for each csv-wave task
for (const task of executableCsvTasks) {
const contextIds = task.context_from.split(';').filter(Boolean)
const prevFindings = contextIds
.map(id => {
const prevRow = masterCsv.find(r => r.id === id)
if (prevRow && prevRow.status === 'completed' && prevRow.findings) {
return `[Task ${id}: ${prevRow.title}] ${prevRow.findings}`
}
return null
})
.filter(Boolean)
.join('\n')
task.prev_context = prevFindings || 'No previous context available'
}
// 5. Write wave CSV and execute csv-wave tasks
if (executableCsvTasks.length > 0) {
const waveHeader = 'id,title,description,role,angle,gc_round,deps,context_from,exec_mode,wave,prev_context'
const waveRows = executableCsvTasks.map(t =>
[t.id, t.title, t.description, t.role, t.angle, t.gc_round, t.deps, t.context_from, t.exec_mode, t.wave, t.prev_context]
.map(cell => `"${String(cell).replace(/"/g, '""')}"`)
.join(',')
)
Write(`${sessionFolder}/wave-${wave}.csv`, [waveHeader, ...waveRows].join('\n'))
const waveResult = spawn_agents_on_csv({
csv_path: `${sessionFolder}/wave-${wave}.csv`,
id_column: "id",
instruction: buildBrainstormInstruction(sessionFolder, wave),
max_concurrency: maxConcurrency,
max_runtime_seconds: 600,
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
gc_signal: { type: "string" },
severity_summary: { type: "string" },
error: { type: "string" }
},
required: ["id", "status", "findings"]
}
})
// Blocks until wave completes
// Merge results into master CSV
const waveResults = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
for (const result of waveResults) {
updateMasterCsvRow(sessionFolder, result.id, {
status: result.status,
findings: result.findings || '',
gc_signal: result.gc_signal || '',
severity_summary: result.severity_summary || '',
error: result.error || ''
})
if (result.status === 'failed') failedIds.add(result.id)
}
Bash(`rm -f "${sessionFolder}/wave-${wave}.csv"`)
}
// 6. Execute post-wave interactive tasks (GC controller)
for (const task of interactiveTasks) {
if (task.status !== 'pending') continue
const deps = task.deps.split(';').filter(Boolean)
if (deps.some(d => failedIds.has(d) || skippedIds.has(d))) {
skippedIds.add(task.id)
continue
}
// Spawn GC controller agent
const gcAgent = spawn_agent({
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~ or <project>/.codex/skills/team-brainstorm/agents/gc-controller.md (MUST read first)
2. Read: ${sessionFolder}/discoveries.ndjson (shared discoveries)
---
Goal: Evaluate critique severity and decide revision vs convergence
Session: ${sessionFolder}
GC Round: ${gcRound}
Max GC Rounds: ${MAX_GC_ROUNDS}
### Context
Read the latest critique file and determine the GC signal.
If REVISION_NEEDED and gcRound < maxRounds: output "REVISION"
If CONVERGED or gcRound >= maxRounds: output "CONVERGE"
`
})
const gcResult = wait({ ids: [gcAgent], timeout_ms: 120000 })
if (gcResult.timed_out) {
send_input({ id: gcAgent, message: "Please finalize your decision now." })
wait({ ids: [gcAgent], timeout_ms: 60000 })
}
close_agent({ id: gcAgent })
// Parse GC decision and potentially create/skip revision tasks
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
task_id: task.id, status: "completed",
gc_decision: gcDecision, gc_round: gcRound,
timestamp: getUtc8ISOString()
}))
if (gcDecision === "CONVERGE") {
// Skip remaining GC tasks, mark revision tasks as skipped
// Unblock SYNTH directly
} else {
gcRound++
// Let the revision wave proceed naturally
}
updateMasterCsvRow(sessionFolder, task.id, { status: 'completed', findings: `GC decision: ${gcDecision}` })
}
}
```
.workflow/.team/BRS-<slug>-<date>/
├── session.json # Session metadata + pipeline + gc_round
├── task-analysis.json # Coordinator analyze output
├── .msg/
│ ├── messages.jsonl # Message bus log
│ └── meta.json # Session state + cross-role state
├── wisdom/ # Cross-task knowledge
│ ├── learnings.md
│ ├── decisions.md
│ ├── conventions.md
│ └── issues.md
├── ideas/ # Ideator output
│ ├── idea-001.md
│ └── idea-002.md
├── critiques/ # Challenger output
│ ├── critique-001.md
│ └── critique-002.md
├── synthesis/ # Synthesizer output
│ └── synthesis-001.md
└── evaluation/ # Evaluator output
└── evaluation-001.md
```
**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
- GC loop controlled with max 2 rounds
## Specs Reference
---
### Phase 3: Post-Wave Interactive
**Objective**: Handle any final GC loop convergence and prepare for synthesis.
If the pipeline used GC loops and the final GC decision was CONVERGE or max rounds reached, ensure SYNTH-001 is unblocked and all remaining GC-related tasks are properly marked.
**Success Criteria**:
- Post-wave interactive processing complete
- Interactive agents closed, results stored
---
### Phase 4: Results Aggregation
**Objective**: Generate final results and human-readable report.
```javascript
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
Write(`${sessionFolder}/results.csv`, masterCsv)
const tasks = parseCsv(masterCsv)
const completed = tasks.filter(t => t.status === 'completed')
const failed = tasks.filter(t => t.status === 'failed')
const skipped = tasks.filter(t => t.status === 'skipped')
const contextContent = `# Team Brainstorm Report
**Session**: ${sessionId}
**Topic**: ${topic}
**Pipeline**: ${pipeline_mode}
**Completed**: ${getUtc8ISOString()}
---
## Summary
| Metric | Count |
|--------|-------|
| Total Tasks | ${tasks.length} |
| Completed | ${completed.length} |
| Failed | ${failed.length} |
| Skipped | ${skipped.length} |
| GC Rounds | ${gcRound} |
---
## Wave Execution
${waveDetails}
---
## Task Details
${taskDetails}
---
## Brainstorm Artifacts
- Ideas: discoveries with type "idea" in discoveries.ndjson
- Critiques: discoveries with type "critique" in discoveries.ndjson
- Synthesis: discoveries with type "synthesis" in discoveries.ndjson
- Evaluation: discoveries with type "evaluation" in discoveries.ndjson
`
Write(`${sessionFolder}/context.md`, contextContent)
```
If not AUTO_YES and there are failed tasks, offer retry or view report.
**Success Criteria**:
- results.csv exported (all tasks, both modes)
- context.md generated
- All interactive agents closed
- Summary displayed to user
---
## Shared Discovery Board Protocol
All agents across all waves share `discoveries.ndjson`. This enables cross-role knowledge sharing.
**Discovery Types**:
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `idea` | `data.title` | `{title, angle, description, assumption, impact}` | Generated idea |
| `critique` | `data.idea_title` | `{idea_title, dimension, severity, challenge, rationale}` | Critique of an idea |
| `theme` | `data.name` | `{name, strength, supporting_ideas[]}` | Extracted theme from synthesis |
| `proposal` | `data.title` | `{title, source_ideas[], feasibility, innovation, description}` | Integrated proposal |
| `evaluation` | `data.proposal_title` | `{proposal_title, weighted_score, rank, recommendation}` | Proposal evaluation |
| `gc_decision` | `data.round` | `{round, signal, severity_counts}` | GC loop decision |
**Format**: NDJSON, each line is self-contained JSON:
```jsonl
{"ts":"2026-03-08T10:00:00+08:00","worker":"IDEA-001","type":"idea","data":{"title":"API Gateway Pattern","angle":"Technical","description":"Centralized API gateway for microservice routing","assumption":"Services need unified entry point","impact":"Simplifies client integration"}}
{"ts":"2026-03-08T10:05:00+08:00","worker":"CHALLENGE-001","type":"critique","data":{"idea_title":"API Gateway Pattern","dimension":"feasibility","severity":"MEDIUM","challenge":"Single point of failure","rationale":"Requires high availability design"}}
```
**Protocol Rules**:
1. Read board before own work → leverage existing context
2. Write discoveries immediately via `echo >>` → don't batch
3. Deduplicate — check existing entries by type + dedup key
4. Append-only — never modify or delete existing lines
---
## Consensus Severity Routing
When the challenger returns critique results with severity-graded verdicts:
| Severity | Action |
|----------|--------|
| HIGH | Trigger revision round (GC loop), max 2 rounds total |
| MEDIUM | Log warning, continue pipeline |
| LOW | Treat as consensus reached |
**Constraints**: Max 2 GC rounds (revision cycles). If still HIGH after 2 rounds, force convergence to synthesizer.
---
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
## 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 |
| 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 |
| GC loop exceeds 2 rounds | Force convergence to synthesizer |
| No ideas generated | Report failure, suggest refining topic |
| Continue mode: no session found | List available sessions, prompt user to select |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 0/1
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
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
---
## Coordinator Role Constraints (Main Agent)
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
| Generator-Critic loop exceeds 2 rounds | Force convergence to synthesizer |
| No ideas generated | Coordinator prompts with seed questions |

122
.codex/skills/team-brainstorm/agents/gc-controller.md
View File

@@ -1,122 +0,0 @@
# GC Controller Agent
Evaluate Generator-Critic loop severity and decide whether to trigger revision or converge to synthesis.
## Identity
- **Type**: `interactive`
- **Responsibility**: GC loop decision making
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read the latest critique file to assess severity
- Make a binary decision: REVISION or CONVERGE
- Respect max GC round limits
- Produce structured output following template
### MUST NOT
- Generate ideas or perform critique (delegate to csv-wave agents)
- Exceed 1 decision per invocation
- Ignore the max round constraint
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load critique artifacts and session state |
| `Glob` | builtin | Find critique files in session directory |
---
## Execution
### Phase 1: Context Loading
**Objective**: Load critique results and GC round state
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Session folder | Yes | Path to session directory |
| GC Round | Yes | Current GC round number |
| Max GC Rounds | Yes | Maximum allowed rounds (default: 2) |
**Steps**:
1. Read the session's discoveries.ndjson for critique entries
2. Parse prev_context for the challenger's findings
3. Extract severity counts from the challenger's severity_summary
4. Load current gc_round from spawn message
**Output**: Severity counts and round state loaded
---
### Phase 2: Decision Making
**Objective**: Determine whether to trigger revision or converge
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Severity counts | Yes | CRITICAL, HIGH, MEDIUM, LOW counts |
| GC round | Yes | Current round number |
| Max rounds | Yes | Maximum allowed rounds |
**Steps**:
1. Check severity threshold:
| Condition | Decision |
|-----------|----------|
| gc_round >= max_rounds | CONVERGE (force, regardless of severity) |
| CRITICAL count > 0 | REVISION (if rounds remain) |
| HIGH count > 0 | REVISION (if rounds remain) |
| All MEDIUM or lower | CONVERGE |
2. Log the decision rationale
**Output**: Decision string "REVISION" or "CONVERGE"
---
## Structured Output Template
```
## Summary
- GC Round: <current>/<max>
- Decision: REVISION | CONVERGE
## Severity Assessment
- CRITICAL: <count>
- HIGH: <count>
- MEDIUM: <count>
- LOW: <count>
## Rationale
- <1-2 sentence explanation of decision>
## Next Action
- REVISION: Ideator should address HIGH/CRITICAL challenges in next round
- CONVERGE: Proceed to synthesis phase, skip remaining revision tasks
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| No critique data found | Default to CONVERGE (no evidence for revision) |
| Severity parsing fails | Default to CONVERGE with warning |
| Timeout approaching | Output current decision immediately |

126
.codex/skills/team-brainstorm/agents/topic-clarifier.md
View File

@@ -1,126 +0,0 @@
# Topic Clarifier Agent
Assess brainstorming topic complexity, recommend pipeline mode, and suggest divergence angles.
## Identity
- **Type**: `interactive`
- **Responsibility**: Topic analysis and pipeline selection
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Perform text-level analysis only (no source code reading)
- Produce structured output with pipeline recommendation
- Suggest meaningful divergence angles for ideation
### MUST NOT
- Read source code or explore codebase
- Generate ideas (that is the ideator's job)
- Make final pipeline decisions (orchestrator confirms with user)
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load project context if available |
---
## Execution
### Phase 1: Signal Detection
**Objective**: Analyze topic keywords for complexity signals
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Topic text | Yes | The brainstorming topic from user |
**Steps**:
1. Scan topic for complexity signals:
| Signal | Weight | Keywords |
|--------|--------|----------|
| Strategic/systemic | +3 | strategy, architecture, system, framework, paradigm |
| Multi-dimensional | +2 | multiple, compare, tradeoff, versus, alternative |
| Innovation-focused | +2 | innovative, creative, novel, breakthrough |
| Simple/basic | -2 | simple, quick, straightforward, basic |
2. Calculate complexity score
**Output**: Complexity score and matched signals
---
### Phase 2: Pipeline Recommendation
**Objective**: Map complexity to pipeline mode and suggest angles
**Steps**:
1. Map score to pipeline:
| Score | Complexity | Pipeline |
|-------|------------|----------|
| >= 4 | High | full (3x parallel ideation + GC + evaluation) |
| 2-3 | Medium | deep (serial with GC loop + evaluation) |
| 0-1 | Low | quick (generate → challenge → synthesize) |
2. Identify divergence angles from topic context:
- **Technical**: Implementation approaches, architecture patterns
- **Product**: User experience, market fit, value proposition
- **Innovation**: Novel approaches, emerging tech, disruption potential
- **Risk**: Failure modes, mitigation strategies, worst cases
- **Business**: Cost, ROI, competitive advantage
- **Organizational**: Team structure, process, culture
3. Select 3-4 most relevant angles based on topic keywords
**Output**: Pipeline mode, angles, complexity rationale
---
## Structured Output Template
```
## Summary
- Topic: <topic>
- Complexity Score: <score> (<level>)
- Recommended Pipeline: <quick|deep|full>
## Signal Detection
- Matched signals: <list of matched signals with weights>
## Suggested Angles
1. <Angle 1>: <why relevant>
2. <Angle 2>: <why relevant>
3. <Angle 3>: <why relevant>
## Pipeline Details
- <pipeline>: <brief description of what this pipeline does>
- Expected tasks: <count>
- Parallel ideation: <yes/no>
- GC rounds: <0/1/2>
- Evaluation: <yes/no>
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Topic too vague | Suggest clarifying questions in output |
| No signal matches | Default to "deep" pipeline with general angles |
| Timeout approaching | Output current analysis with "PARTIAL" status |

105
.codex/skills/team-brainstorm/instructions/agent-instruction.md
View File

@@ -1,105 +0,0 @@
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS
1. Read shared discoveries: .workflow/.csv-wave/{session-id}/discoveries.ndjson (if exists, skip if not)
2. Read project context: .workflow/project-tech.json (if exists)
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**Description**: {description}
**Angle(s)**: {angle}
**GC Round**: {gc_round}
### Previous Tasks' Findings (Context)
{prev_context}
---
## Execution Protocol
1. **Read discoveries**: Load shared discoveries from the session's discoveries.ndjson for cross-task context
2. **Use context**: Apply previous tasks' findings from prev_context above
3. **Execute by role**:
### Role: ideator (IDEA-* tasks)
- **Initial Generation** (gc_round = 0):
- For each angle listed in the Angle(s) field, generate 3+ ideas
- Each idea must include: title, description (2-3 sentences), key assumption, potential impact, implementation hint
- Self-review: ensure >= 6 ideas total, no duplicates, all angles covered
- **GC Revision** (gc_round > 0):
- Read critique findings from prev_context
- Focus on HIGH/CRITICAL severity challenges
- Retain unchallenged ideas intact
- Revise challenged ideas with revision rationale
- Replace unsalvageable ideas with new alternatives
### Role: challenger (CHALLENGE-* tasks)
- Read all idea findings from prev_context
- Challenge each idea across 4 dimensions:
- **Assumption Validity**: Does the core assumption hold? Counter-examples?
- **Feasibility**: Technical/resource/time feasibility?
- **Risk Assessment**: Worst case scenario? Hidden risks?
- **Competitive Analysis**: Better alternatives already exist?
- Assign severity per idea: CRITICAL / HIGH / MEDIUM / LOW
- Determine GC signal:
- Any CRITICAL or HIGH severity → `REVISION_NEEDED`
- All MEDIUM or lower → `CONVERGED`
### Role: synthesizer (SYNTH-* tasks)
- Read all idea and critique findings from prev_context
- Execute synthesis steps:
1. **Theme Extraction**: Identify common themes, rate strength (1-10), list supporting ideas
2. **Conflict Resolution**: Identify contradictions, determine resolution approach
3. **Complementary Grouping**: Group complementary ideas together
4. **Gap Identification**: Discover uncovered perspectives
5. **Integrated Proposals**: Generate 1-3 consolidated proposals with feasibility score (1-10) and innovation score (1-10)
### Role: evaluator (EVAL-* tasks)
- Read synthesis findings from prev_context
- Score each proposal across 4 weighted dimensions:
- Feasibility (30%): Technical feasibility, resource needs, timeline
- Innovation (25%): Novelty, differentiation, breakthrough potential
- Impact (25%): Scope of impact, value creation, problem resolution
- Cost Efficiency (20%): Implementation cost, risk cost, opportunity cost
- Weighted score = (Feasibility * 0.30) + (Innovation * 0.25) + (Impact * 0.25) + (Cost * 0.20)
- Provide recommendation per proposal: Strong Recommend / Recommend / Consider / Pass
- Generate final ranking
4. **Share discoveries**: Append exploration findings to shared board:
```bash
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> .workflow/.csv-wave/{session-id}/discoveries.ndjson
```
Discovery types to share:
- `idea`: {title, angle, description, assumption, impact} — generated idea
- `critique`: {idea_title, dimension, severity, challenge, rationale} — critique finding
- `theme`: {name, strength, supporting_ideas[]} — extracted theme
- `proposal`: {title, source_ideas[], feasibility, innovation, description} — integrated proposal
- `evaluation`: {proposal_title, weighted_score, rank, recommendation} — scored proposal
5. **Report result**: Return JSON via report_agent_job_result
---
## Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key discoveries and implementation notes (max 500 chars)",
"gc_signal": "REVISION_NEEDED | CONVERGED | (empty for non-challenger roles)",
"severity_summary": "CRITICAL:N HIGH:N MEDIUM:N LOW:N (challenger only, empty for others)",
"error": ""
}
**Role-specific findings guidance**:
- **ideator**: List idea count, angles covered, key themes. Example: "Generated 8 ideas across Technical, Product, Innovation. Top ideas: API Gateway, Event Sourcing, DevEx Platform."
- **challenger**: Summarize severity counts and GC signal. Example: "Challenged 8 ideas. 2 HIGH (require revision), 3 MEDIUM, 3 LOW. GC signal: REVISION_NEEDED."
- **synthesizer**: List proposal count and key themes. Example: "Synthesized 3 proposals from 5 themes. Top: Infrastructure Modernization (feasibility:8, innovation:7)."
- **evaluator**: List ranking and top recommendation. Example: "Ranked 3 proposals. #1: Infrastructure Modernization (7.85) - Strong Recommend."

61
.codex/skills/team-brainstorm/roles/challenger/role.md Normal file
View File

@@ -0,0 +1,61 @@
---
role: challenger
prefix: CHALLENGE
inner_loop: false
message_types: [state_update]
---
# Challenger
Devil's advocate role. Assumption challenging, feasibility questioning, risk identification. Acts as the Critic in the Generator-Critic loop.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| Ideas | <session>/ideas/*.md files | Yes |
| Previous critiques | <session>/.msg/meta.json critique_insights | No |
1. Extract session path from task description (match "Session: <path>")
2. Glob idea files from <session>/ideas/
3. Read all idea files for analysis
4. Read .msg/meta.json critique_insights to avoid repeating past challenges
## Phase 3: Critical Analysis
**Challenge Dimensions** (apply to each idea):
| Dimension | Focus |
|-----------|-------|
| Assumption Validity | Does the core assumption hold? Counter-examples? |
| Feasibility | Technical/resource/time feasibility? |
| Risk Assessment | Worst case scenario? Hidden risks? |
| Competitive Analysis | Better alternatives already exist? |
**Severity Classification**:
| Severity | Criteria |
|----------|----------|
| CRITICAL | Fundamental issue, idea may need replacement |
| HIGH | Significant flaw, requires revision |
| MEDIUM | Notable weakness, needs consideration |
| LOW | Minor concern, does not invalidate the idea |
**Generator-Critic Signal**:
| Condition | Signal |
|-----------|--------|
| Any CRITICAL or HIGH severity | REVISION_NEEDED |
| All MEDIUM or lower | CONVERGED |
**Output**: Write to `<session>/critiques/critique-<num>.md`
- Sections: Ideas Reviewed, Per-idea challenges with severity, Summary table with counts, GC Signal
## Phase 4: Severity Summary
1. Count challenges by severity level
2. Determine signal: REVISION_NEEDED if critical+high > 0, else CONVERGED
3. Update shared state:
- Append challenges to .msg/meta.json critique_insights
- Each entry: idea, severity, key_challenge, round

58
.codex/skills/team-brainstorm/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,58 @@
# Analyze Task
Parse user topic -> detect brainstorming capabilities -> assess complexity -> select pipeline.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Prefix |
|----------|------------|--------|
| generate, create, brainstorm, ideas, explore | ideator | IDEA |
| challenge, critique, argue, devil, risk | challenger | CHALLENGE |
| synthesize, integrate, combine, merge, themes | synthesizer | SYNTH |
| evaluate, score, rank, prioritize, select | evaluator | EVAL |
## Dependency Graph
Natural ordering tiers:
- Tier 0: ideator (divergent generation -- no dependencies)
- Tier 1: challenger (requires ideator output)
- Tier 2: ideator-revision (requires challenger output, GC loop)
- Tier 3: synthesizer (requires last challenger output)
- Tier 4: evaluator (requires synthesizer output, deep/full only)
## Complexity Scoring
| Factor | Points |
|--------|--------|
| Per capability needed | +1 |
| Strategic/systemic topic | +3 |
| Multi-dimensional analysis | +2 |
| Innovation-focused request | +2 |
| Simple/basic topic | -2 |
Results: 0-1 Low (quick), 2-3 Medium (deep), 4+ High (full)
## Pipeline Selection
| Complexity | Pipeline | Tasks |
|------------|----------|-------|
| Low | quick | IDEA -> CHALLENGE -> SYNTH |
| Medium | deep | IDEA -> CHALLENGE -> IDEA-fix -> CHALLENGE-2 -> SYNTH -> EVAL |
| High | full | 3x IDEA (parallel) -> CHALLENGE -> IDEA-fix -> SYNTH -> EVAL |
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<quick|deep|full>",
"capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
"dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"angles": ["Technical", "Product", "Innovation", "Risk"]
}
```

162
.codex/skills/team-brainstorm/roles/coordinator/commands/dispatch.md Normal file
View File

@@ -0,0 +1,162 @@
# Command: Dispatch
Create the brainstorm task chain with correct dependencies and structured task descriptions based on selected pipeline mode.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| User topic | From coordinator Phase 1 | Yes |
| Session folder | From coordinator Phase 2 | Yes |
| Pipeline mode | From session.json pipeline | Yes |
| Angles | From session.json angles | Yes |
1. Load topic, pipeline mode, and angles from session.json
2. Determine task chain from pipeline mode
## Phase 3: Task Chain Creation
### Task Description Template
Every task is built as a JSON entry in the tasks array:
```json
{
"id": "<TASK-ID>",
"title": "<TASK-ID>",
"description": "PURPOSE: <what this task achieves> | Success: <completion criteria>\nTASK:\n - <step 1>\n - <step 2>\n - <step 3>\nCONTEXT:\n - Session: <session-folder>\n - Topic: <topic>\n - Angles: <angle-list>\n - Upstream artifacts: <artifact-list>\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits>\n---\nInnerLoop: false",
"status": "pending",
"role": "<role>",
"prefix": "<PREFIX>",
"deps": ["<dependency-list>"],
"findings": "",
"error": ""
}
```
### Pipeline Router
| Mode | Action |
|------|--------|
| quick | Create 3 tasks (IDEA -> CHALLENGE -> SYNTH) |
| deep | Create 6 tasks (IDEA -> CHALLENGE -> IDEA-fix -> CHALLENGE-2 -> SYNTH -> EVAL) |
| full | Create 7 tasks (3 parallel IDEAs -> CHALLENGE -> IDEA-fix -> SYNTH -> EVAL) |
---
### Quick Pipeline
Build the tasks array and write to tasks.json:
```json
[
{
"id": "IDEA-001",
"title": "IDEA-001",
"description": "PURPOSE: Generate multi-angle ideas for brainstorm topic | Success: >= 6 unique ideas across all angles\nTASK:\n - Read topic and angles from session context\n - Generate 3+ ideas per angle with title, description, assumption, impact\n - Self-review for coverage and uniqueness\nCONTEXT:\n - Session: <session-folder>\n - Topic: <topic>\n - Angles: <angle-list>\nEXPECTED: <session>/ideas/idea-001.md with >= 6 ideas\nCONSTRAINTS: Divergent thinking only, no evaluation\n---\nInnerLoop: false",
"status": "pending",
"role": "ideator",
"prefix": "IDEA",
"deps": [],
"findings": "",
"error": ""
},
{
"id": "CHALLENGE-001",
"title": "CHALLENGE-001",
"description": "PURPOSE: Challenge assumptions and assess feasibility of generated ideas | Success: Each idea rated by severity\nTASK:\n - Read all idea files from ideas/ directory\n - Challenge each idea across 4 dimensions (assumption, feasibility, risk, competition)\n - Assign severity (CRITICAL/HIGH/MEDIUM/LOW) per idea\n - Determine GC signal (REVISION_NEEDED or CONVERGED)\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: ideas/idea-001.md\nEXPECTED: <session>/critiques/critique-001.md with severity table and GC signal\nCONSTRAINTS: Critical analysis only, do not generate alternative ideas\n---\nInnerLoop: false",
"status": "pending",
"role": "challenger",
"prefix": "CHALLENGE",
"deps": ["IDEA-001"],
"findings": "",
"error": ""
},
{
"id": "SYNTH-001",
"title": "SYNTH-001",
"description": "PURPOSE: Synthesize ideas and critiques into integrated proposals | Success: >= 1 consolidated proposal\nTASK:\n - Read all ideas and critiques\n - Extract themes, resolve conflicts, group complementary ideas\n - Generate 1-3 integrated proposals with feasibility and innovation scores\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: ideas/*.md, critiques/*.md\nEXPECTED: <session>/synthesis/synthesis-001.md with proposals\nCONSTRAINTS: Integration and synthesis only, no new ideas\n---\nInnerLoop: false",
"status": "pending",
"role": "synthesizer",
"prefix": "SYNTH",
"deps": ["CHALLENGE-001"],
"findings": "",
"error": ""
}
]
```
### Deep Pipeline
Creates all 6 tasks. First 2 same as Quick, then add:
**IDEA-002** (ideator, GC revision):
```json
{
"id": "IDEA-002",
"title": "IDEA-002",
"description": "PURPOSE: Revise ideas based on critique feedback (GC Round 1) | Success: HIGH/CRITICAL challenges addressed\nTASK:\n - Read critique feedback from critiques/\n - Revise challenged ideas, replace unsalvageable ones\n - Retain unchallenged ideas intact\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: critiques/critique-001.md\nEXPECTED: <session>/ideas/idea-002.md with revised ideas\nCONSTRAINTS: Address critique only, focused revision\n---\nInnerLoop: false",
"status": "pending",
"role": "ideator",
"prefix": "IDEA",
"deps": ["CHALLENGE-001"],
"findings": "",
"error": ""
}
```
**CHALLENGE-002** (challenger, round 2):
```json
{
"id": "CHALLENGE-002",
"title": "CHALLENGE-002",
"description": "PURPOSE: Validate revised ideas (GC Round 2) | Success: Severity assessment of revised ideas\nTASK:\n - Read revised idea files\n - Re-evaluate previously challenged ideas\n - Assess new replacement ideas\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: ideas/idea-002.md\nEXPECTED: <session>/critiques/critique-002.md\nCONSTRAINTS: Focus on revised/new ideas\n---\nInnerLoop: false",
"status": "pending",
"role": "challenger",
"prefix": "CHALLENGE",
"deps": ["IDEA-002"],
"findings": "",
"error": ""
}
```
**SYNTH-001** blocked by CHALLENGE-002. **EVAL-001** blocked by SYNTH-001:
```json
{
"id": "EVAL-001",
"title": "EVAL-001",
"description": "PURPOSE: Score and rank synthesized proposals | Success: Ranked list with weighted scores\nTASK:\n - Read synthesis results\n - Score each proposal across 4 dimensions (Feasibility 30%, Innovation 25%, Impact 25%, Cost 20%)\n - Generate final ranking and recommendation\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: synthesis/synthesis-001.md\nEXPECTED: <session>/evaluation/evaluation-001.md with scoring matrix\nCONSTRAINTS: Evaluation only, no new proposals\n---\nInnerLoop: false",
"status": "pending",
"role": "evaluator",
"prefix": "EVAL",
"deps": ["SYNTH-001"],
"findings": "",
"error": ""
}
```
### Full Pipeline
Creates 7 tasks. Parallel ideators:
| Task | Owner | Deps |
|------|-------|------|
| IDEA-001 | ideator-1 | (none) |
| IDEA-002 | ideator-2 | (none) |
| IDEA-003 | ideator-3 | (none) |
| CHALLENGE-001 | challenger | IDEA-001, IDEA-002, IDEA-003 |
| IDEA-004 | ideator | CHALLENGE-001 |
| SYNTH-001 | synthesizer | IDEA-004 |
| EVAL-001 | evaluator | SYNTH-001 |
Each parallel IDEA task scoped to a specific angle from the angles list.
## Phase 4: Validation
1. Verify all tasks created by reading tasks.json
2. Check dependency chain integrity:
- No circular dependencies
- All deps references exist
- First task(s) have empty deps
3. Log task count and pipeline mode

171
.codex/skills/team-brainstorm/roles/coordinator/commands/monitor.md Normal file
View File

@@ -0,0 +1,171 @@
# Monitor Pipeline
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
- SPAWN_MODE: spawn_agent
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team_worker
- MAX_GC_ROUNDS: 2
## Handler Router
| Source | Handler |
|--------|---------|
| Message contains [ideator], [challenger], [synthesizer], [evaluator] | handleCallback |
| "consensus_blocked" | handleConsensus |
| "capability_gap" | handleAdapt |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
## handleCallback
Worker completed. Process and advance.
1. Parse message to identify role and task ID:
| Message Pattern | Role Detection |
|----------------|---------------|
| `[ideator]` or task ID `IDEA-*` | ideator |
| `[challenger]` or task ID `CHALLENGE-*` | challenger |
| `[synthesizer]` or task ID `SYNTH-*` | synthesizer |
| `[evaluator]` or task ID `EVAL-*` | evaluator |
2. Mark task as completed: Read tasks.json, update matching entry status to "completed", write back
3. Record completion in session state
4. **Generator-Critic check** (when challenger completes):
- If completed task is CHALLENGE-* AND pipeline is deep or full:
- Read critique file for GC signal
- Read .msg/meta.json for gc_round
| GC Signal | gc_round < max | Action |
|-----------|----------------|--------|
| REVISION_NEEDED | Yes | Increment gc_round, unblock IDEA-fix task |
| REVISION_NEEDED | No (>= max) | Force convergence, unblock SYNTH |
| CONVERGED | - | Unblock SYNTH (skip remaining GC tasks) |
- Log team_msg with type "gc_loop_trigger" or "task_unblocked"
- If skipping GC tasks, mark them as completed (skip)
5. Close completed agent: `close_agent({ id: <agentId> })`
6. Proceed to handleSpawnNext
## handleCheck
Read-only status report, then STOP.
```
[coordinator] Pipeline Status (<pipeline-mode>)
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] GC Rounds: <gc_round>/<max_gc_rounds>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
## handleResume
1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending"
2. Proceed to handleSpawnNext
## handleSpawnNext
Find ready tasks, spawn workers, STOP.
1. Collect: completedSubjects, inProgressSubjects, readySubjects
2. No ready + work in progress -> report waiting, STOP
3. No ready + nothing in progress -> handleComplete
4. Has ready -> for each:
a. Update tasks.json entry status -> "in_progress"
b. team_msg log -> task_unblocked
c. Spawn team_worker:
```
const agentId = spawn_agent({
agent_type: "team_worker",
items: [{ type: "text", text: `## Role Assignment
role: <role>
role_spec: ~ or <project>/.codex/skills/team-brainstorm/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: brainstorm
requirement: <task-description>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` }]
})
```
d. Collect agent results: `wait_agent({ ids: [agentId], timeout_ms: 900000 })`
e. Read discoveries from output files
f. Update tasks.json with results
g. Close agent: `close_agent({ id: agentId })`
5. Parallel spawn rules:
| Pipeline | Scenario | Spawn Behavior |
|----------|----------|---------------|
| Quick | Single sequential | One worker at a time |
| Deep | Sequential with GC | One worker at a time |
| Full | IDEA-001/002/003 unblocked | Spawn ALL 3 ideator workers in parallel |
| Full | Other stages | One worker at a time |
**Parallel ideator spawn** (Full pipeline):
```
const agentIds = []
for (const task of readyIdeatorTasks) {
agentIds.push(spawn_agent({
agent_type: "team_worker",
items: [{ type: "text", text: `...role: ideator-<N>...` }]
}))
}
const results = wait_agent({ ids: agentIds, timeout_ms: 900000 })
// Process results, close agents
for (const id of agentIds) { close_agent({ id }) }
```
6. Update session, output summary, STOP
## handleComplete
Pipeline done. Generate report and completion action.
Completion check by mode:
| Mode | Completion Condition |
|------|---------------------|
| quick | All 3 tasks completed |
| deep | All 6 tasks (+ any skipped GC tasks) completed |
| full | All 7 tasks (+ any skipped GC tasks) completed |
1. Verify all tasks completed via reading tasks.json
2. If any tasks not completed, return to handleSpawnNext
3. If all completed -> transition to coordinator Phase 5
## handleConsensus
Handle consensus_blocked signals.
| Severity | Action |
|----------|--------|
| HIGH | Pause pipeline, notify user with findings summary |
| MEDIUM | Log finding, attempt to continue |
| LOW | Log finding, continue pipeline |
## handleAdapt
Capability gap reported mid-pipeline.
1. Parse gap description
2. Check if existing role covers it -> redirect
3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/
4. Create new task (add to tasks.json), spawn worker
5. Role count >= 5 -> merge or pause
## Fast-Advance Reconciliation
On every coordinator wake:
1. Read team_msg entries with type="fast_advance"
2. Sync active_workers with spawned successors
3. No duplicate spawns

140
.codex/skills/team-brainstorm/roles/coordinator/role.md Normal file
View File

@@ -0,0 +1,140 @@
# Coordinator
Orchestrate team-brainstorm: topic clarify -> dispatch -> spawn -> monitor -> report.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Topic clarification -> Create team -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Use `team_worker` agent type for all worker spawns
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (deps)
- Stop after spawning workers -- wait for results via wait_agent
- Manage Generator-Critic loop count (max 2 rounds)
- Execute completion action in Phase 5
### MUST NOT
- Generate ideas, challenge assumptions, synthesize, or evaluate -- workers handle this
- Spawn workers without creating tasks first
- Force-advance pipeline past GC loop decisions
- Modify artifact files (ideas/*.md, critiques/*.md, etc.) -- delegate to workers
- Skip GC severity check when critique arrives
## Command Execution Protocol
When coordinator needs to execute a specific phase:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker result | Result from wait_agent contains [ideator], [challenger], [synthesizer], [evaluator] | -> handleCallback (monitor.md) |
| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active session in .workflow/.team/BRS-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/consensus/adapt/complete: load @commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
1. Scan `.workflow/.team/BRS-*/session.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile (read tasks.json, reset in_progress->pending, rebuild team, kick first ready task)
4. Multiple -> request_user_input for selection
## Phase 1: Topic Clarification + Complexity Assessment
TEXT-LEVEL ONLY. No source code reading.
1. Parse topic from $ARGUMENTS
2. Assess topic complexity:
| Signal | Weight | Keywords |
|--------|--------|----------|
| Strategic/systemic | +3 | strategy, architecture, system, framework, paradigm |
| Multi-dimensional | +2 | multiple, compare, tradeoff, versus, alternative |
| Innovation-focused | +2 | innovative, creative, novel, breakthrough |
| Simple/basic | -2 | simple, quick, straightforward, basic |
| Score | Complexity | Pipeline Recommendation |
|-------|------------|-------------------------|
| >= 4 | High | full |
| 2-3 | Medium | deep |
| 0-1 | Low | quick |
3. request_user_input for pipeline mode and divergence angles
4. Store requirements: mode, scope, angles, constraints
## Phase 2: Create Team + Initialize Session
1. Resolve workspace paths (MUST do first):
- `project_root` = result of `Bash("pwd")`
- `skill_root` = `<project_root>/.codex/skills/team-brainstorm`
2. Generate session ID: `BRS-<topic-slug>-<date>`
3. Create session folder structure: ideas/, critiques/, synthesis/, evaluation/, wisdom/, .msg/
4. Create session folder + initialize `tasks.json` (empty array)
5. Write session.json with pipeline, angles, gc_round=0, max_gc_rounds=2
6. Initialize meta.json via team_msg state_update:
```
mcp__ccw-tools__team_msg({
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: { pipeline_mode: "<mode>", pipeline_stages: ["ideator","challenger","synthesizer","evaluator"], team_name: "brainstorm", topic: "<topic>", angles: [...], gc_round: 0 }
})
```
7. Write session.json
## Phase 3: Create Task Chain
Delegate to @commands/dispatch.md:
1. Read pipeline mode and angles from session.json
2. Build tasks array and write to tasks.json with correct deps
3. Update session.json with task count
## Phase 4: Spawn-and-Stop
Delegate to @commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + deps resolved)
2. Spawn team_worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
1. Load session state -> count completed tasks, calculate duration
2. List deliverables:
| Deliverable | Path |
|-------------|------|
| Ideas | <session>/ideas/*.md |
| Critiques | <session>/critiques/*.md |
| Synthesis | <session>/synthesis/*.md |
| Evaluation | <session>/evaluation/*.md (deep/full only) |
3. Output pipeline summary: topic, pipeline mode, GC rounds, total ideas, key themes
4. Execute completion action per session.completion_action:
- interactive -> request_user_input (Archive/Keep/Export)
- auto_archive -> Archive & Clean (status=completed, clean up session)
- auto_keep -> Keep Active (status=paused)
## Error Handling
| Error | Resolution |
|-------|------------|
| Task too vague | request_user_input for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| GC loop exceeded | Force convergence to synthesizer |
| No ideas generated | Coordinator prompts with seed questions |

56
.codex/skills/team-brainstorm/roles/evaluator/role.md Normal file
View File

@@ -0,0 +1,56 @@
---
role: evaluator
prefix: EVAL
inner_loop: false
message_types: [state_update]
---
# Evaluator
Scoring, ranking, and final selection. Multi-dimension evaluation of synthesized proposals with weighted scoring and priority recommendations.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| Synthesis results | <session>/synthesis/*.md files | Yes |
| All ideas | <session>/ideas/*.md files | No (for context) |
| All critiques | <session>/critiques/*.md files | No (for context) |
1. Extract session path from task description (match "Session: <path>")
2. Glob synthesis files from <session>/synthesis/
3. Read all synthesis files for evaluation
4. Optionally read ideas and critiques for full context
## Phase 3: Evaluation and Scoring
**Scoring Dimensions**:
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Feasibility | 30% | Technical feasibility, resource needs, timeline |
| Innovation | 25% | Novelty, differentiation, breakthrough potential |
| Impact | 25% | Scope of impact, value creation, problem resolution |
| Cost Efficiency | 20% | Implementation cost, risk cost, opportunity cost |
**Weighted Score**: `(Feasibility * 0.30) + (Innovation * 0.25) + (Impact * 0.25) + (Cost * 0.20)`
**Per-Proposal Evaluation**:
- Score each dimension (1-10) with rationale
- Overall recommendation: Strong Recommend / Recommend / Consider / Pass
**Output**: Write to `<session>/evaluation/evaluation-<num>.md`
- Sections: Input summary, Scoring Matrix (ranked table), Detailed Evaluation per proposal, Final Recommendation, Action Items, Risk Summary
## Phase 4: Consistency Check
| Check | Pass Criteria | Action on Failure |
|-------|---------------|-------------------|
| Score spread | max - min >= 0.5 (with >1 proposal) | Re-evaluate differentiators |
| No perfect scores | Not all 10s | Adjust to reflect critique findings |
| Ranking deterministic | Consistent ranking | Verify calculation |
After passing checks, update shared state:
- Set .msg/meta.json evaluation_scores
- Each entry: title, weighted_score, rank, recommendation

69
.codex/skills/team-brainstorm/roles/ideator/role.md Normal file
View File

@@ -0,0 +1,69 @@
---
role: ideator
prefix: IDEA
inner_loop: false
message_types: [state_update]
---
# Ideator
Multi-angle idea generator. Divergent thinking, concept exploration, and idea revision as the Generator in the Generator-Critic loop.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| Topic | <session>/.msg/meta.json | Yes |
| Angles | <session>/.msg/meta.json | Yes |
| GC Round | <session>/.msg/meta.json | Yes |
| Previous critique | <session>/critiques/*.md | For revision tasks only |
| Previous ideas | <session>/.msg/meta.json generated_ideas | No |
1. Extract session path from task description (match "Session: <path>")
2. Read .msg/meta.json for topic, angles, gc_round
3. Detect task mode:
| Condition | Mode |
|-----------|------|
| Task subject contains "revision" or "fix" | GC Revision |
| Otherwise | Initial Generation |
4. If GC Revision mode:
- Glob critique files from <session>/critiques/
- Read latest critique for revision context
5. Read previous ideas from .msg/meta.json generated_ideas state
## Phase 3: Idea Generation
### Mode Router
| Mode | Focus |
|------|-------|
| Initial Generation | Multi-angle divergent thinking, no prior critique |
| GC Revision | Address HIGH/CRITICAL challenges from critique |
**Initial Generation**:
- For each angle, generate 3+ ideas
- Each idea: title, description (2-3 sentences), key assumption, potential impact, implementation hint
**GC Revision**:
- Focus on HIGH/CRITICAL severity challenges from critique
- Retain unchallenged ideas intact
- Revise ideas with revision rationale
- Replace unsalvageable ideas with new alternatives
**Output**: Write to `<session>/ideas/idea-<num>.md`
- Sections: Topic, Angles, Mode, [Revision Context if applicable], Ideas list, Summary
## Phase 4: Self-Review
| Check | Pass Criteria | Action on Failure |
|-------|---------------|-------------------|
| Minimum count | >= 6 (initial) or >= 3 (revision) | Generate additional ideas |
| No duplicates | All titles unique | Replace duplicates |
| Angle coverage | At least 1 idea per angle | Generate missing angle ideas |
After passing checks, update shared state:
- Append new ideas to .msg/meta.json generated_ideas
- Each entry: id, title, round, revised flag

57
.codex/skills/team-brainstorm/roles/synthesizer/role.md Normal file
View File

@@ -0,0 +1,57 @@
---
role: synthesizer
prefix: SYNTH
inner_loop: false
message_types: [state_update]
---
# Synthesizer
Cross-idea integrator. Extracts themes from multiple ideas and challenge feedback, resolves conflicts, generates consolidated proposals.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description (Session: line) | Yes |
| All ideas | <session>/ideas/*.md files | Yes |
| All critiques | <session>/critiques/*.md files | Yes |
| GC rounds completed | <session>/.msg/meta.json gc_round | Yes |
1. Extract session path from task description (match "Session: <path>")
2. Glob all idea files from <session>/ideas/
3. Glob all critique files from <session>/critiques/
4. Read all idea and critique files for synthesis
5. Read .msg/meta.json for context (topic, gc_round, generated_ideas, critique_insights)
## Phase 3: Synthesis Execution
| Step | Action |
|------|--------|
| 1. Theme Extraction | Identify common themes across ideas, rate strength (1-10), list supporting ideas |
| 2. Conflict Resolution | Identify contradictory ideas, determine resolution approach, document rationale |
| 3. Complementary Grouping | Group complementary ideas together |
| 4. Gap Identification | Discover uncovered perspectives |
| 5. Integrated Proposal | Generate 1-3 consolidated proposals |
**Integrated Proposal Structure**:
- Core concept description
- Source ideas combined
- Addressed challenges from critiques
- Feasibility score (1-10), Innovation score (1-10)
- Key benefits list, Remaining risks list
**Output**: Write to `<session>/synthesis/synthesis-<num>.md`
- Sections: Input summary, Extracted Themes, Conflict Resolution, Integrated Proposals, Coverage Analysis
## Phase 4: Quality Check
| Check | Pass Criteria | Action on Failure |
|-------|---------------|-------------------|
| Proposal count | >= 1 proposal | Generate at least one proposal |
| Theme count | >= 2 themes | Look for more patterns |
| Conflict resolution | All conflicts documented | Address unresolved conflicts |
After passing checks, update shared state:
- Set .msg/meta.json synthesis_themes
- Each entry: name, strength, supporting_ideas

171
.codex/skills/team-brainstorm/schemas/tasks-schema.md
View File

@@ -1,171 +0,0 @@
# Team Brainstorm — CSV Schema
## Master CSV: tasks.csv
### Column Definitions
#### Input Columns (Set by Decomposer)
| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `id` | string | Yes | Unique task identifier | `"IDEA-001"` |
| `title` | string | Yes | Short task title | `"Multi-angle idea generation"` |
| `description` | string | Yes | Detailed task description (self-contained) | `"Generate 3+ ideas per angle..."` |
| `role` | string | Yes | Worker role: ideator, challenger, synthesizer, evaluator | `"ideator"` |
| `angle` | string | No | Brainstorming angle(s) for ideator tasks (semicolon-separated) | `"Technical;Product;Innovation"` |
| `gc_round` | integer | Yes | Generator-Critic round number (0 = initial, 1+ = revision) | `"0"` |
| `deps` | string | No | Semicolon-separated dependency task IDs | `"IDEA-001"` |
| `context_from` | string | No | Semicolon-separated task IDs for context | `"IDEA-001"` |
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
#### 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) | `"[Task IDEA-001] Generated 8 ideas..."` |
#### Output Columns (Set by Agent)
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| `status` | enum | `pending` → `completed` / `failed` / `skipped` | `"completed"` |
| `findings` | string | Key discoveries (max 500 chars) | `"Generated 8 ideas across 3 angles..."` |
| `gc_signal` | string | Generator-Critic signal (challenger only): `REVISION_NEEDED` or `CONVERGED` | `"REVISION_NEEDED"` |
| `severity_summary` | string | Severity count summary (challenger only) | `"CRITICAL:0 HIGH:2 MEDIUM:3 LOW:1"` |
| `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,role,angle,gc_round,deps,context_from,exec_mode,wave,status,findings,gc_signal,severity_summary,error
"IDEA-001","Multi-angle idea generation","Generate 3+ ideas per angle with title, description, assumption, and potential impact. Cover all assigned angles comprehensively.","ideator","Technical;Product;Innovation","0","","","csv-wave","1","pending","","","",""
"IDEA-002","Parallel angle generation (Risk)","Generate 3+ ideas focused on Risk angle with title, description, assumption, and potential impact.","ideator","Risk","0","","","csv-wave","1","pending","","","",""
"CHALLENGE-001","Critique generated ideas","Read all idea artifacts. Challenge each idea across assumption validity, feasibility, risk, and competition dimensions. Assign severity (CRITICAL/HIGH/MEDIUM/LOW) per idea. Output GC signal.","challenger","","0","IDEA-001;IDEA-002","IDEA-001;IDEA-002","csv-wave","2","pending","","","",""
"GC-CHECK-001","GC loop decision","Evaluate critique severity counts. If any HIGH/CRITICAL: REVISION_NEEDED. Else: CONVERGED.","gc-controller","","1","CHALLENGE-001","CHALLENGE-001","interactive","3","pending","","","",""
"IDEA-003","Revise ideas (GC Round 1)","Address HIGH/CRITICAL challenges from critique. Retain unchallenged ideas intact. Replace unsalvageable ideas.","ideator","","1","GC-CHECK-001","CHALLENGE-001","csv-wave","4","pending","","","",""
"SYNTH-001","Synthesize proposals","Extract themes from ideas and critiques. Resolve conflicts. Generate 1-3 integrated proposals with feasibility and innovation scores.","synthesizer","","0","IDEA-003","IDEA-001;IDEA-002;IDEA-003;CHALLENGE-001","csv-wave","5","pending","","","",""
"EVAL-001","Score and rank proposals","Score each proposal: Feasibility 30%, Innovation 25%, Impact 25%, Cost 20%. Generate final ranking and recommendation.","evaluator","","0","SYNTH-001","SYNTH-001","csv-wave","6","pending","","","",""
```
---
### Column Lifecycle
```
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
───────────────────── ──────────────────── ─────────────────
id ───────────► id ──────────► id
title ───────────► title ──────────► (reads)
description ───────────► description ──────────► (reads)
role ───────────► role ──────────► (reads)
angle ───────────► angle ──────────► (reads)
gc_round ───────────► gc_round ──────────► (reads)
deps ───────────► deps ──────────► (reads)
context_from───────────► context_from──────────► (reads)
exec_mode ───────────► exec_mode ──────────► (reads)
wave ──────────► (reads)
prev_context ──────────► (reads)
status
findings
gc_signal
severity_summary
error
```
---
## Output Schema (JSON)
Agent output via `report_agent_job_result` (csv-wave tasks):
```json
{
"id": "IDEA-001",
"status": "completed",
"findings": "Generated 8 ideas across Technical, Product, Innovation angles. Key themes: API gateway pattern, event-driven architecture, developer experience tools.",
"gc_signal": "",
"severity_summary": "",
"error": ""
}
```
Challenger-specific output:
```json
{
"id": "CHALLENGE-001",
"status": "completed",
"findings": "Challenged 8 ideas. 2 HIGH severity (require revision), 3 MEDIUM, 3 LOW.",
"gc_signal": "REVISION_NEEDED",
"severity_summary": "CRITICAL:0 HIGH:2 MEDIUM:3 LOW:3",
"error": ""
}
```
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
---
## Discovery Types
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `idea` | `data.title` | `{title, angle, description, assumption, impact}` | Generated brainstorm idea |
| `critique` | `data.idea_title` | `{idea_title, dimension, severity, challenge, rationale}` | Critique of an idea |
| `theme` | `data.name` | `{name, strength, supporting_ideas[]}` | Extracted theme from synthesis |
| `proposal` | `data.title` | `{title, source_ideas[], feasibility, innovation, description}` | Integrated proposal |
| `evaluation` | `data.proposal_title` | `{proposal_title, weighted_score, rank, recommendation}` | Scored proposal |
| `gc_decision` | `data.round` | `{round, signal, severity_counts}` | GC loop decision record |
### Discovery NDJSON Format
```jsonl
{"ts":"2026-03-08T10:00:00+08:00","worker":"IDEA-001","type":"idea","data":{"title":"API Gateway Pattern","angle":"Technical","description":"Centralized API gateway for microservice routing","assumption":"Services need unified entry point","impact":"Simplifies client integration"}}
{"ts":"2026-03-08T10:01:00+08:00","worker":"IDEA-001","type":"idea","data":{"title":"Event Sourcing Migration","angle":"Technical","description":"Adopt event sourcing for service state management","assumption":"Current state is hard to trace across services","impact":"Full audit trail and temporal queries"}}
{"ts":"2026-03-08T10:05:00+08:00","worker":"CHALLENGE-001","type":"critique","data":{"idea_title":"API Gateway Pattern","dimension":"feasibility","severity":"MEDIUM","challenge":"Single point of failure risk","rationale":"Requires HA design with circuit breakers"}}
{"ts":"2026-03-08T10:10:00+08:00","worker":"SYNTH-001","type":"theme","data":{"name":"Infrastructure Modernization","strength":8,"supporting_ideas":["API Gateway Pattern","Event Sourcing Migration"]}}
```
> 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 in {pending, completed, failed, skipped} | "Invalid status: {status}" |
| Valid role | role in {ideator, challenger, synthesizer, evaluator, gc-controller} | "Invalid role: {role}" |
| GC round non-negative | gc_round >= 0 | "Invalid gc_round: {value}" |
| Cross-mechanism deps | Interactive→CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |

72
.codex/skills/team-brainstorm/specs/pipelines.md Normal file
View File

@@ -0,0 +1,72 @@
# Pipeline Definitions — team-brainstorm
## Available Pipelines
### Quick Pipeline (3 beats, strictly serial)
```
IDEA-001 → CHALLENGE-001 → SYNTH-001
[ideator] [challenger] [synthesizer]
```
### Deep Pipeline (6 beats, Generator-Critic loop)
```
IDEA-001 → CHALLENGE-001 → IDEA-002(fix) → CHALLENGE-002 → SYNTH-001 → EVAL-001
```
GC loop check: if critique.severity >= HIGH → create IDEA-fix → CHALLENGE-2 → SYNTH; else skip to SYNTH
### Full Pipeline (7 tasks, fan-out parallel ideation + GC)
```
[IDEA-001 + IDEA-002 + IDEA-003](parallel) → CHALLENGE-001(batch) → IDEA-004(fix) → SYNTH-001 → EVAL-001
```
## Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| IDEA-001 | ideator | generate | (none) | Multi-angle idea generation |
| IDEA-002 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
| IDEA-003 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
| CHALLENGE-001 | challenger | challenge | IDEA-001 (or all IDEA-*) | Devil's advocate critique and feasibility challenge |
| IDEA-004 | ideator | gc-fix | CHALLENGE-001 | Revision based on critique (GC loop, if triggered) |
| CHALLENGE-002 | challenger | gc-fix | IDEA-004 | Re-critique of revised ideas (GC loop round 2) |
| SYNTH-001 | synthesizer | synthesize | last CHALLENGE-* | Cross-idea integration, theme extraction, conflict resolution |
| EVAL-001 | evaluator | evaluate | SYNTH-001 | Scoring, ranking, priority recommendation, final selection |
## Checkpoints
| Trigger | Location | Behavior |
|---------|----------|----------|
| Generator-Critic loop | After CHALLENGE-* | If severity >= HIGH → create IDEA-fix task; else proceed to SYNTH |
| GC loop limit | Max 2 rounds | Exceeds limit → force convergence to SYNTH |
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
## Completion Conditions
| Mode | Completion Condition |
|------|---------------------|
| quick | All 3 tasks completed |
| deep | All 6 tasks (+ any skipped GC tasks) completed |
| full | All 7 tasks (+ any skipped GC tasks) completed |
## Shared State (meta.json)
| Role | State Key |
|------|-----------|
| ideator | `generated_ideas` |
| challenger | `critique_insights` |
| synthesizer | `synthesis_themes` |
| evaluator | `evaluation_scores` |
## Message Types
| Role | Types |
|------|-------|
| coordinator | `pipeline_selected`, `gc_loop_trigger`, `task_unblocked`, `error`, `shutdown` |
| ideator | `ideas_ready`, `ideas_revised`, `error` |
| challenger | `critique_ready`, `error` |
| synthesizer | `synthesis_ready`, `error` |
| evaluator | `evaluation_ready`, `error` |

86
.codex/skills/team-brainstorm/specs/team-config.json Normal file
View File

@@ -0,0 +1,86 @@
{
"team_name": "team-brainstorm",
"team_display_name": "Team Brainstorm",
"description": "Head brainstorming team with Generator-Critic loop, shared memory, and dynamic pipeline selection",
"version": "1.0.0",
"roles": {
"coordinator": {
"task_prefix": null,
"responsibility": "Topic clarification, complexity assessment, pipeline selection, convergence monitoring",
"message_types": ["pipeline_selected", "gc_loop_trigger", "task_unblocked", "error", "shutdown"]
},
"ideator": {
"task_prefix": "IDEA",
"responsibility": "Multi-angle idea generation, concept exploration, divergent thinking",
"message_types": ["ideas_ready", "ideas_revised", "error"]
},
"challenger": {
"task_prefix": "CHALLENGE",
"responsibility": "Devil's advocate, assumption challenging, feasibility questioning",
"message_types": ["critique_ready", "error"]
},
"synthesizer": {
"task_prefix": "SYNTH",
"responsibility": "Cross-idea integration, theme extraction, conflict resolution",
"message_types": ["synthesis_ready", "error"]
},
"evaluator": {
"task_prefix": "EVAL",
"responsibility": "Scoring and ranking, priority recommendation, final selection",
"message_types": ["evaluation_ready", "error"]
}
},
"pipelines": {
"quick": {
"description": "Simple topic: generate → challenge → synthesize",
"task_chain": ["IDEA-001", "CHALLENGE-001", "SYNTH-001"],
"gc_loops": 0
},
"deep": {
"description": "Complex topic with Generator-Critic loop (max 2 rounds)",
"task_chain": ["IDEA-001", "CHALLENGE-001", "IDEA-002", "CHALLENGE-002", "SYNTH-001", "EVAL-001"],
"gc_loops": 2
},
"full": {
"description": "Parallel fan-out ideation + Generator-Critic + evaluation",
"task_chain": ["IDEA-001", "IDEA-002", "IDEA-003", "CHALLENGE-001", "IDEA-004", "SYNTH-001", "EVAL-001"],
"gc_loops": 1,
"parallel_groups": [["IDEA-001", "IDEA-002", "IDEA-003"]]
}
},
"innovation_patterns": {
"generator_critic": {
"generator": "ideator",
"critic": "challenger",
"max_rounds": 2,
"convergence_trigger": "critique.severity < HIGH"
},
"shared_memory": {
"file": "shared-memory.json",
"fields": {
"ideator": "generated_ideas",
"challenger": "critique_insights",
"synthesizer": "synthesis_themes",
"evaluator": "evaluation_scores"
}
},
"dynamic_pipeline": {
"selector": "coordinator",
"criteria": "topic_complexity + scope + time_constraint"
}
},
"collaboration_patterns": ["CP-1", "CP-3", "CP-7"],
"session_dirs": {
"base": ".workflow/.team/BRS-{slug}-{YYYY-MM-DD}/",
"ideas": "ideas/",
"critiques": "critiques/",
"synthesis": "synthesis/",
"evaluation": "evaluation/",
"messages": ".workflow/.team-msg/{team-name}/"
}
}

808
.codex/skills/team-coordinate/SKILL.md
View File

@@ -1,667 +1,267 @@
---
name: team-coordinate
description: Universal team coordination skill with dynamic role generation. Analyzes task, generates worker roles at runtime, decomposes into CSV tasks with dependency waves, dispatches parallel CSV agents per wave. Coordinator is orchestrator; all workers are CSV or interactive agents with dynamically generated instructions.
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, request_user_input
description: Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on "Team Coordinate ".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
# Team Coordinate
## Usage
Universal team coordination skill: analyze task -> generate role-specs -> dispatch -> execute -> deliver. Only the **coordinator** is built-in. All worker roles are **dynamically generated** as lightweight role-spec files and spawned via the `team-worker` agent.
```bash
$team-coordinate "Implement user authentication with JWT tokens"
$team-coordinate -c 4 "Refactor payment module and write API documentation"
$team-coordinate -y "Analyze codebase security and fix vulnerabilities"
$team-coordinate --continue "tc-auth-jwt-20260308"
```
**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
Universal team coordination: analyze task -> detect capabilities -> generate dynamic role instructions -> decompose into dependency-ordered CSV tasks -> execute wave-by-wave -> deliver results. Only the **coordinator** (this orchestrator) is built-in. All worker roles are **dynamically generated** as CSV agent instructions at runtime.
**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
## Architecture
```
+-------------------------------------------------------------------+
| TEAM COORDINATE WORKFLOW |
+-------------------------------------------------------------------+
| |
| Phase 0: Pre-Wave Interactive (Requirement Clarification) |
| +- Parse user task description |
| +- Clarify ambiguous requirements (request_user_input) |
| +- Output: refined requirements for decomposition |
| |
| Phase 1: Requirement -> CSV + Classification |
| +- Signal detection: keyword scan -> capability inference |
| +- Dependency graph construction (DAG) |
| +- Role minimization (cap at 5 roles) |
| +- Classify tasks: csv-wave | interactive (exec_mode) |
| +- Compute dependency waves (topological sort) |
| +- Generate tasks.csv with wave + exec_mode columns |
| +- Generate per-role agent instructions dynamically |
| +- User validates task breakdown (skip if -y) |
| |
| Phase 2: Wave Execution Engine (Extended) |
| +- For each wave (1..N): |
| | +- Execute pre-wave interactive tasks (if any) |
| | +- 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 (if any) |
| | +- Merge all results into master tasks.csv |
| | +- Check: any failed? -> skip dependents |
| +- discoveries.ndjson shared across all modes (append-only) |
| |
| Phase 3: Post-Wave Interactive (Completion Action) |
| +- Pipeline completion report |
| +- Interactive completion choice (Archive/Keep/Export) |
| +- Final aggregation / report |
| |
| Phase 4: 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 |
| |
+-------------------------------------------------------------------+
+---------------------------------------------------+
| Skill(skill="team-coordinate") |
| args="task description" |
+-------------------+-------------------------------+
|
Orchestration Mode (auto -> coordinator)
|
Coordinator (built-in)
Phase 0-5 orchestration
|
+-------+-------+-------+-------+
v v v v v
[team-worker agents, each loaded with a dynamic role-spec]
(roles generated at runtime from task analysis)
CLI Tools (callable by any worker):
ccw cli --mode analysis - analysis and exploration
ccw cli --mode write - code generation and modification
```
---
## Shared Constants
## Task Classification Rules
| Constant | Value |
|----------|-------|
| Session prefix | `TC` |
| Session path | `.workflow/.team/TC-<slug>-<date>/` |
| Worker agent | `team-worker` |
| Message bus | `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)` |
| CLI analysis | `ccw cli --mode analysis` |
| CLI write | `ccw cli --mode write` |
| Max roles | 5 |
Each task is classified by `exec_mode`:
## Role Router
| 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, needs clarification, revision cycles |
This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
**Classification Decision**:
### Input Parsing
| Task Property | Classification |
|---------------|---------------|
| Single-pass code implementation | `csv-wave` |
| Single-pass analysis or documentation | `csv-wave` |
| Research with defined scope | `csv-wave` |
| Testing with known targets | `csv-wave` |
| Design requiring iterative refinement | `interactive` |
| Plan requiring user approval checkpoint | `interactive` |
| Revision cycle (fix-verify loop) | `interactive` |
Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
---
### Role Registry
## CSV Schema
Only coordinator is statically registered. All other roles are dynamic, stored as role-specs in session.
### tasks.csv (Master State)
| Role | File | Type |
|------|------|------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | built-in orchestrator |
| (dynamic) | `<session>/role-specs/<role-name>.md` | runtime-generated role-spec |
```csv
id,title,description,role,responsibility_type,output_type,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,error
"RESEARCH-001","Investigate auth patterns","Research JWT authentication patterns and best practices","researcher","orchestration","artifact","","","csv-wave","1","pending","","",""
"IMPL-001","Implement auth module","Build JWT authentication middleware","developer","code-gen","codebase","RESEARCH-001","RESEARCH-001","csv-wave","2","pending","","",""
"TEST-001","Validate auth implementation","Write and run tests for auth module","tester","validation","artifact","IMPL-001","IMPL-001","csv-wave","3","pending","","",""
### CLI Tool Usage
Workers can use CLI tools for analysis and code operations:
| Tool | Purpose |
|------|---------|
| ccw cli --mode analysis | Analysis, exploration, pattern discovery |
| ccw cli --mode write | Code generation, modification, refactoring |
### Dispatch
Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
### Orchestration Mode
User just provides task description.
**Invocation**: `Skill(skill="team-coordinate", args="task description")`
**Lifecycle**:
```
User provides task description
-> coordinator Phase 1: task analysis (detect capabilities, build dependency graph)
-> coordinator Phase 2: generate role-specs + initialize session
-> coordinator Phase 3: create task chain from dependency graph
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
-> Worker executes -> callback -> coordinator advances next step
-> Loop until pipeline complete -> Phase 5 report + completion action
```
**Columns**:
**User Commands** (wake paused coordinator):
| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (PREFIX-NNN format) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description with goal, steps, success criteria |
| `role` | Input | Dynamic role name (researcher, developer, analyst, etc.) |
| `responsibility_type` | Input | `orchestration`, `read-only`, `code-gen`, `code-gen-docs`, `validation` |
| `output_type` | Input | `artifact` (session files), `codebase` (project files), `mixed` |
| `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` |
| `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) |
| `artifacts_produced` | Output | Semicolon-separated paths of produced artifacts |
| `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).
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
| `revise <TASK-ID> [feedback]` | Revise specific task with optional feedback |
| `feedback <text>` | Inject feedback into active pipeline |
| `improve [dimension]` | Auto-improve weakest quality dimension |
---
## Agent Registry (Interactive Agents)
## Coordinator Spawn Template
| Agent | Role File | Pattern | Responsibility | Position |
|-------|-----------|---------|----------------|----------|
| Plan Reviewer | agents/plan-reviewer.md | 2.3 (send_input cycle) | Review and approve plans before execution waves | pre-wave |
| Completion Handler | agents/completion-handler.md | 2.3 (send_input cycle) | Handle pipeline completion action (Archive/Keep/Export) | standalone |
### v2 Worker Spawn (all roles)
> **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 4 |
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
| `context.md` | Human-readable execution report | Created in Phase 4 |
| `task-analysis.json` | Phase 0/1 output: capabilities, dependency graph, roles | Created in Phase 1 |
| `role-instructions/` | Dynamically generated per-role instruction templates | Created in Phase 1 |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
---
## Session Structure
When coordinator spawns workers, use `team-worker` agent with role-spec path:
```
.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
+-- task-analysis.json # Phase 1 analysis output
+-- wave-{N}.csv # Temporary per-wave input (csv-wave only)
+-- role-instructions/ # Dynamically generated instruction templates
| +-- researcher.md
| +-- developer.md
| +-- ...
+-- artifacts/ # All deliverables from workers
| +-- research-findings.md
| +-- implementation-summary.md
| +-- ...
+-- interactive/ # Interactive task artifacts
| +-- {id}-result.json
+-- wisdom/ # Cross-task knowledge
+-- learnings.md
+-- decisions.md
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <session-folder>/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
**Inner Loop roles** (role has 2+ serial same-prefix tasks): Set `inner_loop: true`. The team-worker agent handles the loop internally.
**Single-task roles**: Set `inner_loop: false`.
---
## Implementation
## Completion Action
### Session Initialization
When pipeline completes (all tasks done), coordinator presents an interactive choice:
```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
const requirement = $ARGUMENTS
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
.trim()
const slug = requirement.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = `tc-${slug}-${dateStr}`
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
Bash(`mkdir -p ${sessionFolder}/artifacts ${sessionFolder}/role-instructions ${sessionFolder}/interactive ${sessionFolder}/wisdom`)
// Initialize discoveries.ndjson
Write(`${sessionFolder}/discoveries.ndjson`, '')
// Initialize wisdom files
Write(`${sessionFolder}/wisdom/learnings.md`, '# Learnings\n')
Write(`${sessionFolder}/wisdom/decisions.md`, '# Decisions\n')
```
request_user_input({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Export Results", description: "Export deliverables to target directory, then clean" }
]
}]
})
```
---
### Action Handlers
### Phase 0: Pre-Wave Interactive (Requirement Clarification)
**Objective**: Parse user task, clarify ambiguities, prepare for decomposition.
**Workflow**:
1. **Parse user task description** from $ARGUMENTS
2. **Check for existing sessions** (continue mode):
- Scan `.workflow/.csv-wave/tc-*/tasks.csv` for sessions with pending tasks
- If `--continue`: resume the specified or most recent session, skip to Phase 2
- If active session found: ask user whether to resume or start new
3. **Clarify if ambiguous** (skip if AUTO_YES):
```javascript
request_user_input({
questions: [{
question: "Please confirm the task scope and deliverables.",
header: "Scope",
id: "task_scope",
options: [
{ label: "Proceed (Recommended)", description: "Task is clear enough" },
{ label: "Narrow scope", description: "Specify files/modules/areas" },
{ label: "Add constraints", description: "Timeline, tech stack, style" }
]
}]
})
```
4. **Output**: Refined requirement string for Phase 1
**Success Criteria**:
- Refined requirements available for Phase 1 decomposition
- Existing session detected and handled if applicable
| Choice | Steps |
|--------|-------|
| Archive & Clean | Update session status="completed" -> output final summary with artifact paths |
| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-coordinate', args='resume')" |
| Export Results | request_user_input(target path) -> copy artifacts to target -> Archive & Clean |
---
### Phase 1: Requirement -> CSV + Classification
## Specs Reference
**Objective**: Analyze task, detect capabilities, build dependency graph, generate tasks.csv and role instructions.
| Spec | Purpose |
|------|---------|
| [specs/pipelines.md](specs/pipelines.md) | Dynamic pipeline model, task naming, dependency graph |
| [specs/role-spec-template.md](specs/role-spec-template.md) | Template for dynamic role-spec generation |
| [specs/quality-gates.md](specs/quality-gates.md) | Quality thresholds and scoring dimensions |
| [specs/knowledge-transfer.md](specs/knowledge-transfer.md) | Context transfer protocols between roles |
**Decomposition Rules**:
---
1. **Signal Detection** -- scan task description for capability keywords:
## Session Directory
| Signal | Keywords | Capability | Prefix | Responsibility Type |
|--------|----------|------------|--------|---------------------|
| Research | investigate, explore, compare, survey, find, research, discover | researcher | RESEARCH | orchestration |
| Writing | write, draft, document, article, report, summarize | writer | DRAFT | code-gen-docs |
| Coding | implement, build, code, fix, refactor, develop, create, migrate | developer | IMPL | code-gen |
| Design | design, architect, plan, structure, blueprint, schema | designer | DESIGN | orchestration |
| Analysis | analyze, review, audit, assess, evaluate, inspect, diagnose | analyst | ANALYSIS | read-only |
| Testing | test, verify, validate, QA, quality, check, coverage | tester | TEST | validation |
| Planning | plan, breakdown, organize, schedule, decompose, roadmap | planner | PLAN | orchestration |
2. **Dependency Graph** -- build DAG using natural ordering tiers:
| Tier | Capabilities | Description |
|------|-------------|-------------|
| 0 | researcher, planner | Knowledge gathering / planning |
| 1 | designer | Design (requires tier 0 if present) |
| 2 | writer, developer | Creation (requires design/plan if present) |
| 3 | analyst, tester | Validation (requires artifacts to validate) |
3. **Role Minimization** -- merge overlapping capabilities, cap at 5 roles
4. **Key File Inference** -- extract nouns from task description, map to likely file paths
5. **output_type derivation**:
| Task Signal | output_type |
|-------------|-------------|
| "write report", "analyze", "research" | `artifact` |
| "update code", "modify", "fix bug" | `codebase` |
| "implement feature + write summary" | `mixed` |
**Classification Rules**:
| Task Property | exec_mode |
|---------------|-----------|
| Single-pass implementation/analysis/documentation | `csv-wave` |
| Needs iterative user approval | `interactive` |
| Fix-verify revision cycle | `interactive` |
| Standard research, coding, testing | `csv-wave` |
**Wave Computation**: Kahn's BFS topological sort with depth tracking.
```javascript
// After task analysis, generate dynamic role instruction templates
for (const role of analysisResult.roles) {
const instruction = generateRoleInstruction(role, sessionFolder)
Write(`${sessionFolder}/role-instructions/${role.name}.md`, instruction)
}
// Generate tasks.csv from dependency graph
const tasks = buildTasksCsv(analysisResult)
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
Write(`${sessionFolder}/task-analysis.json`, JSON.stringify(analysisResult, null, 2))
```
.workflow/.team/TC-<slug>-<date>/
+-- team-session.json # Session state + dynamic role registry
+-- task-analysis.json # Phase 1 output: capabilities, dependency graph
+-- role-specs/ # Dynamic role-spec definitions (generated Phase 2)
| +-- <role-1>.md # Lightweight: frontmatter + Phase 2-4 only
| +-- <role-2>.md
+-- artifacts/ # All MD deliverables from workers
| +-- <artifact>.md
+-- .msg/ # Team message bus + state
| +-- messages.jsonl # Message log
| +-- meta.json # Session metadata + cross-role state
+-- wisdom/ # Cross-task knowledge
| +-- learnings.md
| +-- decisions.md
| +-- issues.md
+-- explorations/ # Shared explore cache
| +-- cache-index.json
| +-- explore-<angle>.json
+-- discussions/ # Inline discuss records
| +-- <round>.md
```
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
### team-session.json Schema
**Success Criteria**:
- tasks.csv created with valid schema, wave, and exec_mode assignments
- Role instruction templates generated in role-instructions/
- task-analysis.json written
- 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
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
const maxWave = Math.max(...tasks.map(t => t.wave))
for (let wave = 1; wave <= maxWave; wave++) {
console.log(`\nWave ${wave}/${maxWave}`)
// 1. Separate tasks by exec_mode
const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
// 2. Check dependencies -- skip tasks whose deps failed
for (const task of waveTasks) {
const depIds = (task.deps || '').split(';').filter(Boolean)
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
task.status = 'skipped'
task.error = `Dependency failed: ${depIds.filter((id, i) =>
['failed','skipped'].includes(depStatuses[i])).join(', ')}`
```json
{
"session_id": "TC-<slug>-<date>",
"task_description": "<original user input>",
"status": "active | paused | completed",
"team_name": "<team-name>",
"roles": [
{
"name": "<role-name>",
"prefix": "<PREFIX>",
"responsibility_type": "<type>",
"inner_loop": false,
"role_spec": "role-specs/<role-name>.md"
}
}
// 3. Execute pre-wave interactive tasks (e.g., plan approval)
const preWaveInteractive = interactiveTasks.filter(t => t.status === 'pending')
for (const task of preWaveInteractive) {
// Read agent definition
Read(`agents/plan-reviewer.md`)
const agent = spawn_agent({
message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: ${sessionFolder}/discoveries.ndjson\n\nGoal: ${task.description}\nScope: ${task.title}\nSession: ${sessionFolder}\n\n### Previous Context\n${buildPrevContext(task, tasks)}`
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
if (result.timed_out) {
send_input({ id: agent, message: "Please finalize and output current findings." })
wait({ ids: [agent], timeout_ms: 120000 })
}
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
task_id: task.id, status: "completed", findings: parseFindings(result),
timestamp: getUtc8ISOString()
}))
close_agent({ id: agent })
task.status = 'completed'
task.findings = parseFindings(result)
}
// 4. Build prev_context for csv-wave tasks
const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
for (const task of pendingCsvTasks) {
task.prev_context = buildPrevContext(task, tasks)
}
if (pendingCsvTasks.length > 0) {
// 5. Write wave CSV
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))
// 6. Determine instruction for this wave (use role-specific instruction)
// Group tasks by role, build combined instruction
const waveInstruction = buildWaveInstruction(pendingCsvTasks, sessionFolder, wave)
// 7. Execute wave via spawn_agents_on_csv
spawn_agents_on_csv({
csv_path: `${sessionFolder}/wave-${wave}.csv`,
id_column: "id",
instruction: waveInstruction,
max_concurrency: maxConcurrency,
max_runtime_seconds: 900,
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
artifacts_produced: { type: "string" },
error: { type: "string" }
}
}
})
// 8. Merge results into master CSV
const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
for (const r of results) {
const t = tasks.find(t => t.id === r.id)
if (t) Object.assign(t, r)
}
}
// 9. Update master CSV
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
// 10. Cleanup temp files
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
// 11. Display wave summary
const completed = waveTasks.filter(t => t.status === 'completed').length
const failed = waveTasks.filter(t => t.status === 'failed').length
const skipped = waveTasks.filter(t => t.status === 'skipped').length
console.log(`Wave ${wave} Complete: ${completed} completed, ${failed} failed, ${skipped} skipped`)
],
"pipeline": {
"dependency_graph": {},
"tasks_total": 0,
"tasks_completed": 0
},
"active_workers": [],
"completed_tasks": [],
"completion_action": "interactive",
"created_at": "<timestamp>"
}
```
**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
---
### Phase 3: Post-Wave Interactive (Completion Action)
## Session Resume
**Objective**: Pipeline completion report and interactive completion choice.
Coordinator supports `resume` / `continue` for interrupted sessions:
```javascript
// 1. Generate pipeline summary
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
const completed = tasks.filter(t => t.status === 'completed')
const failed = tasks.filter(t => t.status === 'failed')
console.log(`
============================================
TASK COMPLETE
Deliverables:
${completed.map(t => ` - ${t.id}: ${t.title} (${t.role})`).join('\n')}
Pipeline: ${completed.length}/${tasks.length} tasks
Duration: <elapsed>
Session: ${sessionFolder}
============================================
`)
// 2. Completion action
if (!AUTO_YES) {
const choice = request_user_input({
questions: [{
question: "Team pipeline complete. Choose next action.",
header: "Done",
id: "completion",
options: [
{ label: "Archive (Recommended)", description: "Archive session, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Retry Failed", description: "Re-run failed tasks" }
]
}]
})
// Handle choice accordingly
}
```
**Success Criteria**:
- Post-wave interactive processing complete
- User informed of results
---
### Phase 4: Results Aggregation
**Objective**: Generate final results and human-readable report.
```javascript
// 1. Export results.csv
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
// 2. Generate context.md
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
let contextMd = `# Team Coordinate Report\n\n`
contextMd += `**Session**: ${sessionId}\n`
contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n\n`
contextMd += `## Summary\n`
contextMd += `| Status | Count |\n|--------|-------|\n`
contextMd += `| Completed | ${tasks.filter(t => t.status === 'completed').length} |\n`
contextMd += `| Failed | ${tasks.filter(t => t.status === 'failed').length} |\n`
contextMd += `| Skipped | ${tasks.filter(t => t.status === 'skipped').length} |\n\n`
const maxWave = Math.max(...tasks.map(t => t.wave))
contextMd += `## Wave Execution\n\n`
for (let w = 1; w <= maxWave; w++) {
const waveTasks = tasks.filter(t => t.wave === w)
contextMd += `### Wave ${w}\n\n`
for (const t of waveTasks) {
const icon = t.status === 'completed' ? '[DONE]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
contextMd += `${icon} **${t.title}** [${t.role}] ${t.findings || ''}\n\n`
}
}
Write(`${sessionFolder}/context.md`, contextMd)
// 3. Display final summary
console.log(`Results exported to: ${sessionFolder}/results.csv`)
console.log(`Report generated at: ${sessionFolder}/context.md`)
```
**Success Criteria**:
- results.csv exported (all tasks, both modes)
- context.md generated
- Summary displayed to user
---
## Shared Discovery Board Protocol
All agents (csv-wave and interactive) share a single `discoveries.ndjson` file for cross-task knowledge exchange.
**Format**: One JSON object per line (NDJSON):
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"RESEARCH-001","type":"pattern_found","data":{"pattern_name":"Repository Pattern","location":"src/repos/","description":"Data access layer uses repository pattern"}}
{"ts":"2026-03-08T10:05:00Z","worker":"IMPL-001","type":"file_modified","data":{"file":"src/auth/jwt.ts","change":"Added JWT middleware","lines_added":45}}
```
**Discovery Types**:
| Type | Data Schema | Description |
|------|-------------|-------------|
| `pattern_found` | `{pattern_name, location, description}` | Design pattern identified |
| `file_modified` | `{file, change, lines_added}` | File change recorded |
| `dependency_found` | `{from, to, type}` | Dependency relationship discovered |
| `issue_found` | `{file, line, severity, description}` | Issue or bug discovered |
| `decision_made` | `{decision, rationale, impact}` | Design decision recorded |
| `artifact_produced` | `{name, path, producer, type}` | Deliverable created |
**Protocol**:
1. Agents MUST read discoveries.ndjson at start of execution
2. Agents MUST append relevant discoveries during execution
3. Agents MUST NOT modify or delete existing entries
4. Deduplication by `{type, data.file, data.pattern_name}` key
---
## Dynamic Role Instruction Generation
The coordinator generates role-specific instruction templates during Phase 1. Each template is written to `role-instructions/{role-name}.md` and used as the `instruction` parameter for `spawn_agents_on_csv`.
**Generation Rules**:
1. Each instruction must be self-contained (agent has no access to master CSV)
2. Use `{column_name}` placeholders for CSV column substitution
3. Include session folder path as literal (not placeholder)
4. Include mandatory discovery board read/write steps
5. Include role-specific execution guidance based on responsibility_type
6. Include output schema matching tasks.csv output columns
See `instructions/agent-instruction.md` for the base instruction template that is customized per role.
1. Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
2. Multiple matches -> request_user_input for selection
3. Audit task states -> reconcile session state <-> task status
4. Reset in_progress -> pending (interrupted tasks)
5. Rebuild team and spawn needed workers only
6. Create missing tasks, set dependencies
7. Kick first executable task -> Phase 4 coordination loop
---
## 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 |
| 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 |
| No capabilities detected | Default to single `general` role with TASK prefix |
| All capabilities merge to one | Valid: single-role execution, reduced overhead |
| Task description too vague | request_user_input for clarification in Phase 0 |
| Continue mode: no session found | List available sessions, prompt user to select |
| Role instruction generation fails | Fall back to generic instruction template |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 0/1
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
7. **Skip on Failure**: If a dependency failed, skip the dependent task
8. **Dynamic Roles**: All worker roles are generated at runtime from task analysis -- no static role registry
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
---
## Coordinator Role Constraints (Main Agent)
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Dynamic role-spec not found | Error, coordinator may need to regenerate |
| Command file not found | Fallback to inline execution |
| CLI tool fails | Worker proceeds with direct implementation, logs warning |
| Explore cache corrupt | Clear cache, re-explore |
| Fast-advance spawns wrong task | Coordinator reconciles on next callback |
| capability_gap reported | Coordinator generates new role-spec via handleAdapt |
| Completion action fails | Default to Keep Active, log warning |

127
.codex/skills/team-coordinate/agents/completion-handler.md
View File

@@ -1,127 +0,0 @@
# Completion Handler Agent
Interactive agent for handling pipeline completion actions. Presents results summary and manages Archive/Keep/Export choices.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/completion-handler.md`
- **Responsibility**: Pipeline completion reporting and cleanup action
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read final tasks.csv to compile completion summary
- Present deliverables list with paths
- Execute chosen completion action
- Produce structured output following template
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Delete session data without user confirmation
- Produce unstructured output
- Modify task artifacts
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load tasks.csv, artifacts |
| `request_user_input` | built-in | Get completion choice |
| `Write` | built-in | Store completion result |
| `Bash` | built-in | Archive or export operations |
---
## Execution
### Phase 1: Summary Generation
**Objective**: Compile pipeline completion summary
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| tasks.csv | Yes | Master state with all results |
| artifacts/ | No | Deliverable files |
| discoveries.ndjson | No | Shared discoveries |
**Steps**:
1. Read tasks.csv, count completed/failed/skipped
2. List all produced artifacts with paths
3. Summarize discoveries
4. Calculate pipeline duration if timestamps available
**Output**: Completion summary
---
### Phase 2: Completion Choice
**Objective**: Execute user's chosen completion action
**Steps**:
1. Present completion choice:
```javascript
request_user_input({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
id: "completion_action",
options: [
{ label: "Archive & Clean (Recommended)", description: "Mark session complete, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Export Results", description: "Export deliverables to target directory" }
]
}]
})
```
2. Handle choice:
| Choice | Steps |
|--------|-------|
| Archive & Clean | Write completion status, output artifact paths |
| Keep Active | Keep session files, output resume instructions |
| Export Results | Ask target path, copy artifacts, then archive |
**Output**: Completion action result
---
## Structured Output Template
```
## Summary
- Pipeline status: completed
- Tasks: <completed>/<total>
## Deliverables
- <artifact-path-1> (produced by <role>)
- <artifact-path-2> (produced by <role>)
## Action Taken
- Choice: <archive|keep|export>
- Details: <action-specific details>
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| tasks.csv not found | Report error, suggest manual review |
| Export target path invalid | Ask user for valid path |
| Processing failure | Default to Keep Active, log warning |

145
.codex/skills/team-coordinate/agents/plan-reviewer.md
View File

@@ -1,145 +0,0 @@
# Plan Reviewer Agent
Interactive agent for reviewing and approving plans before execution waves. Used when a task requires user confirmation checkpoint before proceeding.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/plan-reviewer.md`
- **Responsibility**: Review generated plans, seek user approval, handle revision requests
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read the plan artifact being reviewed
- Present a clear summary to the user
- Wait for user approval before reporting complete
- Produce structured output following template
- Include file:line references in findings
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Approve plans without user confirmation
- Modify the plan artifact directly
- Produce unstructured output
- Exceed defined scope boundaries
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load plan artifacts and context |
| `request_user_input` | built-in | Get user approval or revision feedback |
| `Write` | built-in | Store review result |
### Tool Usage Patterns
**Read Pattern**: Load context files before review
```
Read("<session>/artifacts/<plan>.md")
Read("<session>/discoveries.ndjson")
```
**Write Pattern**: Store review result
```
Write("<session>/interactive/<task-id>-result.json", <result>)
```
---
## Execution
### Phase 1: Context Loading
**Objective**: Load the plan artifact and supporting context
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Plan artifact | Yes | The plan document to review |
| discoveries.ndjson | No | Shared discoveries for context |
| Previous task findings | No | Upstream task results |
**Steps**:
1. Extract session path from task assignment
2. Read the plan artifact referenced in the task description
3. Read discoveries.ndjson for additional context
4. Summarize key aspects of the plan
**Output**: Plan summary ready for user review
---
### Phase 2: User Review
**Objective**: Present plan to user and get approval
**Steps**:
1. Display plan summary with key decisions and trade-offs
2. Present approval choice:
```javascript
request_user_input({
questions: [{
question: "Review the plan and decide:",
header: "Plan Review",
id: "plan_review",
options: [
{ label: "Approve (Recommended)", description: "Proceed with execution" },
{ label: "Revise", description: "Request changes to the plan" },
{ label: "Abort", description: "Cancel the pipeline" }
]
}]
})
```
3. Handle response:
| Response | Action |
|----------|--------|
| Approve | Report approved status |
| Revise | Collect revision feedback, report revision needed |
| Abort | Report abort status |
**Output**: Review decision with details
---
## Structured Output Template
```
## Summary
- Plan reviewed: <plan-name>
- Decision: <approved|revision-needed|aborted>
## Findings
- Key strength 1: description
- Key concern 1: description
## Decision Details
- User choice: <choice>
- Feedback: <user feedback if revision>
## Open Questions
1. Any unresolved items from review
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Plan artifact not found | Report in Open Questions, ask user for path |
| User does not respond | Timeout, report partial with "awaiting-review" status |
| Processing failure | Output partial results with clear status indicator |

184
.codex/skills/team-coordinate/instructions/agent-instruction.md
View File

@@ -1,184 +0,0 @@
# Agent Instruction Template -- Team Coordinate
Base instruction template for CSV wave agents. The orchestrator dynamically customizes this per role during Phase 1, writing role-specific versions to `role-instructions/{role-name}.md`.
## Purpose
| Phase | Usage |
|-------|-------|
| Phase 1 | Coordinator generates per-role instruction from this template |
| Phase 2 | Injected as `instruction` parameter to `spawn_agents_on_csv` |
---
## Base Instruction Template
```markdown
## TASK ASSIGNMENT -- Team Coordinate
### 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)
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**Responsibility**: {responsibility_type}
**Output Type**: {output_type}
### Task Description
{description}
### 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 task**:
- Read target files referenced in description
- Follow the execution steps outlined in the TASK section of description
- Produce deliverables matching the EXPECTED section of description
- Verify output matches success criteria
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
- `pattern_found`: {pattern_name, location, description} -- Design pattern identified in codebase
- `file_modified`: {file, change, lines_added} -- File change performed by this agent
- `dependency_found`: {from, to, type} -- Dependency relationship between components
- `issue_found`: {file, line, severity, description} -- Issue or bug discovered
- `decision_made`: {decision, rationale, impact} -- Design decision made during execution
- `artifact_produced`: {name, path, producer, type} -- Deliverable file created
---
## Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key discoveries and implementation notes (max 500 chars)",
"artifacts_produced": "semicolon-separated paths of produced files",
"error": ""
}
```
---
## Role-Specific Customization
The coordinator generates per-role instruction variants during Phase 1. Each variant adds role-specific execution guidance to Step 3.
### For Research / Exploration Roles
Add to execution protocol step 3:
```
3. **Execute**:
- Define exploration scope from description
- Use code search tools to find relevant patterns and implementations
- Survey approaches, compare alternatives
- Document findings with file:line references
- Write research artifact to <session-folder>/artifacts/
```
### For Code Implementation Roles
Add to execution protocol step 3:
```
3. **Execute**:
- Read upstream design/spec artifacts referenced in description
- Read target files listed in description
- Apply code changes following project conventions
- Validate changes compile/lint correctly
- Run relevant tests if available
- Write implementation summary to <session-folder>/artifacts/
```
### For Analysis / Audit Roles
Add to execution protocol step 3:
```
3. **Execute**:
- Read target files/modules for analysis
- Apply analysis criteria systematically
- Classify findings by severity (critical, high, medium, low)
- Include file:line references in findings
- Write analysis report to <session-folder>/artifacts/
```
### For Test / Validation Roles
Add to execution protocol step 3:
```
3. **Execute**:
- Read source files to understand implementation
- Identify test cases from description
- Generate test files following project test conventions
- Run tests and capture results
- Write test report to <session-folder>/artifacts/
```
### For Documentation / Writing Roles
Add to execution protocol step 3:
```
3. **Execute**:
- Read source code and existing documentation
- Generate documentation following template in description
- Ensure accuracy against current implementation
- Include code examples where appropriate
- Write document to <session-folder>/artifacts/
```
### For Design / Architecture Roles
Add to execution protocol step 3:
```
3. **Execute**:
- Read upstream research findings
- Analyze existing codebase structure
- Design component interactions and data flow
- Document architecture decisions with rationale
- Write design document to <session-folder>/artifacts/
```
---
## Quality Requirements
All agents must verify before reporting complete:
| Requirement | Criteria |
|-------------|----------|
| Files produced | Verify all claimed artifacts exist via Read |
| Files modified | Verify content actually changed |
| Findings accuracy | Findings reflect actual work done |
| Discovery sharing | At least 1 discovery shared to board |
| Error reporting | Non-empty error field if status is failed |
---
## Placeholder Reference
| Placeholder | Resolved By | When |
|-------------|------------|------|
| `<session-folder>` | Skill designer (Phase 1) | Literal path baked into instruction |
| `{id}` | spawn_agents_on_csv | Runtime from CSV row |
| `{title}` | spawn_agents_on_csv | Runtime from CSV row |
| `{description}` | spawn_agents_on_csv | Runtime from CSV row |
| `{role}` | spawn_agents_on_csv | Runtime from CSV row |
| `{responsibility_type}` | spawn_agents_on_csv | Runtime from CSV row |
| `{output_type}` | spawn_agents_on_csv | Runtime from CSV row |
| `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row |

247
.codex/skills/team-coordinate/roles/coordinator/commands/analyze-task.md Normal file
View File

@@ -0,0 +1,247 @@
# Command: analyze-task
## Purpose
Parse user task description -> detect required capabilities -> build dependency graph -> design dynamic roles with role-spec metadata. Outputs structured task-analysis.json with frontmatter fields for role-spec generation.
## CRITICAL CONSTRAINT
**TEXT-LEVEL analysis only. MUST NOT read source code or explore codebase.**
**Allowed:**
- Parse user task description text
- request_user_input for clarification
- Keyword-to-capability mapping
- Write `task-analysis.json`
If task context requires codebase knowledge, set `needs_research: true`. Phase 2 will spawn researcher worker.
## When to Use
| Trigger | Condition |
|---------|-----------|
| New task | Coordinator Phase 1 receives task description |
| Re-analysis | User provides revised requirements |
| Adapt | handleAdapt extends analysis for new capability |
## Strategy
- **Delegation**: Inline execution (coordinator processes directly)
- **Mode**: Text-level analysis only (no codebase reading)
- **Output**: `<session>/task-analysis.json`
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | User input from Phase 1 | Yes |
| Clarification answers | request_user_input results (if any) | No |
| Session folder | From coordinator Phase 2 | Yes |
## Phase 3: Task Analysis
### Step 1: Signal Detection
Scan task description for capability keywords:
| Signal | Keywords | Capability | Prefix | Responsibility Type |
|--------|----------|------------|--------|---------------------|
| Research | investigate, explore, compare, survey, find, research, discover, benchmark, study | researcher | RESEARCH | orchestration |
| Writing | write, draft, document, article, report, blog, describe, explain, summarize, content | writer | DRAFT | code-gen (docs) |
| Coding | implement, build, code, fix, refactor, develop, create app, program, migrate, port | developer | IMPL | code-gen (code) |
| Design | design, architect, plan, structure, blueprint, model, schema, wireframe, layout | designer | DESIGN | orchestration |
| Analysis | analyze, review, audit, assess, evaluate, inspect, examine, diagnose, profile | analyst | ANALYSIS | read-only |
| Testing | test, verify, validate, QA, quality, check, assert, coverage, regression | tester | TEST | validation |
| Planning | plan, breakdown, organize, schedule, decompose, roadmap, strategy, prioritize | planner | PLAN | orchestration |
**Multi-match**: A task may trigger multiple capabilities.
**No match**: Default to a single `general` capability with `TASK` prefix.
### Step 2: Artifact Inference
Each capability produces default output artifacts:
| Capability | Default Artifact | Format |
|------------|-----------------|--------|
| researcher | Research findings | `<session>/artifacts/research-findings.md` |
| writer | Written document(s) | `<session>/artifacts/<doc-name>.md` |
| developer | Code implementation | Source files + `<session>/artifacts/implementation-summary.md` |
| designer | Design document | `<session>/artifacts/design-spec.md` |
| analyst | Analysis report | `<session>/artifacts/analysis-report.md` |
| tester | Test results | `<session>/artifacts/test-report.md` |
| planner | Execution plan | `<session>/artifacts/execution-plan.md` |
### Step 2.5: Key File Inference
For each task, infer relevant files based on capability type and task keywords:
| Capability | File Inference Strategy |
|------------|------------------------|
| researcher | Extract domain keywords -> map to likely directories (e.g., "auth" -> `src/auth/**`, `middleware/auth.ts`) |
| developer | Extract feature/module keywords -> map to source files (e.g., "payment" -> `src/payments/**`, `types/payment.ts`) |
| designer | Look for architecture/config keywords -> map to config/schema files |
| analyst | Extract target keywords -> map to files under analysis |
| tester | Extract test target keywords -> map to source + test files |
| writer | Extract documentation target -> map to relevant source files for context |
| planner | No specific files (planning is abstract) |
**Inference rules:**
- Extract nouns and verbs from task description
- Match against common directory patterns (src/, lib/, components/, services/, utils/)
- Include related type definition files (types/, *.d.ts)
- For "fix bug" tasks, include error-prone areas (error handlers, validation)
- For "implement feature" tasks, include similar existing features as reference
### Step 3: Dependency Graph Construction
Build a DAG of work streams using natural ordering tiers:
| Tier | Capabilities | Description |
|------|-------------|-------------|
| 0 | researcher, planner | Knowledge gathering / planning |
| 1 | designer | Design (requires context from tier 0 if present) |
| 2 | writer, developer | Creation (requires design/plan if present) |
| 3 | analyst, tester | Validation (requires artifacts to validate) |
### Step 4: Complexity Scoring
| Factor | Weight | Condition |
|--------|--------|-----------|
| Capability count | +1 each | Number of distinct capabilities |
| Cross-domain factor | +2 | Capabilities span 3+ tiers |
| Parallel tracks | +1 each | Independent parallel work streams |
| Serial depth | +1 per level | Longest dependency chain length |
| Total Score | Complexity | Role Limit |
|-------------|------------|------------|
| 1-3 | Low | 1-2 roles |
| 4-6 | Medium | 2-3 roles |
| 7+ | High | 3-5 roles |
### Step 5: Role Minimization
Apply merging rules to reduce role count (cap at 5).
### Step 6: Role-Spec Metadata Assignment
For each role, determine frontmatter and generation hints:
| Field | Derivation |
|-------|------------|
| `prefix` | From capability prefix (e.g., RESEARCH, DRAFT, IMPL) |
| `inner_loop` | `true` if role has 2+ serial same-prefix tasks |
| `CLI tools` | Suggested, not mandatory -- coordinator may adjust based on task needs |
| `pattern_hint` | Reference pattern name from role-spec-template (research/document/code/analysis/validation) -- guides coordinator's Phase 2-4 composition, NOT a rigid template selector |
| `output_type` | `artifact` (new files in session/artifacts/) / `codebase` (modify existing project files) / `mixed` (both) -- determines verification strategy in Behavioral Traits |
| `message_types.success` | `<prefix>_complete` |
| `message_types.error` | `error` |
**output_type derivation**:
| Task Signal | output_type | Example |
|-------------|-------------|---------|
| "write report", "analyze", "research" | `artifact` | New analysis-report.md in session |
| "update docs", "modify code", "fix bug" | `codebase` | Modify existing project files |
| "implement feature + write summary" | `mixed` | Code changes + implementation summary |
## Phase 4: Output
Write `<session-folder>/task-analysis.json`:
```json
{
"task_description": "<original user input>",
"capabilities": [
{
"name": "researcher",
"prefix": "RESEARCH",
"responsibility_type": "orchestration",
"tasks": [
{
"id": "RESEARCH-001",
"goal": "What this task achieves and why",
"steps": [
"step 1: specific action with clear verb",
"step 2: specific action with clear verb",
"step 3: specific action with clear verb"
],
"key_files": [
"src/path/to/relevant.ts",
"src/path/to/other.ts"
],
"upstream_artifacts": [],
"success_criteria": "Measurable completion condition",
"constraints": "Scope limits, focus areas"
}
],
"artifacts": ["research-findings.md"]
}
],
"dependency_graph": {
"RESEARCH-001": [],
"DRAFT-001": ["RESEARCH-001"],
"ANALYSIS-001": ["DRAFT-001"]
},
"roles": [
{
"name": "researcher",
"prefix": "RESEARCH",
"responsibility_type": "orchestration",
"task_count": 1,
"inner_loop": false,
"role_spec_metadata": {
"CLI tools": ["explore"],
"pattern_hint": "research",
"output_type": "artifact",
"message_types": {
"success": "research_complete",
"error": "error"
}
}
}
],
"complexity": {
"capability_count": 2,
"cross_domain_factor": false,
"parallel_tracks": 0,
"serial_depth": 2,
"total_score": 3,
"level": "low"
},
"needs_research": false,
"artifacts": [
{ "name": "research-findings.md", "producer": "researcher", "path": "artifacts/research-findings.md" }
]
}
```
## Complexity Interpretation
**CRITICAL**: Complexity score is for **role design optimization**, NOT for skipping team workflow.
| Complexity | Team Structure | Coordinator Action |
|------------|----------------|-------------------|
| Low (1-2 roles) | Minimal team | Generate 1-2 role-specs, create team, spawn workers |
| Medium (2-3 roles) | Standard team | Generate role-specs, create team, spawn workers |
| High (3-5 roles) | Full team | Generate role-specs, create team, spawn workers |
**All complexity levels use team_worker architecture**:
- Single-role tasks still spawn team_worker agent
- Coordinator NEVER executes task work directly
- Team infrastructure provides session management, message bus, fast-advance
**Purpose of complexity score**:
- Determine optimal role count (merge vs separate)
- Guide dependency graph design
- Inform user about task scope
- NOT for deciding whether to use team workflow
## Error Handling
| Scenario | Resolution |
|----------|------------|
| No capabilities detected | Default to single `general` role with TASK prefix |
| Circular dependency in graph | Break cycle at lowest-tier edge, warn |
| Task description too vague | Return minimal analysis, coordinator will request_user_input |
| All capabilities merge into one | Valid -- single-role execution via team_worker |

126
.codex/skills/team-coordinate/roles/coordinator/commands/dispatch.md Normal file
View File

@@ -0,0 +1,126 @@
# Command: dispatch
## Purpose
Create task chains from dynamic dependency graphs. Builds pipelines from the task-analysis.json produced by Phase 1. Workers are spawned as team_worker agents with role-spec paths.
## When to Use
| Trigger | Condition |
|---------|-----------|
| After analysis | Phase 1 complete, task-analysis.json exists |
| After adapt | handleAdapt created new roles, needs new tasks |
| Re-dispatch | Pipeline restructuring (rare) |
## Strategy
- **Delegation**: Inline execution (coordinator processes directly)
- **Inputs**: task-analysis.json + team-session.json
- **Output**: tasks.json with dependency chains
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task analysis | `<session-folder>/task-analysis.json` | Yes |
| Session file | `<session-folder>/team-session.json` | Yes |
| Role registry | `team-session.json#roles` | Yes |
| Scope | User requirements description | Yes |
## Phase 3: Task Chain Creation
### Workflow
1. **Read dependency graph** from `task-analysis.json#dependency_graph`
2. **Topological sort** tasks to determine creation order
3. **Validate** all task roles exist in role registry
4. **Build tasks array** (in topological order):
```json
[
{
"id": "<PREFIX>-<NNN>",
"title": "<PREFIX>-<NNN>",
"description": "PURPOSE: <goal> | Success: <success_criteria>\nTASK:\n - <step 1>\n - <step 2>\n - <step 3>\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: <artifact-1.md>, <artifact-2.md>\n - Key files: <file1>, <file2>\n - Shared state: team_msg(operation=\"get_state\", session_id=<session-id>)\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits>\n---\nInnerLoop: <true|false>\nRoleSpec: <session-folder>/role-specs/<role-name>.md",
"status": "pending",
"role": "<role-name>",
"prefix": "<PREFIX>",
"deps": ["<dependency-list from graph>"],
"findings": "",
"error": ""
}
]
```
5. **Write tasks.json** with the complete array
6. **Update team-session.json** with pipeline and tasks_total
7. **Validate** created chain
### Task Description Template
Every task description includes structured fields for clarity:
```
PURPOSE: <goal from task-analysis.json#tasks[].goal> | Success: <success_criteria from task-analysis.json#tasks[].success_criteria>
TASK:
- <step 1 from task-analysis.json#tasks[].steps[]>
- <step 2 from task-analysis.json#tasks[].steps[]>
- <step 3 from task-analysis.json#tasks[].steps[]>
CONTEXT:
- Session: <session-folder>
- Upstream artifacts: <comma-separated list from task-analysis.json#tasks[].upstream_artifacts[]>
- Key files: <comma-separated list from task-analysis.json#tasks[].key_files[]>
- Shared state: team_msg(operation="get_state", session_id=<session-id>)
EXPECTED: <artifact path from task-analysis.json#capabilities[].artifacts[]> + <quality criteria based on capability type>
CONSTRAINTS: <constraints from task-analysis.json#tasks[].constraints>
---
InnerLoop: <true|false>
RoleSpec: <session-folder>/role-specs/<role-name>.md
```
**Field Mapping**:
- `PURPOSE`: From `task-analysis.json#capabilities[].tasks[].goal` + `success_criteria`
- `TASK`: From `task-analysis.json#capabilities[].tasks[].steps[]`
- `CONTEXT.Upstream artifacts`: From `task-analysis.json#capabilities[].tasks[].upstream_artifacts[]`
- `CONTEXT.Key files`: From `task-analysis.json#capabilities[].tasks[].key_files[]`
- `EXPECTED`: From `task-analysis.json#capabilities[].artifacts[]` + quality criteria
- `CONSTRAINTS`: From `task-analysis.json#capabilities[].tasks[].constraints`
### InnerLoop Flag Rules
| Condition | InnerLoop |
|-----------|-----------|
| Role has 2+ serial same-prefix tasks | true |
| Role has 1 task | false |
| Tasks are parallel (no dependency between them) | false |
### Dependency Validation
| Check | Criteria |
|-------|----------|
| No orphan tasks | Every task is reachable from at least one root |
| No circular deps | Topological sort succeeds without cycle |
| All roles valid | Every task role exists in team-session.json#roles |
| All deps valid | Every deps entry references an existing task id |
| Session reference | Every task description contains `Session: <session-folder>` |
| RoleSpec reference | Every task description contains `RoleSpec: <path>` |
## Phase 4: Validation
| Check | Criteria |
|-------|----------|
| Task count | Matches dependency_graph node count |
| Dependencies | Every deps entry references an existing task id |
| Role assignment | Each task role is in role registry |
| Session reference | Every task description contains `Session:` |
| Pipeline integrity | No disconnected subgraphs (warn if found) |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Circular dependency detected | Report cycle, halt task creation |
| Role not in role registry | Error, coordinator must fix roles first |
| Task creation fails | Log error, report to coordinator |
| Duplicate task id | Skip creation, log warning |
| Empty dependency graph | Error, task analysis may have failed |

327
.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md Normal file
View File

@@ -0,0 +1,327 @@
# Command: monitor
## Purpose
Event-driven pipeline coordination with Spawn-and-Stop pattern. Role names are read from `team-session.json#roles`. Workers are spawned as `team_worker` agents with role-spec paths. Includes `handleComplete` for pipeline completion action and `handleAdapt` for mid-pipeline capability gap handling.
## When to Use
| Trigger | Condition |
|---------|-----------|
| Worker result | Result from wait_agent contains [role-name] from session roles |
| User command | "check", "status", "resume", "continue" |
| Capability gap | Worker reports capability_gap |
| Pipeline spawn | After dispatch, initial spawn needed |
| Pipeline complete | All tasks done |
## Strategy
- **Delegation**: Inline execution with handler routing
- **Beat model**: ONE_STEP_PER_INVOCATION -- one handler then STOP
- **Workers**: Spawned as team_worker via spawn_agent
## Constants
| Constant | Value | Description |
|----------|-------|-------------|
| SPAWN_MODE | spawn_agent | All workers spawned via `spawn_agent` |
| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
| FAST_ADVANCE_AWARE | true | Workers may skip coordinator for simple linear successors |
| WORKER_AGENT | team_worker | All workers spawned as team_worker agents |
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session file | `<session-folder>/team-session.json` | Yes |
| Task list | Read tasks.json | Yes |
| Active workers | session.active_workers[] | Yes |
| Role registry | session.roles[] | Yes |
**Dynamic role resolution**: Known worker roles are loaded from `session.roles[].name`. Role-spec paths are in `session.roles[].role_spec`.
## Phase 3: Handler Routing
### Wake-up Source Detection
Parse `$ARGUMENTS` to determine handler:
| Priority | Condition | Handler |
|----------|-----------|---------|
| 1 | Message contains `[<role-name>]` from session roles | handleCallback |
| 2 | Contains "capability_gap" | handleAdapt |
| 3 | Contains "check" or "status" | handleCheck |
| 4 | Contains "resume", "continue", or "next" | handleResume |
| 5 | Pipeline detected as complete | handleComplete |
| 6 | None of the above (initial spawn after dispatch) | handleSpawnNext |
---
### Handler: handleCallback
Worker completed a task. Verify completion, update state, auto-advance.
```
Receive result from wait_agent for [<role>]
+- Find matching active worker by role (from session.roles)
+- Is this a progress update (not final)? (Inner Loop intermediate task completion)
| +- YES -> Update session state, do NOT remove from active_workers -> STOP
+- Task status = completed?
| +- YES -> remove from active_workers -> update session
| | +- Close agent: close_agent({ id: <agentId> })
| | +- -> handleSpawnNext
| +- NO -> progress message, do not advance -> STOP
+- No matching worker found
+- Scan all active workers for completed tasks
+- Found completed -> process each -> handleSpawnNext
+- None completed -> STOP
```
**Fast-advance reconciliation**: A worker may have already spawned its successor via fast-advance. When processing any callback or resume:
1. Read recent `fast_advance` messages from team_msg (type="fast_advance")
2. For each fast_advance message: add the spawned successor to `active_workers` if not already present
3. Check if the expected next task is already `in_progress` (fast-advanced)
4. If yes -> skip spawning that task (already running)
5. If no -> normal handleSpawnNext
---
### Handler: handleCheck
Read-only status report. No pipeline advancement.
**Output format**:
```
[coordinator] Pipeline Status
[coordinator] Progress: <completed>/<total> (<percent>%)
[coordinator] Execution Graph:
<visual representation of dependency graph with status icons>
done=completed >>>=running o=pending .=not created
[coordinator] Active Workers:
> <subject> (<role>) - running <elapsed> [inner-loop: N/M tasks done]
[coordinator] Ready to spawn: <subjects>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
Then STOP.
---
### Handler: handleResume
Check active worker completion, process results, advance pipeline.
```
Load active_workers from session
+- No active workers -> handleSpawnNext
+- Has active workers -> check each:
+- status = completed -> mark done, 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: handleSpawnNext
Find all ready tasks, spawn team_worker agents, update session, STOP.
```
Collect task states from tasks.json
+- completedSubjects: status = completed
+- inProgressSubjects: status = in_progress
+- readySubjects: pending + all deps in completedSubjects
Ready tasks found?
+- NONE + work in progress -> report waiting -> STOP
+- NONE + nothing in progress -> PIPELINE_COMPLETE -> handleComplete
+- HAS ready tasks -> for each:
+- Is task role an Inner Loop role AND that role already has an active_worker?
| +- YES -> SKIP spawn (existing worker will pick it up via inner loop)
| +- NO -> normal spawn below
+- Update tasks.json entry status -> "in_progress"
+- team_msg log -> task_unblocked (session_id=<session-id>)
+- Spawn team_worker (see spawn call below)
+- Add to session.active_workers
Update session file -> output summary -> STOP
```
**Spawn worker call** (one per ready task):
```
const agentId = spawn_agent({
agent_type: "team_worker",
items: [{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <session-folder>/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.` }]
})
// Collect results:
const result = wait_agent({ ids: [agentId], timeout_ms: 900000 })
// Process result, update tasks.json
close_agent({ id: agentId })
```
---
### Handler: handleComplete
Pipeline complete. Execute completion action based on session configuration.
```
All tasks completed (no pending, no in_progress)
+- Generate pipeline summary:
| - Deliverables list with paths
| - Pipeline stats (tasks completed, duration)
| - Discussion verdicts (if any)
|
+- Read session.completion_action:
|
+- "interactive":
| request_user_input({
| questions: [{
| question: "Team pipeline complete. What would you like to do?",
| header: "Completion",
| multiSelect: false,
| options: [
| { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
| { label: "Keep Active", description: "Keep session for follow-up work" },
| { label: "Export Results", description: "Export deliverables to target directory" }
| ]
| }]
| })
| +- "Archive & Clean":
| | Update session status="completed"
| | Clean up session
| | Output final summary with artifact paths
| +- "Keep Active":
| | Update session status="paused"
| | Output: "Resume with: Skill(skill='team-coordinate', args='resume')"
| +- "Export Results":
| request_user_input for target directory
| Copy deliverables to target
| Execute Archive & Clean flow
|
+- "auto_archive":
| Execute Archive & Clean without prompt
|
+- "auto_keep":
Execute Keep Active without prompt
```
**Fallback**: If completion action fails, default to Keep Active (session status="paused"), log warning.
---
### Handler: handleAdapt
Handle mid-pipeline capability gap discovery. A worker reports `capability_gap` when it encounters work outside its scope.
**CONSTRAINT**: Maximum 5 worker roles per session. handleAdapt MUST enforce this limit.
```
Parse capability_gap message:
+- Extract: gap_description, requesting_role, suggested_capability
+- Validate gap is genuine:
+- Check existing roles in session.roles -> does any role cover this?
| +- YES -> redirect to that role -> STOP
| +- NO -> genuine gap, proceed to role-spec generation
+- CHECK ROLE COUNT LIMIT (MAX 5 ROLES):
+- Count current roles in session.roles
+- If count >= 5:
+- Attempt to merge new capability into existing role
+- If merge NOT possible -> PAUSE, report to user
+- Generate new role-spec:
1. Read specs/role-spec-template.md
2. Fill template with: frontmatter (role, prefix, inner_loop, message_types) + Phase 2-4 content
3. Write to <session-folder>/role-specs/<new-role>.md
4. Add to session.roles[]
+- Create new task(s) (add to tasks.json)
+- Update team-session.json
+- Spawn new team_worker -> STOP
```
---
### Worker Failure Handling
When a worker has unexpected status (not completed, not in_progress):
1. Reset task -> pending in tasks.json
2. Log via team_msg (type: error)
3. Report to user: task reset, will retry on next resume
### Fast-Advance Failure Recovery
When coordinator detects a fast-advanced task has failed:
```
handleCallback / handleResume detects:
+- Task is in_progress (was fast-advanced by predecessor)
+- No active_worker entry for this task
+- Resolution:
1. Update tasks.json -> reset task to pending
2. Remove stale active_worker entry (if any)
3. Log via team_msg (type: error)
4. -> handleSpawnNext (will re-spawn the task normally)
```
### Fast-Advance State Sync
On every coordinator wake (handleCallback, handleResume, handleCheck):
1. Read team_msg entries with `type="fast_advance"` since last coordinator wake
2. For each entry: sync `active_workers` with the spawned successor
3. This ensures coordinator's state reflects fast-advance decisions even before the successor's callback arrives
### Consensus-Blocked Handling
```
handleCallback receives message with consensus_blocked flag
+- Route by severity:
+- severity = HIGH
| +- Create REVISION task (same role, incremented suffix)
| +- Max 1 revision per task. If already revised -> PAUSE, escalate to user
+- severity = MEDIUM
| +- Proceed with warning, log to wisdom/issues.md
| +- Normal handleSpawnNext
+- severity = LOW
+- Proceed normally, treat as consensus_reached with notes
```
## Phase 4: Validation
| Check | Criteria |
|-------|----------|
| Session state consistent | active_workers matches tasks.json in_progress tasks |
| No orphaned tasks | Every in_progress task has an active_worker entry |
| Dynamic roles valid | All task roles exist in session.roles |
| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE |
| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers |
## 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) | Check for missing tasks, report to user |
| Fast-advance conflict | Coordinator reconciles, no duplicate spawns |
| Dynamic role-spec file not found | Error, coordinator must regenerate from task-analysis |
| capability_gap when role limit (5) reached | Attempt merge, else pause for user |
| Completion action fails | Default to Keep Active, log warning |

361
.codex/skills/team-coordinate/roles/coordinator/role.md Normal file
View File

@@ -0,0 +1,361 @@
---
role: coordinator
---
# Coordinator Role
Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec generation, task dispatching, progress monitoring, session state, and completion action. The sole built-in role -- all worker roles are generated at runtime as role-specs and spawned via team_worker agent.
## Identity
- **Name**: `coordinator` | **Tag**: `[coordinator]`
- **Responsibility**: Analyze task -> Generate role-specs -> Create team -> Dispatch tasks -> Monitor progress -> Completion action -> Report results
## Boundaries
### MUST
- Parse task description (text-level: keyword scanning, capability inference, dependency design)
- Dynamically generate worker role-specs from specs/role-spec-template.md
- Create session and spawn team_worker agents
- Dispatch tasks with proper dependency chains from task-analysis.json
- Monitor progress via worker results and route messages
- Maintain session state persistence (team-session.json)
- Handle capability_gap reports (generate new role-specs mid-pipeline)
- Handle consensus_blocked HIGH verdicts (create revision tasks or pause)
- Detect fast-advance orphans on resume/check and reset to pending
- Execute completion action when pipeline finishes
### MUST NOT
- **Read source code or perform codebase exploration** (delegate to worker roles)
- Execute task work directly (delegate to workers)
- Modify task output artifacts (workers own their deliverables)
- Call implementation agents (code-developer, etc.) directly
- Skip dependency validation when creating task chains
- Generate more than 5 worker roles (merge if exceeded)
- Override consensus_blocked HIGH without user confirmation
- Spawn workers with wrong agent type (MUST use `team_worker`)
---
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| state_update | outbound | Session init, pipeline progress |
| task_unblocked | outbound | Task ready for execution |
| fast_advance | inbound | Worker skipped coordinator |
| capability_gap | inbound | Worker needs new capability |
| error | inbound | Worker failure |
| impl_complete | inbound | Worker task done |
| consensus_blocked | inbound | Discussion verdict conflict |
## Message Bus Protocol
All coordinator state changes MUST be logged to team_msg BEFORE reporting results:
1. `team_msg(operation="log", ...)` -- log the event
2. Report results via output / report_agent_job_result
3. Update tasks.json entry status
Read state before every handler: `team_msg(operation="get_state", session_id=<session-id>)`
---
## Command Execution Protocol
When coordinator needs to execute a command (analyze-task, dispatch, monitor):
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 1 needs task analysis
-> Read roles/coordinator/commands/analyze-task.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Analysis)
-> Execute Phase 4 (Output)
-> Continue to Phase 2
```
## Toolbox
| Tool | Type | Purpose |
|------|------|---------|
| commands/analyze-task.md | Command | Task analysis and role design |
| commands/dispatch.md | Command | Task chain creation |
| commands/monitor.md | Command | Pipeline monitoring and handlers |
| team_worker | Subagent | Worker spawning via spawn_agent |
| tasks.json | File | Task lifecycle (create/read/update) |
| team_msg | System | Message bus operations |
| request_user_input | System | User interaction |
---
## Entry Router
When coordinator is invoked, first detect the invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker result | Result from wait_agent contains `[role-name]` from session roles | -> handleCallback |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Capability gap | Message contains "capability_gap" | -> handleAdapt |
| Pipeline complete | All tasks completed, no pending/in_progress | -> handleComplete |
| Interrupted session | Active/paused session exists in `.workflow/.team/TC-*` | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Task Analysis) |
For callback/check/resume/adapt/complete: load `@commands/monitor.md` and execute the appropriate handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
- If found, extract `session.roles[].name` for callback detection
2. **Parse $ARGUMENTS** for detection keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler section, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Task Analysis below
---
## Phase 0: Session Resume Check
**Objective**: Detect and resume interrupted sessions before creating new ones.
**Workflow**:
1. Scan `.workflow/.team/TC-*/team-session.json` for sessions with status "active" or "paused"
2. No sessions found -> proceed to Phase 1
3. Single session found -> resume it (-> Session Reconciliation)
4. Multiple sessions -> request_user_input for user selection
**Session Reconciliation**:
1. Read tasks.json -> get real status of all tasks
2. Reconcile: session.completed_tasks <-> tasks.json status (bidirectional sync)
3. Reset any in_progress tasks -> pending (they were interrupted)
4. Detect fast-advance orphans (in_progress without recent activity) -> reset to pending
5. Determine remaining pipeline from reconciled state
6. Rebuild team if disbanded (create session + spawn needed workers only)
7. Create missing tasks (add to tasks.json), set deps
8. Verify dependency chain integrity
9. Update session file with reconciled state
10. Kick first executable task's worker -> Phase 4
---
## Phase 1: Task Analysis
**Objective**: Parse user task, detect capabilities, build dependency graph, design roles.
**Constraint**: This is TEXT-LEVEL analysis only. No source code reading, no codebase exploration.
**Workflow**:
1. **Parse user task description**
2. **Clarify if ambiguous** via request_user_input:
- What is the scope? (specific files, module, project-wide)
- What deliverables are expected? (documents, code, analysis reports)
- Any constraints? (timeline, technology, style)
3. **Delegate to `@commands/analyze-task.md`**:
- Signal detection: scan keywords -> infer capabilities
- Artifact inference: each capability -> default output type (.md)
- Dependency graph: build DAG of work streams
- Complexity scoring: count capabilities, cross-domain factor, parallel tracks
- Role minimization: merge overlapping, absorb trivial, cap at 5
- **Role-spec metadata**: Generate frontmatter fields (prefix, inner_loop, additional_members, message_types)
4. **Output**: Write `<session>/task-analysis.json`
5. **If `needs_research: true`**: Phase 2 will spawn researcher worker first
**Success**: Task analyzed, capabilities detected, dependency graph built, roles designed with role-spec metadata.
**CRITICAL - Team Workflow Enforcement**:
Regardless of complexity score or role count, coordinator MUST:
- Always proceed to Phase 2 (generate role-specs)
- Always create team and spawn workers via team_worker agent
- NEVER execute task work directly, even for single-role low-complexity tasks
- NEVER skip team workflow based on complexity assessment
**Single-role execution is still team-based** - just with one worker. The team architecture provides:
- Consistent message bus communication
- Session state management
- Artifact tracking
- Fast-advance capability
- Resume/recovery mechanisms
---
## Phase 2: Generate Role-Specs + Initialize Session
**Objective**: Create session, generate dynamic role-spec files, initialize shared infrastructure.
**Workflow**:
1. Resolve workspace paths (MUST do first):
- `project_root` = result of `Bash("pwd")`
- `skill_root` = `<project_root>/.codex/skills/team-coordinate`
2. **Check `needs_research` flag** from task-analysis.json:
- If `true`: **Spawn researcher worker first** to gather codebase context
- Wait for researcher result via wait_agent
- Merge research findings into task context
- Update task-analysis.json with enriched context
3. **Generate session ID**: `TC-<slug>-<date>` (slug from first 3 meaningful words of task)
4. **Create session folder structure**:
```
.workflow/.team/<session-id>/
+-- role-specs/
+-- artifacts/
+-- wisdom/
+-- explorations/
+-- discussions/
+-- .msg/
```
5. **Create session folder + initialize `tasks.json`** (empty array)
6. **Read `specs/role-spec-template.md`** for Behavioral Traits + Reference Patterns
7. **For each role in task-analysis.json#roles**:
- Fill YAML frontmatter: role, prefix, inner_loop, additional_members, message_types
- **Compose Phase 2-4 content** (NOT copy from template):
- Phase 2: Derive input sources and context loading steps from **task description + upstream dependencies**
- Phase 3: Describe **execution goal** (WHAT to achieve) from task description -- do NOT prescribe specific CLI tool or approach
- Phase 4: Combine **Behavioral Traits** (from template) + **output_type** (from task analysis) to compose verification steps
- Reference Patterns may guide phase structure, but task description determines specific content
- Write generated role-spec to `<session>/role-specs/<role-name>.md`
8. **Register roles** in team-session.json#roles (with `role_spec` path instead of `role_file`)
9. **Initialize shared infrastructure**:
- `wisdom/learnings.md`, `wisdom/decisions.md`, `wisdom/issues.md` (empty with headers)
- `explorations/cache-index.json` (`{ "entries": [] }`)
- `discussions/` (empty directory)
10. **Initialize pipeline metadata** via team_msg:
```typescript
// Use team_msg to write pipeline metadata to .msg/meta.json
// Note: dynamic roles -- replace <placeholders> with actual role list from task-analysis.json
mcp__ccw-tools__team_msg({
operation: "log",
session_id: "<session-id>",
from: "coordinator",
type: "state_update",
summary: "Session initialized",
data: {
pipeline_mode: "<mode>",
pipeline_stages: ["<role1>", "<role2>", "<...dynamic-roles>"],
roles: ["coordinator", "<role1>", "<role2>", "<...dynamic-roles>"],
team_name: "<team-name>" // extracted from session ID or task description
}
})
```
11. **Write team-session.json** with: session_id, task_description, status="active", roles, pipeline (empty), active_workers=[], completion_action="interactive", created_at
**Success**: Session created, role-spec files generated, shared infrastructure initialized.
---
## Phase 3: Create Task Chain
**Objective**: Dispatch tasks based on dependency graph with proper dependencies.
Delegate to `@commands/dispatch.md` which creates the full task chain:
1. Reads dependency_graph from task-analysis.json
2. Topological sorts tasks
3. Builds tasks array and writes to tasks.json with deps
4. Assigns role based on role mapping from task-analysis.json
5. Includes `Session: <session-folder>` in every task description
6. Sets InnerLoop flag for multi-task roles
7. Updates team-session.json with pipeline and tasks_total
**Success**: All tasks created with correct dependency chains, session updated.
---
## Phase 4: Spawn-and-Stop
**Objective**: Spawn first batch of ready workers, then STOP.
**Design**: Spawn-and-Stop + wait_agent pattern, with worker fast-advance.
**Workflow**:
1. Load `@commands/monitor.md`
2. Find tasks with: status=pending, deps all resolved, role assigned
3. For each ready task -> spawn team_worker (see SKILL.md Coordinator Spawn Template)
4. Output status summary with execution graph
5. STOP
**Pipeline advancement** driven by three wake sources:
- Worker result (automatic) -> Entry Router -> handleCallback
- User "check" -> handleCheck (status only)
- User "resume" -> handleResume (advance)
---
## Phase 5: Report + Completion Action
**Objective**: Completion report, interactive completion choice, and follow-up options.
**Workflow**:
1. Load session state -> count completed tasks, duration
2. List all deliverables with output paths in `<session>/artifacts/`
3. Include discussion summaries (if inline discuss was used)
4. Summarize wisdom accumulated during execution
5. Output report:
```
[coordinator] ============================================
[coordinator] TASK COMPLETE
[coordinator]
[coordinator] Deliverables:
[coordinator] - <artifact-1.md> (<producer role>)
[coordinator] - <artifact-2.md> (<producer role>)
[coordinator]
[coordinator] Pipeline: <completed>/<total> tasks
[coordinator] Roles: <role-list>
[coordinator] Duration: <elapsed>
[coordinator]
[coordinator] Session: <session-folder>
[coordinator] ============================================
```
6. **Execute Completion Action** (based on session.completion_action):
| Mode | Behavior |
|------|----------|
| `interactive` | request_user_input with Archive/Keep/Export options |
| `auto_archive` | Execute Archive & Clean without prompt |
| `auto_keep` | Execute Keep Active without prompt |
**Interactive handler**: See SKILL.md Completion Action section.
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Task timeout | Log, mark failed, ask user to retry or skip |
| Worker crash | Respawn worker, reassign task |
| Dependency cycle | Detect in task analysis, report to user, halt |
| Task description too vague | request_user_input for clarification |
| Session corruption | Attempt recovery, fallback to manual reconciliation |
| Role-spec generation fails | Fall back to single general-purpose role |
| capability_gap reported | handleAdapt: generate new role-spec, create tasks, spawn |
| All capabilities merge to one | Valid: single-role execution, reduced overhead |
| No capabilities detected | Default to single general role with TASK prefix |
| Completion action fails | Default to Keep Active, log warning |

165
.codex/skills/team-coordinate/schemas/tasks-schema.md
View File

@@ -1,165 +0,0 @@
# Team Coordinate -- CSV Schema
## Master CSV: tasks.csv
### Column Definitions
#### Input Columns (Set by Decomposer)
| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `id` | string | Yes | Unique task identifier (PREFIX-NNN) | `"RESEARCH-001"` |
| `title` | string | Yes | Short task title | `"Investigate auth patterns"` |
| `description` | string | Yes | Detailed task description (self-contained) with goal, steps, success criteria, key files | `"PURPOSE: Research JWT auth patterns..."` |
| `role` | string | Yes | Dynamic role name | `"researcher"` |
| `responsibility_type` | enum | Yes | `orchestration`, `read-only`, `code-gen`, `code-gen-docs`, `validation` | `"orchestration"` |
| `output_type` | enum | Yes | `artifact` (session files), `codebase` (project files), `mixed` | `"artifact"` |
| `deps` | string | No | Semicolon-separated dependency task IDs | `"RESEARCH-001;DESIGN-001"` |
| `context_from` | string | No | Semicolon-separated task IDs for context | `"RESEARCH-001"` |
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
#### 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) | `"[RESEARCH-001] Found 3 auth patterns..."` |
#### 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 with refresh token support..."` |
| `artifacts_produced` | string | Semicolon-separated paths of produced artifacts | `"artifacts/research-findings.md;src/auth/jwt.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.
---
### Dynamic Role Prefixes
| Capability | Prefix | Responsibility Type |
|------------|--------|---------------------|
| researcher | RESEARCH | orchestration |
| writer | DRAFT | code-gen-docs |
| developer | IMPL | code-gen |
| designer | DESIGN | orchestration |
| analyst | ANALYSIS | read-only |
| tester | TEST | validation |
| planner | PLAN | orchestration |
| (default) | TASK | orchestration |
---
### Example Data
```csv
id,title,description,role,responsibility_type,output_type,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,error
"RESEARCH-001","Research auth patterns","PURPOSE: Investigate JWT authentication patterns and industry best practices | Success: Comprehensive findings document with pattern comparison\nTASK:\n- Survey JWT vs session-based auth\n- Compare token refresh strategies\n- Document security considerations\nCONTEXT:\n- Key files: src/auth/*, src/middleware/*\nEXPECTED: artifacts/research-findings.md","researcher","orchestration","artifact","","","csv-wave","1","pending","","",""
"DESIGN-001","Design auth architecture","PURPOSE: Design authentication module architecture based on research | Success: Architecture document with component diagram\nTASK:\n- Define auth module structure\n- Design token lifecycle\n- Plan middleware integration\nCONTEXT:\n- Upstream: RESEARCH-001 findings\nEXPECTED: artifacts/auth-design.md","designer","orchestration","artifact","RESEARCH-001","RESEARCH-001","csv-wave","2","pending","","",""
"IMPL-001","Implement auth module","PURPOSE: Build JWT authentication middleware | Success: Working auth module with tests passing\nTASK:\n- Create JWT utility functions\n- Implement auth middleware\n- Add route guards\nCONTEXT:\n- Upstream: DESIGN-001 architecture\n- Key files: src/auth/*, src/middleware/*\nEXPECTED: Source files + artifacts/implementation-summary.md","developer","code-gen","mixed","DESIGN-001","DESIGN-001","csv-wave","3","pending","","",""
"TEST-001","Test auth implementation","PURPOSE: Validate auth module correctness | Success: All tests pass, coverage >= 80%\nTASK:\n- Write unit tests for JWT utilities\n- Write integration tests for middleware\n- Run test suite\nCONTEXT:\n- Upstream: IMPL-001 implementation\nEXPECTED: artifacts/test-report.md","tester","validation","artifact","IMPL-001","IMPL-001","csv-wave","4","pending","","",""
```
---
### Column Lifecycle
```
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
--------------------- -------------------- -----------------
id ----------> id ----------> id
title ----------> title ----------> (reads)
description ----------> description ----------> (reads)
role ----------> role ----------> (reads)
responsibility_type ---> responsibility_type ---> (reads)
output_type ----------> output_type ----------> (reads)
deps ----------> deps ----------> (reads)
context_from----------> context_from----------> (reads)
exec_mode ----------> exec_mode ----------> (reads)
wave ----------> (reads)
prev_context ----------> (reads)
status
findings
artifacts_produced
error
```
---
## Output Schema (JSON)
Agent output via `report_agent_job_result` (csv-wave tasks):
```json
{
"id": "IMPL-001",
"status": "completed",
"findings": "Implemented JWT auth middleware with access/refresh token support. Created 3 files: jwt.ts, auth-middleware.ts, route-guard.ts. All syntax checks pass.",
"artifacts_produced": "artifacts/implementation-summary.md;src/auth/jwt.ts;src/auth/auth-middleware.ts",
"error": ""
}
```
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
---
## Discovery Types
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `pattern_found` | `data.pattern_name+data.location` | `{pattern_name, location, description}` | Design pattern identified |
| `file_modified` | `data.file` | `{file, change, lines_added}` | File change recorded |
| `dependency_found` | `data.from+data.to` | `{from, to, type}` | Dependency relationship |
| `issue_found` | `data.file+data.line` | `{file, line, severity, description}` | Issue discovered |
| `decision_made` | `data.decision` | `{decision, rationale, impact}` | Design decision |
| `artifact_produced` | `data.path` | `{name, path, producer, type}` | Deliverable created |
### Discovery NDJSON Format
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"RESEARCH-001","type":"pattern_found","data":{"pattern_name":"Repository Pattern","location":"src/repos/","description":"Data access layer uses repository pattern"}}
{"ts":"2026-03-08T10:05:00Z","worker":"IMPL-001","type":"file_modified","data":{"file":"src/auth/jwt.ts","change":"Added JWT middleware","lines_added":45}}
{"ts":"2026-03-08T10:10:00Z","worker":"IMPL-001","type":"artifact_produced","data":{"name":"implementation-summary","path":"artifacts/implementation-summary.md","producer":"developer","type":"markdown"}}
```
> 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 in {pending, completed, failed, skipped} | "Invalid status: {status}" |
| Role valid | role matches a generated role-instruction | "No instruction for role: {role}" |
| Cross-mechanism deps | Interactive to CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |

111
.codex/skills/team-coordinate/specs/knowledge-transfer.md Normal file
View File

@@ -0,0 +1,111 @@
# Knowledge Transfer Protocols
## 1. Transfer Channels
| Channel | Scope | Mechanism | When to Use |
|---------|-------|-----------|-------------|
| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
| **Context Accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
| **Exploration Cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
## 2. Context Loading Protocol (Phase 2)
Every role MUST load context in this order before starting work.
| Step | Action | Required |
|------|--------|----------|
| 1 | Extract session path from task description | Yes |
| 2 | `team_msg(operation="get_state", session_id=<session-id>)` | Yes |
| 3 | Read artifact files from upstream state's `ref` paths | Yes |
| 4 | Read `<session>/wisdom/*.md` if exists | Yes |
| 5 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
| 6 | For inner_loop roles: load context_accumulator from prior tasks | If inner_loop |
**Loading rules**:
- Never skip step 2 -- state contains key decisions and findings
- If `ref` path in state does not exist, log warning and continue
- Wisdom files are append-only -- read all entries, newest last
## 3. Context Publishing Protocol (Phase 4)
| Step | Action | Required |
|------|--------|----------|
| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
| 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
## 4. State Update Schema
Sent via `team_msg(type="state_update")` on task completion.
```json
{
"status": "task_complete",
"task_id": "<TASK-NNN>",
"ref": "<session>/artifacts/<filename>",
"key_findings": [
"Finding 1",
"Finding 2"
],
"decisions": [
"Decision with rationale"
],
"files_modified": [
"path/to/file.ts"
],
"verification": "self-validated | peer-reviewed | tested"
}
```
**Field rules**:
- `ref`: Always an artifact path, never inline content
- `key_findings`: Max 5 items, each under 100 chars
- `decisions`: Include rationale, not just the choice
- `files_modified`: Only for implementation tasks
- `verification`: One of `self-validated`, `peer-reviewed`, `tested`
**Write state** (namespaced by role):
```
team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={
"<role_name>": { "key_findings": [...], "scope": "..." }
})
```
**Read state**:
```
team_msg(operation="get_state", session_id=<session-id>)
// Returns merged state from all state_update messages
```
## 5. Exploration Cache Protocol
Prevents redundant research across tasks and discussion rounds.
| Step | Action |
|------|--------|
| 1 | Read `<session>/explorations/cache-index.json` |
| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
| 3 | If not cached, perform exploration |
| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
| 5 | Update `cache-index.json` with new entry |
**cache-index.json format**:
```json
{
"entries": [
{
"angle": "competitor-analysis",
"file": "explore-competitor-analysis.json",
"created_by": "RESEARCH-001",
"timestamp": "2026-01-15T10:30:00Z"
}
]
}
```
**Rules**:
- Cache key is the exploration `angle` (normalized to kebab-case)
- Cache entries never expire within a session
- Any role can read cached explorations; only the creator updates them

97
.codex/skills/team-coordinate/specs/pipelines.md Normal file
View File

@@ -0,0 +1,97 @@
# Pipeline Definitions — Team Coordinate
## Dynamic Pipeline Model
team-coordinate does NOT have a static pipeline. All pipelines are generated at runtime from task-analysis.json based on the user's task description.
## Pipeline Generation Process
```
Phase 1: analyze-task.md
-> Signal detection -> capability mapping -> dependency graph
-> Output: task-analysis.json
Phase 2: dispatch.md
-> Read task-analysis.json dependency graph
-> Create tasks.json entries per dependency node
-> Set deps chains from graph edges
-> Output: tasks.json with correct DAG
Phase 3-N: monitor.md
-> handleSpawnNext: spawn ready tasks as team-worker agents
-> handleCallback: mark completed, advance pipeline
-> Repeat until all tasks done
```
## Dynamic Task Naming
| Capability | Prefix | Example |
|------------|--------|---------|
| researcher | RESEARCH | RESEARCH-001 |
| developer | IMPL | IMPL-001 |
| analyst | ANALYSIS | ANALYSIS-001 |
| designer | DESIGN | DESIGN-001 |
| tester | TEST | TEST-001 |
| writer | DRAFT | DRAFT-001 |
| planner | PLAN | PLAN-001 |
| (default) | TASK | TASK-001 |
## Dependency Graph Structure
task-analysis.json encodes the pipeline:
```json
{
"dependency_graph": {
"RESEARCH-001": { "role": "researcher", "blockedBy": [], "priority": "P0" },
"IMPL-001": { "role": "developer", "blockedBy": ["RESEARCH-001"], "priority": "P1" },
"TEST-001": { "role": "tester", "blockedBy": ["IMPL-001"], "priority": "P2" }
}
}
```
## Role-Worker Map
Dynamic — loaded from session role-specs at runtime:
```
<session>/role-specs/<role-name>.md -> team-worker agent
```
Role-spec files contain YAML frontmatter:
```yaml
---
role: <role-name>
prefix: <PREFIX>
inner_loop: <true|false>
message_types:
success: <type>
error: error
---
```
## Checkpoint
| Trigger | Behavior |
|---------|----------|
| capability_gap reported | handleAdapt: generate new role-spec, spawn new worker |
| consensus_blocked HIGH | Create REVISION task or pause for user |
| All tasks complete | handleComplete: interactive completion action |
## Specs Reference
- [role-spec-template.md](role-spec-template.md) — Template for generating dynamic role-specs
- [quality-gates.md](quality-gates.md) — Quality thresholds and scoring dimensions
- [knowledge-transfer.md](knowledge-transfer.md) — Context transfer protocols between roles
## Quality Gate Integration
Dynamic pipelines reference quality thresholds from [specs/quality-gates.md](quality-gates.md).
| Gate Point | Trigger | Criteria Source |
|------------|---------|----------------|
| After artifact production | Producer role Phase 4 | Behavioral Traits in role-spec |
| After validation tasks | Tester/analyst completion | quality-gates.md thresholds |
| Pipeline completion | All tasks done | Aggregate scoring |
Issue classification: Error (blocks) > Warning (proceed with justification) > Info (log for future).

112
.codex/skills/team-coordinate/specs/quality-gates.md Normal file
View File

@@ -0,0 +1,112 @@
# Quality Gates
## 1. Quality Thresholds
| Result | Score | Action |
|--------|-------|--------|
| Pass | >= 80% | Report completed |
| Review | 60-79% | Report completed with warnings |
| Fail | < 60% | Retry Phase 3 (max 2 retries) |
## 2. Scoring Dimensions
| Dimension | Weight | Criteria |
|-----------|--------|----------|
| Completeness | 25% | All required outputs present with substantive content |
| Consistency | 25% | Terminology, formatting, cross-references are uniform |
| Accuracy | 25% | Outputs are factually correct and verifiable against sources |
| Depth | 25% | Sufficient detail for downstream consumers to act on deliverables |
**Score** = weighted average of all dimensions (0-100 per dimension).
## 3. Dynamic Role Quality Checks
Quality checks vary by `output_type` (from task-analysis.json role metadata).
### output_type: artifact
| Check | Pass Criteria |
|-------|---------------|
| Artifact exists | File written to `<session>/artifacts/` |
| Content non-empty | Substantive content, not just headers |
| Format correct | Expected format (MD, JSON) matches deliverable |
| Cross-references | All references to upstream artifacts resolve |
### output_type: codebase
| Check | Pass Criteria |
|-------|---------------|
| Files modified | Claimed files actually changed (Read to confirm) |
| Syntax valid | No syntax errors in modified files |
| No regressions | Existing functionality preserved |
| Summary artifact | Implementation summary written to artifacts/ |
### output_type: mixed
All checks from both `artifact` and `codebase` apply.
## 4. Verification Protocol
Derived from Behavioral Traits in [role-spec-template.md](role-spec-template.md).
| Step | Action | Required |
|------|--------|----------|
| 1 | Verify all claimed files exist via Read | Yes |
| 2 | Confirm artifact written to `<session>/artifacts/` | Yes |
| 3 | Check verification summary fields present | Yes |
| 4 | Score against quality dimensions | Yes |
| 5 | Apply threshold -> Pass/Review/Fail | Yes |
**On Fail**: Retry Phase 3 (max 2 retries). After 2 retries, report `partial_completion`.
**On Review**: Proceed with warnings logged to `<session>/wisdom/issues.md`.
## 5. Code Review Dimensions
For REVIEW-* or validation tasks during implementation pipelines.
### Quality
| Check | Severity |
|-------|----------|
| Empty catch blocks | Error |
| `as any` type casts | Warning |
| `@ts-ignore` / `@ts-expect-error` | Warning |
| `console.log` in production code | Warning |
| Unused imports/variables | Info |
### Security
| Check | Severity |
|-------|----------|
| Hardcoded secrets/credentials | Error |
| SQL injection vectors | Error |
| `eval()` or `Function()` usage | Error |
| `innerHTML` assignment | Warning |
| Missing input validation | Warning |
### Architecture
| Check | Severity |
|-------|----------|
| Circular dependencies | Error |
| Deep cross-boundary imports (3+ levels) | Warning |
| Files > 500 lines | Warning |
| Functions > 50 lines | Info |
### Requirements Coverage
| Check | Severity |
|-------|----------|
| Core functionality implemented | Error if missing |
| Acceptance criteria covered | Error if missing |
| Edge cases handled | Warning |
| Error states handled | Warning |
## 6. Issue Classification
| Class | Label | Action |
|-------|-------|--------|
| Error | Must fix | Blocks progression, must resolve before proceeding |
| Warning | Should fix | Should resolve, can proceed with justification |
| Info | Nice to have | Optional improvement, log for future |

192
.codex/skills/team-coordinate/specs/role-spec-template.md Normal file
View File

@@ -0,0 +1,192 @@
# Dynamic Role-Spec Template
Template used by coordinator to generate lightweight worker role-spec files at runtime. Each generated role-spec is written to `<session>/role-specs/<role-name>.md`.
**Key difference from v1**: Role-specs contain ONLY Phase 2-4 domain logic + YAML frontmatter. All shared behavior (Phase 1 Task Discovery, Phase 5 Report/Fast-Advance, Message Bus, Consensus, Inner Loop) is built into the `team-worker` agent.
## Template
```markdown
---
role: <role_name>
prefix: <PREFIX>
inner_loop: <true|false>
CLI tools: [<CLI tool-names>]
message_types:
success: <prefix>_complete
error: error
---
# <Role Name> — Phase 2-4
## Phase 2: <phase2_name>
<phase2_content>
## Phase 3: <phase3_name>
<phase3_content>
## Phase 4: <phase4_name>
<phase4_content>
## Error Handling
| Scenario | Resolution |
|----------|------------|
<error_entries>
```
## Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `role` | Yes | Role name matching session registry |
| `prefix` | Yes | Task prefix to filter (e.g., RESEARCH, DRAFT, IMPL) |
| `inner_loop` | Yes | Whether team-worker loops through same-prefix tasks |
| `CLI tools` | No | Array of CLI tool types this role may call |
| `output_tag` | Yes | Output tag for all messages, e.g., `[researcher]` |
| `message_types` | Yes | Message type mapping for team_msg |
| `message_types.success` | Yes | Type string for successful completion |
| `message_types.error` | Yes | Type string for errors (usually "error") |
## Design Rules
| Rule | Description |
|------|-------------|
| Phase 2-4 only | No Phase 1 (Task Discovery) or Phase 5 (Report) — team-worker handles these |
| No message bus code | No team_msg calls — team-worker handles logging |
| No consensus handling | No consensus_reached/blocked logic — team-worker handles routing |
| No inner loop logic | No Phase 5-L/5-F — team-worker handles looping |
| ~80 lines target | Lightweight, domain-focused |
| No pseudocode | Decision tables + text + tool calls only |
| `<placeholder>` notation | Use angle brackets for variable substitution |
| Reference CLI tools by name | team-worker resolves invocation from its delegation templates |
## Generated Role-Spec Structure
Every generated role-spec MUST include these blocks:
### Identity Block (mandatory — first section of generated spec)
```
Tag: [<role_name>] | Prefix: <PREFIX>-*
Responsibility: <one-line from task analysis>
```
### Boundaries Block (mandatory — after Identity)
```
### MUST
- <3-5 rules derived from task analysis>
### MUST NOT
- Execute work outside assigned prefix
- Modify artifacts from other roles
- Skip Phase 4 verification
```
## Behavioral Traits
All dynamically generated role-specs MUST embed these traits into Phase 4. Coordinator copies this section verbatim into every generated role-spec as a Phase 4 appendix.
**Design principle**: Constrain behavioral characteristics (accuracy, feedback, quality gates), NOT specific actions (which tool, which CLI tool, which path). Tasks are diverse — the coordinator composes task-specific Phase 2-3 instructions, while these traits ensure execution quality regardless of task type.
### Accuracy — outputs must be verifiable
- Files claimed as **created** → Read to confirm file exists and has content
- Files claimed as **modified** → Read to confirm content actually changed
- Analysis claimed as **complete** → artifact file exists in `<session>/artifacts/`
### Feedback Contract — completion report must include evidence
Phase 4 must produce a verification summary with these fields:
| Field | When Required | Content |
|-------|---------------|---------|
| `files_produced` | New files created | Path list |
| `files_modified` | Existing files changed | Path + before/after line count |
| `artifacts_written` | Always | Paths in `<session>/artifacts/` |
| `verification_method` | Always | How verified: Read confirm / syntax check / diff |
### Quality Gate — verify before reporting complete
- Phase 4 MUST verify Phase 3's **actual output** (not planned output)
- Verification fails → retry Phase 3 (max 2 retries)
- Still fails → report `partial_completion` with details, NOT `completed`
- Update shared state via `team_msg(operation="log", type="state_update", data={...})` after verification passes
Quality thresholds from [specs/quality-gates.md](quality-gates.md):
- Pass >= 80%: report completed
- Review 60-79%: report completed with warnings
- Fail < 60%: retry Phase 3 (max 2)
### Error Protocol
- Primary approach fails → try alternative (different CLI tool / different tool)
- 2 retries exhausted → escalate to coordinator with failure details
- NEVER: skip verification and report completed
---
## Reference Patterns
Coordinator MAY reference these patterns when composing Phase 2-4 content for a role-spec. These are **structural guidance, not mandatory templates**. The task description determines specific behavior — patterns only suggest common phase structures.
### Research / Exploration
- Phase 2: Define exploration scope + load prior knowledge from shared state and wisdom
- Phase 3: Explore via CLI tools, direct tool calls, or codebase search — approach chosen by agent
- Phase 4: Verify findings documented (Behavioral Traits) + update shared state
### Document / Content
- Phase 2: Load upstream artifacts + read target files (if modifying existing docs)
- Phase 3: Create new documents OR modify existing documents — determined by task, not template
- Phase 4: Verify documents exist with expected content (Behavioral Traits) + update shared state
### Code Implementation
- Phase 2: Load design/spec artifacts from upstream
- Phase 3: Implement code changes — CLI tool choice and approach determined by task complexity
- Phase 4: Syntax check + file verification (Behavioral Traits) + update shared state
### Analysis / Audit
- Phase 2: Load analysis targets (artifacts or source files)
- Phase 3: Multi-dimension analysis — perspectives and depth determined by task
- Phase 4: Verify report exists + severity classification (Behavioral Traits) + update shared state
### Validation / Testing
- Phase 2: Detect test framework + identify changed files from upstream
- Phase 3: Run test-fix cycle — iteration count and strategy determined by task
- Phase 4: Verify pass rate + coverage (Behavioral Traits) + update shared state
---
## Knowledge Transfer Protocol
Full protocol: [specs/knowledge-transfer.md](knowledge-transfer.md)
Generated role-specs Phase 2 MUST declare which upstream sources to load.
Generated role-specs Phase 4 MUST include state update and artifact publishing.
---
## Generated Role-Spec Validation
Coordinator verifies before writing each role-spec:
| Check | Criteria |
|-------|----------|
| Frontmatter complete | All required fields present (role, prefix, inner_loop, output_tag, message_types, CLI tools) |
| Identity block | Tag, prefix, responsibility defined |
| Boundaries | MUST and MUST NOT rules present |
| Phase 2 | Context loading sources specified |
| Phase 3 | Execution goal clear, not prescriptive about tools |
| Phase 4 | Behavioral Traits copied verbatim |
| Error Handling | Table with 3+ scenarios |
| Line count | Target ~80 lines (max 120) |
| No built-in overlap | No Phase 1/5, no message bus code, no consensus handling |

776
.codex/skills/team-designer/SKILL.md
View File

@@ -1,691 +1,153 @@
---
name: team-designer
description: Meta-skill for generating team skills. Analyzes requirements, scaffolds directory structure, generates role definitions and specs, validates completeness. Produces complete Codex team skill packages with SKILL.md orchestrator, CSV schemas, agent instructions, and interactive agents.
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"skill description with roles and domain\""
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
description: Meta-skill for generating team skills following the v4 architecture pattern. Produces complete skill packages with SKILL.md router, coordinator, worker roles, specs, and templates. Triggers on "team-designer", "design team".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
# Team Skill Designer
## Usage
Generate complete team skills following the team-lifecycle-v4 architecture: SKILL.md as universal router, coordinator with beat model, worker roles with optional commands/, shared specs, and templates.
```bash
$team-designer "Design a code review team with analyst, reviewer, security-expert roles"
$team-designer -c 4 "Create a documentation team with researcher, writer, editor"
$team-designer -y "Generate a test automation team with planner, executor, tester"
$team-designer --continue "td-code-review-20260308"
```
**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
Meta-skill for generating complete team skill packages. Takes a skill description with roles and domain, then: analyzes requirements -> scaffolds directory structure -> generates all role files, specs, templates -> validates the package. The generated skill follows the Codex hybrid team architecture (CSV wave primary + interactive secondary).
**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
## Architecture Overview
```
+-------------------------------------------------------------------+
| TEAM SKILL DESIGNER WORKFLOW |
+-------------------------------------------------------------------+
| |
| Phase 0: Pre-Wave Interactive (Requirement Clarification) |
| +- Parse user skill description |
| +- Detect input source (reference, structured, natural) |
| +- Gather core identity (skill name, prefix, domain) |
| +- Output: refined requirements for decomposition |
| |
| Phase 1: Requirement -> CSV + Classification |
| +- Discover roles from domain keywords |
| +- Define pipelines from role combinations |
| +- Determine commands distribution (inline vs commands/) |
| +- Build teamConfig data structure |
| +- Classify tasks: csv-wave | interactive (exec_mode) |
| +- Compute dependency waves (topological sort) |
| +- 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 (if any) |
| | +- 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 (if any) |
| | +- Merge all results into master tasks.csv |
| | +- Check: any failed? -> skip dependents |
| +- discoveries.ndjson shared across all modes (append-only) |
| |
| Phase 3: Post-Wave Interactive (Validation) |
| +- Structural validation (files exist, sections present) |
| +- Reference integrity (role registry matches files) |
| +- Pipeline consistency (no circular deps, roles exist) |
| +- Final aggregation / report |
| |
| Phase 4: 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 |
| |
+-------------------------------------------------------------------+
┌─────────────────────────────────────────────────────────────────┐
│ Team Skill Designer (SKILL.md) │
│ → Orchestrator: gather requirements, generate files, validate │
└───────────────────────────┬──────────────────────────────────────┘
│
┌───────────┬───────────┼───────────┬───────────┐
↓ ↓ ↓ ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
│ Require │ │ Scaffold│ │ Content │ │ Valid │
│ Analysis│ │ Gen │ │ Gen │ │ & Report│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
↓ ↓ ↓ ↓
teamConfig SKILL.md roles/ Validated
+ dirs specs/ skill pkg
templates/
```
---
## Key Design Principles
## Task Classification Rules
1. **v4 Architecture Compliance**: Generated skills follow team-lifecycle-v4 pattern — SKILL.md = pure router, beat model = coordinator-only, unified structure (roles/ + specs/ + templates/)
2. **Golden Sample Reference**: Uses `team-lifecycle-v4` as reference implementation at `~ or <project>/.claude/skills/team-lifecycle-v4/`
3. **Intelligent Commands Distribution**: Auto-determines which roles need `commands/` (2+ commands) vs inline logic (1 command)
4. **team-worker Compatibility**: Role.md files include correct YAML frontmatter for team-worker agent parsing
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, needs clarification, revision cycles |
**Classification Decision**:
| Task Property | Classification |
|---------------|---------------|
| Single-pass file generation (role.md, spec.md) | `csv-wave` |
| Directory scaffold creation | `csv-wave` |
| SKILL.md generation (complex, multi-section) | `csv-wave` |
| Coordinator role generation (multi-file) | `csv-wave` |
| Worker role generation (single file) | `csv-wave` |
| Pipeline spec generation | `csv-wave` |
| Template generation | `csv-wave` |
| User requirement clarification | `interactive` |
| Validation requiring user approval | `interactive` |
| Error recovery (auto-fix vs regenerate choice) | `interactive` |
---
## CSV Schema
### tasks.csv (Master State)
```csv
id,title,description,role,file_target,gen_type,deps,context_from,exec_mode,wave,status,findings,files_produced,error
"SCAFFOLD-001","Create directory structure","Create the complete directory structure for the team skill including roles/, specs/, templates/ subdirectories","scaffolder","skill-dir","directory","","","csv-wave","1","pending","","",""
"SPEC-001","Generate pipelines spec","Generate specs/pipelines.md with pipeline definitions, task registry, conditional routing","spec-writer","specs/pipelines.md","spec","SCAFFOLD-001","","csv-wave","2","pending","","",""
"ROLE-001","Generate coordinator role","Generate roles/coordinator/role.md with entry router, command execution protocol, phase logic","role-writer","roles/coordinator/","role-bundle","SCAFFOLD-001;SPEC-001","SPEC-001","csv-wave","2","pending","","",""
"ROLE-002","Generate analyst worker role","Generate roles/analyst/role.md with domain-specific Phase 2-4 logic","role-writer","roles/analyst/role.md","role-inline","SCAFFOLD-001;SPEC-001","SPEC-001","csv-wave","2","pending","","",""
```
**Columns**:
| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (string) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description with generation instructions |
| `role` | Input | Generator role: `scaffolder`, `spec-writer`, `role-writer`, `router-writer`, `validator` |
| `file_target` | Input | Target file or directory path relative to skill root |
| `gen_type` | Input | Generation type: `directory`, `router`, `role-bundle`, `role-inline`, `spec`, `template` |
| `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` |
| `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) |
| `files_produced` | Output | Semicolon-separated paths of produced files |
| `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 |
|-------|-----------|---------|----------------|----------|
| Requirement Clarifier | agents/requirement-clarifier.md | 2.3 (send_input cycle) | Gather and refine skill requirements interactively | standalone (Phase 0) |
| Validation Reporter | agents/validation-reporter.md | 2.3 (send_input cycle) | Validate generated skill package and report results | standalone (Phase 3) |
> **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 4 |
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
| `context.md` | Human-readable execution report | Created in Phase 4 |
| `teamConfig.json` | Phase 0/1 output: skill config, roles, pipelines | Created in Phase 1 |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
---
## Session Structure
## Execution Flow
```
.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
+-- teamConfig.json # Skill configuration from Phase 1
+-- wave-{N}.csv # Temporary per-wave input (csv-wave only)
+-- artifacts/ # Generated skill files (intermediate)
+-- interactive/ # Interactive task artifacts
| +-- {id}-result.json
+-- validation/ # Validation reports
+-- structural.json
+-- references.json
Input Parsing:
└─ Parse user requirements (skill name, roles, pipelines, domain)
Phase 1: Requirements Analysis
└─ Ref: phases/01-requirements-analysis.md
├─ Tasks: Detect input → Gather roles → Define pipelines → Build teamConfig
└─ Output: teamConfig
Phase 2: Scaffold Generation
└─ Ref: phases/02-scaffold-generation.md
├─ Tasks: Create dirs → Generate SKILL.md router → Verify
└─ Output: SKILL.md + directory structure
Phase 3: Content Generation
└─ Ref: phases/03-content-generation.md
├─ Tasks: Coordinator → Workers → Specs → Templates
└─ Output: roles/**/*.md, specs/*.md, templates/*.md
Phase 4: Validation
└─ Ref: phases/04-validation.md
└─ Output: Validation report (PASS/REVIEW/FAIL)
Return:
└─ Summary with skill location and usage instructions
```
---
**Phase Reference Documents** (read on-demand when phase executes):
## Implementation
| Phase | Document | Purpose |
|-------|----------|---------|
| 1 | [phases/01-requirements-analysis.md](phases/01-requirements-analysis.md) | Gather team skill requirements, build teamConfig |
| 2 | [phases/02-scaffold-generation.md](phases/02-scaffold-generation.md) | Generate SKILL.md router and directory structure |
| 3 | [phases/03-content-generation.md](phases/03-content-generation.md) | Generate coordinator, workers, specs, templates |
| 4 | [phases/04-validation.md](phases/04-validation.md) | Validate structure, references, and consistency |
### Session Initialization
## Golden Sample
```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
Generated skills follow the architecture of `~ or <project>/.claude/skills/team-lifecycle-v4/`:
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
const requirement = $ARGUMENTS
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
.trim()
const slug = requirement.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = `td-${slug}-${dateStr}`
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
Bash(`mkdir -p ${sessionFolder}/artifacts ${sessionFolder}/interactive ${sessionFolder}/validation`)
// Initialize discoveries.ndjson
Write(`${sessionFolder}/discoveries.ndjson`, '')
```
.claude/skills/<skill-name>/
├── SKILL.md # Universal router (all roles read)
├── roles/
│ ├── coordinator/
│ │ ├── role.md # Orchestrator + beat model + entry router
│ │ └── commands/
│ │ ├── analyze.md # Task analysis
│ │ ├── dispatch.md # Task chain creation
│ │ └── monitor.md # Beat control + callbacks
│ ├── <inline-worker>/
│ │ └── role.md # Phase 2-4 embedded (simple role)
│ └── <command-worker>/
│ ├── role.md # Phase 2-4 dispatcher
│ └── commands/
│ ├── <cmd-1>.md
│ └── <cmd-2>.md
├── specs/
│ ├── pipelines.md # Pipeline definitions + task registry
│ └── <domain-specs>.md # Domain-specific specifications
└── templates/ # Optional document templates
```
---
## Data Flow
### Phase 0: Pre-Wave Interactive (Requirement Clarification)
**Objective**: Parse user skill description, clarify ambiguities, build teamConfig.
**Workflow**:
1. **Parse user skill description** from $ARGUMENTS
2. **Detect input source**:
| Source Type | Detection | Action |
|-------------|-----------|--------|
| Reference | Contains "based on", "like", or existing skill path | Read referenced skill, extract structure |
| Structured | Contains ROLES:, PIPELINES:, or DOMAIN: | Parse structured input directly |
| Natural language | Default | Analyze keywords, discover roles |
3. **Check for existing sessions** (continue mode):
- Scan `.workflow/.csv-wave/td-*/tasks.csv` for sessions with pending tasks
- If `--continue`: resume the specified or most recent session, skip to Phase 2
4. **Gather core identity** (skip if AUTO_YES or already clear):
Read `agents/requirement-clarifier.md`, then:
```javascript
const clarifier = spawn_agent({
message: `## TASK ASSIGNMENT
### MANDATORY FIRST STEPS
1. Read: agents/requirement-clarifier.md
2. Read: ${sessionFolder}/discoveries.ndjson (if exists)
---
Goal: Gather team skill requirements from the user
Input: "${requirement}"
Session: ${sessionFolder}
Determine: skill name (kebab-case), session prefix (3-4 chars), domain description, roles, pipelines, commands distribution.`
})
const clarifyResult = wait({ ids: [clarifier], timeout_ms: 600000 })
if (clarifyResult.timed_out) {
send_input({ id: clarifier, message: "Please finalize requirements with current information." })
wait({ ids: [clarifier], timeout_ms: 120000 })
}
Write(`${sessionFolder}/interactive/clarify-result.json`, JSON.stringify({
task_id: "CLARIFY-001", status: "completed", findings: parseFindings(clarifyResult),
timestamp: getUtc8ISOString()
}))
close_agent({ id: clarifier })
```
5. **Build teamConfig** from gathered requirements:
```javascript
const teamConfig = {
skillName: "<kebab-case-name>",
sessionPrefix: "<3-4 char prefix>",
domain: "<domain description>",
title: "<Human Readable Title>",
roles: [
{ name: "coordinator", prefix: "—", inner_loop: false, hasCommands: true, commands: ["analyze", "dispatch", "monitor"], path: "roles/coordinator/role.md" },
// ... discovered worker roles
],
pipelines: [{ name: "<pipeline-name>", tasks: [/* task definitions */] }],
specs: ["pipelines"],
templates: [],
conditionalRouting: false,
targetDir: `.codex/skills/<skill-name>`
}
Write(`${sessionFolder}/teamConfig.json`, JSON.stringify(teamConfig, null, 2))
User Input (skill name, roles, pipelines)
↓
Phase 1: Requirements Analysis
↓ Output: teamConfig
↓
Phase 2: Scaffold Generation
↓ Input: teamConfig
↓ Output: SKILL.md + skillDir
↓
Phase 3: Content Generation
↓ Input: teamConfig + skillDir
↓ Output: roles/, specs/, templates/
↓
Phase 4: Validation
↓ Input: teamConfig + all files
↓ Output: validation report
↓
Return summary to user
```
6. **Decompose into tasks** -- generate tasks.csv from teamConfig:
| Task Pattern | gen_type | Wave | Description |
|--------------|----------|------|-------------|
| Directory scaffold | `directory` | 1 | Create skill directory structure |
| SKILL.md router | `router` | 2 | Generate main SKILL.md orchestrator |
| Pipeline spec | `spec` | 2 | Generate specs/pipelines.md |
| Domain specs | `spec` | 2 | Generate additional specs files |
| Coordinator role | `role-bundle` | 3 | Generate coordinator role.md + commands/ |
| Worker roles (each) | `role-inline` or `role-bundle` | 3 | Generate each worker role.md |
| Templates (each) | `template` | 3 | Generate template files |
| Validation | `validation` | 4 | Validate the complete package |
**Success Criteria**:
- teamConfig.json written with complete configuration
- Refined requirements available for Phase 1 decomposition
- Interactive agents closed, results stored
---
### Phase 1: Requirement -> CSV + Classification
**Objective**: Generate tasks.csv from teamConfig with dependency-ordered waves.
**Decomposition Rules**:
1. **Role Discovery** -- scan domain description for keywords:
| Signal | Keywords | Role Name | Prefix |
|--------|----------|-----------|--------|
| Analysis | analyze, research, investigate, explore | analyst | RESEARCH |
| Planning | plan, design, architect, decompose | planner | PLAN |
| Writing | write, document, draft, spec, report | writer | DRAFT |
| Implementation | implement, build, code, develop | executor | IMPL |
| Testing | test, verify, validate, qa | tester | TEST |
| Review | review, audit, check, inspect | reviewer | REVIEW |
| Security | security, vulnerability, penetration | security-expert | SECURITY |
2. **Commands Distribution** -- determine inline vs commands/:
| Condition | Commands Structure |
|-----------|-------------------|
| 1 distinct action for role | Inline in role.md |
| 2+ distinct actions | commands/ folder |
| Coordinator (always) | commands/: analyze, dispatch, monitor |
3. **Pipeline Construction** -- build from role ordering:
| Role Combination | Pipeline Type |
|------------------|---------------|
| analyst + writer + executor | full-lifecycle |
| analyst + writer (no executor) | spec-only |
| planner + executor (no analyst) | impl-only |
| Other | custom |
**Classification Rules**:
| Task Property | exec_mode |
|---------------|-----------|
| Directory creation | `csv-wave` |
| Single file generation (role.md, spec.md) | `csv-wave` |
| Multi-file bundle generation (coordinator) | `csv-wave` |
| SKILL.md router generation | `csv-wave` |
| User requirement clarification | `interactive` |
| Validation with error recovery | `interactive` |
**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
**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
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
const maxWave = Math.max(...tasks.map(t => t.wave))
for (let wave = 1; wave <= maxWave; wave++) {
console.log(`\nWave ${wave}/${maxWave}`)
// 1. Separate tasks by exec_mode
const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
// 2. Check dependencies -- skip tasks whose deps failed
for (const task of waveTasks) {
const depIds = (task.deps || '').split(';').filter(Boolean)
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
task.status = 'skipped'
task.error = `Dependency failed: ${depIds.filter((id, i) =>
['failed','skipped'].includes(depStatuses[i])).join(', ')}`
}
}
// 3. Execute pre-wave interactive tasks
const preWaveInteractive = interactiveTasks.filter(t => t.status === 'pending')
for (const task of preWaveInteractive) {
// Use appropriate interactive agent
const agentFile = task.gen_type === 'validation'
? 'agents/validation-reporter.md'
: 'agents/requirement-clarifier.md'
Read(agentFile)
const agent = spawn_agent({
message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: ${agentFile}\n2. Read: ${sessionFolder}/discoveries.ndjson\n\nGoal: ${task.description}\nScope: ${task.title}\nSession: ${sessionFolder}\nteamConfig: ${sessionFolder}/teamConfig.json\n\n### Previous Context\n${buildPrevContext(task, tasks)}`
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
if (result.timed_out) {
send_input({ id: agent, message: "Please finalize and output current findings." })
wait({ ids: [agent], timeout_ms: 120000 })
}
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
task_id: task.id, status: "completed", findings: parseFindings(result),
timestamp: getUtc8ISOString()
}))
close_agent({ id: agent })
task.status = 'completed'
task.findings = parseFindings(result)
}
// 4. Build prev_context for csv-wave tasks
const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
for (const task of pendingCsvTasks) {
task.prev_context = buildPrevContext(task, tasks)
}
if (pendingCsvTasks.length > 0) {
// 5. Write wave CSV
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))
// 6. Execute wave via spawn_agents_on_csv
spawn_agents_on_csv({
csv_path: `${sessionFolder}/wave-${wave}.csv`,
id_column: "id",
instruction: Read(`instructions/agent-instruction.md`)
.replace(/<session-folder>/g, sessionFolder),
max_concurrency: maxConcurrency,
max_runtime_seconds: 900,
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
files_produced: { type: "string" },
error: { type: "string" }
}
}
})
// 7. Merge results into master CSV
const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
for (const r of results) {
const t = tasks.find(t => t.id === r.id)
if (t) Object.assign(t, r)
}
}
// 8. Update master CSV
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
// 9. Cleanup temp files
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
// 10. Display wave summary
const completed = waveTasks.filter(t => t.status === 'completed').length
const failed = waveTasks.filter(t => t.status === 'failed').length
const skipped = waveTasks.filter(t => t.status === 'skipped').length
console.log(`Wave ${wave} Complete: ${completed} completed, ${failed} failed, ${skipped} skipped`)
}
```
**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
---
### Phase 3: Post-Wave Interactive (Validation)
**Objective**: Validate the generated team skill package and present results.
Read `agents/validation-reporter.md`, then:
```javascript
const validator = spawn_agent({
message: `## TASK ASSIGNMENT
### MANDATORY FIRST STEPS
1. Read: agents/validation-reporter.md
2. Read: ${sessionFolder}/discoveries.ndjson
3. Read: ${sessionFolder}/teamConfig.json
---
Goal: Validate the generated team skill package at ${teamConfig.targetDir}
Session: ${sessionFolder}
### Validation Checks
1. Structural: All files exist per teamConfig
2. SKILL.md: Required sections present, role registry correct
3. Role frontmatter: YAML frontmatter valid for each worker role
4. Pipeline consistency: No circular deps, roles referenced exist
5. Commands distribution: commands/ matches hasCommands flag
### Previous Context
${buildCompletePrevContext(tasks)}`
})
const validResult = wait({ ids: [validator], timeout_ms: 600000 })
if (validResult.timed_out) {
send_input({ id: validator, message: "Please finalize validation with current findings." })
wait({ ids: [validator], timeout_ms: 120000 })
}
Write(`${sessionFolder}/interactive/validation-result.json`, JSON.stringify({
task_id: "VALIDATE-001", status: "completed", findings: parseFindings(validResult),
timestamp: getUtc8ISOString()
}))
close_agent({ id: validator })
```
**Success Criteria**:
- Post-wave interactive processing complete
- Validation report generated
- Interactive agents closed, results stored
---
### Phase 4: Results Aggregation
**Objective**: Generate final results and human-readable report.
```javascript
// 1. Export results.csv
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
// 2. Generate context.md
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
let contextMd = `# Team Skill Designer Report\n\n`
contextMd += `**Session**: ${sessionId}\n`
contextMd += `**Skill**: ${teamConfig.skillName}\n`
contextMd += `**Target**: ${teamConfig.targetDir}\n\n`
contextMd += `## Summary\n`
contextMd += `| Status | Count |\n|--------|-------|\n`
contextMd += `| Completed | ${tasks.filter(t => t.status === 'completed').length} |\n`
contextMd += `| Failed | ${tasks.filter(t => t.status === 'failed').length} |\n`
contextMd += `| Skipped | ${tasks.filter(t => t.status === 'skipped').length} |\n\n`
contextMd += `## Generated Skill Structure\n\n`
contextMd += `\`\`\`\n${teamConfig.targetDir}/\n`
contextMd += `+-- SKILL.md\n+-- schemas/\n| +-- tasks-schema.md\n+-- instructions/\n| +-- agent-instruction.md\n`
// ... roles, specs, templates
contextMd += `\`\`\`\n\n`
contextMd += `## Validation\n`
// ... validation results
Write(`${sessionFolder}/context.md`, contextMd)
// 3. Display final summary
console.log(`\nTeam Skill Designer Complete`)
console.log(`Generated skill: ${teamConfig.targetDir}`)
console.log(`Results: ${sessionFolder}/results.csv`)
console.log(`Report: ${sessionFolder}/context.md`)
console.log(`\nUsage: $${teamConfig.skillName} "task description"`)
```
**Success Criteria**:
- results.csv exported (all tasks, both modes)
- context.md generated
- All interactive agents closed
- Summary displayed to user
---
## Shared Discovery Board Protocol
All agents (csv-wave and interactive) share a single `discoveries.ndjson` file for cross-task knowledge exchange.
**Format**: One JSON object per line (NDJSON):
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"SCAFFOLD-001","type":"dir_created","data":{"path":"~ or <project>/.codex/skills/team-code-review/","description":"Created skill directory structure"}}
{"ts":"2026-03-08T10:05:00Z","worker":"ROLE-001","type":"file_generated","data":{"file":"roles/coordinator/role.md","gen_type":"role-bundle","sections":["entry-router","commands"]}}
{"ts":"2026-03-08T10:10:00Z","worker":"SPEC-001","type":"pattern_found","data":{"pattern_name":"full-lifecycle","description":"Pipeline with analyst -> writer -> executor -> tester"}}
```
**Discovery Types**:
| Type | Data Schema | Description |
|------|-------------|-------------|
| `dir_created` | `{path, description}` | Directory structure created |
| `file_generated` | `{file, gen_type, sections}` | File generated with specific sections |
| `pattern_found` | `{pattern_name, description}` | Design pattern identified in golden sample |
| `config_decision` | `{decision, rationale, impact}` | Configuration decision made |
| `validation_result` | `{check, passed, message}` | Validation check result |
| `reference_found` | `{source, target, type}` | Cross-reference between generated files |
**Protocol**:
1. Agents MUST read discoveries.ndjson at start of execution
2. Agents MUST append relevant discoveries during execution
3. Agents MUST NOT modify or delete existing entries
4. Deduplication by `{type, data.file, data.path}` key
---
## 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 |
| 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 |
| Invalid role name | Must be lowercase alphanumeric with hyphens, max 20 chars |
| Directory conflict | Warn if skill directory already exists, ask user to confirm overwrite |
| Golden sample not found | Fall back to embedded templates in instructions |
| Validation FAIL | Offer auto-fix, regenerate, or accept as-is |
| Continue mode: no session found | List available sessions, prompt user to select |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 0/1
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
7. **Skip on Failure**: If a dependency failed, skip the dependent task
8. **Golden Sample Fidelity**: Generated files must match existing team skill patterns
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
1. **Start Immediately**: First action is Phase 1 execution
2. **Parse Every Output**: Extract teamConfig from Phase 1 for subsequent phases
3. **Auto-Continue**: After each phase, automatically execute next phase
4. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
5. **Golden Sample Fidelity**: Generated files must match team-lifecycle-v4 patterns
6. **DO NOT STOP**: Continuous workflow until all 4 phases complete
## Input Processing
---
Convert user input to structured format:
## Coordinator Role Constraints (Main Agent)
```
SKILL_NAME: [kebab-case name, e.g., team-code-review]
DOMAIN: [what this team does, e.g., "multi-stage code review with security analysis"]
ROLES: [worker roles beyond coordinator, e.g., "analyst, reviewer, security-expert"]
PIPELINES: [pipeline types and flows, e.g., "review-only: SCAN-001 → REVIEW-001 → REPORT-001"]
SESSION_PREFIX: [3-4 char, e.g., TCR]
```
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
## Error Handling
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns
- **Invalid role name**: Must be lowercase alphanumeric with hyphens, max 20 chars
- **Circular dependencies**: Detect and report in pipeline validation
- **Missing golden sample**: Fall back to embedded templates in phase files
- **Directory conflict**: Warn if skill directory already exists, ask user to confirm overwrite

247
.codex/skills/team-designer/agents/requirement-clarifier.md
View File

@@ -1,247 +0,0 @@
# Requirement Clarifier Agent
Interactive agent for gathering and refining team skill requirements from user input. Used in Phase 0 when the skill description needs clarification or missing details.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/requirement-clarifier.md`
- **Responsibility**: Gather skill name, roles, pipelines, specs, and build teamConfig
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Parse user input to detect input source (reference, structured, natural)
- Gather all required teamConfig fields
- Confirm configuration with user before reporting complete
- Produce structured output following template
- Write teamConfig.json to session folder
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Generate skill files (that is Phase 2 work)
- Approve incomplete configurations
- Produce unstructured output
- Exceed defined scope boundaries
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load reference skills, existing patterns |
| `request_user_input` | built-in | Gather missing details from user |
| `Write` | built-in | Store teamConfig.json |
| `Glob` | built-in | Find reference skill files |
### Tool Usage Patterns
**Read Pattern**: Load reference skill for pattern extraction
```
Read(".codex/skills/<reference-skill>/SKILL.md")
Read(".codex/skills/<reference-skill>/schemas/tasks-schema.md")
```
**Write Pattern**: Store configuration
```
Write("<session>/teamConfig.json", <config>)
```
---
## Execution
### Phase 1: Input Detection
**Objective**: Detect input source type and extract initial information
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| User requirement | Yes | Skill description from $ARGUMENTS |
| Reference skill | No | Existing skill if "based on" detected |
**Steps**:
1. Parse user input to detect source type:
| Source Type | Detection | Action |
|-------------|-----------|--------|
| Reference | Contains "based on", "like", skill path | Read referenced skill, extract roles/pipelines |
| Structured | Contains ROLES:, PIPELINES:, DOMAIN: | Parse structured fields directly |
| Natural language | Default | Analyze keywords for role discovery |
2. Extract initial information from detected source
3. Identify missing required fields
**Output**: Initial teamConfig draft with gaps identified
---
### Phase 2: Requirement Gathering
**Objective**: Fill in all required teamConfig fields
**Steps**:
1. **Core Identity** -- gather if not clear from input:
```javascript
request_user_input({
questions: [
{
question: "Team skill name? (kebab-case, e.g., team-code-review)",
header: "Skill Name",
id: "skill_name",
options: [
{ label: "<auto-suggested-name> (Recommended)", description: "Auto-suggested from description" },
{ label: "Custom", description: "Enter custom name" }
]
},
{
question: "Session prefix? (3-4 chars for task IDs, e.g., TCR)",
header: "Prefix",
id: "session_prefix",
options: [
{ label: "<auto-suggested-prefix> (Recommended)", description: "Auto-suggested" },
{ label: "Custom", description: "Enter custom prefix" }
]
}
]
})
```
2. **Role Discovery** -- identify roles from domain keywords:
| Signal | Keywords | Default Role |
|--------|----------|-------------|
| Analysis | analyze, research, investigate | analyst |
| Planning | plan, design, architect | planner |
| Writing | write, document, draft | writer |
| Implementation | implement, build, code | executor |
| Testing | test, verify, validate | tester |
| Review | review, audit, check | reviewer |
3. **Commands Distribution** -- determine per role:
| Rule | Condition | Result |
|------|-----------|--------|
| Coordinator | Always | commands/: analyze, dispatch, monitor |
| Multi-action role | 2+ distinct actions | commands/ folder |
| Single-action role | 1 action | Inline in role.md |
4. **Pipeline Construction** -- determine from role combination:
| Roles Present | Pipeline Type |
|---------------|---------------|
| analyst + writer + executor | full-lifecycle |
| analyst + writer (no executor) | spec-only |
| planner + executor (no analyst) | impl-only |
| Other combinations | custom |
5. **Specs and Templates** -- determine required specs:
- Always: pipelines.md
- If quality gates needed: quality-gates.md
- If writer role: domain-appropriate templates
**Output**: Complete teamConfig ready for confirmation
---
### Phase 3: Confirmation
**Objective**: Present configuration summary and get user approval
**Steps**:
1. Display configuration summary:
```
Team Skill Configuration Summary
Skill Name: <skillName>
Session Prefix: <sessionPrefix>
Domain: <domain>
Target: .codex/skills/<skillName>/
Roles:
+- coordinator (commands: analyze, dispatch, monitor)
+- <role-a> [PREFIX-*] (inline)
+- <role-b> [PREFIX-*] (commands: cmd1, cmd2)
Pipelines:
+- <pipeline-name>: TASK-001 -> TASK-002 -> TASK-003
Specs: pipelines, <additional>
Templates: <list or none>
```
2. Present confirmation:
```javascript
request_user_input({
questions: [{
question: "Confirm this team skill configuration?",
header: "Config Review",
id: "config_review",
options: [
{ label: "Confirm (Recommended)", description: "Proceed with generation" },
{ label: "Modify Roles", description: "Add, remove, or change roles" },
{ label: "Modify Pipelines", description: "Change pipeline structure" }
]
}]
})
```
3. Handle response:
| Response | Action |
|----------|--------|
| Confirm | Write teamConfig.json, report complete |
| Modify Roles | Loop back to role gathering |
| Modify Pipelines | Loop back to pipeline construction |
| Cancel | Report cancelled status |
**Output**: Confirmed teamConfig.json written to session folder
---
## Structured Output Template
```
## Summary
- Configuration: <confirmed|modified|cancelled>
- Skill: <skill-name>
## Configuration
- Roles: <count> roles defined
- Pipelines: <count> pipelines
- Target: <target-dir>
## Details
- Role list with prefix and commands structure
- Pipeline definitions with task flow
- Specs and templates list
## Open Questions
1. Any unresolved items from clarification
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Reference skill not found | Report error, ask for correct path |
| Invalid role name | Suggest valid kebab-case alternative |
| Conflicting pipeline structure | Ask user to resolve |
| User does not respond | Timeout, report partial with current config |
| Processing failure | Output partial results with clear status indicator |

186
.codex/skills/team-designer/agents/validation-reporter.md
View File

@@ -1,186 +0,0 @@
# Validation Reporter Agent
Validate generated skill package structure and content, reporting results with PASS/WARN/FAIL verdict.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/validation-reporter.md`
- **Responsibility**: Validate generated skill package structure and content, report results
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Load the generated skill package from session artifacts
- Validate all structural integrity checks
- Produce structured output with clear PASS/WARN/FAIL verdict
- Include specific file references in findings
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Modify generated skill files
- Produce unstructured output
- Report PASS without actually validating all checks
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load generated skill files and verify content |
| `Glob` | builtin | Find files by pattern in skill package |
| `Grep` | builtin | Search for cross-references and patterns |
| `Bash` | builtin | Run validation commands, check JSON syntax |
### Tool Usage Patterns
**Read Pattern**: Load skill package files for validation
```
Read("{session_folder}/artifacts/<skill-name>/SKILL.md")
Read("{session_folder}/artifacts/<skill-name>/team-config.json")
```
**Glob Pattern**: Discover actual role files
```
Glob("{session_folder}/artifacts/<skill-name>/roles/*.md")
Glob("{session_folder}/artifacts/<skill-name>/commands/*.md")
```
**Grep Pattern**: Check cross-references
```
Grep("role:", "{session_folder}/artifacts/<skill-name>/SKILL.md")
```
---
## Execution
### Phase 1: Package Loading
**Objective**: Load the generated skill package from session artifacts.
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Skill package path | Yes | Path to generated skill directory in artifacts/ |
| teamConfig.json | Yes | Original configuration used for generation |
**Steps**:
1. Read SKILL.md from the generated package
2. Read team-config.json from the generated package
3. Enumerate all files in the package using Glob
4. Read teamConfig.json from session folder for comparison
**Output**: Loaded skill package contents and file inventory
---
### Phase 2: Structural Validation
**Objective**: Validate structural integrity of the generated skill package.
**Steps**:
1. **SKILL.md validation**:
- Verify file exists
- Verify valid frontmatter (name, description, allowed-tools)
- Verify Role Registry table is present
2. **Role Registry consistency**:
- Extract roles listed in SKILL.md Role Registry table
- Glob actual files in roles/ directory
- Compare: every registry entry has a matching file, every file has a registry entry
3. **Role file validation**:
- Read each role.md in roles/ directory
- Verify valid frontmatter (prefix, inner_loop, message_types)
- Check frontmatter values are non-empty
4. **Pipeline validation**:
- Extract pipeline stages from SKILL.md or specs/pipelines.md
- Verify each stage references an existing role
5. **team-config.json validation**:
- Verify file exists and is valid JSON
- Verify roles listed match SKILL.md Role Registry
6. **Cross-reference validation**:
- Check coordinator commands/ files exist if referenced in SKILL.md
- Verify no broken file paths in cross-references
7. **Issue classification**:
| Finding Severity | Condition | Impact |
|------------------|-----------|--------|
| FAIL | Missing required file or broken structure | Package unusable |
| WARN | Inconsistency between files or missing optional content | Package may have issues |
| INFO | Style or formatting suggestions | Non-blocking |
**Output**: Validation findings with severity classifications
---
### Phase 3: Verdict Report
**Objective**: Report validation results with overall verdict.
| Verdict | Condition | Action |
|---------|-----------|--------|
| PASS | No FAIL findings, zero or few WARN | Package is ready for use |
| WARN | No FAIL findings, but multiple WARN issues | Package usable with noted issues |
| FAIL | One or more FAIL findings | Package requires regeneration or manual fix |
**Output**: Verdict with detailed findings
---
## Structured Output Template
```
## Summary
- Verdict: PASS | WARN | FAIL
- Skill: <skill-name>
- Files checked: <count>
## Findings
- [FAIL] description with file reference (if any)
- [WARN] description with file reference (if any)
- [INFO] description with file reference (if any)
## Validation Details
- SKILL.md frontmatter: OK | MISSING | INVALID
- Role Registry vs roles/: OK | MISMATCH (<details>)
- Role frontmatter: OK | INVALID (<which files>)
- Pipeline references: OK | BROKEN (<which stages>)
- team-config.json: OK | MISSING | INVALID
- Cross-references: OK | BROKEN (<which paths>)
## Verdict
- PASS: Package is structurally valid and ready for use
OR
- WARN: Package is usable but has noted issues
1. Issue description
OR
- FAIL: Package requires fixes before use
1. Issue description + suggested resolution
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Skill package directory not found | Report as FAIL, request correct path |
| SKILL.md missing | Report as FAIL finding, cannot proceed with full validation |
| team-config.json invalid JSON | Report as FAIL, include parse error |
| Role file unreadable | Report as WARN, note which file |
| Timeout approaching | Output current findings with "PARTIAL" status |

163
.codex/skills/team-designer/instructions/agent-instruction.md
View File

@@ -1,163 +0,0 @@
# Agent Instruction Template -- Team Skill Designer
Base instruction template for CSV wave agents. Each agent receives this template with its row's column values substituted at runtime via `spawn_agents_on_csv`.
## Purpose
| Phase | Usage |
|-------|-------|
| Phase 1 | Baked into instruction parameter with session folder path |
| Phase 2 | Injected as `instruction` parameter to `spawn_agents_on_csv` |
---
## Base Instruction Template
```markdown
## TASK ASSIGNMENT -- Team Skill Designer
### 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 teamConfig: <session-folder>/teamConfig.json (REQUIRED -- contains complete skill configuration)
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**File Target**: {file_target}
**Generation Type**: {gen_type}
### Task Description
{description}
### Previous Tasks' Findings (Context)
{prev_context}
---
## Execution Protocol
1. **Read discoveries**: Load <session-folder>/discoveries.ndjson for shared exploration findings
2. **Read teamConfig**: Load <session-folder>/teamConfig.json for complete skill configuration (roles, pipelines, specs, templates)
3. **Use context**: Apply previous tasks' findings from prev_context above
4. **Execute by gen_type**:
### For gen_type = directory
- Parse teamConfig to determine required directories
- Create directory structure at teamConfig.targetDir
- Create subdirectories: roles/, specs/, templates/ (if needed)
- Create per-role subdirectories: roles/<role-name>/ (+ commands/ if hasCommands)
- Verify all directories exist
### For gen_type = router
- Read existing Codex team skill SKILL.md as reference pattern
- Generate SKILL.md with these sections in order:
1. YAML frontmatter (name, description, argument-hint, allowed-tools)
2. Auto Mode section
3. Title + Usage examples
4. Overview with workflow diagram
5. Task Classification Rules
6. CSV Schema (header + column definitions)
7. Agent Registry (if interactive agents exist)
8. Output Artifacts table
9. Session Structure diagram
10. Implementation (session init, phases 0-4)
11. Discovery Board Protocol
12. Error Handling table
13. Core Rules list
- Use teamConfig.roles for role registry
- Use teamConfig.pipelines for pipeline definitions
### For gen_type = role-bundle
- Generate role.md with:
1. YAML frontmatter (role, prefix, inner_loop, message_types)
2. Identity section
3. Boundaries (MUST/MUST NOT)
4. Entry Router (for coordinator)
5. Phase references (Phase 0-5 for coordinator)
- Generate commands/*.md for each command in teamConfig.roles[].commands
- Each command file: Purpose, Constants, Phase 2-4 execution logic
- Coordinator always gets: analyze.md, dispatch.md, monitor.md
### For gen_type = role-inline
- Generate single role.md with:
1. YAML frontmatter (role, prefix, inner_loop, message_types)
2. Identity section
3. Boundaries (MUST/MUST NOT)
4. Phase 2: Context Loading
5. Phase 3: Domain Execution (role-specific logic)
6. Phase 4: Output & Report
### For gen_type = spec
- For pipelines.md: Generate from teamConfig.pipelines
- Pipeline name, task table (ID, Role, Name, Depends On, Checkpoint)
- Task metadata registry
- Conditional routing rules
- Dynamic specialist injection
- For other specs: Generate domain-appropriate content
### For gen_type = template
- Check for reference templates in existing skills
- Generate domain-appropriate template structure
- Include placeholder sections and formatting guidelines
5. **Share discoveries**: Append exploration findings to shared board:
```bash
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> <session-folder>/discoveries.ndjson
```
6. **Report result**: Return JSON via report_agent_job_result
### Discovery Types to Share
- `dir_created`: {path, description} -- Directory structure created
- `file_generated`: {file, gen_type, sections} -- File generated with specific sections
- `pattern_found`: {pattern_name, description} -- Design pattern identified
- `config_decision`: {decision, rationale, impact} -- Configuration decision made
- `reference_found`: {source, target, type} -- Cross-reference between generated files
---
## Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key discoveries and generation notes (max 500 chars)",
"files_produced": "semicolon-separated paths of produced files relative to skill root",
"error": ""
}
```
---
## Quality Requirements
All agents must verify before reporting complete:
| Requirement | Criteria |
|-------------|----------|
| Files produced | Verify all claimed files exist via Read |
| teamConfig adherence | Generated content matches teamConfig specifications |
| Pattern fidelity | Generated files follow existing Codex skill patterns |
| Discovery sharing | At least 1 discovery shared to board |
| Error reporting | Non-empty error field if status is failed |
| YAML frontmatter | Role files must have valid frontmatter for agent parsing |
---
## Placeholder Reference
| Placeholder | Resolved By | When |
|-------------|------------|------|
| `<session-folder>` | Skill designer (Phase 1) | Literal path baked into instruction |
| `{id}` | spawn_agents_on_csv | Runtime from CSV row |
| `{title}` | spawn_agents_on_csv | Runtime from CSV row |
| `{description}` | spawn_agents_on_csv | Runtime from CSV row |
| `{role}` | spawn_agents_on_csv | Runtime from CSV row |
| `{file_target}` | spawn_agents_on_csv | Runtime from CSV row |
| `{gen_type}` | spawn_agents_on_csv | Runtime from CSV row |
| `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row |

250
.codex/skills/team-designer/phases/01-requirements-analysis.md Normal file
View File

@@ -0,0 +1,250 @@
# Phase 1: Requirements Analysis
Gather team skill requirements from user input and build the `teamConfig` data structure that drives all subsequent phases.
## Objective
- Parse user input (text description, reference skill, or interactive)
- Determine roles, pipelines, specs, templates
- Auto-decide commands distribution (inline vs commands/ folder)
- Build comprehensive `teamConfig` object
- Confirm with user before proceeding
## Step 1.1: Detect Input Source
```javascript
function detectInputSource(userInput) {
// Source A: Reference to existing skill
if (userInput.includes('based on') || userInput.includes('参考') || userInput.includes('like')) {
return { type: 'reference', refSkill: extractSkillName(userInput) };
}
// Source B: Structured input with roles/pipelines
if (userInput.includes('ROLES:') || userInput.includes('PIPELINES:')) {
return { type: 'structured', data: parseStructuredInput(userInput) };
}
// Source C: Natural language description
return { type: 'natural', description: userInput };
}
```
**For reference source**: Read the referenced skill's SKILL.md and role files to extract structure.
**For natural language**: Use request_user_input to gather missing details interactively.
## Step 1.2: Gather Core Identity
```javascript
const skillNameResponse = request_user_input({
prompt: `团队技能名称？(kebab-case, e.g., team-code-review)\n\nSuggested: ${suggestedName}\nOr enter a custom name.`
});
const prefixResponse = request_user_input({
prompt: `会话前缀？(3-4字符用于任务ID, e.g., TCR)\n\nSuggested: ${suggestedPrefix}\nOr enter a custom prefix.`
});
```
If user provided clear name/prefix in input, skip this step.
## Step 1.3: Determine Roles
### Role Discovery from Domain
Analyze domain description to identify required roles:
```javascript
function discoverRoles(domain) {
const rolePatterns = {
'analyst': ['分析', 'analyze', 'research', 'explore', 'investigate', 'scan'],
'planner': ['规划', 'plan', 'design', 'architect', 'decompose'],
'writer': ['文档', 'write', 'document', 'draft', 'spec', 'report'],
'executor': ['实现', 'implement', 'execute', 'build', 'code', 'develop'],
'tester': ['测试', 'test', 'verify', 'validate', 'qa'],
'reviewer': ['审查', 'review', 'quality', 'check', 'audit', 'inspect'],
'security-expert': ['安全', 'security', 'vulnerability', 'penetration'],
'performance-optimizer': ['性能', 'performance', 'optimize', 'benchmark'],
'data-engineer': ['数据', 'data', 'pipeline', 'etl', 'migration'],
'devops-engineer': ['部署', 'devops', 'deploy', 'ci/cd', 'infrastructure'],
};
const matched = [];
for (const [role, keywords] of Object.entries(rolePatterns)) {
if (keywords.some(kw => domain.toLowerCase().includes(kw))) {
matched.push(role);
}
}
return matched;
}
```
### Role Configuration
For each discovered role, determine:
```javascript
function configureRole(roleName) {
return {
name: roleName,
prefix: determinePrefix(roleName),
inner_loop: determineInnerLoop(roleName),
hasCommands: false, // determined in Step 1.5
commands: [],
message_types: determineMessageTypes(roleName),
path: `roles/${roleName}/role.md`
};
}
// Standard prefix mapping
const prefixMap = {
'analyst': 'RESEARCH',
'writer': 'DRAFT',
'planner': 'PLAN',
'executor': 'IMPL',
'tester': 'TEST',
'reviewer': 'REVIEW',
// Dynamic roles use uppercase role name
};
// Inner loop: roles that process multiple tasks sequentially
const innerLoopRoles = ['executor', 'writer', 'planner'];
// Message types the role handles
const messageMap = {
'analyst': ['state_update'],
'writer': ['state_update', 'discuss_response'],
'planner': ['state_update'],
'executor': ['state_update', 'revision_request'],
'tester': ['state_update'],
'reviewer': ['state_update', 'discuss_request'],
};
```
## Step 1.4: Define Pipelines
### Pipeline Types from Role Combination
```javascript
function definePipelines(roles, domain) {
const has = name => roles.some(r => r.name === name);
// Full lifecycle: analyst → writer → planner → executor → tester → reviewer
if (has('analyst') && has('writer') && has('planner') && has('executor'))
return [{ name: 'full-lifecycle', tasks: buildFullLifecycleTasks(roles) }];
// Spec-only: analyst → writer → reviewer
if (has('analyst') && has('writer') && !has('executor'))
return [{ name: 'spec-only', tasks: buildSpecOnlyTasks(roles) }];
// Impl-only: planner → executor → tester → reviewer
if (has('planner') && has('executor') && !has('analyst'))
return [{ name: 'impl-only', tasks: buildImplOnlyTasks(roles) }];
// Custom: user-defined
return [{ name: 'custom', tasks: buildCustomTasks(roles, domain) }];
}
```
### Task Schema
```javascript
const taskSchema = {
id: 'PREFIX-NNN', // e.g., RESEARCH-001
role: 'analyst', // which role executes
name: 'Seed Analysis', // human-readable name
dependsOn: [], // task IDs that must complete first
isCheckpoint: false, // true for quality gates
isConditional: false, // true for routing decisions
description: '...'
};
```
## Step 1.5: Determine Commands Distribution
**Rule**: 1 action → inline in role.md. 2+ distinct actions → commands/ folder.
```javascript
function determineCommandsDistribution(roles) {
// Coordinator: always has commands/
// coordinator.commands = ['analyze', 'dispatch', 'monitor']
// Standard multi-action roles:
// executor → implement + fix → commands/
// reviewer (if both code & spec review) → review-code + review-spec → commands/
// All others → typically inline
for (const role of roles) {
const actions = countDistinctActions(role);
if (actions.length >= 2) {
role.hasCommands = true;
role.commands = actions.map(a => a.name);
}
}
}
```
## Step 1.6: Determine Specs and Templates
```javascript
// Specs: always include pipelines, add domain-specific
const specs = ['pipelines'];
if (hasQualityGates) specs.push('quality-gates');
if (hasKnowledgeTransfer) specs.push('knowledge-transfer');
// Templates: only if writer role exists
const templates = [];
if (has('writer')) {
// Detect from domain keywords
if (domain.includes('product')) templates.push('product-brief');
if (domain.includes('requirement')) templates.push('requirements');
if (domain.includes('architecture')) templates.push('architecture');
if (domain.includes('epic')) templates.push('epics');
}
```
## Step 1.7: Build teamConfig
```javascript
const teamConfig = {
skillName: string, // e.g., "team-code-review"
sessionPrefix: string, // e.g., "TCR"
domain: string, // domain description
title: string, // e.g., "Code Review Team"
roles: Array<RoleConfig>, // includes coordinator
pipelines: Array<Pipeline>,
specs: Array<string>, // filenames without .md
templates: Array<string>, // filenames without .md
conditionalRouting: boolean,
dynamicSpecialists: Array<string>,
};
```
## Step 1.8: Confirm with User
```
╔══════════════════════════════════════════╗
║ Team Skill Configuration Summary ║
╠══════════════════════════════════════════╣
Skill Name: ${skillName}
Session Prefix: ${sessionPrefix}
Domain: ${domain}
Roles (N):
├─ coordinator (commands: analyze, dispatch, monitor)
├─ role-a [PREFIX-*] (inline) 🔄
└─ role-b [PREFIX-*] (commands: cmd1, cmd2)
Pipelines:
└─ pipeline-name: TASK-001 → TASK-002 → TASK-003
Specs: pipelines, quality-gates
Templates: (none)
╚══════════════════════════════════════════╝
```
Use request_user_input to confirm or allow modifications.
## Output
- **Variable**: `teamConfig` — complete configuration for all subsequent phases
- **Next**: Phase 2 - Scaffold Generation

228
.codex/skills/team-designer/phases/02-scaffold-generation.md Normal file
View File

@@ -0,0 +1,228 @@
# Phase 2: Scaffold Generation
Generate the SKILL.md universal router and create the directory structure for the team skill.
## Objective
- Create directory structure (roles/, specs/, templates/)
- Generate SKILL.md as universal router following v4 pattern
- SKILL.md must NOT contain beat model, pipeline details, or role Phase 2-4 logic
## Step 2.1: Create Directory Structure
```bash
skillDir=".claude/skills/${teamConfig.skillName}"
mkdir -p "${skillDir}"
# Create role directories
for role in teamConfig.roles:
mkdir -p "${skillDir}/roles/${role.name}"
if role.hasCommands:
mkdir -p "${skillDir}/roles/${role.name}/commands"
# Create specs directory
mkdir -p "${skillDir}/specs"
# Create templates directory (if needed)
if teamConfig.templates.length > 0:
mkdir -p "${skillDir}/templates"
```
## Step 2.2: Generate SKILL.md
The SKILL.md follows a strict template. Every generated SKILL.md contains these sections in order:
### Section 1: Frontmatter
```yaml
---
name: ${teamConfig.skillName}
description: ${teamConfig.domain}. Triggers on "${teamConfig.skillName}".
allowed-tools: spawn_agent(*), wait_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
```
### Section 2: Title + Architecture Diagram
```markdown
# ${Title}
${One-line description}
## Architecture
\```
Skill(skill="${teamConfig.skillName}", args="task description")
|
SKILL.md (this file) = Router
|
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-- analyze → dispatch → spawn workers → STOP
|
+-------+-------+-------+
v v v v
[team-worker agents, each loads roles/<role>/role.md]
\```
```
### Section 3: Role Registry
```markdown
## Role Registry
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | roles/coordinator/role.md | — | — |
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
`| ${r.name} | ${r.path} | ${r.prefix}-* | ${r.inner_loop} |`
).join('\n')}
```
### Section 4: Role Router
```markdown
## Role Router
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
```
### Section 5: Shared Constants
```markdown
## Shared Constants
- **Session prefix**: `${teamConfig.sessionPrefix}`
- **Session path**: `.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
```
### Section 6: Worker Spawn Template
```markdown
## Worker Spawn Template
Coordinator spawns workers using this template:
\```
spawn_agent({
agent_type: "team_worker",
items: [{
description: "Spawn <role> worker",
team_name: <team-name>,
name: "<role>",
prompt: `## Role Assignment
role: <role>
role_spec: .codex/skills/${teamConfig.skillName}/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
}]
})
\```
```
### Section 7: User Commands
```markdown
## User Commands
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph |
| `resume` / `continue` | Advance to next step |
| `revise <TASK-ID> [feedback]` | Revise specific task |
| `feedback <text>` | Inject feedback for revision |
| `recheck` | Re-run quality check |
| `improve [dimension]` | Auto-improve weakest dimension |
```
### Section 8: Completion Action
```markdown
## Completion Action
When pipeline completes, coordinator presents:
\```
request_user_input({
prompt: "Pipeline complete. What would you like to do?\n\nOptions:\n1. Archive & Clean (Recommended) - Archive session, clean up team\n2. Keep Active - Keep session for follow-up work\n3. Export Results - Export deliverables to target directory"
})
\```
```
### Section 9: Specs Reference
```markdown
## Specs Reference
${teamConfig.specs.map(s =>
`- [specs/${s}.md](specs/${s}.md) — ${specDescription(s)}`
).join('\n')}
```
### Section 10: Session Directory
```markdown
## Session Directory
\```
.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/
├── team-session.json # Session state + role registry
├── spec/ # Spec phase outputs
├── plan/ # Implementation plan + TASK-*.json
├── artifacts/ # All deliverables
├── wisdom/ # Cross-task knowledge
├── explorations/ # Shared explore cache
├── discussions/ # Discuss round records
└── .msg/ # Team message bus
\```
```
### Section 11: Error Handling
```markdown
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
```
## Step 2.3: Assemble and Write
Assemble all sections into a single SKILL.md file and write to `${skillDir}/SKILL.md`.
**Quality Rules**:
1. SKILL.md must NOT contain beat model (ONE_STEP_PER_INVOCATION, spawn-and-stop)
2. SKILL.md must NOT contain pipeline task details (task IDs, dependencies)
3. SKILL.md must NOT contain role Phase 2-4 logic
4. SKILL.md MUST contain role registry table with correct paths
5. SKILL.md MUST contain worker spawn template with correct `role_spec` paths
## Output
- **File**: `.claude/skills/${teamConfig.skillName}/SKILL.md`
- **Variable**: `skillDir` (path to skill root directory)
- **Next**: Phase 3 - Content Generation
## Next Phase
Return to orchestrator, then auto-continue to [Phase 3: Content Generation](03-content-generation.md).

330
.codex/skills/team-designer/phases/03-content-generation.md Normal file
View File

@@ -0,0 +1,330 @@
# Phase 3: Content Generation
Generate all role files, specs, and templates based on `teamConfig` and the generated SKILL.md.
## Objective
- Generate coordinator role.md + commands/ (analyze, dispatch, monitor)
- Generate each worker role.md (inline or with commands/)
- Generate specs/ files (pipelines.md + domain specs)
- Generate templates/ if needed
- Follow team-lifecycle-v4 golden sample patterns
## Golden Sample Reference
Read the golden sample at `~ or <project>/.claude/skills/team-lifecycle-v4/` for each file type before generating. This ensures pattern fidelity.
## Step 3.1: Generate Coordinator
The coordinator is the most complex role. It always has 3 commands.
### coordinator/role.md
```markdown
---
role: coordinator
---
# Coordinator — ${teamConfig.title}
## Identity
You are the coordinator for ${teamConfig.title}. You orchestrate the ${teamConfig.domain} pipeline by analyzing requirements, dispatching tasks, and monitoring worker progress.
## Boundaries
- **DO**: Analyze, dispatch, monitor, reconcile, report
- **DO NOT**: Implement domain work directly — delegate to workers
## Command Execution Protocol
Read command file → Execute ALL steps sequentially → Return to entry router.
Commands: `commands/analyze.md`, `commands/dispatch.md`, `commands/monitor.md`.
## Entry Router
On each invocation, detect current state and route:
| Condition | Handler |
|-----------|---------|
| First invocation (no session) | → Phase 1: Requirement Clarification |
| Session exists, no team | → Phase 2: Team Setup |
| Team exists, no tasks | → Phase 3: Dispatch (analyze.md → dispatch.md) |
| Tasks exist, none started | → Phase 4: Spawn First (monitor.md → handleSpawnNext) |
| Callback received | → monitor.md → handleCallback |
| User says "check"/"status" | → monitor.md → handleCheck |
| User says "resume"/"continue" | → monitor.md → handleResume |
| All tasks completed | → Phase 5: Report & Completion |
## Phase 0: Session Resume
If `.workflow/.team/${teamConfig.sessionPrefix}-*/team-session.json` exists:
- Load session state, verify team, reconcile task status
- Route to appropriate handler based on current state
## Phase 1: Requirement Clarification
- Parse user's task description at TEXT LEVEL
- Use request_user_input if requirements are ambiguous
- Execute `commands/analyze.md` for signal detection + complexity scoring
## Phase 2: Team Setup
- Session folder creation with session ID: `${teamConfig.sessionPrefix}-<slug>-<date>`
- Initialize team_msg message bus
- Create session directory structure
## Phase 3: Dispatch
- Execute `commands/dispatch.md`
- Creates task entries in tasks.json with blockedBy dependencies
## Phase 4: Spawn & Monitor
- Execute `commands/monitor.md` → handleSpawnNext
- Spawn ready workers as team_worker agents via spawn_agent()
- **STOP after spawning** — wait for callback
## Phase 5: Report & Completion
- Aggregate all task artifacts
- Present completion action to user
```
### coordinator/commands/analyze.md
Template based on golden sample — includes:
- Signal detection (keywords → capabilities)
- Dependency graph construction (tiers)
- Complexity scoring (1-3 Low, 4-6 Medium, 7+ High)
- Role minimization (cap at 5)
- Output: task-analysis.json
```markdown
# Command: Analyze
## Signal Detection
Scan requirement text for capability signals:
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
`- **${r.name}**: [domain-specific keywords]`
).join('\n')}
## Dependency Graph
Build 4-tier dependency graph:
- Tier 0: Independent tasks (can run in parallel)
- Tier 1: Depends on Tier 0
- Tier 2: Depends on Tier 1
- Tier 3: Depends on Tier 2
## Complexity Scoring
| Score | Level | Strategy |
|-------|-------|----------|
| 1-3 | Low | Direct implementation, skip deep planning |
| 4-6 | Medium | Standard pipeline with planning |
| 7+ | High | Full spec → plan → implement cycle |
## Output
Write `task-analysis.json` to session directory:
\```json
{
"signals": [...],
"roles_needed": [...],
"dependency_tiers": [...],
"complexity": { "score": N, "level": "Low|Medium|High" },
"pipeline": "${teamConfig.pipelines[0].name}"
}
\```
```
### coordinator/commands/dispatch.md
Template — includes:
- Topological sort from dependency graph
- tasks.json entries with blockedBy for dependencies
- Task description template (PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS)
### coordinator/commands/monitor.md
Template — includes:
- Beat model constants (ONE_STEP_PER_INVOCATION, SPAWN_MODE: spawn-and-stop)
- 6 handlers: handleCallback, handleCheck, handleResume, handleSpawnNext, handleComplete, handleAdapt
- Checkpoint detection for quality gates
- Fast-advance reconciliation
**Critical**: This is the ONLY file that contains beat model logic.
## Step 3.2: Generate Worker Roles
For each worker role in `teamConfig.roles`:
### Inline Role Template (no commands/)
```markdown
---
role: ${role.name}
prefix: ${role.prefix}
inner_loop: ${role.inner_loop}
message_types: [${role.message_types.join(', ')}]
---
# ${capitalize(role.name)} — ${teamConfig.title}
## Identity
You are the ${role.name} for ${teamConfig.title}.
Task prefix: `${role.prefix}-*`
## Phase 2: Context Loading
- Read task description from tasks.json (find by id)
- Load relevant session artifacts from session directory
- Load specs from `specs/` as needed
## Phase 3: Domain Execution
[Domain-specific execution logic for this role]
### Execution Steps
1. [Step 1 based on role's domain]
2. [Step 2]
3. [Step 3]
### Tools Available
- CLI tools: `ccw cli --mode analysis|write`
- Direct tools: Read, Write, Edit, Bash, Grep, Glob
- Message bus: `mcp__ccw-tools__team_msg`
- **Cannot use spawn_agent()** — workers must use CLI or direct tools
## Phase 4: Output & Report
- Write artifacts to session directory
- Log state_update via team_msg
- Publish wisdom if cross-task knowledge discovered
```
### Command-Based Role Template (has commands/)
```markdown
---
role: ${role.name}
prefix: ${role.prefix}
inner_loop: ${role.inner_loop}
message_types: [${role.message_types.join(', ')}]
---
# ${capitalize(role.name)} — ${teamConfig.title}
## Identity
You are the ${role.name} for ${teamConfig.title}.
Task prefix: `${role.prefix}-*`
## Phase 2: Context Loading
Load task description, detect mode/command.
## Phase 3: Command Router
| Condition | Command |
|-----------|---------|
${role.commands.map(cmd =>
`| [condition for ${cmd}] | → commands/${cmd}.md |`
).join('\n')}
Read command file → Execute ALL steps → Return to Phase 4.
## Phase 4: Output & Report
Write artifacts, log state_update.
```
Then generate each `commands/<cmd>.md` with domain-specific logic.
## Step 3.3: Generate Specs
### specs/pipelines.md
```markdown
# Pipeline Definitions
## Available Pipelines
${teamConfig.pipelines.map(p => `
### ${p.name}
| Task ID | Role | Name | Depends On | Checkpoint |
|---------|------|------|------------|------------|
${p.tasks.map(t =>
`| ${t.id} | ${t.role} | ${t.name} | ${t.dependsOn.join(', ') || '—'} | ${t.isCheckpoint ? '✓' : '—'} |`
).join('\n')}
`).join('\n')}
## Task Metadata Registry
Standard task description template:
\```
PURPOSE: [goal]
TASK: [steps]
CONTEXT: [session artifacts + specs]
EXPECTED: [deliverable format]
CONSTRAINTS: [scope limits]
\```
## Conditional Routing
${teamConfig.conditionalRouting ? `
PLAN-001 complexity assessment routes to:
- Low (1-3): Direct implementation
- Medium (4-6): Standard planning
- High (7+): Full spec → plan → implement
` : 'No conditional routing in this pipeline.'}
## Dynamic Specialist Injection
${teamConfig.dynamicSpecialists.length > 0 ?
teamConfig.dynamicSpecialists.map(s => `- ${s}: Injected when domain keywords detected`).join('\n') :
'No dynamic specialists configured.'
}
```
### Additional Specs
For each additional spec in `teamConfig.specs` (beyond pipelines), generate domain-appropriate content:
- **quality-gates.md**: Thresholds (Pass≥80%, Review 60-79%, Fail<60%), scoring dimensions, per-phase gates
- **knowledge-transfer.md**: 5 transfer channels, Phase 2 loading protocol, Phase 4 publishing protocol
## Step 3.4: Generate Templates
For each template in `teamConfig.templates`:
1. Check if golden sample has matching template at `~ or <project>/.claude/skills/team-lifecycle-v4/templates/`
2. If exists: copy and adapt for new domain
3. If not: generate domain-appropriate template structure
## Step 3.5: Generation Order
Execute in this order (respects dependencies):
1. **specs/** — needed by roles for reference
2. **coordinator/** — role.md + commands/ (3 files)
3. **workers/** — each role.md (+ optional commands/)
4. **templates/** — independent, generate last
For each file:
1. Read golden sample equivalent (if exists)
2. Adapt content for current teamConfig
3. Write file
4. Verify file exists
## Output
- **Files**: All role.md, commands/*.md, specs/*.md, templates/*.md
- **Next**: Phase 4 - Validation

320
.codex/skills/team-designer/phases/04-validation.md Normal file
View File

@@ -0,0 +1,320 @@
# Phase 4: Validation
Validate the generated team skill package for structural completeness, reference integrity, role consistency, and team-worker compatibility.
## Objective
- Verify all required files exist
- Validate SKILL.md role registry matches actual role files
- Check role.md frontmatter format for team-worker compatibility
- Verify pipeline task references match existing roles
- Report validation results
## Step 4.1: Structural Validation
```javascript
function validateStructure(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
// Check SKILL.md exists
if (!fileExists(`${skillDir}/SKILL.md`)) {
results.errors.push('SKILL.md not found');
}
// Check coordinator structure
if (!fileExists(`${skillDir}/roles/coordinator/role.md`)) {
results.errors.push('Coordinator role.md not found');
}
for (const cmd of ['analyze', 'dispatch', 'monitor']) {
if (!fileExists(`${skillDir}/roles/coordinator/commands/${cmd}.md`)) {
results.errors.push(`Coordinator command ${cmd}.md not found`);
}
}
// Check worker roles
for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
if (!fileExists(`${skillDir}/roles/${role.name}/role.md`)) {
results.errors.push(`Worker role.md not found: ${role.name}`);
}
if (role.hasCommands) {
for (const cmd of role.commands) {
if (!fileExists(`${skillDir}/roles/${role.name}/commands/${cmd}.md`)) {
results.errors.push(`Worker command not found: ${role.name}/commands/${cmd}.md`);
}
}
}
}
// Check specs
if (!fileExists(`${skillDir}/specs/pipelines.md`)) {
results.errors.push('specs/pipelines.md not found');
}
return results;
}
```
## Step 4.2: SKILL.md Content Validation
```javascript
function validateSkillMd(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
const skillMd = Read(`${skillDir}/SKILL.md`);
// Required sections
const requiredSections = [
'Role Registry', 'Role Router', 'Shared Constants',
'Worker Spawn Template', 'User Commands', 'Session Directory'
];
for (const section of requiredSections) {
if (!skillMd.includes(section)) {
results.errors.push(`SKILL.md missing section: ${section}`);
}
}
// Verify role registry completeness
for (const role of teamConfig.roles) {
if (!skillMd.includes(role.path || `roles/${role.name}/role.md`)) {
results.errors.push(`Role registry missing path for: ${role.name}`);
}
}
// Verify session prefix
if (!skillMd.includes(teamConfig.sessionPrefix)) {
results.warnings.push(`Session prefix ${teamConfig.sessionPrefix} not found in SKILL.md`);
}
// Verify NO beat model content in SKILL.md
const beatModelPatterns = [
'ONE_STEP_PER_INVOCATION',
'spawn-and-stop',
'SPAWN_MODE',
'handleCallback',
'handleSpawnNext'
];
for (const pattern of beatModelPatterns) {
if (skillMd.includes(pattern)) {
results.errors.push(`SKILL.md contains beat model content: ${pattern} (should be in coordinator only)`);
}
}
return results;
}
```
## Step 4.3: Role Frontmatter Validation
Verify role.md files have correct YAML frontmatter for team-worker agent compatibility:
```javascript
function validateRoleFrontmatter(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
const roleMd = Read(`${skillDir}/roles/${role.name}/role.md`);
// Check frontmatter exists
if (!roleMd.startsWith('---')) {
results.errors.push(`${role.name}/role.md missing YAML frontmatter`);
continue;
}
// Extract frontmatter
const fmMatch = roleMd.match(/^---\n([\s\S]*?)\n---/);
if (!fmMatch) {
results.errors.push(`${role.name}/role.md malformed frontmatter`);
continue;
}
const fm = fmMatch[1];
// Required fields
if (!fm.includes(`role: ${role.name}`)) {
results.errors.push(`${role.name}/role.md frontmatter missing 'role: ${role.name}'`);
}
if (!fm.includes(`prefix: ${role.prefix}`)) {
results.errors.push(`${role.name}/role.md frontmatter missing 'prefix: ${role.prefix}'`);
}
if (!fm.includes(`inner_loop: ${role.inner_loop}`)) {
results.warnings.push(`${role.name}/role.md frontmatter missing 'inner_loop: ${role.inner_loop}'`);
}
if (!fm.includes('message_types:')) {
results.warnings.push(`${role.name}/role.md frontmatter missing 'message_types'`);
}
}
return results;
}
```
## Step 4.4: Pipeline Consistency
```javascript
function validatePipelines(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
// Check every role referenced in pipelines exists
const definedRoles = new Set(teamConfig.roles.map(r => r.name));
for (const pipeline of teamConfig.pipelines) {
for (const task of pipeline.tasks) {
if (!definedRoles.has(task.role)) {
results.errors.push(
`Pipeline '${pipeline.name}' task ${task.id} references undefined role: ${task.role}`
);
}
}
// Check for circular dependencies
const visited = new Set();
const stack = new Set();
for (const task of pipeline.tasks) {
if (hasCycle(task, pipeline.tasks, visited, stack)) {
results.errors.push(`Pipeline '${pipeline.name}' has circular dependency involving ${task.id}`);
}
}
}
// Verify specs/pipelines.md contains all pipelines
const pipelinesMd = Read(`${skillDir}/specs/pipelines.md`);
for (const pipeline of teamConfig.pipelines) {
if (!pipelinesMd.includes(pipeline.name)) {
results.warnings.push(`specs/pipelines.md missing pipeline: ${pipeline.name}`);
}
}
return results;
}
```
## Step 4.5: Commands Distribution Validation
```javascript
function validateCommandsDistribution(teamConfig) {
const skillDir = `.claude/skills/${teamConfig.skillName}`;
const results = { errors: [], warnings: [], info: [] };
for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
if (role.hasCommands) {
// Verify commands/ directory exists and has files
const cmdDir = `${skillDir}/roles/${role.name}/commands`;
if (role.commands.length < 2) {
results.warnings.push(
`${role.name} has commands/ but only ${role.commands.length} command(s) — consider inline`
);
}
// Verify role.md references commands
const roleMd = Read(`${skillDir}/roles/${role.name}/role.md`);
for (const cmd of role.commands) {
if (!roleMd.includes(`commands/${cmd}.md`)) {
results.warnings.push(
`${role.name}/role.md doesn't reference commands/${cmd}.md`
);
}
}
} else {
// Verify no commands/ directory exists
const cmdDir = `${skillDir}/roles/${role.name}/commands`;
if (directoryExists(cmdDir)) {
results.warnings.push(
`${role.name} is inline but has commands/ directory`
);
}
}
}
return results;
}
```
## Step 4.6: Aggregate Results and Report
```javascript
function generateValidationReport(teamConfig) {
const structural = validateStructure(teamConfig);
const skillMd = validateSkillMd(teamConfig);
const frontmatter = validateRoleFrontmatter(teamConfig);
const pipelines = validatePipelines(teamConfig);
const commands = validateCommandsDistribution(teamConfig);
const allErrors = [
...structural.errors, ...skillMd.errors,
...frontmatter.errors, ...pipelines.errors, ...commands.errors
];
const allWarnings = [
...structural.warnings, ...skillMd.warnings,
...frontmatter.warnings, ...pipelines.warnings, ...commands.warnings
];
const gate = allErrors.length === 0 ? 'PASS' :
allErrors.length <= 2 ? 'REVIEW' : 'FAIL';
const skillDir = `.claude/skills/${teamConfig.skillName}`;
console.log(`
╔══════════════════════════════════════╗
║ Team Skill Validation Report ║
╠══════════════════════════════════════╣
║ Skill: ${teamConfig.skillName.padEnd(28)}║
║ Gate: ${gate.padEnd(28)}║
╚══════════════════════════════════════╝
Structure:
${skillDir}/
├── SKILL.md ✓
├── roles/
│ ├── coordinator/
│ │ ├── role.md ✓
│ │ └── commands/ (analyze, dispatch, monitor)
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r => {
const structure = r.hasCommands
? ` │ ├── ${r.name}/ (role.md + commands/)`
: ` │ ├── ${r.name}/role.md`;
return `${structure.padEnd(50)}✓`;
}).join('\n')}
├── specs/
│ └── pipelines.md ✓
└── templates/ ${teamConfig.templates.length > 0 ? '✓' : '(empty)'}
${allErrors.length > 0 ? `Errors (${allErrors.length}):\n${allErrors.map(e => ` ✗ ${e}`).join('\n')}` : 'Errors: None ✓'}
${allWarnings.length > 0 ? `Warnings (${allWarnings.length}):\n${allWarnings.map(w => ` ⚠ ${w}`).join('\n')}` : 'Warnings: None ✓'}
Usage:
Skill(skill="${teamConfig.skillName}", args="<task description>")
`);
return { gate, errors: allErrors, warnings: allWarnings };
}
```
## Step 4.7: Error Recovery
```javascript
if (report.gate === 'FAIL') {
const recovery = request_user_input({
prompt: `Validation found ${report.errors.length} errors. How to proceed?\n\nOptions:\n1. Auto-fix - Attempt automatic fixes (missing files, frontmatter)\n2. Regenerate - Re-run Phase 3 with fixes\n3. Accept as-is - Manual fix later`
});
}
```
## Output
- **Report**: Validation results with quality gate (PASS/REVIEW/FAIL)
- **Completion**: Team skill package ready at `.claude/skills/${teamConfig.skillName}/`
## Completion
Team Skill Designer has completed. The generated team skill is ready for use.
```
Next Steps:
1. Review SKILL.md router for correctness
2. Review each role.md for domain accuracy
3. Test: Skill(skill="${teamConfig.skillName}", args="<test task>")
4. Iterate based on execution results
```

180
.codex/skills/team-designer/schemas/tasks-schema.md
View File

@@ -1,180 +0,0 @@
# Team Skill Designer -- CSV Schema
## Master CSV: tasks.csv
### Column Definitions
#### Input Columns (Set by Decomposer)
| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `id` | string | Yes | Unique task identifier | `"SCAFFOLD-001"` |
| `title` | string | Yes | Short task title | `"Create directory structure"` |
| `description` | string | Yes | Detailed generation instructions (self-contained) | `"Create roles/, specs/, templates/ directories..."` |
| `role` | string | Yes | Generator role name | `"scaffolder"` |
| `file_target` | string | Yes | Target file/directory path relative to skill root | `"roles/coordinator/role.md"` |
| `gen_type` | enum | Yes | `directory`, `router`, `role-bundle`, `role-inline`, `spec`, `template`, `validation` | `"role-inline"` |
| `deps` | string | No | Semicolon-separated dependency task IDs | `"SCAFFOLD-001;SPEC-001"` |
| `context_from` | string | No | Semicolon-separated task IDs for context | `"SPEC-001"` |
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
#### 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) | `"[SCAFFOLD-001] Created directory structure at .codex/skills/..."` |
#### Output Columns (Set by Agent)
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` |
| `findings` | string | Key discoveries (max 500 chars) | `"Generated coordinator with 3 commands: analyze, dispatch, monitor"` |
| `files_produced` | string | Semicolon-separated paths of produced files | `"roles/coordinator/role.md;roles/coordinator/commands/analyze.md"` |
| `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.
---
### Generator Roles
| Role | gen_type Values | Description |
|------|-----------------|-------------|
| `scaffolder` | `directory` | Creates directory structures |
| `router-writer` | `router` | Generates SKILL.md orchestrator files |
| `role-writer` | `role-bundle`, `role-inline` | Generates role.md files (+ optional commands/) |
| `spec-writer` | `spec` | Generates specs/*.md files |
| `template-writer` | `template` | Generates templates/*.md files |
| `validator` | `validation` | Validates generated skill package |
---
### gen_type Values
| gen_type | Target | Description |
|----------|--------|-------------|
| `directory` | Directory path | Create directory structure with subdirectories |
| `router` | SKILL.md | Generate main orchestrator SKILL.md with frontmatter, role registry, router |
| `role-bundle` | Directory path | Generate role.md + commands/ folder with multiple command files |
| `role-inline` | Single .md file | Generate single role.md with inline Phase 2-4 logic |
| `spec` | Single .md file | Generate spec file (pipelines, quality-gates, etc.) |
| `template` | Single .md file | Generate document template file |
| `validation` | Report | Validate complete skill package structure and references |
---
### Example Data
```csv
id,title,description,role,file_target,gen_type,deps,context_from,exec_mode,wave,status,findings,files_produced,error
"SCAFFOLD-001","Create directory structure","Create complete directory structure for team-code-review skill:\n- ~ or <project>/.codex/skills/team-code-review/\n- roles/coordinator/ + commands/\n- roles/analyst/\n- roles/reviewer/\n- specs/\n- templates/","scaffolder","skill-dir","directory","","","csv-wave","1","pending","","",""
"ROUTER-001","Generate SKILL.md","Generate ~ or <project>/.codex/skills/team-code-review/SKILL.md with:\n- Frontmatter (name, description, allowed-tools)\n- Architecture diagram\n- Role registry table\n- CSV schema reference\n- Session structure\n- Wave execution engine\nUse teamConfig.json for role list and pipeline definitions","router-writer","SKILL.md","router","SCAFFOLD-001","SCAFFOLD-001","csv-wave","2","pending","","",""
"SPEC-001","Generate pipelines spec","Generate specs/pipelines.md with:\n- Pipeline definitions from teamConfig\n- Task registry with PREFIX-NNN format\n- Conditional routing rules\n- Dynamic specialist injection\nRoles: analyst(ANALYSIS-*), reviewer(REVIEW-*)","spec-writer","specs/pipelines.md","spec","SCAFFOLD-001","SCAFFOLD-001","csv-wave","2","pending","","",""
"ROLE-001","Generate coordinator","Generate roles/coordinator/role.md with entry router and commands/analyze.md, commands/dispatch.md, commands/monitor.md. Coordinator orchestrates the analysis pipeline","role-writer","roles/coordinator/","role-bundle","SCAFFOLD-001;SPEC-001","SPEC-001","csv-wave","3","pending","","",""
"ROLE-002","Generate analyst role","Generate roles/analyst/role.md with Phase 2 (context loading), Phase 3 (analysis execution), Phase 4 (output). Prefix: ANALYSIS, inner_loop: false","role-writer","roles/analyst/role.md","role-inline","SCAFFOLD-001;SPEC-001","SPEC-001","csv-wave","3","pending","","",""
"ROLE-003","Generate reviewer role","Generate roles/reviewer/role.md with Phase 2 (load artifacts), Phase 3 (review execution), Phase 4 (report). Prefix: REVIEW, inner_loop: false","role-writer","roles/reviewer/role.md","role-inline","SCAFFOLD-001;SPEC-001","SPEC-001","csv-wave","3","pending","","",""
```
---
### Column Lifecycle
```
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
--------------------- -------------------- -----------------
id ----------> id ----------> id
title ----------> title ----------> (reads)
description ----------> description ----------> (reads)
role ----------> role ----------> (reads)
file_target ----------> file_target ----------> (reads)
gen_type ----------> gen_type ----------> (reads)
deps ----------> deps ----------> (reads)
context_from----------> context_from----------> (reads)
exec_mode ----------> exec_mode ----------> (reads)
wave ----------> (reads)
prev_context ----------> (reads)
status
findings
files_produced
error
```
---
## Output Schema (JSON)
Agent output via `report_agent_job_result` (csv-wave tasks):
```json
{
"id": "ROLE-001",
"status": "completed",
"findings": "Generated coordinator role with entry router, 3 commands (analyze, dispatch, monitor), beat model in monitor.md only",
"files_produced": "roles/coordinator/role.md;roles/coordinator/commands/analyze.md;roles/coordinator/commands/dispatch.md;roles/coordinator/commands/monitor.md",
"error": ""
}
```
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
---
## Discovery Types
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `dir_created` | `data.path` | `{path, description}` | Directory structure created |
| `file_generated` | `data.file` | `{file, gen_type, sections}` | File generated with sections |
| `pattern_found` | `data.pattern_name` | `{pattern_name, description}` | Design pattern from golden sample |
| `config_decision` | `data.decision` | `{decision, rationale, impact}` | Config decision made |
| `validation_result` | `data.check` | `{check, passed, message}` | Validation check result |
| `reference_found` | `data.source+data.target` | `{source, target, type}` | Cross-reference between files |
### Discovery NDJSON Format
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"SCAFFOLD-001","type":"dir_created","data":{"path":"~ or <project>/.codex/skills/team-code-review/roles/","description":"Created roles directory with coordinator, analyst, reviewer subdirs"}}
{"ts":"2026-03-08T10:05:00Z","worker":"ROLE-001","type":"file_generated","data":{"file":"roles/coordinator/role.md","gen_type":"role-bundle","sections":["entry-router","phase-0","phase-1","phase-2","phase-3"]}}
{"ts":"2026-03-08T10:10:00Z","worker":"SPEC-001","type":"config_decision","data":{"decision":"full-lifecycle pipeline","rationale":"Both analyst and reviewer roles present","impact":"4-tier dependency graph"}}
```
> 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 in {pending, completed, failed, skipped} | "Invalid status: {status}" |
| gen_type valid | Value in {directory, router, role-bundle, role-inline, spec, template, validation} | "Invalid gen_type: {value}" |
| file_target valid | Path is relative and uses forward slashes | "Invalid file_target: {path}" |
| Cross-mechanism deps | Interactive to CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |

576
.codex/skills/team-executor/SKILL.md
View File

@@ -1,447 +1,185 @@
---
name: team-executor
description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution via worker agents. No analysis, no role generation -- only loads and executes. Session path required.
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"--session=<path>\""
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "Team Executor".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
# Team Executor
## Usage
Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
```bash
$team-executor "--session=.workflow/.team/TC-project-2026-03-08"
$team-executor -c 4 "--session=.workflow/.team/TC-auth-2026-03-07"
$team-executor -y "--session=.workflow/.team/TC-api-2026-03-06"
$team-executor --continue "EX-project-2026-03-08"
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-executor") |
| args="--session=<path>" [REQUIRED] |
+-------------------+-------------------------------+
| Session Validation
+---- --session valid? ----+
| NO | YES
v v
Error immediately Orchestration Mode
(no session) -> executor
|
+-------+-------+-------+
v v v v
[team-worker agents loaded from session role-specs]
```
**Flags**:
- `-y, --yes`: Skip all confirmations (auto mode)
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
- `--continue`: Resume existing executor session
---
## Session Validation (BEFORE routing)
**CRITICAL**: Session validation MUST occur before any execution.
### Parse Arguments
Extract from `$ARGUMENTS`:
- `--session=<path>`: Path to team-coordinate session folder (REQUIRED)
**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)
### Validation Steps
---
1. **Check `--session` provided**:
- If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
## Overview
Lightweight session execution skill: load team-coordinate session → reconcile state → spawn worker agents → execute → deliver. No analysis, no role generation -- only executes existing sessions.
**Execution Model**: Hybrid — CSV wave pipeline (primary) + individual agent spawn (secondary)
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Team Executor WORKFLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 0: Session Validation + State Reconciliation │
│ ├─ Validate session structure (team-session.json, task-analysis.json)│
│ ├─ Load session state and role specifications │
│ ├─ Reconcile with TaskList (bidirectional sync) │
│ ├─ Reset interrupted tasks (in_progress → pending) │
│ ├─ Detect fast-advance orphans and reset │
│ └─ Output: validated session, reconciled state │
│ │
│ Phase 1: Requirement → CSV + Classification │
│ ├─ Load task-analysis.json from session │
│ ├─ Create tasks from analysis with role assignments │
│ ├─ Classify tasks: csv-wave | interactive (from role specs) │
│ ├─ 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 (if any) │
│ │ ├─ 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 (if any) │
│ │ ├─ 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` based on role specification:
| exec_mode | Mechanism | Criteria |
|-----------|-----------|----------|
| `csv-wave` | `spawn_agents_on_csv` | Role has inner_loop=false |
| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Role has inner_loop=true |
**Classification Decision**:
| Task Property | Classification |
|---------------|---------------|
| Role inner_loop=false | `csv-wave` |
| Role inner_loop=true | `interactive` |
---
## CSV Schema
### tasks.csv (Master State)
```csv
id,title,description,deps,context_from,exec_mode,role,wave,status,findings,error
1,Implement auth module,Create authentication module with JWT,,,"csv-wave","implementer",1,pending,"",""
2,Write tests,Write unit tests for auth module,1,1,"csv-wave","tester",2,pending,"",""
3,Review code,Review implementation and tests,2,2,"interactive","reviewer",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` |
| `role` | Input | Role name from session role-specs |
| `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)
Interactive agents are loaded dynamically from session role-specs where `inner_loop=true`.
> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding role-spec.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 |
---
## 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
├── 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
```
---
## Implementation
### Session Initialization
```javascript
// Parse arguments
const args = parseArguments($ARGUMENTS)
const AUTO_YES = args.yes || args.y || false
const CONCURRENCY = args.concurrency || args.c || 3
const CONTINUE_SESSION = args.continue || null
const SESSION_PATH = args.session || null
// Validate session path
if (!SESSION_PATH) {
throw new Error("Session required. Usage: --session=<path-to-TC-folder>")
}
// Generate executor session ID
const sessionId = `EX-${extractSessionName(SESSION_PATH)}-${formatDate(new Date(), 'yyyy-MM-dd')}`
const sessionDir = `.workflow/.csv-wave/${sessionId}`
// Create session structure
Bash({ command: `mkdir -p "${sessionDir}/interactive" "${sessionDir}/agents"` })
Write(`${sessionDir}/discoveries.ndjson`, '')
Write(`${sessionDir}/agents/registry.json`, JSON.stringify({ active: [], closed: [] }))
```
---
### Phase 0: Session Validation + State Reconciliation
**Objective**: Validate session structure and reconcile session state with actual task status
**Validation Steps**:
1. Check `--session` provided
2. Validate session structure:
2. **Validate session structure** (see specs/session-schema.md):
- Directory exists at path
- `team-session.json` exists and valid JSON
- `task-analysis.json` exists and valid JSON
- `role-specs/` directory has at least one `.md` file
- Each role in `team-session.json#roles` has corresponding `.md` file in `role-specs/`
3. If validation fails → ERROR with specific reason → STOP
**Reconciliation Steps**:
1. Load team-session.json and task-analysis.json
2. Compare TaskList() with session.completed_tasks, bidirectional sync
3. Reset any in_progress tasks to pending
4. Detect fast-advance orphans (in_progress tasks without matching active_worker + created > 5 minutes) → reset to pending
5. Create missing tasks (if needed) from task-analysis
6. Update session file with reconciled state
7. TeamCreate if team does not exist
**Success Criteria**:
- Session validated, state reconciled, team ready
- All role-specs loaded and validated
3. **Validation failure**:
- Report specific missing component
- Suggest re-running team-coordinate or checking path
---
### Phase 1: Requirement → CSV + Classification
## Role Router
**Objective**: Generate task breakdown from session task-analysis and create master CSV
This skill is **executor-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
**Decomposition Rules**:
### Dispatch Logic
Load task-analysis.json from session and create tasks with:
- Task ID, title, description from analysis
- Dependencies from analysis
- Role assignment from analysis
- exec_mode classification based on role inner_loop flag
| Scenario | Action |
|----------|--------|
| No `--session` | **ERROR** immediately |
| `--session` invalid | **ERROR** with specific reason |
| Valid session | Orchestration Mode -> executor |
**Classification Rules**:
### Orchestration Mode
Read each role-spec file to determine inner_loop flag:
- inner_loop=false → `exec_mode=csv-wave`
- inner_loop=true → `exec_mode=interactive`
**Invocation**: `Skill(skill="team-executor", args="--session=<session-folder>")`
**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
**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 = readCSV(`${sessionDir}/tasks.csv`)
const maxWave = Math.max(...masterCSV.map(t => t.wave))
for (let wave = 1; wave <= maxWave; wave++) {
// Execute pre-wave interactive tasks
const preWaveTasks = masterCSV.filter(t =>
t.wave === wave && t.exec_mode === 'interactive' && t.position === 'pre-wave'
)
for (const task of preWaveTasks) {
const roleSpec = Read(`${SESSION_PATH}/role-specs/${task.role}.md`)
const agent = spawn_agent({
message: buildWorkerPrompt(task, roleSpec, sessionDir)
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
close_agent({ id: agent })
updateTaskStatus(task.id, result)
}
// Build wave CSV (csv-wave tasks only)
const waveTasks = masterCSV.filter(t => t.wave === wave && t.exec_mode === 'csv-wave')
if (waveTasks.length > 0) {
// Inject prev_context from context_from tasks
for (const task of waveTasks) {
if (task.context_from) {
const contextIds = task.context_from.split(';')
const contextFindings = masterCSV
.filter(t => contextIds.includes(t.id))
.map(t => `[Task ${t.id}] ${t.findings}`)
.join('\n\n')
task.prev_context = contextFindings
}
}
// Write wave CSV
writeCSV(`${sessionDir}/wave-${wave}.csv`, waveTasks)
// Execute wave
spawn_agents_on_csv({
csv_path: `${sessionDir}/wave-${wave}.csv`,
instruction_path: `${sessionDir}/instructions/agent-instruction.md`,
concurrency: CONCURRENCY
})
// Merge results back to master
const waveResults = readCSV(`${sessionDir}/wave-${wave}.csv`)
for (const result of waveResults) {
const masterTask = masterCSV.find(t => t.id === result.id)
Object.assign(masterTask, result)
}
writeCSV(`${sessionDir}/tasks.csv`, masterCSV)
// Cleanup wave CSV
Bash({ command: `rm "${sessionDir}/wave-${wave}.csv"` })
}
// Execute post-wave interactive tasks
const postWaveTasks = masterCSV.filter(t =>
t.wave === wave && t.exec_mode === 'interactive' && t.position === 'post-wave'
)
for (const task of postWaveTasks) {
const roleSpec = Read(`${SESSION_PATH}/role-specs/${task.role}.md`)
const agent = spawn_agent({
message: buildWorkerPrompt(task, roleSpec, sessionDir)
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
close_agent({ id: agent })
updateTaskStatus(task.id, result)
}
// Check for failures and skip dependents
const failedTasks = masterCSV.filter(t => t.wave === wave && t.status === 'failed')
if (failedTasks.length > 0) {
skipDependents(masterCSV, failedTasks)
}
}
**Lifecycle**:
```
Validate session
-> executor Phase 0: Reconcile state (reset interrupted, detect orphans)
-> executor Phase 1: Spawn first batch team-worker agents (background) -> STOP
-> Worker executes -> callback -> executor advances next step
-> Loop until pipeline complete -> Phase 2 report + completion action
```
**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
**User Commands** (wake paused executor):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
---
### Phase 3: Results Aggregation
## Role Registry
**Objective**: Generate final results and human-readable report.
| Role | File | Type |
|------|------|------|
| executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator |
| (dynamic) | `<session>/role-specs/<role-name>.md` | loaded from session |
```javascript
// Export results.csv
const masterCSV = readCSV(`${sessionDir}/tasks.csv`)
writeCSV(`${sessionDir}/results.csv`, masterCSV)
---
// Generate context.md
const contextMd = generateContextReport(masterCSV, sessionDir)
Write(`${sessionDir}/context.md`, contextMd)
## Executor Spawn Template
// Cleanup interactive agents
const registry = JSON.parse(Read(`${sessionDir}/agents/registry.json`))
for (const agent of registry.active) {
close_agent({ id: agent.id })
}
Write(`${sessionDir}/agents/registry.json`, JSON.stringify({ active: [], closed: registry.closed }))
### v2 Worker Spawn (all roles)
// Display summary
const summary = {
total: masterCSV.length,
completed: masterCSV.filter(t => t.status === 'completed').length,
failed: masterCSV.filter(t => t.status === 'failed').length,
skipped: masterCSV.filter(t => t.status === 'skipped').length
}
console.log(`Pipeline complete: ${summary.completed}/${summary.total} tasks completed`)
When executor spawns workers, use `team-worker` agent with role-spec path:
// Completion action
const action = request_user_input({
```
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <session-folder>/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
---
## Completion Action
When pipeline completes (all tasks done), executor presents an interactive choice:
```
request_user_input({
questions: [{
question: "Team pipeline complete. Choose next action.",
header: "Done",
id: "completion",
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive (Recommended)", description: "Archive session, clean up team" },
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Export Results", description: "Export deliverables to target directory, then clean" }
]
}]
})
// Handle completion action
if (action.answers.completion.answers[0] === "Archive (Recommended)") {
// Update session status, cleanup team
} else if (action === "Keep Active") {
// Update session status to paused
} else if (action === "Export Results") {
// Ask for target path, copy artifacts, then archive
}
```
**Success Criteria**:
- results.csv exported (all tasks, both modes)
- context.md generated
- All interactive agents closed (registry.json cleanup)
- Summary displayed to user
- Completion action executed
### Action Handlers
| Choice | Steps |
|--------|-------|
| Archive & Clean | Update session status="completed" -> output final summary with artifact paths |
| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-executor', args='--session=<path>')" |
| Export Results | request_user_input(target path) -> copy artifacts to target -> Archive & Clean |
---
## Shared Discovery Board Protocol
## Integration with team-coordinate
**Discovery Types**:
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `implementation` | `file+function` | `{file, function, approach, notes}` | Implementation approach taken |
| `test_result` | `test_name` | `{test_name, status, duration}` | Test execution result |
| `review_comment` | `file+line` | `{file, line, severity, comment}` | Code review comment |
| `pattern` | `pattern_name` | `{pattern, files[], occurrences}` | Code pattern identified |
**Discovery NDJSON Format**:
```jsonl
{"ts":"2026-03-08T14:30:22Z","worker":"1","type":"implementation","data":{"file":"src/auth.ts","function":"login","approach":"JWT-based","notes":"Used bcrypt for password hashing"}}
{"ts":"2026-03-08T14:35:10Z","worker":"2","type":"test_result","data":{"test_name":"auth.login.success","status":"pass","duration":125}}
{"ts":"2026-03-08T14:40:05Z","worker":"3","type":"review_comment","data":{"file":"src/auth.ts","line":42,"severity":"medium","comment":"Consider adding rate limiting"}}
```
> Both csv-wave and interactive agents read/write the same discoveries.ndjson file.
| Scenario | Skill |
|----------|-------|
| New task, no session | team-coordinate |
| Existing session, resume execution | **team-executor** |
| Session needs new roles | team-coordinate (with resume) |
| Pure execution, no analysis | **team-executor** |
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Scenario | Resolution |
|----------|------------|
| No --session provided | ERROR immediately with usage message |
| Session directory not found | ERROR with path, suggest checking path |
| team-session.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
@@ -449,67 +187,5 @@ if (action.answers.completion.answers[0] === "Archive (Recommended)") {
| No role-specs in session | ERROR, session incomplete, suggest re-run team-coordinate |
| Role-spec file not found | ERROR with expected path |
| capability_gap reported | Warn only, cannot generate new role-specs |
| 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 |
| 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 |
| Fast-advance spawns wrong task | Executor reconciles on next callback |
| Completion action fails | Default to Keep Active, log warning |
---
## Core Rules
1. **Start Immediately**: First action is session validation, then Phase 0/1
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 role inner_loop=true
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
---
## Coordinator Role Constraints (Main Agent)
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns

62
.codex/skills/team-executor/instructions/agent-instruction.md
View File

@@ -1,62 +0,0 @@
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS
1. Read role definition: {role_spec_path} (MUST read first)
2. Read shared discoveries: {session_folder}/discoveries.ndjson (if exists, skip if not)
3. Read project context: .workflow/project-tech.json (if exists)
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Description**: {description}
**Role**: {role}
### Previous Tasks' Findings (Context)
{prev_context}
---
## Execution Protocol
1. **Read role definition**: Load {role_spec_path} for Phase 2-4 domain instructions (MANDATORY)
2. **Read discoveries**: Load {session_folder}/discoveries.ndjson for shared exploration findings
3. **Use context**: Apply previous tasks' findings from prev_context above
4. **Execute**: Follow the role-specific instructions from your role definition file
5. **Share discoveries**: Append exploration findings to shared board:
```bash
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> {session_folder}/discoveries.ndjson
```
6. **Report result**: Return JSON via report_agent_job_result
### Role Definition Structure
Your role definition file contains:
- **Phase 2**: Context & scope resolution
- **Phase 3**: Execution steps
- **Phase 4**: Output generation
Follow the phases in order as defined in your role file.
### Discovery Types to Share
- `implementation`: {file, function, approach, notes} — Implementation approach taken
- `test_result`: {test_name, status, duration} — Test execution result
- `review_comment`: {file, line, severity, comment} — Code review comment
- `pattern`: {pattern, files[], occurrences} — Code pattern identified
---
## Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key discoveries and implementation notes (max 500 chars)",
"error": ""
}
**Findings format**: Concise summary of what was accomplished, key decisions made, and any important notes for downstream tasks.

280
.codex/skills/team-executor/roles/executor/commands/monitor.md Normal file
View File

@@ -0,0 +1,280 @@
# Command: monitor
## Purpose
Synchronous pipeline coordination using spawn_agent + wait_agent for team-executor v2. Role names are read from `tasks.json#roles`. Workers are spawned as `team_worker` agents with role-spec paths. **handleAdapt is LIMITED**: only warns, cannot generate new role-specs. Includes `handleComplete` for pipeline completion action.
## Constants
| Constant | Value | Description |
|----------|-------|-------------|
| WORKER_AGENT | team_worker | All workers spawned via spawn_agent |
| ONE_STEP_PER_INVOCATION | false | Synchronous wait loop |
| FAST_ADVANCE_AWARE | true | Workers may skip executor for simple linear successors |
| ROLE_GENERATION | disabled | handleAdapt cannot generate new role-specs |
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session file | `<session-folder>/tasks.json` | Yes |
| Active agents | tasks.json active_agents | Yes |
| Role registry | tasks.json roles[] | Yes |
**Dynamic role resolution**: Known worker roles are loaded from `tasks.json roles[].name`. Role-spec paths are in `tasks.json roles[].role_spec`.
## Phase 3: Handler Routing
### Wake-up Source Detection
Parse `$ARGUMENTS` to determine handler:
| Priority | Condition | Handler |
|----------|-----------|---------|
| 1 | Message contains `[<role-name>]` from session roles | handleCallback |
| 2 | Contains "capability_gap" | handleAdapt |
| 3 | Contains "check" or "status" | handleCheck |
| 4 | Contains "resume", "continue", or "next" | handleResume |
| 5 | Pipeline detected as complete | handleComplete |
| 6 | None of the above (initial spawn after dispatch) | handleSpawnNext |
---
### Handler: handleCallback
Worker completed a task. Verify completion, update state, auto-advance.
```
Receive callback from [<role>]
+- Find matching active agent by role (from tasks.json roles)
+- Is this a progress update (not final)?
| +- YES -> Update tasks.json state, do NOT remove from active_agents -> STOP
+- Task status = completed?
| +- YES -> close_agent, remove from active_agents -> update tasks.json
| | +- -> handleSpawnNext
| +- NO -> progress message, do not advance -> STOP
+- No matching agent found
+- Scan all active agents for completed tasks
+- Found completed -> process each -> handleSpawnNext
+- None completed -> STOP
```
**Fast-advance note**: Check if expected next task is already `in_progress` (fast-advanced). If yes -> skip spawning, sync active_agents.
---
### Handler: handleCheck
Read-only status report. No pipeline advancement.
```
[executor] Pipeline Status
[executor] Progress: <completed>/<total> (<percent>%)
[executor] Execution Graph:
<visual representation with status icons>
done=completed >>>=running o=pending .=not created
[executor] Active agents:
> <subject> (<role>) - running <elapsed>
[executor] Ready to spawn: <subjects>
[executor] Commands: 'resume' to advance | 'check' to refresh
```
Then STOP.
---
### Handler: handleResume
Check active agent completion, process results, advance pipeline.
```
Load active_agents from tasks.json
+- No active agents -> handleSpawnNext
+- Has active agents -> check each:
+- status = completed -> mark done, close_agent, 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: handleSpawnNext
Find all ready tasks, spawn team_worker agents, wait for completion, process results.
```
Read tasks.json
+- completedTasks: status = completed
+- inProgressTasks: status = in_progress
+- readyTasks: pending + all deps in completedTasks
Ready tasks found?
+- NONE + work in progress -> report waiting -> STOP
+- NONE + nothing in progress -> PIPELINE_COMPLETE -> handleComplete
+- HAS ready tasks -> for each:
+- Is task owner an Inner Loop role AND already has active_agents?
| +- YES -> SKIP spawn (existing worker picks it up)
| +- NO -> normal spawn below
+- Update task status in tasks.json -> in_progress
+- team_msg log -> task_unblocked (session_id=<session-id>)
+- Spawn team_worker (see spawn tool call below)
+- Add to tasks.json active_agents
```
**Spawn worker tool call**:
```javascript
const agentId = spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: ${task.role}
role_spec: ${sessionFolder}/role-specs/${task.role}.md
session: ${sessionFolder}
session_id: ${sessionId}
team_name: ${teamName}
requirement: ${task.description}
inner_loop: ${hasInnerLoop(task.role)}` },
{ type: "text", text: `Read role_spec file (${sessionFolder}/role-specs/${task.role}.md) to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: ${taskId}
title: ${task.title}
description: ${task.description}` },
{ type: "text", text: `## Upstream Context\n${prevContext}` }
]
})
state.active_agents[taskId] = { agentId, role: task.role, started_at: now }
```
### Wait and Process Results
After spawning all ready tasks:
```javascript
// Batch wait for all spawned workers
const agentIds = Object.values(state.active_agents)
.filter(a => !a.resident)
.map(a => a.agentId)
wait_agent({ ids: agentIds, timeout_ms: 900000 })
// Collect results from discoveries/{task_id}.json
for (const [taskId, agent] of Object.entries(state.active_agents)) {
if (agent.resident) continue
try {
const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`))
state.tasks[taskId].status = disc.status || 'completed'
state.tasks[taskId].findings = disc.findings || ''
state.tasks[taskId].error = disc.error || null
} catch {
state.tasks[taskId].status = 'failed'
state.tasks[taskId].error = 'No discovery file produced'
}
close_agent({ id: agent.agentId })
delete state.active_agents[taskId]
}
```
### Persist and Loop
After processing all results:
1. Write updated tasks.json
2. Check if more tasks are now ready (deps newly resolved)
3. If yes -> loop back to step 1 of handleSpawnNext
4. If no more ready and all done -> handleComplete
5. If no more ready but some still blocked -> report status, STOP
---
### Handler: handleComplete
Pipeline complete. Execute completion action.
```
All tasks completed (no pending, no in_progress)
+- Generate pipeline summary (deliverables, stats, duration)
+- Read tasks.json completion_action:
|
+- "interactive":
| request_user_input -> user choice:
| +- "Archive & Clean": rm -rf session folder -> summary
| +- "Keep Active": session status="paused" -> resume command
| +- "Export Results": copy artifacts -> Archive & Clean
|
+- "auto_archive": Execute Archive & Clean
+- "auto_keep": Execute Keep Active
```
**Fallback**: If completion action fails, default to Keep Active, log warning.
---
### Handler: handleAdapt (LIMITED)
**UNLIKE team-coordinate, executor CANNOT generate new role-specs.**
```
Receive capability_gap from [<role>]
+- Log via team_msg (type: warning)
+- Check existing roles -> does any cover this?
| +- YES -> redirect to that role -> STOP
| +- NO -> genuine gap, report to user:
| "Capability gap detected. team-executor cannot generate new role-specs.
| Options: 1. Continue 2. Re-run team-coordinate 3. Manually add role-spec"
+- Continue execution with existing roles
```
---
### Worker Failure Handling
1. Reset task -> pending in tasks.json
2. Log via team_msg (type: error)
3. Report to user: task reset, will retry on next resume
### Fast-Advance Failure Recovery
Detect orphaned tasks (in_progress without active_agents, > 5 minutes) -> reset to pending -> handleSpawnNext.
### Consensus-Blocked Handling
```
Route by severity:
+- HIGH: Create REVISION task (max 1). Already revised -> PAUSE for user (request_user_input)
+- MEDIUM: Proceed with warning, log to wisdom/issues.md
+- LOW: Proceed normally as consensus_reached with notes
```
## Phase 4: Validation
| Check | Criteria |
|-------|----------|
| Session state consistent | active_agents matches tasks.json in_progress tasks |
| No orphaned tasks | Every in_progress task has an active_agents entry |
| Dynamic roles valid | All task owners exist in tasks.json roles |
| Completion detection | readyTasks=0 + inProgressTasks=0 -> PIPELINE_COMPLETE |
| Fast-advance tracking | Detect fast-advanced tasks, sync to active_agents |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Session file not found | Error, suggest re-run team-coordinate |
| Unknown role in callback | Log info, scan for other completions |
| All workers still running on resume | Report status, suggest check later |
| Pipeline stall | Check for missing tasks, report to user |
| Fast-advance conflict | Executor reconciles, no duplicate spawns |
| Role-spec file not found | Error, cannot proceed |
| capability_gap | WARN only, cannot generate new role-specs |
| Completion action fails | Default to Keep Active, log warning |

170
.codex/skills/team-executor/roles/executor/role.md Normal file
View File

@@ -0,0 +1,170 @@
# Executor Role
Orchestrate the team-executor workflow: session validation, state reconciliation, team_worker dispatch, progress monitoring, completion action. The sole built-in role -- all worker roles are loaded from session role-specs and spawned via team_worker agent.
## Identity
- **Name**: `executor` | **Tag**: `[executor]`
- **Responsibility**: Validate session -> Reconcile state -> Create session -> Dispatch team_worker agents -> Monitor progress -> Completion action -> Report results
## Boundaries
### MUST
- Validate session structure before any execution
- Reconcile session state with tasks.json on startup
- Reset in_progress tasks to pending (interrupted tasks)
- Detect fast-advance orphans and reset to pending
- Spawn team_worker agents via spawn_agent and wait via wait_agent
- Monitor progress via wait_agent and route messages
- Maintain session state persistence (tasks.json)
- Handle capability_gap reports with warning only (cannot generate role-specs)
- Execute completion action when pipeline finishes
### MUST NOT
- Execute task work directly (delegate to workers)
- Modify task output artifacts (workers own their deliverables)
- Call CLI tools or spawn utility members directly for implementation (code-developer, etc.)
- Generate new role-specs (use existing session role-specs only)
- Skip session validation
- Override consensus_blocked HIGH without user confirmation
- Spawn workers with `general-purpose` agent (MUST use `team_worker`)
> **Core principle**: executor is the orchestrator, not the executor. All actual work is delegated to session-defined worker roles via team_worker agents. Unlike team-coordinate coordinator, executor CANNOT generate new role-specs.
---
## Entry Router
When executor is invoked, first detect the invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Capability gap | Message contains "capability_gap" | -> handleAdapt |
| Pipeline complete | All tasks completed, no pending/in_progress | -> handleComplete |
| New execution | None of above | -> Phase 0 |
For check/resume/adapt/complete: load `commands/monitor.md` and execute the appropriate handler, then STOP.
---
## Phase 0: Session Validation + State Reconciliation
**Objective**: Validate session structure and reconcile session state with actual task status.
### Step 1: Session Validation
Validate session structure (see SKILL.md Session Validation):
- [ ] Directory exists at session path
- [ ] `tasks.json` exists and parses
- [ ] `task-analysis.json` exists and parses
- [ ] `role-specs/` directory has >= 1 .md files
- [ ] All roles in tasks.json#roles have corresponding role-spec .md files
- [ ] Role-spec files have valid YAML frontmatter + Phase 2-4 sections
If validation fails -> ERROR with specific reason -> STOP
### Step 2: Load Session State
Read tasks.json and task-analysis.json.
### Step 3: Reconcile with tasks.json
Compare tasks.json task statuses with session expectations, bidirectional sync.
### Step 4: Reset Interrupted Tasks
Reset any in_progress tasks to pending.
### Step 5: Detect Fast-Advance Orphans
In_progress tasks without matching active_agents + created > 5 minutes -> reset to pending.
### Step 6: Create Missing Tasks (if needed)
For each task in task-analysis, check if exists in tasks.json, create if missing.
### Step 7: Update Session File
Write reconciled tasks.json.
### Step 8: Session Setup
Initialize session folder if needed.
**Success**: Session validated, state reconciled, session ready -> Phase 1
---
## Phase 1: Spawn-and-Wait
**Objective**: Spawn first batch of ready workers as team_worker agents, wait for completion, then continue.
**Workflow**:
1. Load `commands/monitor.md`
2. Find tasks with: status=pending, deps all resolved, owner assigned
3. For each ready task -> spawn team_worker via spawn_agent, wait via wait_agent
4. Process results, advance pipeline
5. Repeat until all tasks complete or pipeline blocked
6. Output status summary with execution graph
**Pipeline advancement** driven by:
- Synchronous wait_agent loop (automatic)
- User "check" -> handleCheck (status only)
- User "resume" -> handleResume (advance)
---
## Phase 2: Report + Completion Action
**Objective**: Completion report, interactive completion choice, and follow-up options.
**Workflow**:
1. Load session state -> count completed tasks, duration
2. List all deliverables with output paths in `<session>/artifacts/`
3. Include discussion summaries (if inline discuss was used)
4. Summarize wisdom accumulated during execution
5. Output report:
```
[executor] ============================================
[executor] TASK COMPLETE
[executor]
[executor] Deliverables:
[executor] - <artifact-1.md> (<producer role>)
[executor] - <artifact-2.md> (<producer role>)
[executor]
[executor] Pipeline: <completed>/<total> tasks
[executor] Roles: <role-list>
[executor] Duration: <elapsed>
[executor]
[executor] Session: <session-folder>
[executor] ============================================
```
6. **Execute Completion Action** (based on tasks.json completion_action):
| Mode | Behavior |
|------|----------|
| `interactive` | request_user_input with Archive/Keep/Export options |
| `auto_archive` | Execute Archive & Clean (rm -rf session folder) without prompt |
| `auto_keep` | Execute Keep Active without prompt |
**Interactive handler**: See SKILL.md Completion Action section.
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Session validation fails | ERROR with specific reason, suggest re-run team-coordinate |
| Task timeout | Log, mark failed, ask user to retry or skip |
| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
| Session corruption | Attempt recovery, fallback to manual reconciliation |
| capability_gap reported | handleAdapt: WARN only, cannot generate new role-specs |
| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
| Fast-advance conflict | Executor reconciles, no duplicate spawns |
| Role-spec file not found | ERROR, cannot proceed without role definition |
| Completion action fails | Default to Keep Active, log warning |

141
.codex/skills/team-executor/schemas/tasks-schema.md
View File

@@ -1,141 +0,0 @@
# Team Executor — CSV Schema
## Master CSV: tasks.csv
### Column Definitions
#### Input Columns (Set by Decomposer)
| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `id` | string | Yes | Unique task identifier | `"1"` |
| `title` | string | Yes | Short task title | `"Implement auth module"` |
| `description` | string | Yes | Detailed task description (self-contained) | `"Create authentication module with JWT support"` |
| `deps` | string | No | Semicolon-separated dependency task IDs | `"1;2"` |
| `context_from` | string | No | Semicolon-separated task IDs for context | `"1"` |
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
| `role` | string | Yes | Role name from session role-specs | `"implementer"` |
#### 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) | `"[Task 1] Created auth module..."` |
#### 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 auth with bcrypt password hashing"` |
| `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,role,wave,status,findings,error
1,Implement auth module,Create authentication module with JWT,,,"csv-wave","implementer",1,pending,"",""
2,Write tests,Write unit tests for auth module,1,1,"csv-wave","tester",2,pending,"",""
3,Review code,Review implementation and tests,2,2,"interactive","reviewer",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)
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": "1",
"status": "completed",
"findings": "Implemented JWT authentication with bcrypt password hashing. Created login, logout, and token refresh endpoints. Added middleware for protected routes.",
"error": ""
}
```
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
---
## Discovery Types
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `implementation` | `file+function` | `{file, function, approach, notes}` | Implementation approach taken |
| `test_result` | `test_name` | `{test_name, status, duration}` | Test execution result |
| `review_comment` | `file+line` | `{file, line, severity, comment}` | Code review comment |
| `pattern` | `pattern_name` | `{pattern, files[], occurrences}` | Code pattern identified |
### Discovery NDJSON Format
```jsonl
{"ts":"2026-03-08T14:30:22Z","worker":"1","type":"implementation","data":{"file":"src/auth.ts","function":"login","approach":"JWT-based","notes":"Used bcrypt for password hashing"}}
{"ts":"2026-03-08T14:35:10Z","worker":"2","type":"test_result","data":{"test_name":"auth.login.success","status":"pass","duration":125}}
{"ts":"2026-03-08T14:40:05Z","worker":"3","type":"review_comment","data":{"file":"src/auth.ts","line":42,"severity":"medium","comment":"Consider adding rate limiting"}}
```
> 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 non-empty | Every task has role | "Empty role for task: {id}" |
| Role exists | Role has corresponding role-spec file | "Role not found: {role}" |

264
.codex/skills/team-executor/specs/session-schema.md Normal file
View File

@@ -0,0 +1,264 @@
# Session Schema
Required session structure for team-executor v2. All components MUST exist for valid execution. Updated for role-spec architecture (lightweight Phase 2-4 files instead of full role.md files).
## Directory Structure
```
<session-folder>/
+-- team-session.json # Session state + dynamic role registry (REQUIRED)
+-- task-analysis.json # Task analysis output: capabilities, dependency graph (REQUIRED)
+-- role-specs/ # Dynamic role-spec definitions (REQUIRED, >= 1 .md file)
| +-- <role-1>.md # Lightweight: YAML frontmatter + Phase 2-4 only
| +-- <role-2>.md
+-- artifacts/ # All MD deliverables from workers
| +-- <artifact>.md
+-- .msg/ # Team message bus + state
| +-- messages.jsonl # Message log
| +-- meta.json # Session metadata + cross-role state
+-- wisdom/ # Cross-task knowledge
| +-- learnings.md
| +-- decisions.md
| +-- issues.md
+-- explorations/ # Shared explore cache
| +-- cache-index.json
| +-- explore-<angle>.json
+-- discussions/ # Inline discuss records
| +-- <round>.md
```
## Validation Checklist
team-executor validates the following before execution:
### Required Components
| Component | Validation | Error Message |
|-----------|------------|---------------|
| `--session` argument | Must be provided | "Session required. Usage: --session=<path-to-TC-folder>" |
| Directory | Must exist at path | "Session directory not found: <path>" |
| `team-session.json` | Must exist, parse as JSON, and contain all required fields | "Invalid session: team-session.json missing, corrupt, or missing required fields" |
| `task-analysis.json` | Must exist, parse as JSON, and contain all required fields | "Invalid session: task-analysis.json missing, corrupt, or missing required fields" |
| `role-specs/` directory | Must exist and contain >= 1 .md file | "Invalid session: no role-spec files in role-specs/" |
| Role-spec file mapping | Each role in team-session.json#roles must have .md file | "Role-spec file not found: role-specs/<role>.md" |
| Role-spec structure | Each role-spec must have YAML frontmatter + Phase 2-4 sections | "Invalid role-spec: role-specs/<role>.md missing required section" |
### Validation Algorithm
```
1. Parse --session=<path> from arguments
+- Not provided -> ERROR: "Session required. Usage: --session=<path-to-TC-folder>"
2. Check directory exists
+- Not exists -> ERROR: "Session directory not found: <path>"
3. Check team-session.json
+- Not exists -> ERROR: "Invalid session: team-session.json missing"
+- Parse error -> ERROR: "Invalid session: team-session.json corrupt"
+- Validate required fields:
+- session_id (string) -> missing -> ERROR
+- task_description (string) -> missing -> ERROR
+- status (string: active|paused|completed) -> invalid -> ERROR
+- team_name (string) -> missing -> ERROR
+- roles (array, non-empty) -> missing/empty -> ERROR
4. Check task-analysis.json
+- Not exists -> ERROR: "Invalid session: task-analysis.json missing"
+- Parse error -> ERROR: "Invalid session: task-analysis.json corrupt"
+- Validate required fields:
+- capabilities (array) -> missing -> ERROR
+- dependency_graph (object) -> missing -> ERROR
+- roles (array, non-empty) -> missing/empty -> ERROR
5. Check role-specs/ directory
+- Not exists -> ERROR: "Invalid session: role-specs/ directory missing"
+- No .md files -> ERROR: "Invalid session: no role-spec files in role-specs/"
6. Check role-spec file mapping and structure
+- For each role in team-session.json#roles:
+- Check role-specs/<role.name>.md exists
+- Not exists -> ERROR: "Role-spec file not found: role-specs/<role.name>.md"
+- Validate role-spec structure (see Role-Spec Structure Validation)
7. All checks pass -> proceed to Phase 0
```
---
## team-session.json Schema
```json
{
"session_id": "TC-<slug>-<date>",
"task_description": "<original user input>",
"status": "active | paused | completed",
"team_name": "<team-name>",
"roles": [
{
"name": "<role-name>",
"prefix": "<PREFIX>",
"responsibility_type": "<type>",
"inner_loop": false,
"role_spec": "role-specs/<role-name>.md"
}
],
"pipeline": {
"dependency_graph": {},
"tasks_total": 0,
"tasks_completed": 0
},
"active_workers": [],
"completed_tasks": [],
"completion_action": "interactive",
"created_at": "<timestamp>"
}
```
### Required Fields
| Field | Type | Description |
|-------|------|-------------|
| `session_id` | string | Unique session identifier |
| `task_description` | string | Original task description from user |
| `status` | string | One of: "active", "paused", "completed" |
| `team_name` | string | Team name for Agent tool |
| `roles` | array | List of role definitions |
| `roles[].name` | string | Role name (must match .md filename) |
| `roles[].prefix` | string | Task prefix for this role |
| `roles[].role_spec` | string | Relative path to role-spec file |
### Optional Fields
| Field | Type | Description |
|-------|------|-------------|
| `pipeline` | object | Pipeline metadata |
| `active_workers` | array | Currently running workers |
| `completed_tasks` | array | List of completed task IDs |
| `completion_action` | string | Completion mode: interactive, auto_archive, auto_keep |
| `created_at` | string | ISO timestamp |
---
## task-analysis.json Schema
```json
{
"capabilities": [
{
"name": "<capability-name>",
"description": "<description>",
"artifact_type": "<type>"
}
],
"dependency_graph": {
"<task-id>": {
"depends_on": ["<dependency-task-id>"],
"role": "<role-name>"
}
},
"roles": [
{
"name": "<role-name>",
"prefix": "<PREFIX>",
"responsibility_type": "<type>",
"inner_loop": false,
"role_spec_metadata": {
"additional_members": [],
"message_types": {
"success": "<prefix>_complete",
"error": "error"
}
}
}
],
"complexity_score": 0
}
```
---
## Role-Spec File Schema
Each role-spec in `role-specs/<role-name>.md` follows the lightweight format with YAML frontmatter + Phase 2-4 body.
### Required Structure
```markdown
---
role: <name>
prefix: <PREFIX>
inner_loop: <true|false>
message_types:
success: <type>
error: error
---
# <Role Name> — Phase 2-4
## Phase 2: <Name>
<domain-specific context loading>
## Phase 3: <Name>
<domain-specific execution>
## Phase 4: <Name>
<domain-specific validation>
```
### Role-Spec Structure Validation
```
For each role-spec in role-specs/<role>.md:
1. Read file content
2. Check for YAML frontmatter (content between --- markers)
+- Not found -> ERROR: "Invalid role-spec: role-specs/<role>.md missing frontmatter"
3. Parse frontmatter, check required fields:
+- role (string) -> missing -> ERROR
+- prefix (string) -> missing -> ERROR
+- inner_loop (boolean) -> missing -> ERROR
+- message_types (object) -> missing -> ERROR
4. Check for "## Phase 2" section
+- Not found -> ERROR: "Invalid role-spec: missing Phase 2"
5. Check for "## Phase 3" section
+- Not found -> ERROR: "Invalid role-spec: missing Phase 3"
6. Check for "## Phase 4" section
+- Not found -> ERROR: "Invalid role-spec: missing Phase 4"
7. All checks pass -> role-spec valid
```
---
## Example Valid Session
```
.workflow/.team/TC-auth-feature-2026-02-27/
+-- team-session.json # Valid JSON with session metadata
+-- task-analysis.json # Valid JSON with dependency graph
+-- role-specs/
| +-- researcher.md # YAML frontmatter + Phase 2-4
| +-- developer.md # YAML frontmatter + Phase 2-4
| +-- tester.md # YAML frontmatter + Phase 2-4
+-- artifacts/ # (may be empty)
+-- .msg/ # Team message bus + state (messages.jsonl + meta.json)
+-- wisdom/
| +-- learnings.md
| +-- decisions.md
| +-- issues.md
+-- explorations/
| +-- cache-index.json
+-- discussions/ # (may be empty)
```
---
## Recovery from Invalid Sessions
If session validation fails:
1. **Missing team-session.json**: Re-run team-coordinate with original task
2. **Missing task-analysis.json**: Re-run team-coordinate with resume
3. **Missing role-spec files**: Re-run team-coordinate with resume
4. **Invalid frontmatter**: Manual fix or re-run team-coordinate
5. **Corrupt JSON**: Manual inspection or re-run team-coordinate
**team-executor cannot fix invalid sessions** -- it can only report errors and suggest recovery steps.

878
.codex/skills/team-frontend-debug/SKILL.md
View File

@@ -1,183 +1,85 @@
---
name: team-frontend-debug
description: Frontend debugging team using Chrome DevTools MCP. Dual-mode -- feature-list testing or bug-report debugging. Covers reproduction, root cause analysis, code fixes, and verification. CSV wave pipeline with conditional skip and iteration loops.
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"feature list or bug description\""
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
description: Frontend debugging team using Chrome DevTools MCP. Dual-mode — feature-list testing or bug-report debugging. Triggers on "team-frontend-debug", "frontend debug".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__chrome-devtools__*(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
# Frontend Debug Team
## Usage
Dual-mode frontend debugging: feature-list testing or bug-report debugging, powered by Chrome DevTools MCP.
```bash
$team-frontend-debug "Test features: login, dashboard, user profile at localhost:3000"
$team-frontend-debug "Bug: clicking save button on /settings causes white screen"
$team-frontend-debug -y "Test: 1. User registration 2. Email verification 3. Password reset"
$team-frontend-debug --continue "tfd-login-bug-20260308"
```
**Flags**:
- `-y, --yes`: Skip all confirmations (auto mode)
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 2)
- `--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
Dual-mode frontend debugging: feature-list testing or bug-report debugging, powered by Chrome DevTools MCP. Roles: tester (test-pipeline), reproducer (debug-pipeline), analyzer, fixer, verifier. Supports conditional skip (all tests pass -> no downstream tasks), iteration loops (analyzer requesting more evidence, verifier triggering re-fix), and Chrome DevTools-based browser interaction.
**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
## Architecture
```
+-------------------------------------------------------------------+
| FRONTEND DEBUG WORKFLOW |
+-------------------------------------------------------------------+
| |
| Phase 0: Pre-Wave Interactive (Input Analysis) |
| +- Parse user input (feature list or bug report) |
| +- Detect mode: test-pipeline or debug-pipeline |
| +- Extract: base URL, features/steps, evidence plan |
| +- Output: refined requirements for decomposition |
| |
| Phase 1: Requirement -> CSV + Classification |
| +- Select pipeline (test or debug) |
| +- Build dependency graph from pipeline definition |
| +- Classify tasks: csv-wave | interactive (exec_mode) |
| +- Compute dependency waves (topological sort) |
| +- 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 (if any) |
| | +- 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 (if any) |
| | +- Merge all results into master tasks.csv |
| | +- Conditional skip: TEST-001 with 0 issues -> done |
| | +- Iteration: ANALYZE needs more evidence -> REPRODUCE-002 |
| | +- Re-fix: VERIFY fails -> FIX-002 -> VERIFY-002 |
| +- discoveries.ndjson shared across all modes (append-only) |
| |
| Phase 3: Post-Wave Interactive (Completion Action) |
| +- Pipeline completion report with debug summary |
| +- Interactive completion choice (Archive/Keep/Export) |
| +- Final aggregation / report |
| |
| Phase 4: 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 |
| |
+-------------------------------------------------------------------+
Skill(skill="team-frontend-debug", args="feature list or bug description")
|
SKILL.md (this file) = Router
|
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-- analyze input → select pipeline → dispatch → spawn → STOP
|
┌──────────────────────────┼──────────────────────┐
v v v
[test-pipeline] [debug-pipeline] [shared]
tester(DevTools) reproducer(DevTools) analyzer
fixer
verifier
```
---
## Pipeline Modes
| Input Pattern | Pipeline | Flow |
|---------------|----------|------|
| Feature list / function checklist / test items | `test-pipeline` | TEST -> ANALYZE -> FIX -> VERIFY |
| Bug report / error description / crash report | `debug-pipeline` | REPRODUCE -> ANALYZE -> FIX -> VERIFY |
| Input | Pipeline | Flow |
|-------|----------|------|
| Feature list / 功能清单 | `test-pipeline` | TEST → ANALYZE → FIX → VERIFY |
| Bug report / 错误描述 | `debug-pipeline` | REPRODUCE → ANALYZE → FIX → VERIFY |
### Pipeline Selection Keywords
## Role Registry
| Keywords | Pipeline |
|----------|----------|
| feature, test, list, check, verify functions, validate | `test-pipeline` |
| bug, error, crash, broken, white screen, not working | `debug-pipeline` |
| performance, slow, latency, memory leak | `debug-pipeline` (perf dimension) |
| Ambiguous / unclear | request_user_input to clarify |
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | true |
| reproducer | [roles/reproducer/role.md](roles/reproducer/role.md) | REPRODUCE-* | false |
| analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false |
| fixer | [roles/fixer/role.md](roles/fixer/role.md) | FIX-* | true |
| verifier | [roles/verifier/role.md](roles/verifier/role.md) | VERIFY-* | false |
---
## Role Router
## Task Classification Rules
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → `roles/coordinator/role.md`, execute entry router
Each task is classified by `exec_mode`:
## Shared Constants
| 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, progress updates, inner loop |
- **Session prefix**: `TFD`
- **Session path**: `.workflow/.team/TFD-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
**Classification Decision**:
## Workspace Resolution
| Task Property | Classification |
|---------------|---------------|
| Feature testing with inner loop (tester iterates over features) | `csv-wave` |
| Bug reproduction (single pass) | `csv-wave` |
| Root cause analysis (single pass) | `csv-wave` |
| Code fix implementation | `csv-wave` |
| Fix verification (single pass) | `csv-wave` |
| Conditional skip gate (evaluating TEST results) | `interactive` |
| Pipeline completion action | `interactive` |
Coordinator MUST resolve paths at Phase 2 before spawning workers:
---
1. Run `Bash({ command: "pwd" })` → capture `project_root` (absolute path)
2. `skill_root = <project_root>/.claude/skills/team-frontend-debug`
3. Store in `team-session.json`:
```json
{ "project_root": "/abs/path/to/project", "skill_root": "/abs/path/to/skill" }
```
4. All worker `role_spec` values MUST use `<skill_root>/roles/<role>/role.md` (absolute)
## CSV Schema
### tasks.csv (Master State)
```csv
id,title,description,role,pipeline_mode,base_url,evidence_dimensions,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,issues_count,verdict,error
"TEST-001","Feature testing","PURPOSE: Test all features from list | Success: All features tested with evidence","tester","test-pipeline","http://localhost:3000","screenshot;console;network","","","csv-wave","1","pending","","","","",""
"ANALYZE-001","Root cause analysis","PURPOSE: Analyze discovered issues | Success: RCA for each issue","analyzer","test-pipeline","","console;network","TEST-001","TEST-001","csv-wave","2","pending","","","","",""
```
**Columns**:
| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (PREFIX-NNN: TEST, REPRODUCE, ANALYZE, FIX, VERIFY) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS |
| `role` | Input | Role name: `tester`, `reproducer`, `analyzer`, `fixer`, `verifier` |
| `pipeline_mode` | Input | Pipeline: `test-pipeline` or `debug-pipeline` |
| `base_url` | Input | Target URL for browser-based tasks (empty for non-browser tasks) |
| `evidence_dimensions` | Input | Semicolon-separated evidence types: `screenshot`, `console`, `network`, `snapshot`, `performance` |
| `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` |
| `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) |
| `artifacts_produced` | Output | Semicolon-separated paths of produced artifacts |
| `issues_count` | Output | Number of issues found (tester/analyzer), empty for others |
| `verdict` | Output | Verification verdict: `pass`, `pass_with_warnings`, `fail` (verifier only) |
| `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 |
|-------|-----------|---------|----------------|----------|
| Conditional Skip Gate | agents/conditional-skip-gate.md | 2.3 (send_input cycle) | Evaluate TEST results and skip downstream if no issues | post-wave |
| Iteration Handler | agents/iteration-handler.md | 2.3 (send_input cycle) | Handle analyzer's need_more_evidence request | post-wave |
| Completion Handler | agents/completion-handler.md | 2.3 (send_input cycle) | Handle pipeline completion action (Archive/Keep/Export) | standalone |
> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.
---
This ensures workers always receive an absolute, resolvable path regardless of their working directory.
## Chrome DevTools MCP Tools
All browser inspection operations use Chrome DevTools MCP. Tester, reproducer, and verifier are primary consumers. These tools are available to CSV wave agents.
All browser inspection operations use Chrome DevTools MCP. Reproducer and Verifier are primary consumers.
| Tool | Purpose |
|------|---------|
@@ -197,625 +99,93 @@ All browser inspection operations use Chrome DevTools MCP. Tester, reproducer, a
| `mcp__chrome-devtools__wait_for` | Wait for element/text |
| `mcp__chrome-devtools__list_pages` | List open browser tabs |
| `mcp__chrome-devtools__select_page` | Switch active tab |
| `mcp__chrome-devtools__press_key` | Press keyboard keys |
---
## Worker Spawn Template
## 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 4 |
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
| `context.md` | Human-readable execution report | Created in Phase 4 |
| `task-analysis.json` | Phase 0/1 output: mode, features/steps, dimensions | Created in Phase 1 |
| `role-instructions/` | Per-role instruction templates for CSV agents | Created in Phase 1 |
| `artifacts/` | All deliverables: test reports, RCA reports, fix changes, verification reports | Created by agents |
| `evidence/` | Screenshots, snapshots, network logs, performance traces | Created by tester/reproducer/verifier |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
---
## Session Structure
Coordinator spawns workers using this template:
```
.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
+-- task-analysis.json # Phase 1 analysis output
+-- wave-{N}.csv # Temporary per-wave input (csv-wave only)
+-- role-instructions/ # Per-role instruction templates
| +-- tester.md # (test-pipeline)
| +-- reproducer.md # (debug-pipeline)
| +-- analyzer.md
| +-- fixer.md
| +-- verifier.md
+-- artifacts/ # All deliverables
| +-- TEST-001-report.md
| +-- TEST-001-issues.json
| +-- ANALYZE-001-rca.md
| +-- FIX-001-changes.md
| +-- VERIFY-001-report.md
+-- evidence/ # Browser evidence
| +-- F-001-login-before.png
| +-- F-001-login-after.png
| +-- before-screenshot.png
| +-- after-screenshot.png
| +-- before-snapshot.txt
| +-- after-snapshot.txt
| +-- evidence-summary.json
+-- interactive/ # Interactive task artifacts
| +-- {id}-result.json
+-- wisdom/ # Cross-task knowledge
+-- learnings.md
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
---
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
## Implementation
## User Commands
### Session Initialization
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph |
| `resume` / `continue` | Advance to next step |
| `revise <TASK-ID> [feedback]` | Revise specific task |
| `feedback <text>` | Inject feedback for revision |
| `retry <TASK-ID>` | Re-run a failed task |
```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
## Completion Action
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 2
When pipeline completes, coordinator presents:
const requirement = $ARGUMENTS
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
.trim()
const slug = requirement.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = `tfd-${slug}-${dateStr}`
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
Bash(`mkdir -p ${sessionFolder}/artifacts ${sessionFolder}/evidence ${sessionFolder}/role-instructions ${sessionFolder}/interactive ${sessionFolder}/wisdom`)
Write(`${sessionFolder}/discoveries.ndjson`, '')
Write(`${sessionFolder}/wisdom/learnings.md`, '# Debug Learnings\n')
```
request_user_input({
questions: [{
question: "Pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up" },
{ label: "Keep Active", description: "Keep session for follow-up debugging" },
{ label: "Export Results", description: "Export debug report and patches" }
]
}]
})
```
---
## Specs Reference
### Phase 0: Pre-Wave Interactive (Input Analysis)
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
- [specs/debug-tools.md](specs/debug-tools.md) — Chrome DevTools MCP usage patterns and evidence collection
**Objective**: Parse user input, detect mode (test vs debug), extract parameters.
## Session Directory
**Workflow**:
1. **Parse user input** from $ARGUMENTS
2. **Check for existing sessions** (continue mode):
- Scan `.workflow/.csv-wave/tfd-*/tasks.csv` for sessions with pending tasks
- If `--continue`: resume the specified or most recent session, skip to Phase 2
3. **Detect mode**:
| Input Pattern | Mode |
|---------------|------|
| Contains: feature, test, list, check, verify | `test-pipeline` |
| Contains: bug, error, crash, broken, not working | `debug-pipeline` |
| Ambiguous | request_user_input to clarify |
4. **Extract parameters by mode**:
**Test Mode**:
- `base_url`: URL in text or request_user_input
- `features`: Parse feature list (bullet points, numbered list, free text)
- Generate structured feature items with id, name, url
**Debug Mode**:
- `bug_description`: Bug description text
- `target_url`: URL in text or request_user_input
- `reproduction_steps`: Steps in text or request_user_input
- `evidence_plan`: Detect dimensions from keywords (UI, network, console, performance)
5. **Dimension Detection** (debug mode):
| Keywords | Dimension |
|----------|-----------|
| render, style, display, layout, CSS | screenshot, snapshot |
| request, API, network, timeout | network |
| error, crash, exception | console |
| slow, performance, lag, memory | performance |
| interaction, click, input, form | screenshot, console |
**Success Criteria**:
- Mode determined (test-pipeline or debug-pipeline)
- Base URL and features/steps extracted
- Evidence dimensions identified
---
### Phase 1: Requirement -> CSV + Classification
**Objective**: Build task dependency graph, generate tasks.csv and per-role instruction templates.
**Decomposition Rules**:
1. **Pipeline Definition**:
**Test Pipeline** (4 tasks, conditional):
```
TEST-001 -> [issues?] -> ANALYZE-001 -> FIX-001 -> VERIFY-001
|
+-- no issues -> Pipeline Complete (skip downstream)
```
**Debug Pipeline** (4 tasks, linear with iteration):
```
REPRODUCE-001 -> ANALYZE-001 -> FIX-001 -> VERIFY-001
^ |
| (if fail) |
+--- REPRODUCE-002 <-----+
```
2. **Task Description Template**: Every task uses PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS format with session path, base URL, and upstream artifact references
3. **Role Instruction Generation**: Write per-role instruction templates to `role-instructions/{role}.md` using the base instruction template customized for each role
**Classification Rules**:
| Task Property | exec_mode |
|---------------|-----------|
| Feature testing (tester with inner loop) | `csv-wave` |
| Bug reproduction (single pass) | `csv-wave` |
| Root cause analysis (single pass) | `csv-wave` |
| Code fix (may need multiple passes) | `csv-wave` |
| Fix verification (single pass) | `csv-wave` |
| All standard pipeline tasks | `csv-wave` |
**Wave Computation**: Kahn's BFS topological sort with depth tracking.
```javascript
// Generate per-role instruction templates
const roles = pipelineMode === 'test-pipeline'
? ['tester', 'analyzer', 'fixer', 'verifier']
: ['reproducer', 'analyzer', 'fixer', 'verifier']
for (const role of roles) {
const instruction = generateRoleInstruction(role, sessionFolder, pipelineMode)
Write(`${sessionFolder}/role-instructions/${role}.md`, instruction)
}
const tasks = buildTasksCsv(pipelineMode, requirement, sessionFolder, baseUrl, evidencePlan)
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
Write(`${sessionFolder}/task-analysis.json`, JSON.stringify(analysisResult, null, 2))
```
**User Validation**: Display task breakdown (skip if AUTO_YES).
**Success Criteria**:
- tasks.csv created with valid schema and wave assignments
- Role instruction templates generated
- task-analysis.json written
- No circular dependencies
---
### Phase 2: Wave Execution Engine (Extended)
**Objective**: Execute tasks wave-by-wave with conditional skip, iteration loops, and re-fix cycles.
```javascript
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
let maxWave = Math.max(...tasks.map(t => t.wave))
let fixRound = 0
const MAX_FIX_ROUNDS = 3
const MAX_REPRODUCE_ROUNDS = 2
for (let wave = 1; wave <= maxWave; wave++) {
console.log(`\nWave ${wave}/${maxWave}`)
const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
// Check dependencies -- skip tasks whose deps failed
for (const task of waveTasks) {
const depIds = (task.deps || '').split(';').filter(Boolean)
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
task.status = 'skipped'
task.error = `Dependency failed: ${depIds.filter((id, i) =>
['failed','skipped'].includes(depStatuses[i])).join(', ')}`
}
}
// Execute pre-wave interactive tasks (if any)
for (const task of interactiveTasks.filter(t => t.status === 'pending')) {
// Determine agent file based on task type
const agentFile = task.id.includes('skip') ? 'agents/conditional-skip-gate.md'
: task.id.includes('iter') ? 'agents/iteration-handler.md'
: 'agents/completion-handler.md'
Read(agentFile)
const agent = spawn_agent({
message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: ${agentFile}\n2. Read: ${sessionFolder}/discoveries.ndjson\n\nGoal: ${task.description}\nSession: ${sessionFolder}\n\n### Previous Context\n${buildPrevContext(task, tasks)}`
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
if (result.timed_out) {
send_input({ id: agent, message: "Please finalize and output current findings." })
wait({ ids: [agent], timeout_ms: 120000 })
}
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
task_id: task.id, status: "completed", findings: parseFindings(result),
timestamp: getUtc8ISOString()
}))
close_agent({ id: agent })
task.status = 'completed'
task.findings = parseFindings(result)
}
// Build prev_context for csv-wave tasks
const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
for (const task of pendingCsvTasks) {
task.prev_context = buildPrevContext(task, tasks)
}
if (pendingCsvTasks.length > 0) {
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))
const waveInstruction = buildWaveInstruction(pendingCsvTasks, sessionFolder, wave)
spawn_agents_on_csv({
csv_path: `${sessionFolder}/wave-${wave}.csv`,
id_column: "id",
instruction: waveInstruction,
max_concurrency: maxConcurrency,
max_runtime_seconds: 1200,
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
artifacts_produced: { type: "string" },
issues_count: { type: "string" },
verdict: { type: "string" },
error: { type: "string" }
}
}
})
// Merge results into master CSV
const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
for (const r of results) {
const t = tasks.find(t => t.id === r.id)
if (t) Object.assign(t, r)
}
// Conditional Skip: TEST-001 with 0 issues
const testResult = results.find(r => r.id === 'TEST-001')
if (testResult && parseInt(testResult.issues_count || '0') === 0) {
// Skip all downstream tasks
tasks.filter(t => t.wave > wave && t.status === 'pending').forEach(t => {
t.status = 'skipped'
t.error = 'No issues found in testing -- skipped'
})
console.log('All features passed. No issues found. Pipeline complete.')
}
// Iteration: Analyzer needs more evidence
const analyzerResult = results.find(r => r.id.startsWith('ANALYZE') && r.findings?.includes('need_more_evidence'))
if (analyzerResult) {
const reproduceRound = tasks.filter(t => t.id.startsWith('REPRODUCE')).length
if (reproduceRound < MAX_REPRODUCE_ROUNDS) {
const newRepId = `REPRODUCE-${String(reproduceRound + 1).padStart(3, '0')}`
const newAnalyzeId = `ANALYZE-${String(tasks.filter(t => t.id.startsWith('ANALYZE')).length + 1).padStart(3, '0')}`
tasks.push({
id: newRepId, title: 'Supplemental evidence collection',
description: `PURPOSE: Collect additional evidence per Analyzer request | Success: Targeted evidence collected`,
role: 'reproducer', pipeline_mode: tasks[0].pipeline_mode,
base_url: tasks[0].base_url, evidence_dimensions: tasks[0].evidence_dimensions,
deps: '', context_from: analyzerResult.id,
exec_mode: 'csv-wave', wave: wave + 1, status: 'pending',
findings: '', artifacts_produced: '', issues_count: '', verdict: '', error: ''
})
tasks.push({
id: newAnalyzeId, title: 'Re-analysis with supplemental evidence',
description: `PURPOSE: Re-analyze with additional evidence | Success: Higher-confidence RCA`,
role: 'analyzer', pipeline_mode: tasks[0].pipeline_mode,
base_url: '', evidence_dimensions: '',
deps: newRepId, context_from: `${analyzerResult.id};${newRepId}`,
exec_mode: 'csv-wave', wave: wave + 2, status: 'pending',
findings: '', artifacts_produced: '', issues_count: '', verdict: '', error: ''
})
// Update FIX task deps
const fixTask = tasks.find(t => t.id === 'FIX-001' && t.status === 'pending')
if (fixTask) fixTask.deps = newAnalyzeId
}
}
// Re-fix: Verifier verdict = fail
const verifyResult = results.find(r => r.id.startsWith('VERIFY') && r.verdict === 'fail')
if (verifyResult && fixRound < MAX_FIX_ROUNDS) {
fixRound++
const newFixId = `FIX-${String(fixRound + 1).padStart(3, '0')}`
const newVerifyId = `VERIFY-${String(fixRound + 1).padStart(3, '0')}`
tasks.push({
id: newFixId, title: `Re-fix (round ${fixRound + 1})`,
description: `PURPOSE: Re-fix based on verification failure | Success: Issue resolved`,
role: 'fixer', pipeline_mode: tasks[0].pipeline_mode,
base_url: '', evidence_dimensions: '',
deps: verifyResult.id, context_from: verifyResult.id,
exec_mode: 'csv-wave', wave: wave + 1, status: 'pending',
findings: '', artifacts_produced: '', issues_count: '', verdict: '', error: ''
})
tasks.push({
id: newVerifyId, title: `Re-verify (round ${fixRound + 1})`,
description: `PURPOSE: Re-verify after fix | Success: Bug resolved`,
role: 'verifier', pipeline_mode: tasks[0].pipeline_mode,
base_url: tasks[0].base_url, evidence_dimensions: tasks[0].evidence_dimensions,
deps: newFixId, context_from: newFixId,
exec_mode: 'csv-wave', wave: wave + 2, status: 'pending',
findings: '', artifacts_produced: '', issues_count: '', verdict: '', error: ''
})
}
}
// Update master CSV
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
// Cleanup temp files
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
// Recalculate maxWave (may have grown from iteration/re-fix)
maxWave = Math.max(maxWave, ...tasks.map(t => t.wave))
// Display wave summary
const completed = waveTasks.filter(t => t.status === 'completed').length
const failed = waveTasks.filter(t => t.status === 'failed').length
const skipped = waveTasks.filter(t => t.status === 'skipped').length
console.log(`Wave ${wave} Complete: ${completed} completed, ${failed} failed, ${skipped} skipped`)
}
.workflow/.team/TFD-<slug>-<date>/
├── team-session.json # Session state + role registry
├── evidence/ # Screenshots, snapshots, network logs
├── artifacts/ # Test reports, RCA reports, patches, verification reports
├── wisdom/ # Cross-task debug knowledge
└── .msg/ # Team message bus
```
**Success Criteria**:
- All waves executed in order
- Conditional skip handled (TEST with 0 issues)
- Iteration loops handled (analyzer need_more_evidence)
- Re-fix cycles handled (verifier fail verdict)
- discoveries.ndjson accumulated across all waves
- Max iteration/fix bounds respected
---
### Phase 3: Post-Wave Interactive (Completion Action)
**Objective**: Pipeline completion report with debug summary.
```javascript
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
const completed = tasks.filter(t => t.status === 'completed')
const pipelineMode = tasks[0]?.pipeline_mode
console.log(`
============================================
FRONTEND DEBUG COMPLETE
Pipeline: ${pipelineMode} | ${completed.length}/${tasks.length} tasks
Fix Rounds: ${fixRound}/${MAX_FIX_ROUNDS}
Session: ${sessionFolder}
Results:
${completed.map(t => ` [DONE] ${t.id} (${t.role}): ${t.findings?.substring(0, 80) || 'completed'}`).join('\n')}
============================================
`)
if (!AUTO_YES) {
request_user_input({
questions: [{
question: "Debug pipeline complete. Choose next action.",
header: "Done",
id: "completion",
options: [
{ label: "Archive (Recommended)", description: "Archive session, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up debugging" },
{ label: "Export Results", description: "Export debug report and patches" }
]
}]
})
}
```
**Success Criteria**:
- User informed of debug pipeline results
- Completion action taken
---
### Phase 4: Results Aggregation
**Objective**: Generate final results and human-readable report.
```javascript
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
let contextMd = `# Frontend Debug Report\n\n`
contextMd += `**Session**: ${sessionId}\n`
contextMd += `**Pipeline**: ${tasks[0]?.pipeline_mode}\n`
contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n\n`
contextMd += `## Summary\n`
contextMd += `| Status | Count |\n|--------|-------|\n`
contextMd += `| Completed | ${tasks.filter(t => t.status === 'completed').length} |\n`
contextMd += `| Failed | ${tasks.filter(t => t.status === 'failed').length} |\n`
contextMd += `| Skipped | ${tasks.filter(t => t.status === 'skipped').length} |\n\n`
const maxWave = Math.max(...tasks.map(t => t.wave))
contextMd += `## Wave Execution\n\n`
for (let w = 1; w <= maxWave; w++) {
const waveTasks = tasks.filter(t => t.wave === w)
contextMd += `### Wave ${w}\n\n`
for (const t of waveTasks) {
const icon = t.status === 'completed' ? '[DONE]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
contextMd += `${icon} **${t.title}** [${t.role}]`
if (t.verdict) contextMd += ` Verdict: ${t.verdict}`
if (t.issues_count) contextMd += ` Issues: ${t.issues_count}`
contextMd += ` ${t.findings || ''}\n\n`
}
}
// Debug-specific sections
const verifyTasks = tasks.filter(t => t.role === 'verifier' && t.verdict)
if (verifyTasks.length > 0) {
contextMd += `## Verification Results\n\n`
for (const v of verifyTasks) {
contextMd += `- **${v.id}**: ${v.verdict}\n`
}
}
Write(`${sessionFolder}/context.md`, contextMd)
console.log(`Results exported to: ${sessionFolder}/results.csv`)
console.log(`Report generated at: ${sessionFolder}/context.md`)
```
**Success Criteria**:
- results.csv exported
- context.md generated with debug summary
- Summary displayed to user
---
## Shared Discovery Board Protocol
All agents share a single `discoveries.ndjson` file.
**Format**: One JSON object per line (NDJSON):
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"TEST-001","type":"feature_tested","data":{"feature":"F-001","name":"Login","result":"fail","issues":2}}
{"ts":"2026-03-08T10:05:00Z","worker":"REPRODUCE-001","type":"bug_reproduced","data":{"url":"/settings","steps":3,"console_errors":2,"network_failures":1}}
{"ts":"2026-03-08T10:10:00Z","worker":"ANALYZE-001","type":"root_cause_found","data":{"category":"TypeError","file":"src/components/Settings.tsx","line":142,"confidence":"high"}}
{"ts":"2026-03-08T10:15:00Z","worker":"FIX-001","type":"file_modified","data":{"file":"src/components/Settings.tsx","change":"Added null check","lines_added":3}}
{"ts":"2026-03-08T10:20:00Z","worker":"VERIFY-001","type":"verification_result","data":{"verdict":"pass","original_error_resolved":true,"new_errors":0}}
```
**Discovery Types**:
| Type | Data Schema | Description |
|------|-------------|-------------|
| `feature_tested` | `{feature, name, result, issues}` | Feature test result |
| `bug_reproduced` | `{url, steps, console_errors, network_failures}` | Bug reproduction result |
| `evidence_collected` | `{dimension, file, description}` | Evidence artifact saved |
| `root_cause_found` | `{category, file, line, confidence}` | Root cause identified |
| `file_modified` | `{file, change, lines_added}` | Code fix applied |
| `verification_result` | `{verdict, original_error_resolved, new_errors}` | Fix verification result |
| `issue_found` | `{file, line, severity, description}` | Issue discovered |
**Protocol**:
1. Agents MUST read discoveries.ndjson at start of execution
2. Agents MUST append relevant discoveries during execution
3. Agents MUST NOT modify or delete existing entries
4. Deduplication by `{type, data.file}` key
---
## Conditional Skip Logic
After TEST-001 completes, evaluate issues:
| Condition | Action |
|-----------|--------|
| `issues_count === 0` | Skip ANALYZE/FIX/VERIFY. Pipeline complete with all-pass. |
| Only low-severity warnings | request_user_input: fix warnings or complete |
| High/medium severity issues | Proceed with ANALYZE -> FIX -> VERIFY |
---
## Iteration Rules
| Trigger | Condition | Action | Max |
|---------|-----------|--------|-----|
| Analyzer -> Reproducer | Confidence < 50% | Create REPRODUCE-002 -> ANALYZE-002 | 2 reproduction rounds |
| Verifier -> Fixer | Verdict = fail | Create FIX-002 -> VERIFY-002 | 3 fix rounds |
| Max iterations reached | Round >= max | Report to user for manual intervention | -- |
---
## 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 |
| 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 |
| All features pass test | Skip downstream tasks, report success |
| Bug not reproducible | Report failure, ask user for more details |
| Scenario | Resolution |
|----------|------------|
| All features pass test | Report success, pipeline completes without ANALYZE/FIX/VERIFY |
| Bug not reproducible | Reproducer reports failure, coordinator asks user for more details |
| Browser not available | Report error, suggest manual reproduction steps |
| Analysis inconclusive | Request more evidence via iteration loop |
| Fix introduces regression | Verifier reports fail, dispatch re-fix |
| Max iterations reached | Escalate to user for manual intervention |
| Continue mode: no session found | List available sessions, prompt user to select |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 0/1
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
7. **Skip on Failure**: If a dependency failed, skip the dependent task
8. **Conditional Skip**: If TEST finds 0 issues, skip all downstream tasks
9. **Iteration Bounds**: Max 2 reproduction rounds, max 3 fix rounds
10. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
11. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
---
## Coordinator Role Constraints (Main Agent)
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns
| Analysis inconclusive | Analyzer requests more evidence via iteration loop |
| Fix introduces regression | Verifier reports fail, coordinator dispatches re-fix |
| No issues found in test | Skip downstream tasks, report all-pass |
| Unknown command | Error with available command list |
| Role not found | Error with role registry |

142
.codex/skills/team-frontend-debug/agents/completion-handler.md
View File

@@ -1,142 +0,0 @@
# Completion Handler Agent
Interactive agent for handling pipeline completion action. Presents debug summary and offers Archive/Keep/Export choices.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/completion-handler.md`
- **Responsibility**: Present debug pipeline results, handle completion choice, execute cleanup or export
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read all task results from master CSV
- Present debug summary (reproduction, RCA, fix, verification)
- Wait for user choice before acting
- Produce structured output following template
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Delete session files without user approval
- Modify task artifacts
- Produce unstructured output
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load task results and artifacts |
| `request_user_input` | built-in | Get user completion choice |
| `Write` | built-in | Store completion result |
| `Bash` | built-in | Execute archive/export operations |
---
## Execution
### Phase 1: Results Loading
**Objective**: Load all task results and build debug summary
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| tasks.csv | Yes | Master state with all task results |
| Artifact files | No | Verify deliverables exist |
**Steps**:
1. Read master tasks.csv
2. Parse all completed tasks and their artifacts
3. Build debug summary:
- Bug description and reproduction results
- Root cause analysis findings
- Files modified and patches applied
- Verification results (pass/fail)
- Evidence inventory (screenshots, logs, traces)
4. Calculate pipeline statistics
**Output**: Debug summary ready for user
---
### Phase 2: Completion Choice
**Objective**: Present debug results and get user action
**Steps**:
1. Display pipeline summary with debug details
2. Present completion choice:
```javascript
request_user_input({
questions: [{
question: "Debug pipeline complete. What would you like to do?",
header: "Completion",
id: "completion_action",
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up debugging" },
{ label: "Export Results", description: "Export debug report and patches" }
]
}]
})
```
3. Handle response:
| Response | Action |
|----------|--------|
| Archive & Clean | Mark session completed, output final summary |
| Keep Active | Mark session paused, keep all evidence/artifacts |
| Export Results | Copy RCA report, fix changes, verification report to project directory |
**Output**: Completion action result
---
## Structured Output Template
```
## Summary
- Pipeline mode: <test-pipeline|debug-pipeline>
- Tasks completed: <count>/<total>
- Fix rounds: <count>/<max>
- Final verdict: <pass|pass_with_warnings|fail>
## Debug Summary
- Bug: <description>
- Root cause: <category at file:line>
- Fix: <description of changes>
- Verification: <pass/fail>
## Evidence Inventory
- Screenshots: <count>
- Console logs: <captured/not captured>
- Network logs: <captured/not captured>
- Performance trace: <captured/not captured>
## Action Taken
- Choice: <archive|keep|export>
- Session status: <completed|paused|exported>
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| tasks.csv not found | Report error, cannot complete |
| Artifacts missing | Report partial completion with gaps noted |
| User does not respond | Timeout, default to keep active |

130
.codex/skills/team-frontend-debug/agents/conditional-skip-gate.md
View File

@@ -1,130 +0,0 @@
# Conditional Skip Gate Agent
Interactive agent for evaluating TEST-001 results and determining whether to skip downstream tasks (ANALYZE, FIX, VERIFY) when no issues are found.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/conditional-skip-gate.md`
- **Responsibility**: Read TEST results, evaluate issue severity, decide skip/proceed
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read the TEST-001 issues JSON
- Evaluate issue count and severity distribution
- Apply conditional skip logic
- Present decision to user when only warnings exist
- Produce structured output following template
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Auto-skip when high/medium issues exist
- Modify test artifacts directly
- Produce unstructured output
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load test results and issues |
| `request_user_input` | built-in | Get user decision on warnings |
| `Write` | built-in | Store gate decision result |
---
## Execution
### Phase 1: Load Test Results
**Objective**: Load TEST-001 issues and evaluate severity
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| TEST-001-issues.json | Yes | Discovered issues with severity |
| TEST-001-report.md | No | Full test report |
**Steps**:
1. Extract session path from task assignment
2. Read TEST-001-issues.json
3. Parse issues array
4. Count by severity: high, medium, low, warning
**Output**: Issue severity distribution
---
### Phase 2: Skip Decision
**Objective**: Apply conditional skip logic
**Steps**:
1. Evaluate issues:
| Condition | Action |
|-----------|--------|
| `issues.length === 0` | Skip all downstream. Report "all_pass". |
| Only low/warning severity | Ask user: fix or complete |
| Any high/medium severity | Proceed with ANALYZE -> FIX -> VERIFY |
2. If only warnings, present choice:
```javascript
request_user_input({
questions: [{
question: "Testing found only low-severity warnings. How would you like to proceed?",
header: "Test Results",
id: "warning_decision",
options: [
{ label: "Fix warnings (Recommended)", description: "Proceed with analysis and fixes for warnings" },
{ label: "Complete", description: "Accept current state, skip remaining tasks" }
]
}]
})
```
3. Handle response and record decision
**Output**: Skip/proceed directive
---
## Structured Output Template
```
## Summary
- Test report evaluated: TEST-001
- Issues found: <total>
- High: <count>, Medium: <count>, Low: <count>, Warning: <count>
- Decision: <all_pass|skip_warnings|proceed>
## Findings
- All features tested: <count>
- Pass rate: <percentage>
## Decision Details
- Action: <skip-downstream|proceed-with-fixes>
- Downstream tasks affected: ANALYZE-001, FIX-001, VERIFY-001
- User choice: <if applicable>
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| TEST-001-issues.json not found | Report error, cannot evaluate |
| Issues JSON malformed | Report parse error, default to proceed |
| User does not respond | Timeout, default to proceed with fixes |

120
.codex/skills/team-frontend-debug/agents/iteration-handler.md
View File

@@ -1,120 +0,0 @@
# Iteration Handler Agent
Interactive agent for handling the analyzer's request for more evidence. Creates supplemental reproduction and re-analysis tasks when root cause analysis confidence is low.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/iteration-handler.md`
- **Responsibility**: Parse analyzer evidence request, create REPRODUCE-002 + ANALYZE-002 tasks, update dependency chain
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read the analyzer's need_more_evidence request
- Parse specific evidence dimensions and actions requested
- Create supplemental reproduction task description
- Create re-analysis task description
- Update FIX dependency to point to new ANALYZE task
- Produce structured output following template
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Ignore the analyzer's specific requests
- Create tasks beyond iteration bounds (max 2 reproduction rounds)
- Modify existing task artifacts
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load analyzer output and session state |
| `Write` | built-in | Store iteration handler result |
---
## Execution
### Phase 1: Parse Evidence Request
**Objective**: Understand what additional evidence the analyzer needs
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Analyzer findings | Yes | Contains need_more_evidence with specifics |
| Session state | No | Current iteration count |
**Steps**:
1. Extract session path from task assignment
2. Read analyzer's findings or RCA report (partial)
3. Parse evidence request:
- Additional dimensions needed (network_detail, state_inspection, etc.)
- Specific actions (capture request body, evaluate React state, etc.)
4. Check current iteration count
**Output**: Parsed evidence request
---
### Phase 2: Create Iteration Tasks
**Objective**: Build task descriptions for supplemental reproduction and re-analysis
**Steps**:
1. Check iteration bounds:
| Condition | Action |
|-----------|--------|
| Reproduction rounds < 2 | Create REPRODUCE-002 + ANALYZE-002 |
| Reproduction rounds >= 2 | Escalate to user for manual investigation |
2. Build REPRODUCE-002 description with specific evidence requests from analyzer
3. Build ANALYZE-002 description that loads both original and supplemental evidence
4. Record new tasks and dependency updates
**Output**: Task descriptions for dynamic wave extension
---
## Structured Output Template
```
## Summary
- Analyzer evidence request processed
- Iteration round: <current>/<max>
- Action: <create-reproduction|escalate>
## Evidence Request
- Dimensions needed: <list>
- Specific actions: <list>
## Tasks Created
- REPRODUCE-002: <description summary>
- ANALYZE-002: <description summary>
## Dependency Updates
- FIX-001 deps updated: ANALYZE-001 -> ANALYZE-002
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Evidence request unclear | Use all default dimensions |
| Max iterations reached | Escalate to user |
| Session state missing | Default to iteration round 1 |

272
.codex/skills/team-frontend-debug/instructions/agent-instruction.md
View File

@@ -1,272 +0,0 @@
# Agent Instruction Template -- Team Frontend Debug
Base instruction template for CSV wave agents. The orchestrator dynamically customizes this per role during Phase 1, writing role-specific versions to `role-instructions/{role}.md`.
## Purpose
| Phase | Usage |
|-------|-------|
| Phase 1 | Coordinator generates per-role instruction from this template |
| Phase 2 | Injected as `instruction` parameter to `spawn_agents_on_csv` |
---
## Base Instruction Template
```markdown
## TASK ASSIGNMENT -- Team Frontend Debug
### 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)
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**Pipeline Mode**: {pipeline_mode}
**Base URL**: {base_url}
**Evidence Dimensions**: {evidence_dimensions}
### Task Description
{description}
### 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 task**: Follow role-specific instructions below
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
- `feature_tested`: {feature, name, result, issues} -- Feature test result
- `bug_reproduced`: {url, steps, console_errors, network_failures} -- Bug reproduction outcome
- `evidence_collected`: {dimension, file, description} -- Evidence artifact saved
- `root_cause_found`: {category, file, line, confidence} -- Root cause identified
- `file_modified`: {file, change, lines_added} -- Code fix applied
- `verification_result`: {verdict, original_error_resolved, new_errors} -- Verification outcome
- `issue_found`: {file, line, severity, description} -- Issue discovered
---
## Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key discoveries and implementation notes (max 500 chars)",
"artifacts_produced": "semicolon-separated paths of produced files",
"issues_count": "",
"verdict": "",
"error": ""
}
```
---
## Role-Specific Customization
The coordinator generates per-role instruction variants during Phase 1.
### For Tester Role (test-pipeline)
```
3. **Execute**:
- Parse feature list from task description
- For each feature:
a. Navigate to feature URL: mcp__chrome-devtools__navigate_page({ type: "url", url: "<base_url><path>" })
b. Wait for page load: mcp__chrome-devtools__wait_for({ text: ["<expected>"], timeout: 10000 })
c. Explore page structure: mcp__chrome-devtools__take_snapshot()
d. Generate test scenarios from UI elements if not predefined
e. Capture baseline: take_screenshot (before), list_console_messages
f. Execute test steps: map step descriptions to MCP actions
- Click: take_snapshot -> find uid -> click({ uid })
- Fill: take_snapshot -> find uid -> fill({ uid, value })
- Hover: take_snapshot -> find uid -> hover({ uid })
- Wait: wait_for({ text: ["expected"] })
- Navigate: navigate_page({ type: "url", url: "path" })
- Press key: press_key({ key: "Enter" })
g. Capture result: take_screenshot (after), list_console_messages (errors), list_network_requests
h. Evaluate: console errors? network failures? expected text present? visual issues?
i. Classify: pass / fail / warning
- Compile test report: <session>/artifacts/TEST-001-report.md
- Compile issues list: <session>/artifacts/TEST-001-issues.json
- Set issues_count in output
```
### For Reproducer Role (debug-pipeline)
```
3. **Execute**:
- Verify browser accessible: mcp__chrome-devtools__list_pages()
- Navigate to target URL: mcp__chrome-devtools__navigate_page({ type: "url", url: "<target>" })
- Wait for load: mcp__chrome-devtools__wait_for({ text: ["<expected>"], timeout: 10000 })
- Capture baseline evidence:
- Screenshot (before): take_screenshot({ filePath: "<session>/evidence/before-screenshot.png" })
- DOM snapshot (before): take_snapshot({ filePath: "<session>/evidence/before-snapshot.txt" })
- Console baseline: list_console_messages()
- Execute reproduction steps:
- For each step, parse action and execute via MCP tools
- Track DOM changes via snapshots after key steps
- Capture post-action evidence:
- Screenshot (after): take_screenshot({ filePath: "<session>/evidence/after-screenshot.png" })
- DOM snapshot (after): take_snapshot({ filePath: "<session>/evidence/after-snapshot.txt" })
- Console errors: list_console_messages({ types: ["error", "warn"] })
- Network requests: list_network_requests({ resourceTypes: ["xhr", "fetch"] })
- Request details for failures: get_network_request({ reqid: <id> })
- Performance trace (if dimension): performance_start_trace() + reproduce + performance_stop_trace()
- Write evidence-summary.json to <session>/evidence/
```
### For Analyzer Role
```
3. **Execute**:
- Load evidence from upstream (reproducer evidence/ or tester artifacts/)
- Console error analysis (priority):
- Filter by type: error > warn > log
- Extract stack traces, identify source file:line
- Classify: TypeError, ReferenceError, NetworkError, etc.
- Network analysis (if dimension):
- Identify failed requests (4xx, 5xx, timeout, CORS)
- Check auth tokens, API endpoints, payload issues
- DOM structure analysis (if snapshots):
- Compare before/after snapshots
- Identify missing/extra elements, attribute anomalies
- Performance analysis (if trace):
- Identify long tasks (>50ms), layout thrashing, memory leaks
- Cross-correlation: build timeline, identify trigger point
- Source code mapping:
- Use mcp__ace-tool__search_context or Grep to locate root cause
- Read identified source files
- Confidence assessment:
- High (>80%): clear stack trace + specific line
- Medium (50-80%): likely cause, needs confirmation
- Low (<50%): request more evidence (set findings to include "need_more_evidence")
- Write RCA report to <session>/artifacts/ANALYZE-001-rca.md
- Set issues_count in output
```
### For Fixer Role
```
3. **Execute**:
- Load RCA report from analyzer output
- Extract root cause: category, file, line, recommended fix
- Read identified source files
- Search for similar patterns: mcp__ace-tool__search_context
- Plan fix: minimal change addressing root cause
- Apply fix strategy by category:
- TypeError/null: add null check, default value
- API error: fix URL, add error handling
- Missing import: add import statement
- CSS/rendering: fix styles, layout
- State bug: fix state update logic
- Race condition: add async handling
- Implement fix using Edit tool (fallback: mcp__ccw-tools__edit_file)
- Validate: run syntax/type checks
- Document changes in <session>/artifacts/FIX-001-changes.md
```
### For Verifier Role
```
3. **Execute**:
- Load original evidence (reproducer) and fix changes (fixer)
- Pre-verification: check modified files contain expected changes
- Navigate to same URL: mcp__chrome-devtools__navigate_page
- Execute EXACT same reproduction/test steps
- Capture post-fix evidence:
- Screenshot: take_screenshot({ filePath: "<session>/evidence/verify-screenshot.png" })
- DOM snapshot: take_snapshot({ filePath: "<session>/evidence/verify-snapshot.txt" })
- Console: list_console_messages({ types: ["error", "warn"] })
- Network: list_network_requests({ resourceTypes: ["xhr", "fetch"] })
- Compare evidence:
- Console: original error gone?
- Network: failed request now succeeds?
- Visual: expected rendering achieved?
- New errors: any regression?
- Determine verdict:
- pass: original resolved AND no new errors
- pass_with_warnings: original resolved BUT new issues
- fail: original still present
- Write verification report to <session>/artifacts/VERIFY-001-report.md
- Set verdict in output
```
---
## Chrome DevTools MCP Reference
### Common Patterns
**Navigate and Wait**:
```
mcp__chrome-devtools__navigate_page({ type: "url", url: "<url>" })
mcp__chrome-devtools__wait_for({ text: ["<expected>"], timeout: 10000 })
```
**Find Element and Interact**:
```
mcp__chrome-devtools__take_snapshot() // Get uids
mcp__chrome-devtools__click({ uid: "<uid>" })
mcp__chrome-devtools__fill({ uid: "<uid>", value: "<value>" })
```
**Capture Evidence**:
```
mcp__chrome-devtools__take_screenshot({ filePath: "<path>" })
mcp__chrome-devtools__list_console_messages({ types: ["error", "warn"] })
mcp__chrome-devtools__list_network_requests({ resourceTypes: ["xhr", "fetch"] })
```
**Debug API Error**:
```
mcp__chrome-devtools__list_network_requests() // Find request
mcp__chrome-devtools__get_network_request({ reqid: <id> }) // Inspect details
```
---
## Quality Requirements
All agents must verify before reporting complete:
| Requirement | Criteria |
|-------------|----------|
| Files produced | Verify all claimed artifacts exist via Read |
| Evidence captured | All planned dimensions have evidence files |
| Findings accuracy | Findings reflect actual observations |
| Discovery sharing | At least 1 discovery shared to board |
| Error reporting | Non-empty error field if status is failed |
| Verdict set | verifier role sets verdict field |
| Issues count set | tester/analyzer roles set issues_count field |
---
## Placeholder Reference
| Placeholder | Resolved By | When |
|-------------|------------|------|
| `<session-folder>` | Skill designer (Phase 1) | Literal path baked into instruction |
| `{id}` | spawn_agents_on_csv | Runtime from CSV row |
| `{title}` | spawn_agents_on_csv | Runtime from CSV row |
| `{description}` | spawn_agents_on_csv | Runtime from CSV row |
| `{role}` | spawn_agents_on_csv | Runtime from CSV row |
| `{pipeline_mode}` | spawn_agents_on_csv | Runtime from CSV row |
| `{base_url}` | spawn_agents_on_csv | Runtime from CSV row |
| `{evidence_dimensions}` | spawn_agents_on_csv | Runtime from CSV row |
| `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row |

208
.codex/skills/team-frontend-debug/roles/analyzer/role.md Normal file
View File

@@ -0,0 +1,208 @@
---
role: analyzer
prefix: ANALYZE
inner_loop: false
message_types:
success: rca_ready
iteration: need_more_evidence
error: error
---
# Analyzer
Root cause analysis from debug evidence.
## Identity
- Tag: [analyzer] | Prefix: ANALYZE-*
- Responsibility: Analyze evidence artifacts, identify root cause, produce RCA report
## Boundaries
### MUST
- Load ALL evidence from reproducer before analysis
- Correlate findings across multiple evidence types
- Identify specific file:line location when possible
- Request supplemental evidence if analysis is inconclusive
- Produce structured RCA report
### MUST NOT
- Modify source code or project files
- Skip loading upstream evidence
- Guess root cause without evidence support
- Proceed with low-confidence RCA (request more evidence instead)
## Phase 2: Load Evidence
1. Load debug specs: Run `ccw spec load --category debug` for known issues, workarounds, and root-cause notes
2. Read upstream artifacts via team_msg(operation="get_state", role="reproducer")
3. Extract evidence paths from reproducer's state_update ref
3. Load evidence-summary.json from session evidence/
4. Load all evidence files:
- Read screenshot files (visual inspection)
- Read DOM snapshots (structural analysis)
- Parse console error messages
- Parse network request logs
- Read performance trace if available
5. Load wisdom/ for any prior debug knowledge
## Phase 3: Root Cause Analysis
### Step 3.1: Console Error Analysis
Priority analysis — most bugs have console evidence:
1. Filter console messages by type: error > warn > log
2. For each error:
- Extract error message and stack trace
- Identify source file and line number from stack
- Classify: TypeError, ReferenceError, SyntaxError, NetworkError, CustomError
3. Map errors to reproduction steps (correlation by timing)
### Step 3.2: Network Analysis
If network evidence collected:
1. Identify failed requests (4xx, 5xx, timeout, CORS)
2. For each failed request:
- Request URL, method, headers
- Response status, body (if captured)
- Timing information
3. Check for:
- Missing authentication tokens
- Incorrect API endpoints
- CORS policy violations
- Request/response payload issues
### Step 3.3: DOM Structure Analysis
If snapshots collected:
1. Compare before/after snapshots
2. Identify:
- Missing or extra elements
- Incorrect attributes or content
- Accessibility tree anomalies
- State-dependent rendering issues
### Step 3.4: Performance Analysis
If performance trace collected:
1. Identify long tasks (>50ms)
2. Check for:
- JavaScript execution bottlenecks
- Layout thrashing
- Excessive re-renders
- Memory leaks (growing heap)
- Large resource loads
### Step 3.5: Cross-Correlation
Combine findings from all dimensions:
1. Build timeline of events leading to bug
2. Identify the earliest trigger point
3. Trace from trigger to visible symptom
4. Determine if issue is:
- Frontend code bug (logic error, missing null check, etc.)
- Backend/API issue (wrong data, missing endpoint)
- Configuration issue (env vars, build config)
- Race condition / timing issue
### Step 3.6: Source Code Mapping
Use codebase search to locate root cause:
```
mcp__ace-tool__search_context({
project_root_path: "<project-root>",
query: "<error message or function name from stack trace>"
})
```
Read identified source files to confirm root cause location.
### Step 3.7: Confidence Assessment
| Confidence | Criteria | Action |
|------------|----------|--------|
| High (>80%) | Stack trace points to specific line + error is clear | Proceed with RCA |
| Medium (50-80%) | Likely cause identified but needs confirmation | Proceed with caveats |
| Low (<50%) | Multiple possible causes, insufficient evidence | Request more evidence |
If Low confidence: send `need_more_evidence` message with specific requests.
## Phase 4: RCA Report
Write `<session>/artifacts/ANALYZE-001-rca.md`:
```markdown
# Root Cause Analysis Report
## Bug Summary
- **Description**: <bug description>
- **URL**: <target url>
- **Reproduction**: <success/partial/failed>
## Root Cause
- **Category**: <JS Error | Network | Rendering | Performance | State>
- **Confidence**: <High | Medium | Low>
- **Source File**: <file path>
- **Source Line**: <line number>
- **Root Cause**: <detailed explanation>
## Evidence Chain
1. <evidence 1 -> finding>
2. <evidence 2 -> finding>
3. <correlation -> root cause>
## Fix Recommendation
- **Approach**: <description of recommended fix>
- **Files to modify**: <list>
- **Risk level**: <Low | Medium | High>
- **Estimated scope**: <lines of code / number of files>
## Additional Observations
- <any related issues found>
- <potential regression risks>
```
Send state_update:
```json
{
"status": "task_complete",
"task_id": "ANALYZE-001",
"ref": "<session>/artifacts/ANALYZE-001-rca.md",
"key_findings": ["Root cause: <summary>", "Location: <file:line>"],
"decisions": ["Recommended fix: <approach>"],
"verification": "self-validated"
}
```
## Iteration Protocol
When evidence is insufficient (confidence < 50%):
1. Send state_update with `need_more_evidence: true`:
```json
{
"status": "need_more_evidence",
"task_id": "ANALYZE-001",
"ref": null,
"key_findings": ["Partial analysis: <what we know>"],
"decisions": [],
"evidence_request": {
"dimensions": ["network_detail", "state_inspection"],
"specific_actions": ["Capture request body for /api/users", "Evaluate React state after click"]
}
}
```
2. Coordinator creates REPRODUCE-002 + ANALYZE-002
3. ANALYZE-002 loads both original and supplemental evidence
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Evidence files missing | Report with available data, note gaps |
| No clear root cause | Request supplemental evidence via iteration |
| Multiple possible causes | Rank by likelihood, report top 3 |
| Source code not found | Report with best available location info |

174
.codex/skills/team-frontend-debug/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,174 @@
# Analyze Input
Parse user input -> detect mode (feature-test vs bug-report) -> build dependency graph -> assign roles.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Step 1: Detect Input Mode
```
if input contains: 功能, feature, 清单, list, 测试, test, 完成, done, 验收
→ mode = "test-pipeline"
elif input contains: bug, 错误, 报错, crash, 问题, 不工作, 白屏, 异常
→ mode = "debug-pipeline"
else
→ request_user_input to clarify
```
```
request_user_input({
questions: [{
question: "请确认调试模式",
header: "Mode",
multiSelect: false,
options: [
{ label: "功能测试", description: "根据功能清单逐项测试，发现并修复问题" },
{ label: "Bug修复", description: "针对已知Bug进行复现、分析和修复" }
]
}]
})
```
---
## Mode A: Feature Test (test-pipeline)
### Parse Feature List
Extract from user input:
| Field | Source | Required |
|-------|--------|----------|
| base_url | URL in text or request_user_input | Yes |
| features | Feature list (bullet points, numbered list, or free text) | Yes |
| test_depth | User preference or default "standard" | Auto |
Parse features into structured format:
```json
[
{ "id": "F-001", "name": "用户登录", "url": "/login", "description": "..." },
{ "id": "F-002", "name": "数据列表", "url": "/dashboard", "description": "..." }
]
```
If base_url missing:
```
request_user_input({
questions: [{
question: "请提供应用的访问地址",
header: "Base URL",
multiSelect: false,
options: [
{ label: "localhost:3000", description: "本地开发服务器" },
{ label: "localhost:5173", description: "Vite默认端口" },
{ label: "Custom", description: "自定义URL" }
]
}]
})
```
### Complexity Scoring (Test Mode)
| Factor | Points |
|--------|--------|
| Per feature | +1 |
| Features > 5 | +2 |
| Features > 10 | +3 |
| Cross-page workflows | +1 |
Results: 1-3 Low, 4-6 Medium, 7+ High
### Output (Test Mode)
```json
{
"mode": "test-pipeline",
"base_url": "<url>",
"features": [
{ "id": "F-001", "name": "<name>", "url": "<path>", "description": "<desc>" }
],
"pipeline_type": "test-pipeline",
"dependency_graph": {
"TEST-001": { "role": "tester", "blockedBy": [], "priority": "P0" },
"ANALYZE-001": { "role": "analyzer", "blockedBy": ["TEST-001"], "priority": "P0", "conditional": true },
"FIX-001": { "role": "fixer", "blockedBy": ["ANALYZE-001"], "priority": "P0", "conditional": true },
"VERIFY-001": { "role": "verifier", "blockedBy": ["FIX-001"], "priority": "P0", "conditional": true }
},
"roles": [
{ "name": "tester", "prefix": "TEST", "inner_loop": true },
{ "name": "analyzer", "prefix": "ANALYZE", "inner_loop": false },
{ "name": "fixer", "prefix": "FIX", "inner_loop": true },
{ "name": "verifier", "prefix": "VERIFY", "inner_loop": false }
],
"complexity": { "score": 0, "level": "Low|Medium|High" }
}
```
---
## Mode B: Bug Report (debug-pipeline)
### Parse Bug Report
Extract from user input:
| Field | Source | Required |
|-------|--------|----------|
| bug_description | User text | Yes |
| target_url | URL in text or request_user_input | Yes |
| reproduction_steps | Steps in text or request_user_input | Yes |
| expected_behavior | User description | Recommended |
| actual_behavior | User description | Recommended |
| severity | User indication or auto-assess | Auto |
### Debug Dimension Detection
| Keywords | Dimension | Evidence Needed |
|----------|-----------|-----------------|
| 渲染, 样式, 显示, 布局, CSS | UI/Rendering | screenshot, snapshot |
| 请求, API, 接口, 网络, 超时 | Network | network_requests |
| 错误, 报错, 异常, crash | JavaScript Error | console_messages |
| 慢, 卡顿, 性能, 加载 | Performance | performance_trace |
| 状态, 数据, 更新, 不同步 | State Management | console + snapshot |
| 交互, 点击, 输入, 表单 | User Interaction | click/fill + screenshot |
### Complexity Scoring (Debug Mode)
| Factor | Points |
|--------|--------|
| Single dimension (e.g., JS error only) | 1 |
| Multi-dimension (UI + Network) | +1 per extra |
| Intermittent / hard to reproduce | +2 |
| Performance profiling needed | +1 |
Results: 1-2 Low, 3-4 Medium, 5+ High
### Output (Debug Mode)
```json
{
"mode": "debug-pipeline",
"bug_description": "<original>",
"target_url": "<url>",
"reproduction_steps": ["step 1", "step 2"],
"dimensions": ["ui_rendering", "javascript_error"],
"evidence_plan": {
"screenshot": true, "snapshot": true,
"console": true, "network": true, "performance": false
},
"pipeline_type": "debug-pipeline",
"dependency_graph": {
"REPRODUCE-001": { "role": "reproducer", "blockedBy": [], "priority": "P0" },
"ANALYZE-001": { "role": "analyzer", "blockedBy": ["REPRODUCE-001"], "priority": "P0" },
"FIX-001": { "role": "fixer", "blockedBy": ["ANALYZE-001"], "priority": "P0" },
"VERIFY-001": { "role": "verifier", "blockedBy": ["FIX-001"], "priority": "P0" }
},
"roles": [
{ "name": "reproducer", "prefix": "REPRODUCE", "inner_loop": false },
{ "name": "analyzer", "prefix": "ANALYZE", "inner_loop": false },
{ "name": "fixer", "prefix": "FIX", "inner_loop": true },
{ "name": "verifier", "prefix": "VERIFY", "inner_loop": false }
],
"complexity": { "score": 0, "level": "Low|Medium|High" }
}
```

198
.codex/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md Normal file
View File

@@ -0,0 +1,198 @@
# Dispatch Debug Tasks
Create task chains from dependency graph with proper blockedBy relationships.
## Workflow
1. Read task-analysis.json -> extract pipeline_type and dependency_graph
2. Read specs/pipelines.md -> get task registry for selected pipeline
3. Topological sort tasks (respect blockedBy)
4. Validate all owners exist in role registry (SKILL.md)
5. For each task (in order):
- Build JSON entry with structured description (see template below)
- Set blockedBy and owner fields in the entry
6. Write all entries to `<session>/tasks.json`
7. Update team-session.json with pipeline.tasks_total
8. Validate chain (no orphans, no cycles, all refs valid)
## Task Description Template
Each task is a JSON entry in the tasks array:
```json
{
"id": "<TASK-ID>",
"subject": "<TASK-ID>",
"description": "PURPOSE: <goal> | Success: <criteria>\nTASK:\n - <step 1>\n - <step 2>\nCONTEXT:\n - Session: <session-folder>\n - Base URL / Bug URL: <url>\n - Upstream artifacts: <list>\nEXPECTED: <artifact path> + <quality criteria>\nCONSTRAINTS: <scope limits>\n---\nInnerLoop: <true|false>\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/<role>/role.md",
"status": "pending",
"owner": "<role>",
"blockedBy": ["<dependency-list>"]
}
```
---
## Test Pipeline Tasks (mode: test-pipeline)
### TEST-001: Feature Testing
```json
{
"id": "TEST-001",
"subject": "TEST-001",
"description": "PURPOSE: Test all features from feature list and discover issues | Success: All features tested with pass/fail results\nTASK:\n - Parse feature list from task description\n - For each feature: navigate to URL, explore page, generate test scenarios\n - Execute test scenarios using Chrome DevTools MCP (click, fill, hover, etc.)\n - Capture evidence: screenshots, console logs, network requests\n - Classify results: pass / fail / warning\n - Compile test report with discovered issues\nCONTEXT:\n - Session: <session-folder>\n - Base URL: <base-url>\n - Features: <feature-list-from-task-analysis>\nEXPECTED: <session>/artifacts/TEST-001-report.md + <session>/artifacts/TEST-001-issues.json\nCONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code | Test all listed features\n---\nInnerLoop: true\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/tester/role.md",
"status": "pending",
"owner": "tester",
"blockedBy": []
}
```
### ANALYZE-001 (Test Mode): Analyze Discovered Issues
```json
{
"id": "ANALYZE-001",
"subject": "ANALYZE-001",
"description": "PURPOSE: Analyze issues discovered by tester to identify root causes | Success: RCA for each discovered issue\nTASK:\n - Load test report and issues list from TEST-001\n - For each high/medium severity issue: analyze evidence, identify root cause\n - Correlate console errors, network failures, DOM anomalies to source code\n - Produce consolidated RCA report covering all issues\nCONTEXT:\n - Session: <session-folder>\n - Upstream: <session>/artifacts/TEST-001-issues.json\n - Test evidence: <session>/evidence/\nEXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root causes for all issues\nCONSTRAINTS: Read-only analysis | Skip low-severity warnings unless user requests\n---\nInnerLoop: false\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/analyzer/role.md",
"status": "pending",
"owner": "analyzer",
"blockedBy": ["TEST-001"]
}
```
**Conditional**: If TEST-001 reports zero issues -> skip ANALYZE-001, FIX-001, VERIFY-001. Pipeline completes.
### FIX-001 (Test Mode): Fix All Issues
```json
{
"id": "FIX-001",
"subject": "FIX-001",
"description": "PURPOSE: Fix all identified issues from RCA | Success: All high/medium issues resolved\nTASK:\n - Load consolidated RCA report from ANALYZE-001\n - For each root cause: locate code, implement fix\n - Run syntax/type check after all modifications\n - Document all changes\nCONTEXT:\n - Session: <session-folder>\n - Upstream: <session>/artifacts/ANALYZE-001-rca.md\nEXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md\nCONSTRAINTS: Minimal changes per issue | Follow existing code style\n---\nInnerLoop: true\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/fixer/role.md",
"status": "pending",
"owner": "fixer",
"blockedBy": ["ANALYZE-001"]
}
```
### VERIFY-001 (Test Mode): Re-Test After Fix
```json
{
"id": "VERIFY-001",
"subject": "VERIFY-001",
"description": "PURPOSE: Re-run failed test scenarios to verify fixes | Success: Previously failed scenarios now pass\nTASK:\n - Load original test report (failed scenarios only)\n - Re-execute failed scenarios using Chrome DevTools MCP\n - Capture evidence and compare with original\n - Report pass/fail per scenario\nCONTEXT:\n - Session: <session-folder>\n - Original test report: <session>/artifacts/TEST-001-report.md\n - Fix changes: <session>/artifacts/FIX-001-changes.md\n - Failed features: <from TEST-001-issues.json>\nEXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail per previously-failed scenario\nCONSTRAINTS: Only re-test failed scenarios | Use Chrome DevTools MCP only\n---\nInnerLoop: false\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/verifier/role.md",
"status": "pending",
"owner": "verifier",
"blockedBy": ["FIX-001"]
}
```
---
## Debug Pipeline Tasks (mode: debug-pipeline)
### REPRODUCE-001: Evidence Collection
```json
{
"id": "REPRODUCE-001",
"subject": "REPRODUCE-001",
"description": "PURPOSE: Reproduce reported bug and collect debug evidence | Success: Bug reproduced with evidence artifacts\nTASK:\n - Navigate to target URL\n - Execute reproduction steps using Chrome DevTools MCP\n - Capture evidence: screenshots, DOM snapshots, console logs, network requests\n - If performance dimension: run performance trace\n - Package all evidence into session evidence/ directory\nCONTEXT:\n - Session: <session-folder>\n - Bug URL: <target-url>\n - Steps: <reproduction-steps>\n - Evidence plan: <from task-analysis.json>\nEXPECTED: <session>/evidence/ directory with all captures + reproduction report\nCONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code\n---\nInnerLoop: false\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/reproducer/role.md",
"status": "pending",
"owner": "reproducer",
"blockedBy": []
}
```
### ANALYZE-001 (Debug Mode): Root Cause Analysis
```json
{
"id": "ANALYZE-001",
"subject": "ANALYZE-001",
"description": "PURPOSE: Analyze evidence to identify root cause | Success: RCA report with specific file:line location\nTASK:\n - Load evidence from REPRODUCE-001\n - Analyze console errors and stack traces\n - Analyze failed/abnormal network requests\n - Compare DOM snapshot against expected structure\n - Correlate findings to source code location\nCONTEXT:\n - Session: <session-folder>\n - Upstream: <session>/evidence/\n - Bug description: <bug-description>\nEXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root cause, file:line, fix recommendation\nCONSTRAINTS: Read-only analysis | Request more evidence if inconclusive\n---\nInnerLoop: false\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/analyzer/role.md",
"status": "pending",
"owner": "analyzer",
"blockedBy": ["REPRODUCE-001"]
}
```
### FIX-001 (Debug Mode): Code Fix
```json
{
"id": "FIX-001",
"subject": "FIX-001",
"description": "PURPOSE: Fix the identified bug | Success: Code changes that resolve the root cause\nTASK:\n - Load RCA report from ANALYZE-001\n - Locate the problematic code\n - Implement fix following existing code patterns\n - Run syntax/type check on modified files\nCONTEXT:\n - Session: <session-folder>\n - Upstream: <session>/artifacts/ANALYZE-001-rca.md\nEXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md\nCONSTRAINTS: Minimal changes | Follow existing code style | No breaking changes\n---\nInnerLoop: true\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/fixer/role.md",
"status": "pending",
"owner": "fixer",
"blockedBy": ["ANALYZE-001"]
}
```
### VERIFY-001 (Debug Mode): Fix Verification
```json
{
"id": "VERIFY-001",
"subject": "VERIFY-001",
"description": "PURPOSE: Verify bug is fixed | Success: Original bug no longer reproduces\nTASK:\n - Navigate to same URL as REPRODUCE-001\n - Execute same reproduction steps\n - Capture evidence and compare with original\n - Confirm bug is resolved and no regressions\nCONTEXT:\n - Session: <session-folder>\n - Original evidence: <session>/evidence/\n - Fix changes: <session>/artifacts/FIX-001-changes.md\nEXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail verdict\nCONSTRAINTS: Use Chrome DevTools MCP only | Same steps as reproduction\n---\nInnerLoop: false\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/verifier/role.md",
"status": "pending",
"owner": "verifier",
"blockedBy": ["FIX-001"]
}
```
---
## Dynamic Iteration Tasks
### REPRODUCE-002 (Debug Mode): Supplemental Evidence
Created when Analyzer requests more evidence -- add new entry to `<session>/tasks.json`:
```json
{
"id": "REPRODUCE-002",
"subject": "REPRODUCE-002",
"description": "PURPOSE: Collect additional evidence per Analyzer request | Success: Targeted evidence collected\nTASK: <specific evidence requests from Analyzer>\nCONTEXT: Session + Analyzer request\n---\nInnerLoop: false\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/reproducer/role.md",
"status": "pending",
"owner": "reproducer",
"blockedBy": []
}
```
### FIX-002 (Either Mode): Re-Fix After Failed Verification
Created when Verifier reports fail -- add new entry to `<session>/tasks.json`:
```json
{
"id": "FIX-002",
"subject": "FIX-002",
"description": "PURPOSE: Re-fix based on verification failure feedback | Success: Issue resolved\nTASK: Review VERIFY-001 failure details, apply corrective fix\nCONTEXT: Session + VERIFY-001-report.md\n---\nInnerLoop: true\nRoleSpec: ~ or <project>/.codex/skills/team-frontend-debug/roles/fixer/role.md",
"status": "pending",
"owner": "fixer",
"blockedBy": ["VERIFY-001"]
}
```
## Conditional Skip Rules
| Condition | Action |
|-----------|--------|
| test-pipeline + TEST-001 finds 0 issues | Skip ANALYZE/FIX/VERIFY -> pipeline complete |
| test-pipeline + TEST-001 finds only warnings | request_user_input: fix warnings or complete |
| debug-pipeline + REPRODUCE-001 cannot reproduce | request_user_input: retry with more info or abort |
## InnerLoop Flag Rules
- true: tester (iterates over features), fixer (may need multiple fix passes)
- false: reproducer, analyzer, verifier (single-pass tasks)
## Dependency Validation
- No orphan tasks (all tasks have valid owner)
- No circular dependencies
- All blockedBy references exist
- Session reference in every task description
- RoleSpec reference in every task description

143
.codex/skills/team-frontend-debug/roles/coordinator/commands/monitor.md Normal file
View File

@@ -0,0 +1,143 @@
# Monitor Pipeline
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
- SPAWN_MODE: background
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team-worker
## Handler Router
| Source | Handler |
|--------|---------|
| Message contains [role-name] | handleCallback |
| "need_more_evidence" | handleIteration |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
## handleCallback
Worker completed. Process and advance.
1. Find matching worker by role in message
2. Check if progress update (inner loop) or final completion
3. Progress -> update session state, STOP
4. Completion -> mark task done (read `<session>/tasks.json`, set status to "completed", write back), remove from active_workers
5. Check for special conditions:
- **TEST-001 with 0 issues** -> skip ANALYZE/FIX/VERIFY (mark as completed in tasks.json), handleComplete
- **TEST-001 with only warnings** -> request_user_input: fix warnings or complete
- **TEST-001 with high/medium issues** -> proceed to ANALYZE-001
- ANALYZE-001 with `need_more_evidence: true` -> handleIteration
- VERIFY-001 with `verdict: fail` -> re-dispatch FIX (add FIX-002 entry to tasks.json blocked by VERIFY-001)
- VERIFY-001 with `verdict: pass` -> handleComplete
6. -> handleSpawnNext
## handleIteration
Analyzer needs more evidence. Create supplemental reproduction task.
1. Parse Analyzer's evidence request (dimensions, specific actions)
2. Add REPRODUCE-002 entry to `<session>/tasks.json`:
- Set owner to "reproducer" (no blockedBy -- can start immediately)
3. Add ANALYZE-002 entry to `<session>/tasks.json`:
- Set blockedBy: ["REPRODUCE-002"]
- Update FIX-001 entry to add ANALYZE-002 to its blockedBy
4. Write updated tasks.json
5. -> handleSpawnNext
## handleCheck
Read-only status report, then STOP.
Output:
```
[coordinator] Debug Pipeline Status
[coordinator] Bug: <bug-description-summary>
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] Evidence: <list of collected evidence types>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
## handleResume
1. No active workers -> handleSpawnNext
2. Has active -> check each status
- completed -> mark done
- in_progress -> still running
3. Some completed -> handleSpawnNext
4. All running -> report status, STOP
## handleSpawnNext
Find ready tasks, spawn workers, STOP.
1. Collect: completedSubjects, inProgressSubjects, readySubjects (from tasks.json)
2. No ready + work in progress -> report waiting, STOP
3. No ready + nothing in progress -> handleComplete
4. Has ready -> for each:
a. Check if inner loop role with active worker -> skip (worker picks up)
b. Standard spawn:
- Update task status to "in_progress" in tasks.json
- team_msg log -> task_unblocked
- Spawn team-worker:
```
spawn_agent({
agent_type: "team_worker",
items: [{
description: "Spawn <role> worker for <task-id>",
team_name: "frontend-debug",
name: "<role>",
prompt: `## Role Assignment
role: <role>
role_spec: ~ or <project>/.codex/skills/team-frontend-debug/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: frontend-debug
requirement: <task-description>
inner_loop: <true|false>
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.`
}]
})
```
- Add to active_workers
5. Update session, output summary, STOP
6. Use `wait_agent({ ids: [<spawned-agent-ids>] })` to wait for callbacks. Workers use `report_agent_job_result()` to send results back.
## handleComplete
Pipeline done. Generate debug report and completion action.
1. Generate debug summary:
- Bug description and reproduction results
- Root cause analysis (from ANALYZE artifacts)
- Code changes applied (from FIX artifacts)
- Verification verdict (from VERIFY artifacts)
- Evidence inventory (screenshots, logs, traces)
2. Read session.completion_action:
- interactive -> request_user_input (Archive/Keep/Export)
- auto_archive -> Archive & Clean (status=completed, remove/archive session folder)
- auto_keep -> Keep Active (status=paused)
## handleAdapt
Not typically needed for debug pipeline. If Analyzer identifies a dimension not covered:
1. Parse gap description
2. Check if reproducer can cover it -> add to evidence plan
3. Create supplemental REPRODUCE task entry in tasks.json
## Fast-Advance Reconciliation
On every coordinator wake:
1. Read team_msg entries with type="fast_advance"
2. Sync active_workers with spawned successors
3. No duplicate spawns

131
.codex/skills/team-frontend-debug/roles/coordinator/role.md Normal file
View File

@@ -0,0 +1,131 @@
# Coordinator Role
Orchestrate team-frontend-debug: analyze -> dispatch -> spawn -> monitor -> report.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Analyze bug report -> Create team -> Dispatch debug tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Parse bug report description (text-level only, no codebase reading)
- Create team and spawn team-worker agents in background
- Dispatch tasks with proper dependency chains
- Monitor progress via callbacks and route messages
- Maintain session state (team-session.json)
- Handle iteration loops (analyzer requesting more evidence)
- Execute completion action when pipeline finishes
### MUST NOT
- Read source code or explore codebase (delegate to workers)
- Execute debug/fix work directly
- Modify task output artifacts
- Spawn workers with general-purpose agent (MUST use team-worker)
- Generate more than 5 worker roles
## Command Execution Protocol
When coordinator needs to execute a specific phase:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains [role-name] | -> handleCallback (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Iteration request | Message contains "need_more_evidence" | -> handleIteration (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active session in .workflow/.team/TFD-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/iteration/complete: load commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
1. Scan .workflow/.team/TFD-*/team-session.json for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile:
a. Audit tasks.json, reset in_progress->pending
b. Rebuild team workers
c. Kick first ready task
4. Multiple -> request_user_input for selection
## Phase 1: Requirement Clarification
TEXT-LEVEL ONLY. No source code reading.
1. Parse user input — detect mode:
- Feature list / 功能清单 → **test-pipeline**
- Bug report / 错误描述 → **debug-pipeline**
- Ambiguous → request_user_input to clarify
2. Extract relevant info based on mode:
- Test mode: base URL, feature list
- Debug mode: bug description, URL, reproduction steps
3. Clarify if ambiguous (request_user_input)
4. Delegate to @commands/analyze.md
5. Output: task-analysis.json
6. CRITICAL: Always proceed to Phase 2, never skip team workflow
## Phase 2: Create Team + Initialize Session
1. Resolve workspace paths (MUST do first):
- `project_root` = result of `Bash({ command: "pwd" })`
- `skill_root` = `<project_root>/.claude/skills/team-frontend-debug`
2. Generate session ID: TFD-<slug>-<date>
3. Create session folder structure:
```
.workflow/.team/TFD-<slug>-<date>/
├── team-session.json
├── evidence/
├── artifacts/
├── wisdom/
└── .msg/
```
3. Initialize session folder (replaces TeamCreate)
4. Read specs/pipelines.md -> select pipeline (default: debug-pipeline)
5. Register roles in team-session.json
6. Initialize pipeline via team_msg state_update
7. Write team-session.json
## Phase 3: Create Task Chain
Delegate to @commands/dispatch.md:
1. Read dependency graph from task-analysis.json
2. Read specs/pipelines.md for debug-pipeline task registry
3. Topological sort tasks
4. Build tasks array as JSON entries in `<session>/tasks.json`; set deps via `blockedBy` field in each entry
5. Update team-session.json
## Phase 4: Spawn-and-Stop
Delegate to @commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + blockedBy resolved)
2. Spawn team-worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
1. Generate debug summary:
- Bug description and reproduction results
- Root cause analysis findings
- Files modified and patches applied
- Verification results (pass/fail)
2. Execute completion action per session.completion_action:
- interactive -> request_user_input (Archive/Keep/Export)
- auto_archive -> Archive & Clean
## Error Handling
| Error | Resolution |
|-------|------------|
| Bug report too vague | request_user_input for URL, steps, expected behavior |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| Dependency cycle | Detect in analysis, halt |
| Browser unavailable | Report to user, suggest manual steps |

147
.codex/skills/team-frontend-debug/roles/fixer/role.md Normal file
View File

@@ -0,0 +1,147 @@
---
role: fixer
prefix: FIX
inner_loop: true
message_types:
success: fix_complete
progress: fix_progress
error: error
---
# Fixer
Code fix implementation based on root cause analysis.
## Identity
- Tag: [fixer] | Prefix: FIX-*
- Responsibility: Implement code fixes based on RCA report, validate with syntax checks
## Boundaries
### MUST
- Read RCA report before any code changes
- Locate exact source code to modify
- Follow existing code patterns and style
- Run syntax/type check after modifications
- Document all changes made
### MUST NOT
- Skip reading the RCA report
- Make changes unrelated to the identified root cause
- Introduce new dependencies without justification
- Skip syntax validation after changes
- Make breaking changes to public APIs
## Phase 2: Parse RCA + Plan Fix
1. Read upstream artifacts via team_msg(operation="get_state", role="analyzer")
2. Extract RCA report path from analyzer's state_update ref
3. Load RCA report: `<session>/artifacts/ANALYZE-001-rca.md`
4. Extract:
- Root cause category and description
- Source file(s) and line(s)
- Recommended fix approach
- Risk level
5. Read identified source files to understand context
6. Search for similar patterns in codebase:
```
mcp__ace-tool__search_context({
project_root_path: "<project-root>",
query: "<function/component name from RCA>"
})
```
7. Plan fix approach:
- Minimal change that addresses root cause
- Consistent with existing code patterns
- No side effects on other functionality
## Phase 3: Implement Fix
### Fix Strategy by Category
| Category | Typical Fix | Tools |
|----------|-------------|-------|
| TypeError / null | Add null check, default value | Edit |
| API Error | Fix URL, add error handling | Edit |
| Missing import | Add import statement | Edit |
| CSS/Rendering | Fix styles, layout properties | Edit |
| State bug | Fix state update logic | Edit |
| Race condition | Add proper async handling | Edit |
| Performance | Optimize render, memoize | Edit |
### Implementation Steps
1. Read the target file(s)
2. Apply minimal code changes using Edit tool
3. If Edit fails, use mcp__ccw-tools__edit_file as fallback
4. For each modified file:
- Keep changes minimal and focused
- Preserve existing code style (indentation, naming)
- Add inline comment only if fix is non-obvious
### Syntax Validation
After all changes:
```
mcp__ide__getDiagnostics({ uri: "file://<modified-file>" })
```
If diagnostics show errors:
- Fix syntax/type errors
- Re-validate
- Max 3 fix iterations for syntax issues
## Phase 4: Document Changes + Report
Write `<session>/artifacts/FIX-001-changes.md`:
```markdown
# Fix Report
## Root Cause Reference
- RCA: <session>/artifacts/ANALYZE-001-rca.md
- Category: <category>
- Source: <file:line>
## Changes Applied
### <file-path>
- **Line(s)**: <line numbers>
- **Change**: <description of what was changed>
- **Reason**: <why this change fixes the root cause>
## Validation
- Syntax check: <pass/fail>
- Type check: <pass/fail>
- Diagnostics: <clean / N warnings>
## Files Modified
- <file1.ts>
- <file2.tsx>
## Risk Assessment
- Breaking changes: <none / description>
- Side effects: <none / potential>
- Rollback: <how to revert>
```
Send state_update:
```json
{
"status": "task_complete",
"task_id": "FIX-001",
"ref": "<session>/artifacts/FIX-001-changes.md",
"key_findings": ["Fixed <root-cause-summary>", "Modified N files"],
"decisions": ["Applied <fix-approach>"],
"files_modified": ["path/to/file1.ts", "path/to/file2.tsx"],
"verification": "self-validated"
}
```
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Source file not found | Search codebase, report if not found |
| RCA location incorrect | Use ACE search to find correct location |
| Syntax errors after fix | Iterate fix (max 3 attempts) |
| Fix too complex | Report complexity, suggest manual intervention |
| Multiple files need changes | Apply all changes, validate each |

147
.codex/skills/team-frontend-debug/roles/reproducer/role.md Normal file
View File

@@ -0,0 +1,147 @@
---
role: reproducer
prefix: REPRODUCE
inner_loop: false
message_types:
success: evidence_ready
error: error
---
# Reproducer
Bug reproduction and evidence collection using Chrome DevTools MCP.
## Identity
- Tag: [reproducer] | Prefix: REPRODUCE-*
- Responsibility: Reproduce bug in browser, collect structured debug evidence
## Boundaries
### MUST
- Navigate to target URL using Chrome DevTools MCP
- Execute reproduction steps precisely
- Collect ALL evidence types specified in evidence plan
- Save evidence to session evidence/ directory
- Report reproduction success/failure with evidence paths
### MUST NOT
- Modify source code or any project files
- Make architectural decisions or suggest fixes
- Skip evidence collection for any planned dimension
- Navigate away from target URL without completing steps
## Phase 2: Prepare Reproduction
1. Read upstream artifacts via team_msg(operation="get_state")
2. Extract from task description:
- Session folder path
- Target URL
- Reproduction steps (ordered list)
- Evidence plan (which dimensions to capture)
3. Verify browser is accessible:
```
mcp__chrome-devtools__list_pages()
```
4. If no pages available, report error to coordinator
## Phase 3: Execute Reproduction + Collect Evidence
### Step 3.1: Navigate to Target
```
mcp__chrome-devtools__navigate_page({ type: "url", url: "<target-url>" })
```
Wait for page load:
```
mcp__chrome-devtools__wait_for({ text: ["<expected-element>"], timeout: 10000 })
```
### Step 3.2: Capture Baseline Evidence
Before executing steps, capture baseline state:
| Evidence Type | Tool | Save To |
|---------------|------|---------|
| Screenshot (before) | `take_screenshot({ filePath: "<session>/evidence/before-screenshot.png" })` | evidence/ |
| DOM Snapshot (before) | `take_snapshot({ filePath: "<session>/evidence/before-snapshot.txt" })` | evidence/ |
| Console messages | `list_console_messages()` | In-memory for comparison |
### Step 3.3: Execute Reproduction Steps
For each reproduction step:
1. Parse action type from step description:
| Action | Tool |
|--------|------|
| Click element | `mcp__chrome-devtools__click({ uid: "<uid>" })` |
| Fill input | `mcp__chrome-devtools__fill({ uid: "<uid>", value: "<value>" })` |
| Hover element | `mcp__chrome-devtools__hover({ uid: "<uid>" })` |
| Press key | `mcp__chrome-devtools__press_key({ key: "<key>" })` |
| Wait for element | `mcp__chrome-devtools__wait_for({ text: ["<text>"] })` |
| Run script | `mcp__chrome-devtools__evaluate_script({ function: "<js>" })` |
2. After each step, take snapshot to track DOM changes if needed
3. If step involves finding an element by text/role:
- First `take_snapshot()` to get current DOM with uids
- Find target uid from snapshot
- Execute action with uid
### Step 3.4: Capture Post-Action Evidence
After all steps executed:
| Evidence | Tool | Condition |
|----------|------|-----------|
| Screenshot (after) | `take_screenshot({ filePath: "<session>/evidence/after-screenshot.png" })` | Always |
| DOM Snapshot (after) | `take_snapshot({ filePath: "<session>/evidence/after-snapshot.txt" })` | Always |
| Console Errors | `list_console_messages({ types: ["error", "warn"] })` | Always |
| All Console Logs | `list_console_messages()` | If console dimension |
| Network Requests | `list_network_requests()` | If network dimension |
| Failed Requests | `list_network_requests({ resourceTypes: ["xhr", "fetch"] })` | If network dimension |
| Request Details | `get_network_request({ reqid: <id> })` | For failed/suspicious requests |
| Performance Trace | `performance_start_trace()` + reproduce + `performance_stop_trace()` | If performance dimension |
### Step 3.5: Save Evidence Summary
Write `<session>/evidence/evidence-summary.json`:
```json
{
"reproduction_success": true,
"target_url": "<url>",
"steps_executed": ["step1", "step2"],
"evidence_collected": {
"screenshots": ["before-screenshot.png", "after-screenshot.png"],
"snapshots": ["before-snapshot.txt", "after-snapshot.txt"],
"console_errors": [{ "type": "error", "text": "..." }],
"network_failures": [{ "url": "...", "status": 500, "method": "GET" }],
"performance_trace": "trace.json"
},
"observations": ["Error X appeared after step 3", "Network request Y failed"]
}
```
## Phase 4: Report
1. Write evidence summary to session evidence/
2. Send state_update:
```json
{
"status": "task_complete",
"task_id": "REPRODUCE-001",
"ref": "<session>/evidence/evidence-summary.json",
"key_findings": ["Bug reproduced successfully", "3 console errors captured", "1 failed API request"],
"decisions": [],
"verification": "self-validated"
}
```
3. Report: reproduction result, evidence inventory, key observations
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Page fails to load | Retry once, then report navigation error |
| Element not found | Take snapshot, search alternative selectors, report if still not found |
| Bug not reproduced | Report with evidence of non-reproduction, suggest step refinement |
| Browser disconnected | Report error to coordinator |
| Timeout during wait | Capture current state, report partial reproduction |

231
.codex/skills/team-frontend-debug/roles/tester/role.md Normal file
View File

@@ -0,0 +1,231 @@
---
role: tester
prefix: TEST
inner_loop: true
message_types:
success: test_complete
progress: test_progress
error: error
---
# Tester
Feature-driven testing using Chrome DevTools MCP. Proactively discover bugs from feature list.
## Identity
- Tag: [tester] | Prefix: TEST-*
- Responsibility: Parse feature list → generate test scenarios → execute in browser → report discovered issues
## Boundaries
### MUST
- Parse feature list into testable scenarios
- Navigate to each feature's page using Chrome DevTools MCP
- Execute test scenarios with user interaction simulation
- Capture evidence for each test (screenshot, console, network)
- Classify results: pass / fail / warning
- Report all discovered issues with evidence
### MUST NOT
- Modify source code or project files
- Skip features in the list
- Report pass without actually testing
- Make assumptions about expected behavior without evidence
## Phase 2: Parse Feature List + Plan Tests
1. Read upstream artifacts via team_msg(operation="get_state")
2. Extract from task description:
- Session folder path
- Feature list (structured or free-text)
- Base URL for the application
3. Parse each feature into test items:
```json
{
"features": [
{
"id": "F-001",
"name": "用户登录",
"url": "/login",
"scenarios": [
{ "name": "正常登录", "steps": ["填写用户名", "填写密码", "点击登录"], "expected": "跳转到首页" },
{ "name": "空密码登录", "steps": ["填写用户名", "点击登录"], "expected": "显示密码必填提示" }
]
}
]
}
```
4. If feature descriptions lack detail, use page exploration to generate scenarios:
- Navigate to feature URL
- Take snapshot to discover interactive elements
- Generate scenarios from available UI elements (forms, buttons, links)
## Phase 3: Execute Tests
### Inner Loop: Process One Feature at a Time
For each feature in the list:
#### Step 3.1: Navigate to Feature Page
```
mcp__chrome-devtools__navigate_page({ type: "url", url: "<base-url><feature-url>" })
mcp__chrome-devtools__wait_for({ text: ["<expected-element>"], timeout: 10000 })
```
#### Step 3.2: Explore Page Structure
```
mcp__chrome-devtools__take_snapshot()
```
Parse snapshot to identify:
- Interactive elements (buttons, inputs, links, selects)
- Form fields and their labels
- Navigation elements
- Dynamic content areas
If no predefined scenarios, generate test scenarios from discovered elements.
#### Step 3.3: Execute Each Scenario
For each scenario:
1. **Capture baseline**:
```
mcp__chrome-devtools__take_screenshot({ filePath: "<session>/evidence/F-<id>-<scenario>-before.png" })
mcp__chrome-devtools__list_console_messages() // baseline errors
```
2. **Execute steps**:
- Map step descriptions to MCP actions:
| Step Pattern | MCP Action |
|-------------|------------|
| 点击/click XX | `take_snapshot` → find uid → `click({ uid })` |
| 填写/输入/fill XX with YY | `take_snapshot` → find uid → `fill({ uid, value })` |
| 悬停/hover XX | `take_snapshot` → find uid → `hover({ uid })` |
| 等待/wait XX | `wait_for({ text: ["XX"] })` |
| 导航/navigate to XX | `navigate_page({ type: "url", url: "XX" })` |
| 按键/press XX | `press_key({ key: "XX" })` |
| 滚动/scroll | `evaluate_script({ function: "() => window.scrollBy(0, 500)" })` |
3. **Capture result**:
```
mcp__chrome-devtools__take_screenshot({ filePath: "<session>/evidence/F-<id>-<scenario>-after.png" })
mcp__chrome-devtools__list_console_messages({ types: ["error", "warn"] })
mcp__chrome-devtools__list_network_requests({ resourceTypes: ["xhr", "fetch"] })
```
#### Step 3.4: Evaluate Scenario Result
| Check | Pass Condition | Fail Condition |
|-------|---------------|----------------|
| Console errors | No new errors after action | New Error/TypeError/ReferenceError |
| Network requests | All 2xx responses | Any 4xx/5xx response |
| Expected text | Expected text appears on page | Expected text not found |
| Visual state | Page renders without broken layout | Blank area, overflow, missing elements |
| Page responsive | Actions complete within timeout | Timeout or page freeze |
Classify result:
```
pass: All checks pass
fail: Console error OR network failure OR expected behavior not met
warning: Deprecation warnings OR slow response (>3s) OR minor visual issue
```
#### Step 3.5: Report Progress (Inner Loop)
After each feature, send progress via state_update:
```json
{
"status": "in_progress",
"task_id": "TEST-001",
"progress": "3/5 features tested",
"issues_found": 2
}
```
## Phase 4: Test Report
Write `<session>/artifacts/TEST-001-report.md`:
```markdown
# Test Report
## Summary
- **Features tested**: N
- **Passed**: X
- **Failed**: Y
- **Warnings**: Z
- **Test date**: <timestamp>
- **Base URL**: <url>
## Results by Feature
### F-001: <feature-name> — PASS/FAIL/WARNING
**Scenarios:**
| # | Scenario | Result | Issue |
|---|----------|--------|-------|
| 1 | <scenario-name> | PASS | — |
| 2 | <scenario-name> | FAIL | Console TypeError at step 3 |
**Evidence:**
- Screenshot (before): evidence/F-001-scenario1-before.png
- Screenshot (after): evidence/F-001-scenario1-after.png
- Console errors: [list]
- Network failures: [list]
### F-002: ...
## Discovered Issues
| ID | Feature | Severity | Description | Evidence |
|----|---------|----------|-------------|----------|
| BUG-001 | F-001 | High | TypeError on login submit | Console error + screenshot |
| BUG-002 | F-003 | Medium | API returns 500 on save | Network log |
| BUG-003 | F-005 | Low | Deprecation warning in console | Console warning |
```
Write `<session>/artifacts/TEST-001-issues.json`:
```json
{
"issues": [
{
"id": "BUG-001",
"feature": "F-001",
"feature_name": "用户登录",
"severity": "high",
"description": "点击登录按钮后控制台报TypeError",
"category": "javascript_error",
"evidence": {
"console_errors": ["TypeError: Cannot read property 'token' of undefined"],
"screenshot": "evidence/F-001-login-after.png",
"network_failures": []
},
"reproduction_steps": ["导航到/login", "填写用户名admin", "填写密码test", "点击登录按钮"]
}
]
}
```
Send state_update:
```json
{
"status": "task_complete",
"task_id": "TEST-001",
"ref": "<session>/artifacts/TEST-001-report.md",
"key_findings": ["Tested N features", "Found X issues (Y high, Z medium)"],
"decisions": [],
"verification": "tested",
"issues_ref": "<session>/artifacts/TEST-001-issues.json"
}
```
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Feature URL not accessible | Log as failed, continue to next feature |
| Element not found for action | Take snapshot, search alternatives, skip scenario if not found |
| Page crash during test | Capture console, reload, continue next scenario |
| All features pass | Report success, no downstream ANALYZE needed |
| Timeout during interaction | Capture current state, mark as warning, continue |

172
.codex/skills/team-frontend-debug/roles/verifier/role.md Normal file
View File

@@ -0,0 +1,172 @@
---
role: verifier
prefix: VERIFY
inner_loop: false
message_types:
success: verification_result
error: error
---
# Verifier
Fix verification using Chrome DevTools MCP to confirm bug resolution.
## Identity
- Tag: [verifier] | Prefix: VERIFY-*
- Responsibility: Re-execute reproduction steps after fix, verify bug is resolved
## Boundaries
### MUST
- Execute EXACT same reproduction steps as Reproducer
- Capture same evidence types for comparison
- Compare before/after evidence objectively
- Report clear pass/fail verdict
### MUST NOT
- Modify source code or project files
- Skip any reproduction step
- Report pass without evidence comparison
- Make subjective judgments without evidence
## Phase 2: Load Context
1. Read upstream artifacts via team_msg(operation="get_state")
2. Load from multiple upstream roles:
- Reproducer: evidence-summary.json (original evidence + steps)
- Fixer: FIX-001-changes.md (what was changed)
3. Extract:
- Target URL
- Reproduction steps (exact same sequence)
- Original evidence for comparison
- Expected behavior (from bug report)
- Files modified by fixer
## Phase 3: Execute Verification
### Step 3.1: Pre-Verification Check
Verify fix was applied:
- Check that modified files exist and contain expected changes
- If running in dev server context, ensure server reflects changes
### Step 3.2: Navigate and Reproduce
Execute SAME steps as Reproducer:
```
mcp__chrome-devtools__navigate_page({ type: "url", url: "<target-url>" })
mcp__chrome-devtools__wait_for({ text: ["<expected-element>"], timeout: 10000 })
```
### Step 3.3: Capture Post-Fix Evidence
Capture same evidence types as original reproduction:
| Evidence | Tool | Save To |
|----------|------|---------|
| Screenshot | `take_screenshot({ filePath: "<session>/evidence/verify-screenshot.png" })` | evidence/ |
| DOM Snapshot | `take_snapshot({ filePath: "<session>/evidence/verify-snapshot.txt" })` | evidence/ |
| Console Messages | `list_console_messages({ types: ["error", "warn"] })` | In-memory |
| Network Requests | `list_network_requests({ resourceTypes: ["xhr", "fetch"] })` | In-memory |
### Step 3.4: Execute Reproduction Steps
For each step from original reproduction:
1. Execute same action (click, fill, hover, etc.)
2. Observe result
3. Note any differences from original reproduction
### Step 3.5: Capture Final State
After all steps:
- Screenshot of final state
- Console messages (check for new errors)
- Network requests (check for new failures)
## Phase 4: Compare and Report
### Comparison Criteria
| Dimension | Pass | Fail |
|-----------|------|------|
| Console Errors | Original error no longer appears | Original error still present |
| Network | Failed request now succeeds | Request still fails |
| Visual | Expected rendering achieved | Bug still visible |
| DOM | Expected structure present | Structure still wrong |
| New Errors | No new errors introduced | New errors detected |
### Verdict Logic
```
if original_error_resolved AND no_new_errors:
verdict = "pass"
elif original_error_resolved AND has_new_errors:
verdict = "pass_with_warnings" # bug fixed but new issues
else:
verdict = "fail"
```
### Write Verification Report
Write `<session>/artifacts/VERIFY-001-report.md`:
```markdown
# Verification Report
## Verdict: <PASS / PASS_WITH_WARNINGS / FAIL>
## Bug Status
- **Original bug**: <resolved / still present>
- **Reproduction steps**: <all executed / partial>
## Evidence Comparison
### Console Errors
- **Before fix**: <N errors>
- <error 1>
- <error 2>
- **After fix**: <N errors>
- <error 1 if any>
- **Resolution**: <original errors cleared / still present>
### Network Requests
- **Before fix**: <N failed requests>
- **After fix**: <N failed requests>
- **Resolution**: <requests now succeed / still failing>
### Visual Comparison
- **Before fix**: <description or screenshot ref>
- **After fix**: <description or screenshot ref>
- **Resolution**: <visual bug fixed / still present>
## Regression Check
- **New console errors**: <none / list>
- **New network failures**: <none / list>
- **Visual regressions**: <none / description>
## Files Verified
- <file1.ts> — changes confirmed applied
- <file2.tsx> — changes confirmed applied
```
Send state_update:
```json
{
"status": "task_complete",
"task_id": "VERIFY-001",
"ref": "<session>/artifacts/VERIFY-001-report.md",
"key_findings": ["Verdict: <PASS/FAIL>", "Original bug: <resolved/present>"],
"decisions": [],
"verification": "tested",
"verdict": "<pass|pass_with_warnings|fail>"
}
```
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Page fails to load | Retry once, report if still fails |
| Fix not applied | Report to coordinator, suggest re-fix |
| New errors detected | Report pass_with_warnings with details |
| Bug still present | Report fail with evidence comparison |
| Partial reproduction | Report with completed steps, note gaps |

198
.codex/skills/team-frontend-debug/schemas/tasks-schema.md
View File

@@ -1,198 +0,0 @@
# Team Frontend Debug -- CSV Schema
## Master CSV: tasks.csv
### Column Definitions
#### Input Columns (Set by Decomposer)
| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `id` | string | Yes | Unique task identifier (PREFIX-NNN) | `"TEST-001"` |
| `title` | string | Yes | Short task title | `"Feature testing"` |
| `description` | string | Yes | Detailed task description (self-contained) with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | `"PURPOSE: Test all features from list..."` |
| `role` | enum | Yes | Worker role: `tester`, `reproducer`, `analyzer`, `fixer`, `verifier` | `"tester"` |
| `pipeline_mode` | enum | Yes | Pipeline mode: `test-pipeline` or `debug-pipeline` | `"test-pipeline"` |
| `base_url` | string | No | Target URL for browser-based tasks | `"http://localhost:3000"` |
| `evidence_dimensions` | string | No | Semicolon-separated evidence types to collect | `"screenshot;console;network"` |
| `deps` | string | No | Semicolon-separated dependency task IDs | `"TEST-001"` |
| `context_from` | string | No | Semicolon-separated task IDs for context | `"TEST-001"` |
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
#### 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) | `"[TEST-001] Found 3 issues: 2 high, 1 medium..."` |
#### Output Columns (Set by Agent)
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` |
| `findings` | string | Key discoveries (max 500 chars) | `"Tested 5 features: 3 pass, 2 fail. BUG-001: TypeError on login. BUG-002: API 500 on save."` |
| `artifacts_produced` | string | Semicolon-separated paths of produced artifacts | `"artifacts/TEST-001-report.md;artifacts/TEST-001-issues.json"` |
| `issues_count` | string | Number of issues found (tester/analyzer only, empty for others) | `"2"` |
| `verdict` | string | Verification verdict: `pass`, `pass_with_warnings`, `fail` (verifier only) | `"pass"` |
| `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.
---
### Role Prefixes
| Role | Prefix | Pipeline | Inner Loop |
|------|--------|----------|------------|
| tester | TEST | test-pipeline | Yes (iterates over features) |
| reproducer | REPRODUCE | debug-pipeline | No |
| analyzer | ANALYZE | both | No |
| fixer | FIX | both | Yes (may need multiple fix passes) |
| verifier | VERIFY | both | No |
---
### Example Data (Test Pipeline)
```csv
id,title,description,role,pipeline_mode,base_url,evidence_dimensions,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,issues_count,verdict,error
"TEST-001","Feature testing","PURPOSE: Test all features from feature list and discover issues | Success: All features tested with pass/fail results\nTASK:\n- Parse feature list\n- Navigate to each feature URL using Chrome DevTools\n- Execute test scenarios (click, fill, hover)\n- Capture evidence: screenshots, console logs, network requests\n- Classify results: pass/fail/warning\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-login-test-20260308\n- Base URL: http://localhost:3000\n- Features: Login, Dashboard, Profile\nEXPECTED: artifacts/TEST-001-report.md + artifacts/TEST-001-issues.json\nCONSTRAINTS: Chrome DevTools MCP only | No code modifications","tester","test-pipeline","http://localhost:3000","screenshot;console;network","","","csv-wave","1","pending","","","","",""
"ANALYZE-001","Root cause analysis","PURPOSE: Analyze discovered issues to identify root causes | Success: RCA for each high/medium issue\nTASK:\n- Load test report and issues list\n- Analyze console errors, network failures, DOM anomalies\n- Map to source code locations\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-login-test-20260308\n- Upstream: artifacts/TEST-001-issues.json\nEXPECTED: artifacts/ANALYZE-001-rca.md","analyzer","test-pipeline","","console;network","TEST-001","TEST-001","csv-wave","2","pending","","","","",""
"FIX-001","Fix all issues","PURPOSE: Fix identified issues | Success: All high/medium issues resolved\nTASK:\n- Load RCA report\n- Locate and fix each root cause\n- Run syntax/type checks\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-login-test-20260308\n- Upstream: artifacts/ANALYZE-001-rca.md\nEXPECTED: Modified source files + artifacts/FIX-001-changes.md","fixer","test-pipeline","","","ANALYZE-001","ANALYZE-001","csv-wave","3","pending","","","","",""
"VERIFY-001","Verify fixes","PURPOSE: Re-test failed scenarios to verify fixes | Success: Previously failed scenarios now pass\nTASK:\n- Re-execute failed test scenarios\n- Capture evidence and compare\n- Report pass/fail per scenario\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-login-test-20260308\n- Original: artifacts/TEST-001-report.md\n- Fix: artifacts/FIX-001-changes.md\nEXPECTED: artifacts/VERIFY-001-report.md","verifier","test-pipeline","http://localhost:3000","screenshot;console;network","FIX-001","FIX-001;TEST-001","csv-wave","4","pending","","","","",""
```
### Example Data (Debug Pipeline)
```csv
id,title,description,role,pipeline_mode,base_url,evidence_dimensions,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,issues_count,verdict,error
"REPRODUCE-001","Bug reproduction","PURPOSE: Reproduce bug and collect evidence | Success: Bug reproduced with artifacts\nTASK:\n- Navigate to target URL\n- Execute reproduction steps\n- Capture screenshots, snapshots, console logs, network\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-save-crash-20260308\n- Bug URL: http://localhost:3000/settings\n- Steps: 1. Click save 2. Observe white screen\nEXPECTED: evidence/ directory with all captures","reproducer","debug-pipeline","http://localhost:3000/settings","screenshot;console;network;snapshot","","","csv-wave","1","pending","","","","",""
"ANALYZE-001","Root cause analysis","PURPOSE: Analyze evidence to find root cause | Success: RCA with file:line location\nTASK:\n- Load evidence from reproducer\n- Analyze console errors and stack traces\n- Map to source code\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-save-crash-20260308\n- Upstream: evidence/\nEXPECTED: artifacts/ANALYZE-001-rca.md","analyzer","debug-pipeline","","","REPRODUCE-001","REPRODUCE-001","csv-wave","2","pending","","","","",""
"FIX-001","Code fix","PURPOSE: Fix the identified bug | Success: Root cause resolved\nTASK:\n- Load RCA report\n- Implement fix\n- Validate syntax\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-save-crash-20260308\n- Upstream: artifacts/ANALYZE-001-rca.md\nEXPECTED: Modified files + artifacts/FIX-001-changes.md","fixer","debug-pipeline","","","ANALYZE-001","ANALYZE-001","csv-wave","3","pending","","","","",""
"VERIFY-001","Fix verification","PURPOSE: Verify bug is fixed | Success: Original bug no longer reproduces\nTASK:\n- Same reproduction steps as REPRODUCE-001\n- Capture evidence and compare\n- Confirm resolution\nCONTEXT:\n- Session: .workflow/.csv-wave/tfd-save-crash-20260308\n- Original: evidence/\n- Fix: artifacts/FIX-001-changes.md\nEXPECTED: artifacts/VERIFY-001-report.md","verifier","debug-pipeline","http://localhost:3000/settings","screenshot;console;network;snapshot","FIX-001","FIX-001;REPRODUCE-001","csv-wave","4","pending","","","","",""
```
---
### Column Lifecycle
```
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
--------------------- -------------------- -----------------
id ----------> id ----------> id
title ----------> title ----------> (reads)
description ----------> description ----------> (reads)
role ----------> role ----------> (reads)
pipeline_mode ---------> pipeline_mode ---------> (reads)
base_url ----------> base_url ----------> (reads)
evidence_dimensions ---> evidence_dimensions ---> (reads)
deps ----------> deps ----------> (reads)
context_from----------> context_from----------> (reads)
exec_mode ----------> exec_mode ----------> (reads)
wave ----------> (reads)
prev_context ----------> (reads)
status
findings
artifacts_produced
issues_count
verdict
error
```
---
## Output Schema (JSON)
Agent output via `report_agent_job_result` (csv-wave tasks):
Tester output:
```json
{
"id": "TEST-001",
"status": "completed",
"findings": "Tested 5 features: 3 pass, 2 fail. BUG-001: TypeError on login submit. BUG-002: API 500 on profile save.",
"artifacts_produced": "artifacts/TEST-001-report.md;artifacts/TEST-001-issues.json",
"issues_count": "2",
"verdict": "",
"error": ""
}
```
Verifier output:
```json
{
"id": "VERIFY-001",
"status": "completed",
"findings": "Original bug resolved. Login error no longer appears. No new console errors. No new network failures.",
"artifacts_produced": "artifacts/VERIFY-001-report.md",
"issues_count": "",
"verdict": "pass",
"error": ""
}
```
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
---
## Discovery Types
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `feature_tested` | `data.feature` | `{feature, name, result, issues}` | Feature test result |
| `bug_reproduced` | `data.url` | `{url, steps, console_errors, network_failures}` | Bug reproduction result |
| `evidence_collected` | `data.dimension+data.file` | `{dimension, file, description}` | Evidence artifact saved |
| `root_cause_found` | `data.file+data.line` | `{category, file, line, confidence}` | Root cause identified |
| `file_modified` | `data.file` | `{file, change, lines_added}` | Code fix applied |
| `verification_result` | `data.verdict` | `{verdict, original_error_resolved, new_errors}` | Fix verification |
| `issue_found` | `data.file+data.line` | `{file, line, severity, description}` | Issue discovered |
### Discovery NDJSON Format
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"TEST-001","type":"feature_tested","data":{"feature":"F-001","name":"Login","result":"fail","issues":1}}
{"ts":"2026-03-08T10:05:00Z","worker":"REPRODUCE-001","type":"bug_reproduced","data":{"url":"/settings","steps":3,"console_errors":2,"network_failures":0}}
{"ts":"2026-03-08T10:10:00Z","worker":"ANALYZE-001","type":"root_cause_found","data":{"category":"TypeError","file":"src/components/Settings.tsx","line":142,"confidence":"high"}}
{"ts":"2026-03-08T10:15:00Z","worker":"FIX-001","type":"file_modified","data":{"file":"src/components/Settings.tsx","change":"Added null check for user object","lines_added":3}}
```
> 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 in {pending, completed, failed, skipped} | "Invalid status: {status}" |
| Role valid | role in {tester, reproducer, analyzer, fixer, verifier} | "Invalid role: {role}" |
| Pipeline mode valid | pipeline_mode in {test-pipeline, debug-pipeline} | "Invalid pipeline_mode: {mode}" |
| Verdict valid | verdict in {pass, pass_with_warnings, fail, ""} | "Invalid verdict: {verdict}" |
| Base URL for browser tasks | tester/reproducer/verifier have non-empty base_url | "Missing base_url for browser task: {id}" |

215
.codex/skills/team-frontend-debug/specs/debug-tools.md Normal file
View File

@@ -0,0 +1,215 @@
# Chrome DevTools MCP Usage Patterns
Reference for debug tool usage across all roles. Reproducer and Verifier are primary consumers.
## 1. Navigation & Page Control
### Navigate to URL
```
mcp__chrome-devtools__navigate_page({ type: "url", url: "http://localhost:3000/page" })
```
### Wait for Page Load
```
mcp__chrome-devtools__wait_for({ text: ["Expected Text"], timeout: 10000 })
```
### Reload Page
```
mcp__chrome-devtools__navigate_page({ type: "reload" })
```
### List Open Pages
```
mcp__chrome-devtools__list_pages()
```
### Select Page
```
mcp__chrome-devtools__select_page({ pageId: 0 })
```
## 2. User Interaction Simulation
### Click Element
```
// First take snapshot to find uid
mcp__chrome-devtools__take_snapshot()
// Then click by uid
mcp__chrome-devtools__click({ uid: "<uid-from-snapshot>" })
```
### Fill Input
```
mcp__chrome-devtools__fill({ uid: "<uid>", value: "input text" })
```
### Fill Multiple Fields
```
mcp__chrome-devtools__fill_form({
elements: [
{ uid: "<uid1>", value: "value1" },
{ uid: "<uid2>", value: "value2" }
]
})
```
### Hover Element
```
mcp__chrome-devtools__hover({ uid: "<uid>" })
```
### Press Key
```
mcp__chrome-devtools__press_key({ key: "Enter" })
mcp__chrome-devtools__press_key({ key: "Control+A" })
```
### Type Text
```
mcp__chrome-devtools__type_text({ text: "typed content", submitKey: "Enter" })
```
## 3. Evidence Collection
### Screenshot
```
// Full viewport
mcp__chrome-devtools__take_screenshot({ filePath: "<session>/evidence/screenshot.png" })
// Full page
mcp__chrome-devtools__take_screenshot({ filePath: "<path>", fullPage: true })
// Specific element
mcp__chrome-devtools__take_screenshot({ uid: "<uid>", filePath: "<path>" })
```
### DOM/A11y Snapshot
```
// Standard snapshot
mcp__chrome-devtools__take_snapshot()
// Verbose (all a11y info)
mcp__chrome-devtools__take_snapshot({ verbose: true })
// Save to file
mcp__chrome-devtools__take_snapshot({ filePath: "<session>/evidence/snapshot.txt" })
```
### Console Messages
```
// All messages
mcp__chrome-devtools__list_console_messages()
// Errors and warnings only
mcp__chrome-devtools__list_console_messages({ types: ["error", "warn"] })
// Get specific message detail
mcp__chrome-devtools__get_console_message({ msgid: 5 })
```
### Network Requests
```
// All requests
mcp__chrome-devtools__list_network_requests()
// XHR/Fetch only (API calls)
mcp__chrome-devtools__list_network_requests({ resourceTypes: ["xhr", "fetch"] })
// Get request detail (headers, body, response)
mcp__chrome-devtools__get_network_request({ reqid: 3 })
// Save response to file
mcp__chrome-devtools__get_network_request({ reqid: 3, responseFilePath: "<path>" })
```
### Performance Trace
```
// Start trace (auto-reload and auto-stop)
mcp__chrome-devtools__performance_start_trace({ reload: true, autoStop: true })
// Start manual trace
mcp__chrome-devtools__performance_start_trace({ reload: false, autoStop: false })
// Stop and save
mcp__chrome-devtools__performance_stop_trace({ filePath: "<session>/evidence/trace.json" })
```
## 4. Script Execution
### Evaluate JavaScript
```
// Get page title
mcp__chrome-devtools__evaluate_script({ function: "() => document.title" })
// Get element state
mcp__chrome-devtools__evaluate_script({
function: "(el) => ({ text: el.innerText, classes: el.className })",
args: ["<uid>"]
})
// Check React state (if applicable)
mcp__chrome-devtools__evaluate_script({
function: "() => { const fiber = document.querySelector('#root')._reactRootContainer; return fiber ? 'React detected' : 'No React'; }"
})
// Get computed styles
mcp__chrome-devtools__evaluate_script({
function: "(el) => JSON.stringify(window.getComputedStyle(el))",
args: ["<uid>"]
})
```
## 5. Common Debug Patterns
### Pattern: Reproduce Click Bug
```
1. navigate_page → target URL
2. wait_for → page loaded
3. take_snapshot → find target element uid
4. take_screenshot → before state
5. list_console_messages → baseline errors
6. click → target element
7. wait_for → expected result (or timeout)
8. take_screenshot → after state
9. list_console_messages → new errors
10. list_network_requests → triggered requests
```
### Pattern: Debug API Error
```
1. navigate_page → target URL
2. wait_for → page loaded
3. take_snapshot → find trigger element
4. click/fill → trigger API call
5. list_network_requests → find the API request
6. get_network_request → inspect headers, body, response
7. list_console_messages → check for error handling
```
### Pattern: Debug Performance Issue
```
1. navigate_page → target URL (set URL first)
2. performance_start_trace → start recording with reload
3. (auto-stop after page loads)
4. Read trace results → identify long tasks, bottlenecks
```
### Pattern: Debug Visual/CSS Issue
```
1. navigate_page → target URL
2. take_screenshot → capture current visual state
3. take_snapshot({ verbose: true }) → full a11y tree with styles
4. evaluate_script → get computed styles of problematic element
5. Compare expected vs actual styles
```
## 6. Error Handling
| Error | Meaning | Resolution |
|-------|---------|------------|
| "No page selected" | No browser tab active | list_pages → select_page |
| "Element not found" | uid is stale | take_snapshot → get new uid |
| "Navigation timeout" | Page didn't load | Check URL, retry with longer timeout |
| "Evaluation failed" | JS error in script | Check script syntax, page context |
| "No trace recording" | stop_trace without start | Ensure start_trace was called first |

94
.codex/skills/team-frontend-debug/specs/pipelines.md Normal file
View File

@@ -0,0 +1,94 @@
# Pipeline Definitions
## 1. Pipeline Selection Criteria
| Keywords | Pipeline |
|----------|----------|
| 功能, feature, 清单, list, 测试, test, 完成, done, 验收 | `test-pipeline` |
| bug, 错误, 报错, crash, 问题, 不工作, 白屏, 异常 | `debug-pipeline` |
| performance, 性能, slow, 慢, latency, memory | `debug-pipeline` (perf dimension) |
| Ambiguous / unclear | request_user_input |
## 2. Test Pipeline (Feature-List Driven)
**4 tasks, linear with conditional skip**
```
TEST-001 → [issues found?] → ANALYZE-001 → FIX-001 → VERIFY-001
|
└─ no issues → Pipeline Complete (skip ANALYZE/FIX/VERIFY)
```
| Task | Role | Description | Conditional |
|------|------|-------------|-------------|
| TEST-001 | tester | Test all features, discover issues | Always |
| ANALYZE-001 | analyzer | Analyze discovered issues, produce RCA | Skip if 0 issues |
| FIX-001 | fixer | Fix all identified root causes | Skip if 0 issues |
| VERIFY-001 | verifier | Re-test failed scenarios to verify fixes | Skip if 0 issues |
### Conditional Skip Logic
After TEST-001 completes, coordinator reads `TEST-001-issues.json`:
- `issues.length === 0` → All pass. Skip downstream tasks, report success.
- `issues.filter(i => i.severity !== "low").length === 0` → Only warnings. request_user_input: fix or complete.
- `issues.filter(i => i.severity === "high" || i.severity === "medium").length > 0` → Proceed with ANALYZE → FIX → VERIFY.
### Re-Fix Iteration
If VERIFY-001 reports failures:
- Create FIX-002 (blockedBy: VERIFY-001) → VERIFY-002 (blockedBy: FIX-002)
- Max 3 fix iterations
## 3. Debug Pipeline (Bug-Report Driven)
**4 tasks, linear with iteration support**
```
REPRODUCE-001 → ANALYZE-001 → FIX-001 → VERIFY-001
↑ |
| (if fail) |
+--- REPRODUCE-002 ←----+
```
| Task | Role | Description |
|------|------|-------------|
| REPRODUCE-001 | reproducer | Reproduce bug, collect evidence |
| ANALYZE-001 | analyzer | Analyze evidence, produce RCA report |
| FIX-001 | fixer | Implement code fix based on RCA |
| VERIFY-001 | verifier | Verify fix with same reproduction steps |
### Iteration Rules
- **Analyzer → Reproducer**: If Analyzer confidence < 50%, creates REPRODUCE-002 → ANALYZE-002
- **Verifier → Fixer**: If Verifier verdict = fail, creates FIX-002 → VERIFY-002
### Maximum Iterations
- Max reproduction iterations: 2
- Max fix iterations: 3
- After max iterations: report to user for manual intervention
## 4. Task Metadata Registry
| Task ID | Role | Pipeline | Depends On | Priority |
|---------|------|----------|------------|----------|
| TEST-001 | tester | test | - | P0 |
| REPRODUCE-001 | reproducer | debug | - | P0 |
| ANALYZE-001 | analyzer | both | TEST-001 or REPRODUCE-001 | P0 |
| FIX-001 | fixer | both | ANALYZE-001 | P0 |
| VERIFY-001 | verifier | both | FIX-001 | P0 |
| REPRODUCE-002 | reproducer | debug | (dynamic) | P0 |
| ANALYZE-002 | analyzer | debug | REPRODUCE-002 | P0 |
| FIX-002 | fixer | both | VERIFY-001 | P0 |
| VERIFY-002 | verifier | both | FIX-002 | P0 |
## 5. Evidence Types Registry
| Dimension | Evidence | MCP Tool | Collector Roles |
|-----------|----------|----------|----------------|
| Visual | Screenshots | take_screenshot | tester, reproducer, verifier |
| DOM | A11y snapshots | take_snapshot | tester, reproducer, verifier |
| Console | Error/warn messages | list_console_messages | tester, reproducer, verifier |
| Network | API requests/responses | list/get_network_request | tester, reproducer, verifier |
| Performance | Trace recording | performance_start/stop_trace | reproducer, verifier |
| Interaction | User actions | click/fill/hover | tester, reproducer, verifier |

811
.codex/skills/team-frontend/SKILL.md
View File

@@ -1,750 +1,129 @@
---
name: team-frontend
description: Frontend development team with built-in ui-ux-pro-max design intelligence. Covers requirement analysis, design system generation, frontend implementation, and quality assurance. CSV wave pipeline with interactive QA gates.
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"frontend task description\""
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
description: Unified team skill for frontend development. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), WebFetch(*), WebSearch(*), mcp__ace-tool__search_context(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults for scope/industry/constraints.
# Team Frontend Development
## Usage
Unified team skill: frontend development with built-in ui-ux-pro-max design intelligence. Covers requirement analysis, design system generation, frontend implementation, and quality assurance. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from role.md specs.
```bash
$team-frontend "Build a SaaS dashboard with user management and analytics"
$team-frontend -c 3 "Create a healthcare patient portal with WCAG AA compliance"
$team-frontend -y "Implement e-commerce product listing page with dark mode"
$team-frontend --continue "fe-saas-dashboard-20260308"
```
**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
Unified frontend development team: analyze requirements, retrieve design intelligence (ui-ux-pro-max), generate design token system, architect components, implement code, and run 5-dimension quality audit. Roles: analyst, architect, developer, qa -- dynamically assigned as CSV wave tasks with dependency ordering. Supports page (4-task), feature (5-task), and system (7-task) pipeline modes.
**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
## Architecture
```
+-------------------------------------------------------------------+
| TEAM FRONTEND WORKFLOW |
+-------------------------------------------------------------------+
| |
| Phase 0: Pre-Wave Interactive (Requirement Clarification) |
| +- Parse frontend task description |
| +- Select scope (page/feature/system), industry, constraints |
| +- Output: refined requirements for decomposition |
| |
| Phase 1: Requirement -> CSV + Classification |
| +- Signal detection: keyword scan -> capability inference |
| +- Pipeline selection (page: 4-task, feature: 5-task, system) |
| +- Dependency graph from pipeline definition |
| +- Classify tasks: csv-wave | interactive (exec_mode) |
| +- Compute dependency waves (topological sort) |
| +- 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 (if any) |
| | +- 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 (if any) |
| | +- Merge all results into master tasks.csv |
| | +- Check: any failed? -> skip dependents |
| | +- GC Loop: if QA fails, create DEV-fix + QA-recheck |
| +- discoveries.ndjson shared across all modes (append-only) |
| |
| Phase 3: Post-Wave Interactive (Completion Action) |
| +- Pipeline completion report with deliverables listing |
| +- Interactive completion choice (Archive/Keep/Export) |
| +- Final aggregation / report |
| |
| Phase 4: 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 |
| |
+-------------------------------------------------------------------+
Skill(skill="team-frontend", args="task description")
|
SKILL.md (this file) = Router
|
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-- analyze -> dispatch -> spawn workers -> STOP
|
+-------+-------+-------+
v v v v
[analyst] [architect] [developer] [qa]
(team-worker agents, each loads roles/<role>/role.md)
```
---
## Role Registry
## Task Classification Rules
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYZE-* | false |
| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | false |
| developer | [roles/developer/role.md](roles/developer/role.md) | DEV-* | true |
| qa | [roles/qa/role.md](roles/qa/role.md) | QA-* | false |
Each task is classified by `exec_mode`:
## Role Router
| 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, revision cycles, user approval |
Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → `roles/coordinator/role.md`, execute entry router
**Classification Decision**:
## Shared Constants
| Task Property | Classification |
|---------------|---------------|
| Requirement analysis (analyst) | `csv-wave` |
| Architecture design (architect) | `csv-wave` |
| Code implementation (developer) | `csv-wave` |
| QA audit (qa) | `csv-wave` |
| Architecture review gate (qa approving architecture before dev starts) | `interactive` |
| GC loop revision (developer fixing QA issues) | `csv-wave` |
| Pipeline completion action | `interactive` |
- **Session prefix**: `FE`
- **Session path**: `.workflow/.team/FE-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
---
## Worker Spawn Template
## CSV Schema
### tasks.csv (Master State)
```csv
id,title,description,role,pipeline_mode,scope,review_type,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,qa_score,qa_verdict,error
"ANALYZE-001","Requirement analysis + design intelligence","PURPOSE: Analyze frontend requirements and retrieve design intelligence | Success: design-intelligence.json produced","analyst","feature","full","","","","csv-wave","1","pending","","","","",""
"ARCH-001","Design token system + component architecture","PURPOSE: Define design token system and component specs | Success: design-tokens.json + component specs produced","architect","feature","full","","ANALYZE-001","ANALYZE-001","csv-wave","2","pending","","","","",""
"QA-001","Architecture review","PURPOSE: Review architecture artifacts before development | Success: Architecture approved","qa","feature","full","architecture-review","ARCH-001","ARCH-001","csv-wave","3","pending","","","","",""
```
**Columns**:
| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (PREFIX-NNN format: ANALYZE, ARCH, DEV, QA) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS |
| `role` | Input | Role name: `analyst`, `architect`, `developer`, `qa` |
| `pipeline_mode` | Input | Pipeline: `page`, `feature`, `system` |
| `scope` | Input | Task scope: `full`, `tokens`, `components` |
| `review_type` | Input | QA review type: `architecture-review`, `code-review`, `final` (empty for non-QA) |
| `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` |
| `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) |
| `artifacts_produced` | Output | Semicolon-separated paths of produced artifacts |
| `qa_score` | Output | QA weighted score (0-10, empty for non-QA tasks) |
| `qa_verdict` | Output | QA verdict: `PASSED`, `PASSED_WITH_WARNINGS`, `FIX_REQUIRED` (empty for non-QA) |
| `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 |
|-------|-----------|---------|----------------|----------|
| QA Gate Reviewer | agents/qa-gate-reviewer.md | 2.3 (send_input cycle) | Review QA verdict and handle GC loop decisions | post-wave |
| Completion Handler | agents/completion-handler.md | 2.3 (send_input cycle) | Handle pipeline completion action (Archive/Keep/Export) | standalone |
> **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 4 |
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
| `context.md` | Human-readable execution report | Created in Phase 4 |
| `task-analysis.json` | Phase 0/1 output: capabilities, pipeline, roles | Created in Phase 1 |
| `role-instructions/` | Per-role instruction templates for CSV agents | Created in Phase 1 |
| `artifacts/` | All deliverables: design-intelligence.json, design-tokens.json, component-specs/, QA audits | Created by agents |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
---
## Session Structure
Coordinator spawns workers using this template:
```
.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
+-- task-analysis.json # Phase 1 analysis output
+-- wave-{N}.csv # Temporary per-wave input (csv-wave only)
+-- role-instructions/ # Per-role instruction templates
| +-- analyst.md
| +-- architect.md
| +-- developer.md
| +-- qa.md
+-- artifacts/ # All deliverables
| +-- analysis/
| | +-- design-intelligence.json
| | +-- requirements.md
| +-- architecture/
| | +-- design-tokens.json
| | +-- component-specs/
| | +-- project-structure.md
| +-- qa/
| | +-- audit-001.md
| +-- build/
+-- interactive/ # Interactive task artifacts
| +-- {id}-result.json
+-- wisdom/ # Cross-task knowledge
+-- learnings.md
+-- decisions.md
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: <true|false>
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
---
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
## Implementation
## User Commands
### Session Initialization
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph |
| `resume` / `continue` | Advance to next step |
```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
const requirement = $ARGUMENTS
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
.trim()
const slug = requirement.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = `fe-${slug}-${dateStr}`
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
Bash(`mkdir -p ${sessionFolder}/artifacts/analysis ${sessionFolder}/artifacts/architecture/component-specs ${sessionFolder}/artifacts/qa ${sessionFolder}/artifacts/build ${sessionFolder}/role-instructions ${sessionFolder}/interactive ${sessionFolder}/wisdom`)
Write(`${sessionFolder}/discoveries.ndjson`, '')
Write(`${sessionFolder}/wisdom/learnings.md`, '# Learnings\n')
Write(`${sessionFolder}/wisdom/decisions.md`, '# Decisions\n')
```
---
### Phase 0: Pre-Wave Interactive (Requirement Clarification)
**Objective**: Parse frontend task, clarify scope/industry/constraints, prepare for decomposition.
**Workflow**:
1. **Parse user task description** from $ARGUMENTS
2. **Check for existing sessions** (continue mode):
- Scan `.workflow/.csv-wave/fe-*/tasks.csv` for sessions with pending tasks
- If `--continue`: resume the specified or most recent session, skip to Phase 2
- If active session found: ask user whether to resume or start new
3. **Clarify scope and industry** (skip if AUTO_YES):
**Scope Selection**:
| Option | Pipeline | Task Count |
|--------|----------|------------|
| Single page | page | 4 tasks (linear) |
| Multi-component feature | feature | 5 tasks (with arch review gate) |
| Full frontend system | system | 7 tasks (dual-track parallel) |
**Industry Selection**:
| Option | Strictness |
|--------|------------|
| SaaS/Tech | standard |
| E-commerce/Retail | standard |
| Healthcare/Finance | strict (extra accessibility) |
| Other | standard |
**Design Constraints** (multi-select): Existing design system, WCAG AA, Responsive, Dark mode
4. **Record requirements**: mode, scope, industry, constraints
5. **Signal Detection** for pipeline selection:
| Signal | Keywords | Capability |
|--------|----------|------------|
| Analysis | analyze, requirements, design intelligence | analyst |
| Architecture | design tokens, component architecture, design system | architect |
| Implementation | implement, build, code, develop, page, component | developer |
| Quality | review, audit, quality, test, accessibility | qa |
6. **Complexity Scoring**:
| Factor | Points |
|--------|--------|
| ui-ux-pro-max integration needed | +1 |
| Existing design system detected | +1 |
| Accessibility strict mode (healthcare/finance) | +2 |
| Multiple tech stacks | +2 |
| Dark mode required | +1 |
Results: 1-2 page, 3-4 feature, 5+ system. Default: feature.
**Success Criteria**:
- Scope, industry, constraints determined
- Pipeline mode selected (page/feature/system)
---
### Phase 1: Requirement -> CSV + Classification
**Objective**: Build task dependency graph, generate tasks.csv and per-role instruction templates.
**Decomposition Rules**:
1. **Pipeline Selection** based on scope:
| Scope | Pipeline | Tasks |
|-------|----------|-------|
| page | ANALYZE-001 -> ARCH-001 -> DEV-001 -> QA-001 | 4 |
| feature | ANALYZE-001 -> ARCH-001 -> QA-001(arch) -> DEV-001 -> QA-002(code) | 5 |
| system | ANALYZE-001 -> ARCH-001 -> QA-001(arch) -> [ARCH-002 + DEV-001] -> QA-002 -> DEV-002 -> QA-003(final) | 7 |
2. **Task Description Template**: Every task description uses PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS format (see dispatch.md for full templates)
3. **Role Instruction Generation**: Write per-role instruction templates to `role-instructions/{role}.md` using the base instruction template customized for each role (analyst, architect, developer, qa)
**Classification Rules**:
| Task Property | exec_mode |
|---------------|-----------|
| Analyst analysis pass | `csv-wave` |
| Architect design pass | `csv-wave` |
| Developer implementation pass | `csv-wave` |
| QA audit pass | `csv-wave` |
| All standard pipeline tasks | `csv-wave` |
**Wave Computation**: Kahn's BFS topological sort with depth tracking.
```javascript
// Generate per-role instruction templates
for (const role of ['analyst', 'architect', 'developer', 'qa']) {
const instruction = generateRoleInstruction(role, sessionFolder)
Write(`${sessionFolder}/role-instructions/${role}.md`, instruction)
}
// Generate tasks.csv from pipeline definition
const tasks = buildTasksCsv(pipelineMode, requirement, sessionFolder, industry, constraints)
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
Write(`${sessionFolder}/task-analysis.json`, JSON.stringify(analysisResult, null, 2))
```
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
**Success Criteria**:
- tasks.csv created with valid schema, wave, and exec_mode assignments
- Role instruction templates generated in role-instructions/
- task-analysis.json written
- 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
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
const maxWave = Math.max(...tasks.map(t => t.wave))
let gcRound = 0
const MAX_GC_ROUNDS = 2
for (let wave = 1; wave <= maxWave; wave++) {
console.log(`\nWave ${wave}/${maxWave}`)
// 1. Separate tasks by exec_mode
const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
// 2. Check dependencies -- skip tasks whose deps failed
for (const task of waveTasks) {
const depIds = (task.deps || '').split(';').filter(Boolean)
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
task.status = 'skipped'
task.error = `Dependency failed: ${depIds.filter((id, i) =>
['failed','skipped'].includes(depStatuses[i])).join(', ')}`
}
}
// 3. Execute pre-wave interactive tasks (if any)
const preWaveInteractive = interactiveTasks.filter(t => t.status === 'pending')
for (const task of preWaveInteractive) {
Read(`agents/qa-gate-reviewer.md`)
const agent = spawn_agent({
message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: agents/qa-gate-reviewer.md\n2. Read: ${sessionFolder}/discoveries.ndjson\n\nGoal: ${task.description}\nScope: ${task.title}\nSession: ${sessionFolder}\n\n### Previous Context\n${buildPrevContext(task, tasks)}`
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
if (result.timed_out) {
send_input({ id: agent, message: "Please finalize and output current findings." })
wait({ ids: [agent], timeout_ms: 120000 })
}
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
task_id: task.id, status: "completed", findings: parseFindings(result),
timestamp: getUtc8ISOString()
}))
close_agent({ id: agent })
task.status = 'completed'
task.findings = parseFindings(result)
}
// 4. Build prev_context for csv-wave tasks
const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
for (const task of pendingCsvTasks) {
task.prev_context = buildPrevContext(task, tasks)
}
if (pendingCsvTasks.length > 0) {
// 5. Write wave CSV
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))
// 6. Build instruction per role group
const waveInstruction = buildWaveInstruction(pendingCsvTasks, sessionFolder, wave)
// 7. Execute wave via spawn_agents_on_csv
spawn_agents_on_csv({
csv_path: `${sessionFolder}/wave-${wave}.csv`,
id_column: "id",
instruction: waveInstruction,
max_concurrency: maxConcurrency,
max_runtime_seconds: 900,
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
artifacts_produced: { type: "string" },
qa_score: { type: "string" },
qa_verdict: { type: "string" },
error: { type: "string" }
}
}
})
// 8. Merge results into master CSV
const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
for (const r of results) {
const t = tasks.find(t => t.id === r.id)
if (t) Object.assign(t, r)
}
// 9. GC Loop Check: if a QA task returned FIX_REQUIRED
const qaResults = results.filter(r => r.id.startsWith('QA') && r.qa_verdict === 'FIX_REQUIRED')
for (const qr of qaResults) {
if (gcRound < MAX_GC_ROUNDS) {
gcRound++
// Create DEV-fix and QA-recheck tasks, append to tasks array
const fixId = `DEV-fix-${gcRound}`
const recheckId = `QA-recheck-${gcRound}`
tasks.push({
id: fixId, title: `Fix QA issues (round ${gcRound})`,
description: `PURPOSE: Fix issues from ${qr.id} audit | Success: All critical/high resolved\nTASK:\n- Load QA audit report\n- Fix critical/high issues\n- Re-validate\nCONTEXT:\n- Session: ${sessionFolder}\n- Upstream: ${sessionFolder}/artifacts/qa/\nEXPECTED: Fixed source files\nCONSTRAINTS: Targeted fixes only`,
role: 'developer', pipeline_mode: tasks[0].pipeline_mode, scope: 'full',
review_type: '', deps: qr.id, context_from: qr.id,
exec_mode: 'csv-wave', wave: wave + 1, status: 'pending',
findings: '', artifacts_produced: '', qa_score: '', qa_verdict: '', error: ''
})
tasks.push({
id: recheckId, title: `QA recheck (round ${gcRound})`,
description: `PURPOSE: Re-audit after fixes | Success: Score >= 8, critical == 0\nTASK:\n- Execute 5-dimension audit on fixed code\n- Focus on previously flagged issues\nCONTEXT:\n- Session: ${sessionFolder}\n- Review type: code-review\nEXPECTED: ${sessionFolder}/artifacts/qa/audit-recheck-${gcRound}.md`,
role: 'qa', pipeline_mode: tasks[0].pipeline_mode, scope: 'full',
review_type: 'code-review', deps: fixId, context_from: fixId,
exec_mode: 'csv-wave', wave: wave + 2, status: 'pending',
findings: '', artifacts_produced: '', qa_score: '', qa_verdict: '', error: ''
})
// Extend maxWave
}
}
}
// 10. Update master CSV
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
// 11. Cleanup temp files
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
// 12. Display wave summary
const completed = waveTasks.filter(t => t.status === 'completed').length
const failed = waveTasks.filter(t => t.status === 'failed').length
const skipped = waveTasks.filter(t => t.status === 'skipped').length
console.log(`Wave ${wave} Complete: ${completed} completed, ${failed} failed, ${skipped} skipped`)
}
```
**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
- GC loop (developer <-> qa) handled with max 2 rounds
- discoveries.ndjson accumulated across all waves and mechanisms
---
### Phase 3: Post-Wave Interactive (Completion Action)
**Objective**: Pipeline completion report with deliverables listing and interactive completion choice.
```javascript
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
const completed = tasks.filter(t => t.status === 'completed')
const failed = tasks.filter(t => t.status === 'failed')
// List deliverables
const deliverables = [
{ name: "Design Intelligence", path: `${sessionFolder}/artifacts/analysis/design-intelligence.json` },
{ name: "Requirements", path: `${sessionFolder}/artifacts/analysis/requirements.md` },
{ name: "Design Tokens", path: `${sessionFolder}/artifacts/architecture/design-tokens.json` },
{ name: "Component Specs", path: `${sessionFolder}/artifacts/architecture/component-specs/` },
{ name: "Project Structure", path: `${sessionFolder}/artifacts/architecture/project-structure.md` },
{ name: "QA Audits", path: `${sessionFolder}/artifacts/qa/` }
]
console.log(`
============================================
FRONTEND TEAM COMPLETE
Pipeline: ${completed.length}/${tasks.length} tasks (${tasks[0]?.pipeline_mode} mode)
GC Rounds: ${gcRound}/${MAX_GC_ROUNDS}
Session: ${sessionFolder}
Deliverables:
${deliverables.map(d => ` - ${d.name}: ${d.path}`).join('\n')}
============================================
`)
if (!AUTO_YES) {
request_user_input({
questions: [{
question: "Frontend pipeline complete. Choose next action.",
header: "Done",
id: "completion",
options: [
{ label: "Archive (Recommended)", description: "Archive session, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Export Results", description: "Export design tokens and component specs" }
]
}]
})
}
```
**Success Criteria**:
- Post-wave interactive processing complete
- User informed of deliverables and pipeline status
---
### Phase 4: Results Aggregation
**Objective**: Generate final results and human-readable report.
```javascript
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
let contextMd = `# Frontend Development Report\n\n`
contextMd += `**Session**: ${sessionId}\n`
contextMd += `**Pipeline**: ${tasks[0]?.pipeline_mode} mode\n`
contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n\n`
contextMd += `## Summary\n`
contextMd += `| Status | Count |\n|--------|-------|\n`
contextMd += `| Completed | ${tasks.filter(t => t.status === 'completed').length} |\n`
contextMd += `| Failed | ${tasks.filter(t => t.status === 'failed').length} |\n`
contextMd += `| Skipped | ${tasks.filter(t => t.status === 'skipped').length} |\n\n`
const maxWave = Math.max(...tasks.map(t => t.wave))
contextMd += `## Wave Execution\n\n`
for (let w = 1; w <= maxWave; w++) {
const waveTasks = tasks.filter(t => t.wave === w)
contextMd += `### Wave ${w}\n\n`
for (const t of waveTasks) {
const icon = t.status === 'completed' ? '[DONE]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
contextMd += `${icon} **${t.title}** [${t.role}]`
if (t.qa_score) contextMd += ` Score: ${t.qa_score}/10 (${t.qa_verdict})`
contextMd += ` ${t.findings || ''}\n\n`
}
}
contextMd += `## QA Summary\n\n`
const qaResults = tasks.filter(t => t.role === 'qa' && t.qa_score)
for (const q of qaResults) {
contextMd += `- **${q.id}**: Score ${q.qa_score}/10 - ${q.qa_verdict}\n`
}
Write(`${sessionFolder}/context.md`, contextMd)
console.log(`Results exported to: ${sessionFolder}/results.csv`)
console.log(`Report generated at: ${sessionFolder}/context.md`)
```
**Success Criteria**:
- results.csv exported (all tasks, both modes)
- context.md generated with QA summary
- Summary displayed to user
---
## Shared Discovery Board Protocol
All agents (csv-wave and interactive) share a single `discoveries.ndjson` file for cross-task knowledge exchange.
**Format**: One JSON object per line (NDJSON):
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"ANALYZE-001","type":"tech_stack_detected","data":{"stack":"react","framework":"nextjs","ui_lib":"shadcn"}}
{"ts":"2026-03-08T10:05:00Z","worker":"ARCH-001","type":"token_generated","data":{"category":"color","count":24,"supports_dark_mode":true}}
{"ts":"2026-03-08T10:10:00Z","worker":"DEV-001","type":"file_modified","data":{"file":"src/styles/tokens.css","change":"Generated CSS custom properties","lines_added":85}}
{"ts":"2026-03-08T10:15:00Z","worker":"QA-001","type":"issue_found","data":{"file":"src/components/Button.tsx","line":42,"severity":"high","description":"Missing cursor-pointer on button"}}
```
**Discovery Types**:
| Type | Data Schema | Description |
|------|-------------|-------------|
| `tech_stack_detected` | `{stack, framework, ui_lib}` | Tech stack identified by analyst |
| `design_pattern_found` | `{pattern_name, location, description}` | Existing design pattern in codebase |
| `token_generated` | `{category, count, supports_dark_mode}` | Design token category created |
| `file_modified` | `{file, change, lines_added}` | File change recorded |
| `issue_found` | `{file, line, severity, description}` | QA issue discovered |
| `anti_pattern_violation` | `{pattern, file, line, description}` | Industry anti-pattern detected |
| `artifact_produced` | `{name, path, producer, type}` | Deliverable created |
**Protocol**:
1. Agents MUST read discoveries.ndjson at start of execution
2. Agents MUST append relevant discoveries during execution
3. Agents MUST NOT modify or delete existing entries
4. Deduplication by `{type, data.file}` key
---
## Pipeline Definitions
### Page Mode (4 tasks, linear)
## Session Directory
```
ANALYZE-001 --> ARCH-001 --> DEV-001 --> QA-001
[analyst] [architect] [developer] [qa:code-review]
wave 1 wave 2 wave 3 wave 4
.workflow/.team/FE-<slug>-<YYYY-MM-DD>/
├── .msg/
│ ├── messages.jsonl # Message bus log
│ └── meta.json # Session state + cross-role state
├── task-analysis.json # Coordinator analyze output
├── wisdom/ # Cross-task knowledge
├── analysis/ # Analyst output
│ ├── design-intelligence.json
│ └── requirements.md
├── architecture/ # Architect output
│ ├── design-tokens.json
│ ├── component-specs/
│ └── project-structure.md
├── qa/ # QA output
│ └── audit-<NNN>.md
└── build/ # Developer output
```
### Feature Mode (5 tasks, with architecture review gate)
## Specs Reference
```
ANALYZE-001 --> ARCH-001 --> QA-001 --> DEV-001 --> QA-002
[analyst] [architect] [qa:arch] [developer] [qa:code-review]
wave 1 wave 2 wave 3 wave 4 wave 5
```
### System Mode (7 tasks, dual-track parallel)
```
ANALYZE-001 --> ARCH-001 --> QA-001 --> ARCH-002 --+
[analyst] [architect] [qa:arch] [architect] |
DEV-001 --+--> QA-002 --> DEV-002 --> QA-003
[dev:tokens] [qa] [dev:comp] [qa:final]
wave 1 wave 2 wave 3 wave 4 wave 5 wave 6 wave 7
```
### Generator-Critic Loop (developer <-> qa)
```
developer (Generator) -> QA artifact -> qa (Critic)
<- QA feedback <-
(max 2 rounds)
Convergence: qa.score >= 8 && qa.critical_count === 0
```
---
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
## 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 |
| 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 |
| QA score < 6 over 2 GC rounds | Escalate to user for manual intervention |
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| QA score < 6 over 2 GC rounds | Escalate to user |
| ui-ux-pro-max unavailable | Degrade to LLM general design knowledge |
| Task description too vague | request_user_input for clarification in Phase 0 |
| Continue mode: no session found | List available sessions, prompt user to select |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 0/1
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
7. **Skip on Failure**: If a dependency failed, skip the dependent task
8. **GC Loop Cap**: Max 2 generator-critic rounds between developer and qa
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
---
## Coordinator Role Constraints (Main Agent)
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns
| Worker no response | Report waiting task, suggest user `resume` |
| Pipeline deadlock | Check blockedBy chain, report blocking point |

131
.codex/skills/team-frontend/agents/completion-handler.md
View File

@@ -1,131 +0,0 @@
# Completion Handler Agent
Interactive agent for handling pipeline completion action. Presents deliverables summary and offers Archive/Keep/Export choices.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/completion-handler.md`
- **Responsibility**: Present pipeline results, handle completion choice, execute cleanup or export
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read all task results from master CSV
- Present complete deliverables listing
- Wait for user choice before acting
- Produce structured output following template
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Delete session files without user approval
- Modify task artifacts
- Produce unstructured output
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load task results and artifacts |
| `request_user_input` | built-in | Get user completion choice |
| `Write` | built-in | Store completion result |
| `Bash` | built-in | Execute archive/export operations |
---
## Execution
### Phase 1: Results Loading
**Objective**: Load all task results and build deliverables inventory
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| tasks.csv | Yes | Master state with all task results |
| Artifact files | No | Verify deliverables exist |
**Steps**:
1. Read master tasks.csv
2. Parse all completed tasks and their artifacts
3. Build deliverables inventory
4. Calculate pipeline statistics
**Output**: Deliverables summary ready for user
---
### Phase 2: Completion Choice
**Objective**: Present results and get user action
**Steps**:
1. Display pipeline summary with deliverables
2. Present completion choice:
```javascript
request_user_input({
questions: [{
question: "Frontend pipeline complete. What would you like to do?",
header: "Completion",
id: "completion_action",
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, output final summary" },
{ label: "Keep Active", description: "Keep session for follow-up work" },
{ label: "Export Results", description: "Export design tokens, component specs, and QA audits" }
]
}]
})
```
3. Handle response:
| Response | Action |
|----------|--------|
| Archive & Clean | Mark session as completed, output final summary |
| Keep Active | Mark session as paused, keep all artifacts |
| Export Results | Copy key artifacts to project directory |
**Output**: Completion action result
---
## Structured Output Template
```
## Summary
- Pipeline completed: <task-count> tasks
- Status: <all-pass|with-warnings|with-failures>
- QA final score: <score>/10
## Deliverables
- Design Intelligence: <path>
- Design Tokens: <path>
- Component Specs: <path>
- QA Audits: <path>
- Implementation: <file-count> files
## Action Taken
- Choice: <archive|keep|export>
- Session status: <completed|paused|exported>
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| tasks.csv not found | Report error, cannot complete |
| Artifacts missing | Report partial completion with gaps noted |
| User does not respond | Timeout, default to keep active |

153
.codex/skills/team-frontend/agents/qa-gate-reviewer.md
View File

@@ -1,153 +0,0 @@
# QA Gate Reviewer Agent
Interactive agent for reviewing QA audit verdicts and handling the Generator-Critic (GC) loop decision. Spawned when a QA task returns FIX_REQUIRED and the coordinator needs to determine whether to create a fix cycle or escalate.
## Identity
- **Type**: `interactive`
- **Role File**: `agents/qa-gate-reviewer.md`
- **Responsibility**: Review QA audit verdicts, handle architecture review gates, manage GC loop decisions
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read the QA audit report being reviewed
- Present a clear summary of QA findings to the user
- Wait for user decision before proceeding (if not AUTO_YES)
- Produce structured output following template
- Include file:line references in findings
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Auto-approve FIX_REQUIRED verdicts without checking GC round count
- Modify QA audit artifacts directly
- Produce unstructured output
- Exceed defined scope boundaries
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | built-in | Load QA audit reports and context |
| `request_user_input` | built-in | Get user decision on QA gate |
| `Write` | built-in | Store review result |
### Tool Usage Patterns
**Read Pattern**: Load context files before review
```
Read("<session>/artifacts/qa/audit-*.md")
Read("<session>/discoveries.ndjson")
```
**Write Pattern**: Store review result
```
Write("<session>/interactive/<task-id>-result.json", <result>)
```
---
## Execution
### Phase 1: Context Loading
**Objective**: Load QA audit report and GC loop state
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| QA audit report | Yes | The audit document to review |
| discoveries.ndjson | No | Shared discoveries for context |
| Master CSV (tasks.csv) | No | For GC round tracking |
**Steps**:
1. Extract session path from task assignment
2. Read the QA audit report referenced in the task description
3. Read discoveries.ndjson for additional context
4. Check current GC round count from session state
**Output**: QA verdict summary ready for review
---
### Phase 2: Gate Decision
**Objective**: Determine next action based on QA verdict
**Steps**:
1. Parse QA verdict from audit report:
| Verdict | GC Round | Action |
|---------|----------|--------|
| PASSED | any | Report approved, no fix cycle needed |
| PASSED_WITH_WARNINGS | any | Report approved with warnings noted |
| FIX_REQUIRED | < 2 | Create DEV-fix + QA-recheck tasks |
| FIX_REQUIRED | >= 2 | Escalate to user for manual intervention |
2. If escalation needed, present choice:
```javascript
request_user_input({
questions: [{
question: "QA has flagged issues after 2 fix rounds. How would you like to proceed?",
header: "QA Gate",
id: "qa_gate_decision",
options: [
{ label: "Accept current state (Recommended)", description: "Proceed despite remaining issues" },
{ label: "Manual fix", description: "You will fix the issues manually" },
{ label: "Abort pipeline", description: "Stop the pipeline" }
]
}]
})
```
3. Handle response accordingly
**Output**: Gate decision with action directive
---
## Structured Output Template
```
## Summary
- QA audit reviewed: <audit-id>
- Verdict: <PASSED|PASSED_WITH_WARNINGS|FIX_REQUIRED>
- Score: <score>/10
- Decision: <approved|fix-cycle|escalated|aborted>
## Findings
- Critical issues: <count>
- High issues: <count>
- Medium issues: <count>
- Low issues: <count>
## Decision Details
- GC round: <current>/<max>
- Action: <proceed|create-fix-cycle|escalate|abort>
- User feedback: <if applicable>
## Open Questions
1. Any unresolved items from review
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| QA audit report not found | Report in Open Questions, ask for path |
| GC round state missing | Default to round 0 |
| User does not respond | Timeout, report partial with "awaiting-review" status |
| Processing failure | Output partial results with clear status indicator |

197
.codex/skills/team-frontend/instructions/agent-instruction.md
View File

@@ -1,197 +0,0 @@
# Agent Instruction Template -- Team Frontend
Base instruction template for CSV wave agents. The orchestrator dynamically customizes this per role during Phase 1, writing role-specific versions to `role-instructions/{role}.md`.
## Purpose
| Phase | Usage |
|-------|-------|
| Phase 1 | Coordinator generates per-role instruction from this template |
| Phase 2 | Injected as `instruction` parameter to `spawn_agents_on_csv` |
---
## Base Instruction Template
```markdown
## TASK ASSIGNMENT -- Team Frontend
### 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)
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**Pipeline Mode**: {pipeline_mode}
**Scope**: {scope}
**Review Type**: {review_type}
### Task Description
{description}
### 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 task**: Follow role-specific instructions below
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
- `tech_stack_detected`: {stack, framework, ui_lib} -- Tech stack identification
- `design_pattern_found`: {pattern_name, location, description} -- Existing design pattern
- `token_generated`: {category, count, supports_dark_mode} -- Design token category created
- `file_modified`: {file, change, lines_added} -- File change performed
- `issue_found`: {file, line, severity, description} -- Issue discovered
- `anti_pattern_violation`: {pattern, file, line, description} -- Anti-pattern detected
- `artifact_produced`: {name, path, producer, type} -- Deliverable created
---
## Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key discoveries and implementation notes (max 500 chars)",
"artifacts_produced": "semicolon-separated paths of produced files",
"qa_score": "",
"qa_verdict": "",
"error": ""
}
```
---
## Role-Specific Customization
The coordinator generates per-role instruction variants during Phase 1. Each variant adds role-specific execution guidance to Step 3.
### For Analyst Role
```
3. **Execute**:
- Detect tech stack from package.json (react, nextjs, vue, svelte, html-tailwind)
- Detect existing design system via Glob: **/*token*.*, **/*.css
- Retrieve design intelligence via ui-ux-pro-max skill:
- Full design system: Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")
- UX guidelines: Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")
- Tech stack guide: Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")
- Fallback if skill unavailable: generate from LLM general design knowledge
- Analyze existing codebase patterns (color palette, typography, spacing, components)
- Optional: WebSearch for "<industry> web design trends best practices"
- Compile design-intelligence.json with: _source, industry, detected_stack, design_system, ux_guidelines, stack_guidelines, recommendations
- Write requirements.md summarizing all requirements
- Output to <session-folder>/artifacts/analysis/
```
### For Architect Role
```
3. **Execute**:
- Load design-intelligence.json from analyst output
- Generate design token system (design-tokens.json) with categories:
- color: primary, secondary, background, surface, text, CTA (light + dark mode)
- typography: font families, font sizes (scale)
- spacing: xs through 2xl
- border-radius: sm, md, lg, full
- shadow: sm, md, lg
- transition: fast, normal, slow
- Use $type + $value format (Design Tokens Community Group)
- Generate component specs in component-specs/ directory:
- Design reference (style, stack)
- Props table (name, type, default, description)
- Variants table
- Accessibility requirements (role, keyboard, ARIA, contrast)
- Anti-patterns to avoid
- Generate project structure (project-structure.md) using stack-specific layout
- Output to <session-folder>/artifacts/architecture/
```
### For Developer Role
```
3. **Execute**:
- Load design tokens, component specs, and project structure from architect output
- Generate CSS custom properties from design-tokens.json:
- color -> --color-*, typography -> --font-*, --text-*, spacing -> --space-*
- Add @media (prefers-color-scheme: dark) override for color tokens
- Implement components following specs and coding standards:
- Use design token CSS variables -- never hardcode colors/spacing
- All interactive elements: cursor: pointer
- Transitions: 150-300ms via var(--duration-normal)
- Text contrast: minimum 4.5:1 ratio
- Include focus-visible styles for keyboard navigation
- Support prefers-reduced-motion
- Responsive: mobile-first with md/lg breakpoints
- No emoji as functional icons
- Self-validate: scan for hardcoded colors, missing cursor-pointer, missing focus styles
- Auto-fix where possible
- Output to src/ directory (codebase files) + implementation summary
```
### For QA Role
```
3. **Execute**:
- Load design intelligence and design tokens for compliance checks
- Collect files to review based on review_type:
- architecture-review: <session>/artifacts/architecture/**/*
- code-review: src/**/*.{tsx,jsx,vue,svelte,html,css}
- final: src/**/*.{tsx,jsx,vue,svelte,html,css}
- Execute 5-dimension audit:
- Dim 1 Code Quality (0.20): file length, console.log, empty catch, unused imports
- Dim 2 Accessibility (0.25): alt text, labels, headings, focus styles, ARIA
- Dim 3 Design Compliance (0.20): hardcoded colors, spacing, anti-patterns
- Dim 4 UX Best Practices (0.20): cursor-pointer, transitions, responsive, states
- Dim 5 Pre-Delivery (0.15): final checklist (code-review/final types only)
- Calculate weighted score: sum(dimension_score * weight)
- Determine verdict: score >= 8 AND critical == 0 -> PASSED; score >= 6 AND critical == 0 -> PASSED_WITH_WARNINGS; else -> FIX_REQUIRED
- Write audit report to <session-folder>/artifacts/qa/
- Set qa_score and qa_verdict in output
```
---
## Quality Requirements
All agents must verify before reporting complete:
| Requirement | Criteria |
|-------------|----------|
| Files produced | Verify all claimed artifacts exist via Read |
| Files modified | Verify content actually changed |
| Findings accuracy | Findings reflect actual work done |
| Discovery sharing | At least 1 discovery shared to board |
| Error reporting | Non-empty error field if status is failed |
| QA fields | qa_score and qa_verdict set for QA role tasks |
---
## Placeholder Reference
| Placeholder | Resolved By | When |
|-------------|------------|------|
| `<session-folder>` | Skill designer (Phase 1) | Literal path baked into instruction |
| `{id}` | spawn_agents_on_csv | Runtime from CSV row |
| `{title}` | spawn_agents_on_csv | Runtime from CSV row |
| `{description}` | spawn_agents_on_csv | Runtime from CSV row |
| `{role}` | spawn_agents_on_csv | Runtime from CSV row |
| `{pipeline_mode}` | spawn_agents_on_csv | Runtime from CSV row |
| `{scope}` | spawn_agents_on_csv | Runtime from CSV row |
| `{review_type}` | spawn_agents_on_csv | Runtime from CSV row |
| `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row |

92
.codex/skills/team-frontend/roles/analyst/role.md Normal file
View File

@@ -0,0 +1,92 @@
---
role: analyst
prefix: ANALYZE
inner_loop: false
message_types:
success: analyze_ready
error: error
---
# Requirements Analyst
Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Industry context | Extracted from task description | Yes |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path, industry type, and tech stack from task description
2. Detect existing design system:
| Signal | Detection Method |
|--------|-----------------|
| Token files | Glob `**/*token*.*` |
| CSS files | Glob `**/*.css` |
| Package.json | Read for framework dependencies |
3. Detect tech stack from package.json:
| Dependency | Stack |
|------------|-------|
| `next` | nextjs |
| `react` | react |
| `vue` | vue |
| `svelte` | svelte |
| `@shadcn/ui` | shadcn |
| (none) | html-tailwind |
4. Load .msg/meta.json for shared state
## Phase 3: Design Intelligence Retrieval
Retrieve design intelligence via ui-ux-pro-max skill integration.
**Step 1: Invoke ui-ux-pro-max** (primary path):
| Action | Invocation |
|--------|------------|
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
**Step 2: Fallback** (if skill unavailable):
- Generate design recommendations from LLM general knowledge
- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
**Step 3: Analyze existing codebase** (if token/CSS files found):
- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
**Step 4: Competitive reference** (optional, if industry is not "Other"):
- `WebSearch({ query: "<industry> web design trends best practices" })`
**Step 5: Compile design-intelligence.json**:
| Field | Source |
|-------|--------|
| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
| `industry` | Task description |
| `detected_stack` | Phase 2 detection |
| `design_system` | Skill output (colors, typography, effects) |
| `ux_guidelines` | Skill UX domain output |
| `stack_guidelines` | Skill stack output |
| `recommendations` | Synthesized: style, anti-patterns, must-have |
**Output files**:
- `<session>/analysis/design-intelligence.json`
- `<session>/analysis/requirements.md`
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| JSON validity | Parse design-intelligence.json | No parse errors |
| Required fields | Check _source, industry, design_system | All present |
| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
| Requirements doc exists | File check | requirements.md written |
Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.

86
.codex/skills/team-frontend/roles/architect/role.md Normal file
View File

@@ -0,0 +1,86 @@
---
role: architect
prefix: ARCH
inner_loop: false
message_types:
success: arch_ready
error: error
---
# Frontend Architect
Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path and scope from task description
2. Load design intelligence from analyst output
3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
4. Detect existing project structure via Glob `src/**/*`
**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
## Phase 3: Architecture Design
**Scope selection**:
| Scope | Output |
|-------|--------|
| `tokens` | Design token system only |
| `components` | Component specs only |
| `full` | Both tokens and components + project structure |
**Step 1: Design Token System** (scope: tokens or full):
Generate `<session>/architecture/design-tokens.json` with categories:
| Category | Content | Source |
|----------|---------|--------|
| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
| `spacing` | xs through 2xl | Standard scale |
| `border-radius` | sm, md, lg, full | Standard scale |
| `shadow` | sm, md, lg | Standard elevation |
| `transition` | fast, normal, slow | Standard durations |
Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
**Step 2: Component Architecture** (scope: components or full):
Generate component specs in `<session>/architecture/component-specs/`:
- Design reference (style, stack)
- Props table (name, type, default, description)
- Variants table
- Accessibility requirements (role, keyboard, ARIA, contrast)
- Anti-patterns to avoid (from design intelligence)
**Step 3: Project Structure** (scope: full):
Generate `<session>/architecture/project-structure.md` with stack-specific layout:
| Stack | Key Directories |
|-------|----------------|
| react | src/components/, src/pages/, src/hooks/, src/styles/ |
| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
| vue | src/components/, src/views/, src/composables/, src/styles/ |
| html-tailwind | src/components/, src/pages/, src/styles/ |
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| JSON validity | Parse design-tokens.json | No errors |
| Required categories | Check color, typography, spacing | All present |
| Anti-pattern compliance | Token values vs anti-patterns | No violations |
| Component specs complete | Each has props + accessibility | All complete |
| File existence | Verify all planned files | All present |
Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.

52
.codex/skills/team-frontend/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,52 @@
# Analyze Task
Parse frontend task -> detect capabilities -> assess pipeline complexity -> design roles.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Role |
|----------|------------|------|
| analyze, requirements, design intelligence | analyst | analyst |
| design tokens, component architecture, design system | architect | architect |
| implement, build, code, develop, page, component | developer | developer |
| review, audit, quality, test, accessibility | qa | qa |
## Pipeline Selection
| Scope Signal | Pipeline |
|--------------|----------|
| single page, landing, simple | page (4-beat) |
| feature, multi-component, complex | feature (5-beat with arch review gate) |
| full system, design system, multiple pages | system (7-beat dual-track) |
Default to `feature` if ambiguous.
## Complexity Scoring
| Factor | Points |
|--------|--------|
| ui-ux-pro-max integration needed | +1 |
| Existing design system detected | +1 |
| Accessibility strict mode (healthcare/finance) | +2 |
| Multiple tech stacks | +2 |
| Dark mode required | +1 |
Results: 1-2 page, 3-4 feature, 5+ system
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<page|feature|system>",
"capabilities": [{ "name": "<cap>", "role": "<role>", "keywords": ["..."] }],
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"industry": "<industry>",
"constraints": [],
"needs_ui_ux_pro_max": true
}
```

151
.codex/skills/team-frontend/roles/coordinator/commands/dispatch.md Normal file
View File

@@ -0,0 +1,151 @@
# Command: Dispatch
Create the frontend development task chain with correct dependencies and structured task descriptions. Supports page, feature, and system pipeline modes.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| User requirement | From coordinator Phase 1 | Yes |
| Session folder | From coordinator Phase 2 | Yes |
| Pipeline mode | From session.json `pipeline_mode` | Yes |
| Industry | From session.json `industry` | Yes |
| Constraints | From session.json `constraints` | No |
1. Load user requirement and scope from session.json
2. Load pipeline mode (page / feature / system) from session.json
3. Load industry and constraints for task descriptions
## Phase 3: Task Chain Creation
### Task Description Template
Every task is a JSON entry in the tasks array, written to `<session>/tasks.json`:
```json
{
"id": "<TASK-ID>",
"subject": "<TASK-ID>",
"description": "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>\nTASK:\n - <step 1: specific action>\n - <step 2: specific action>\n - <step 3: specific action>\nCONTEXT:\n - Session: <session-folder>\n - Industry: <industry>\n - Scope: <scope>\n - Upstream artifacts: <artifact-1>, <artifact-2>\n - Shared memory: <session>/.msg/meta.json\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits, focus areas>",
"status": "pending",
"owner": "<role>",
"blockedBy": ["<dependency-list>"]
}
```
After building all entries, write the full array to `<session>/tasks.json`.
### Mode Router
| Mode | Task Chain |
|------|------------|
| `page` | ANALYZE-001 -> ARCH-001 -> DEV-001 -> QA-001 |
| `feature` | ANALYZE-001 -> ARCH-001 -> QA-001 -> DEV-001 -> QA-002 |
| `system` | ANALYZE-001 -> ARCH-001 -> QA-001 -> [ARCH-002 &#124;&#124; DEV-001] -> QA-002 -> DEV-002 -> QA-003 |
---
### Page Mode Task Chain (4 tasks)
**ANALYZE-001** (analyst):
```json
{
"id": "ANALYZE-001",
"subject": "ANALYZE-001",
"description": "PURPOSE: Analyze frontend requirements and retrieve design intelligence | Success: design-intelligence.json produced with industry-specific recommendations\nTASK:\n - Detect tech stack and existing design system\n - Retrieve design intelligence via ui-ux-pro-max (or LLM fallback)\n - Analyze existing codebase patterns\n - Compile design-intelligence.json and requirements.md\nCONTEXT:\n - Session: <session-folder>\n - Industry: <industry>\n - Scope: <scope>\n - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/analysis/design-intelligence.json + requirements.md | Structured design data\nCONSTRAINTS: Read-only analysis | No code modifications",
"status": "pending",
"owner": "analyst",
"blockedBy": []
}
```
**ARCH-001** (architect):
```json
{
"id": "ARCH-001",
"subject": "ARCH-001",
"description": "PURPOSE: Define design token system and component architecture | Success: design-tokens.json + component specs produced\nTASK:\n - Load design intelligence from analyst output\n - Generate design token system (colors, typography, spacing, shadows)\n - Define component architecture and specs\n - Generate project structure\nCONTEXT:\n - Session: <session-folder>\n - Industry: <industry>\n - Scope: full\n - Upstream artifacts: design-intelligence.json, requirements.md\n - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/architecture/design-tokens.json + component-specs/ + project-structure.md\nCONSTRAINTS: Use ui-ux-pro-max recommendations for token values | Support light/dark mode",
"status": "pending",
"owner": "architect",
"blockedBy": ["ANALYZE-001"]
}
```
**DEV-001** (developer):
```json
{
"id": "DEV-001",
"subject": "DEV-001",
"description": "PURPOSE: Implement frontend page/components from architecture artifacts | Success: All planned files implemented with design token usage\nTASK:\n - Load design tokens, component specs, project structure\n - Generate CSS custom properties from design tokens\n - Implement components following specs and coding standards\n - Self-validate: no hardcoded colors, cursor-pointer, focus styles, responsive\nCONTEXT:\n - Session: <session-folder>\n - Industry: <industry>\n - Scope: full\n - Upstream artifacts: design-tokens.json, component-specs/, project-structure.md\n - Shared memory: <session>/.msg/meta.json\nEXPECTED: src/styles/tokens.css + component files | Design-token compliant code\nCONSTRAINTS: Use CSS variables from tokens | Mobile-first responsive | WCAG AA",
"status": "pending",
"owner": "developer",
"blockedBy": ["ARCH-001"]
}
```
**QA-001** (qa):
```json
{
"id": "QA-001",
"subject": "QA-001",
"description": "PURPOSE: Execute 5-dimension quality audit on implementation | Success: Score >= 8 with 0 critical issues\nTASK:\n - Load design intelligence and tokens for compliance checks\n - Execute 5-dimension audit (code quality, accessibility, design compliance, UX, pre-delivery)\n - Calculate weighted score and determine verdict\n - Write audit report\nCONTEXT:\n - Session: <session-folder>\n - Industry: <industry>\n - Review type: code-review\n - Upstream artifacts: design-intelligence.json, design-tokens.json, src/**\n - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/qa/audit-001.md | Weighted score + verdict + categorized issues\nCONSTRAINTS: Read-only review | No code modifications",
"status": "pending",
"owner": "qa",
"blockedBy": ["DEV-001"]
}
```
---
### Feature Mode Task Chain (5 tasks)
Create ANALYZE-001 and ARCH-001 as page mode above, then:
**QA-001** (qa, architecture review):
- blockedBy: ["ARCH-001"]
- Review type: architecture-review
- Reviews architecture artifacts before developer starts
**DEV-001** (developer):
- blockedBy: ["QA-001"] (waits for arch review to pass)
**QA-002** (qa, code review):
- blockedBy: ["DEV-001"]
- Review type: code-review
---
### System Mode Task Chain (7 tasks)
Create ANALYZE-001, ARCH-001, QA-001 as feature mode above, then:
**ARCH-002** (architect, parallel with DEV-001):
- blockedBy: ["QA-001"]
- Scope: components (refined specs after QA feedback)
**DEV-001** (developer, parallel with ARCH-002):
- blockedBy: ["QA-001"]
- Scope: tokens (CSS generation)
**QA-002** (qa):
- blockedBy: ["ARCH-002"]
- Review type: component-review
**DEV-002** (developer):
- blockedBy: ["QA-002"]
- Scope: components
**QA-003** (qa, final review):
- blockedBy: ["DEV-002"]
- Review type: final
## Phase 4: Validation
| Check | Method | Expected |
|-------|--------|----------|
| Task count correct | Read tasks.json, count entries | page: 4, feature: 5, system: 7 |
| Dependencies correct | Trace dependency graph | Acyclic, correct blockedBy |
| Structured descriptions | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
| Owner assignments correct | Role matches task prefix | ANALYZE->analyst, ARCH->architect, DEV->developer, QA->qa |
If validation fails, fix the specific task entry in tasks.json and re-validate.

188
.codex/skills/team-frontend/roles/coordinator/commands/monitor.md Normal file
View File

@@ -0,0 +1,188 @@
# Command: Monitor
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
- SPAWN_MODE: background
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team-worker
- MAX_GC_ROUNDS: 2
## Handler Router
| Source | Handler |
|--------|---------|
| Message contains [analyst], [architect], [developer], [qa] | handleCallback |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session state | <session>/session.json | Yes |
| Task list | Read `<session>/tasks.json` | Yes |
| Trigger event | From Entry Router detection | Yes |
| Pipeline definition | From SKILL.md | Yes |
1. Load session.json for current state, `pipeline_mode`, `gc_rounds`
2. Read `<session>/tasks.json` to get current task statuses
3. Identify trigger event type from Entry Router
## Phase 3: Event Handlers
### handleCallback
Triggered when a worker sends completion message.
1. Parse message to identify role and task ID:
| Message Pattern | Role Detection |
|----------------|---------------|
| `[analyst]` or task ID `ANALYZE-*` | analyst |
| `[architect]` or task ID `ARCH-*` | architect |
| `[developer]` or task ID `DEV-*` | developer |
| `[qa]` or task ID `QA-*` | qa |
2. Mark task as completed:
Read `<session>/tasks.json`, find entry by id `<task-id>`, set `"status": "completed"`, write back.
3. Record completion in session state
4. Check if checkpoint applies:
| Completed Task | Pipeline Mode | Checkpoint Action |
|---------------|---------------|-------------------|
| ANALYZE-001 | all | Log: analysis ready |
| ARCH-001 | feature/system | Log: architecture ready for review |
| QA-001 (arch review) | feature/system | Gate: pause if critical issues, wait for architect revision |
| QA-* (code review) | all | Check verdict for GC loop (see below) |
5. **GC Loop Check** (when QA completes with fix_required):
| Condition | Action |
|-----------|--------|
| QA verdict = PASSED or PASSED_WITH_WARNINGS | Proceed to handleSpawnNext |
| QA verdict = FIX_REQUIRED AND gc_round < 2 | Create DEV-fix + QA-recheck tasks, increment gc_round |
| QA verdict = FIX_REQUIRED AND gc_round >= 2 | Escalate to user: accept current state or manual intervention |
**GC Fix Task Creation** -- add new entries to `<session>/tasks.json`:
```json
{
"id": "DEV-fix-<round>",
"subject": "DEV-fix-<round>",
"description": "PURPOSE: Fix issues identified in QA audit | Success: All critical/high issues resolved\nTASK:\n - Load QA audit report with findings\n - Address critical and high severity issues\n - Re-validate fixes against coding standards\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: <session>/qa/audit-<NNN>.md\n - Shared memory: <session>/.msg/meta.json\nEXPECTED: Fixed source files | QA issues resolved\nCONSTRAINTS: Targeted fixes only | Do not introduce regressions",
"status": "pending",
"owner": "developer",
"blockedBy": []
}
```
```json
{
"id": "QA-recheck-<round>",
"subject": "QA-recheck-<round>",
"description": "PURPOSE: Re-audit after developer fixes | Success: Score >= 8, critical == 0\nTASK:\n - Execute 5-dimension audit on fixed code\n - Focus on previously flagged issues\n - Calculate new score\nCONTEXT:\n - Session: <session-folder>\n - Review type: code-review\n - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/qa/audit-<NNN>.md | Improved score\nCONSTRAINTS: Read-only review",
"status": "pending",
"owner": "qa",
"blockedBy": ["DEV-fix-<round>"]
}
```
6. Proceed to handleSpawnNext
### handleSpawnNext
Find and spawn the next ready tasks.
1. Scan tasks.json for tasks where:
- Status is "pending"
- All blockedBy tasks have status "completed"
2. For each ready task, spawn team-worker:
```
spawn_agent({
agent_type: "team_worker",
items: [{
description: "Spawn <role> worker for <task-id>",
team_name: "frontend",
name: "<role>",
prompt: `## Role Assignment
role: <role>
role_spec: ~ or <project>/.codex/skills/team-frontend/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: frontend
requirement: <task-description>
inner_loop: <true|false>
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.`
}]
})
```
3. **Parallel spawn rules**:
| Mode | Scenario | Spawn Behavior |
|------|----------|---------------|
| page | Each stage sequential | One worker at a time |
| feature | After QA-001 arch review | Spawn DEV-001 |
| system | After QA-001 arch review | Spawn ARCH-002 + DEV-001 in parallel |
4. STOP after spawning -- use `wait_agent({ ids: [<spawned-agent-ids>] })` to wait for next callback
### handleCheck
Output current pipeline status.
```
Pipeline Status (<mode> mode):
[DONE] ANALYZE-001 (analyst) -> design-intelligence.json
[DONE] ARCH-001 (architect) -> design-tokens.json
[RUN] DEV-001 (developer) -> implementing...
[WAIT] QA-001 (qa) -> blocked by DEV-001
GC Rounds: 0/2
Session: <session-id>
```
Output status -- do NOT advance pipeline.
### handleResume
Resume pipeline after user pause or interruption.
1. Audit tasks.json for inconsistencies:
- Tasks stuck in "in_progress" -> reset to "pending"
- Tasks with completed blockers but still "pending" -> include in spawn list
2. Proceed to handleSpawnNext
### handleComplete
Triggered when all pipeline tasks are completed.
**Completion check**:
| Mode | Completion Condition |
|------|---------------------|
| page | All 4 tasks (+ any GC fix/recheck tasks) completed |
| feature | All 5 tasks (+ any GC fix/recheck tasks) completed |
| system | All 7 tasks (+ any GC fix/recheck tasks) completed |
1. If any tasks not completed, return to handleSpawnNext
2. If all completed, transition to coordinator Phase 5
## Phase 4: State Persistence
After every handler execution:
1. Update session.json with current state (active tasks, gc_rounds, last event)
2. Verify tasks.json consistency
3. STOP and wait for next event

157
.codex/skills/team-frontend/roles/coordinator/role.md Normal file
View File

@@ -0,0 +1,157 @@
# Coordinator Role
Orchestrate team-frontend: analyze -> dispatch -> spawn -> monitor -> report.
## Identity
- Name: coordinator | Tag: [coordinator]
- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
- Follow Command Execution Protocol for dispatch and monitor commands
- Respect pipeline stage dependencies (blockedBy)
- Stop after spawning workers -- wait for callbacks
- Handle GC loops (developer <-> qa) with max 2 iterations
- Execute completion action in Phase 5
### MUST NOT
- Implement domain logic (analyzing, designing, coding, reviewing) -- workers handle this
- Spawn workers without creating tasks first
- Skip architecture review gate when configured (feature/system modes)
- Force-advance pipeline past failed QA review
- Modify source code directly -- delegate to developer worker
## Command Execution Protocol
When coordinator needs to execute a command:
1. Read `commands/<command>.md`
2. Follow the workflow defined in the command
3. Commands are inline execution guides, NOT separate agents
4. Execute synchronously, complete before proceeding
## Entry Router
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains [analyst], [architect], [developer], [qa] | -> handleCallback (monitor.md) |
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
| Interrupted session | Active/paused session in .workflow/.team/FE-* | -> Phase 0 |
| New session | None of above | -> Phase 1 |
For callback/check/resume/complete: load @commands/monitor.md, execute handler, STOP.
## Phase 0: Session Resume Check
1. Scan `.workflow/.team/FE-*/.msg/meta.json` for active/paused sessions
2. No sessions -> Phase 1
3. Single session -> reconcile (audit tasks.json, reset in_progress->pending, rebuild team, kick first ready task)
4. Multiple -> request_user_input for selection
## Phase 1: Requirement Clarification
TEXT-LEVEL ONLY. No source code reading.
1. Parse task description from $ARGUMENTS
2. Delegate to @commands/analyze.md -> produces task-analysis.json
3. Ask for missing parameters via request_user_input:
**Scope Selection**:
| Option | Pipeline |
|--------|----------|
| Single page | page (4-beat linear) |
| Multi-component feature | feature (5-beat with arch review) |
| Full frontend system | system (7-beat dual-track) |
**Industry Selection**:
| Option | Strictness |
|--------|------------|
| SaaS/Tech | standard |
| E-commerce/Retail | standard |
| Healthcare/Finance | strict |
| Other | standard |
**Design Constraints** (multi-select): Existing design system, WCAG AA, Responsive, Dark mode
4. Record requirements: mode, scope, industry, constraints
5. CRITICAL: Always proceed to Phase 2, never skip team workflow
## Phase 2: Session & Team Setup
1. Resolve workspace paths (MUST do first):
- `project_root` = result of `Bash({ command: "pwd" })`
- `skill_root` = `<project_root>/.claude/skills/team-frontend`
3. Generate session ID: `FE-<slug>-<YYYY-MM-DD>`
4. Create session folder structure (replaces TeamCreate):
```
mkdir -p .workflow/.team/<session-id>/{.msg,wisdom,analysis,architecture,qa,build}
```
5. Read specs/pipelines.md -> select pipeline based on scope
6. Register roles in session state
7. Initialize meta.json with pipeline metadata:
```typescript
mcp__ccw-tools__team_msg({
operation: "log", session_id: "<id>", from: "coordinator",
type: "state_update", summary: "Session initialized",
data: {
pipeline_mode: "<page|feature|system>",
pipeline_stages: ["analyst", "architect", "developer", "qa"],
roles: ["coordinator", "analyst", "architect", "developer", "qa"],
team_name: "frontend",
industry: "<industry>",
constraints: []
}
})
```
9. Write session.json
## Phase 3: Task Chain Creation
Delegate to @commands/dispatch.md:
1. Read specs/pipelines.md for selected pipeline task registry
2. Build tasks array as JSON entries in `<session>/tasks.json`; set deps via `blockedBy` field in each entry
3. Update session.json
## Phase 4: Spawn-and-Stop
Delegate to @commands/monitor.md#handleSpawnNext:
1. Find ready tasks (pending + blockedBy resolved)
2. Spawn team-worker agents (see SKILL.md Spawn Template)
3. Output status summary
4. STOP
## Phase 5: Report + Completion Action
1. Load session state -> count completed tasks, calculate duration
2. List deliverables:
| Deliverable | Path |
|-------------|------|
| Design Intelligence | <session>/analysis/design-intelligence.json |
| Requirements | <session>/analysis/requirements.md |
| Design Tokens | <session>/architecture/design-tokens.json |
| Component Specs | <session>/architecture/component-specs/ |
| Project Structure | <session>/architecture/project-structure.md |
| QA Audits | <session>/qa/audit-*.md |
3. Output pipeline summary: task count, duration, QA scores
4. Execute completion action per session.completion_action:
- interactive -> request_user_input (Archive/Keep/Export)
- auto_archive -> Archive & Clean (status=completed, remove/archive session folder)
- auto_keep -> Keep Active (status=paused)
## Error Handling
| Error | Resolution |
|-------|------------|
| Task too vague | request_user_input for clarification |
| Session corruption | Attempt recovery, fallback to manual |
| Worker crash | Reset task to pending, respawn |
| Dependency cycle | Detect in analysis, halt |
| QA score < 6 over 2 GC rounds | Escalate to user |
| ui-ux-pro-max unavailable | Degrade to LLM general design knowledge |

93
.codex/skills/team-frontend/roles/developer/role.md Normal file
View File

@@ -0,0 +1,93 @@
---
role: developer
prefix: DEV
inner_loop: true
message_types:
success: dev_complete
error: error
---
# Frontend Developer
Consume architecture artifacts (design tokens, component specs, project structure) to implement frontend code. Reference design-intelligence.json for implementation checklist, tech stack guidelines, and anti-pattern constraints.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
| Design intelligence | <session>/analysis/design-intelligence.json | No |
| Design tokens | <session>/architecture/design-tokens.json | Yes |
| Component specs | <session>/architecture/component-specs/*.md | No |
| Project structure | <session>/architecture/project-structure.md | No |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path and scope from task description
2. Load design tokens (required -- if missing, report to coordinator)
3. Load design intelligence for anti-patterns and guidelines
4. Load component specs and project structure
5. Detect tech stack from design intelligence `detected_stack`
6. Load .msg/meta.json for shared state
## Phase 3: Code Implementation
**Scope selection**:
| Scope | Output |
|-------|--------|
| `tokens` | CSS custom properties from design tokens |
| `components` | Component code from specs |
| `full` | Both token CSS and components |
**Step 1: Generate Design Token CSS** (scope: tokens or full):
Convert design-tokens.json to `src/styles/tokens.css`:
| JSON Category | CSS Variable Prefix |
|---------------|---------------------|
| color | `--color-` |
| typography.font-family | `--font-` |
| typography.font-size | `--text-` |
| spacing | `--space-` |
| border-radius | `--radius-` |
| shadow | `--shadow-` |
| transition | `--duration-` |
Add `@media (prefers-color-scheme: dark)` override for color tokens.
**Step 2: Implement Components** (scope: components or full):
Implementation strategy by complexity:
| Condition | Strategy |
|-----------|----------|
| <= 2 components | Direct inline Edit/Write |
| 3-5 components | Single batch implementation |
| > 5 components | Group by module, implement per batch |
**Coding standards** (mandatory):
- Use design token CSS variables -- never hardcode colors/spacing
- All interactive elements: `cursor: pointer`
- Transitions: 150-300ms via `var(--duration-normal)`
- Text contrast: minimum 4.5:1 ratio
- Include `focus-visible` styles for keyboard navigation
- Support `prefers-reduced-motion`
- Responsive: mobile-first with md/lg breakpoints
- No emoji as functional icons
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| Hardcoded colors | Scan for hex codes outside tokens.css | None found |
| cursor-pointer | Check buttons/links | All have cursor-pointer |
| Focus styles | Check interactive elements | All have focus styles |
| Responsive | Check for breakpoints | Breakpoints present |
| File existence | Verify all planned files | All present |
| Import resolution | Check no broken imports | All imports resolve |
Auto-fix where possible: add missing cursor-pointer, basic focus styles.
Update .msg/meta.json: merge `component_inventory` key with implemented file list.

79
.codex/skills/team-frontend/roles/qa/role.md Normal file
View File

@@ -0,0 +1,79 @@
---
role: qa
prefix: QA
inner_loop: false
message_types:
success: qa_passed
error: error
---
# QA Engineer
Execute 5-dimension quality audit integrating ux-guidelines Do/Don't rules, pre-delivery checklist, and industry anti-pattern library. Perform CSS-level precise review on architecture artifacts and implementation code.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | From task subject/description | Yes |
| Session path | Extracted from task description | Yes |
| Review type | Extracted from task description | No (default: code-review) |
| Design intelligence | <session>/analysis/design-intelligence.json | No |
| Design tokens | <session>/architecture/design-tokens.json | No |
| .msg/meta.json | <session>/.msg/meta.json | No |
1. Extract session path and review type from task description
2. Load design intelligence (for anti-patterns, must-have rules)
3. Load design tokens (for compliance checks)
4. Load .msg/meta.json (for industry context, strictness level)
5. Collect files to review based on review type:
| Type | Files to Review |
|------|-----------------|
| architecture-review | `<session>/architecture/**/*` |
| token-review | `<session>/architecture/**/*` |
| code-review | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
| final | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
## Phase 3: 5-Dimension Audit
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Code Quality | 0.20 | Structure, naming, maintainability |
| Accessibility | 0.25 | WCAG compliance, keyboard nav, screen reader |
| Design Compliance | 0.20 | Anti-pattern check, design token usage |
| UX Best Practices | 0.20 | Interaction patterns, responsive, animations |
| Pre-Delivery | 0.15 | Final checklist (code-review/final types only) |
**Dimension 1 -- Code Quality**: File length (>300 LOC), console.log, empty catch, unused imports.
**Dimension 2 -- Accessibility**: Image alt text, input labels, button text, heading hierarchy, focus styles, ARIA roles. Strict mode (medical/financial): prefers-reduced-motion required.
**Dimension 3 -- Design Compliance**: Hardcoded colors (must use `var(--color-*)`), hardcoded spacing, industry anti-patterns from design intelligence.
**Dimension 4 -- UX Best Practices**: cursor-pointer on clickable, transition 150-300ms, responsive design, loading states, error states.
**Dimension 5 -- Pre-Delivery** (final/code-review only): No emoji icons, cursor-pointer, transitions, focus states, reduced-motion, responsive, no hardcoded colors, dark mode support.
**Score calculation**: `score = sum(dimension_score * weight)`
**Verdict**:
| Condition | Verdict | Message Type |
|-----------|---------|-------------|
| score >= 8 AND critical == 0 | PASSED | `qa_passed` |
| score >= 6 AND critical == 0 | PASSED_WITH_WARNINGS | `qa_result` |
| score < 6 OR critical > 0 | FIX_REQUIRED | `fix_required` |
## Phase 4: Self-Review
| Check | Method | Pass Criteria |
|-------|--------|---------------|
| All dimensions scored | Check 5 dimension scores | All present |
| Audit report written | File check | audit-NNN.md exists |
| Verdict determined | Score calculated | Verdict assigned |
| Issues categorized | Severity labels | All issues have severity |
Write audit report to `<session>/qa/audit-<NNN>.md` with: summary, dimension scores, issues by severity, passed dimensions.
Update .msg/meta.json: append to `qa_history` array.

188
.codex/skills/team-frontend/schemas/tasks-schema.md
View File

@@ -1,188 +0,0 @@
# Team Frontend -- CSV Schema
## Master CSV: tasks.csv
### Column Definitions
#### Input Columns (Set by Decomposer)
| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `id` | string | Yes | Unique task identifier (PREFIX-NNN) | `"ANALYZE-001"` |
| `title` | string | Yes | Short task title | `"Requirement analysis + design intelligence"` |
| `description` | string | Yes | Detailed task description (self-contained) with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | `"PURPOSE: Analyze frontend requirements..."` |
| `role` | enum | Yes | Worker role: `analyst`, `architect`, `developer`, `qa` | `"analyst"` |
| `pipeline_mode` | enum | Yes | Pipeline mode: `page`, `feature`, `system` | `"feature"` |
| `scope` | enum | Yes | Task scope: `full`, `tokens`, `components` | `"full"` |
| `review_type` | string | No | QA review type: `architecture-review`, `code-review`, `final` (empty for non-QA tasks) | `"code-review"` |
| `deps` | string | No | Semicolon-separated dependency task IDs | `"ANALYZE-001"` |
| `context_from` | string | No | Semicolon-separated task IDs for context | `"ANALYZE-001"` |
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
#### 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) | `"[ANALYZE-001] Detected React + shadcn stack..."` |
#### Output Columns (Set by Agent)
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` |
| `findings` | string | Key discoveries (max 500 chars) | `"Generated 24 color tokens with dark mode..."` |
| `artifacts_produced` | string | Semicolon-separated paths of produced artifacts | `"artifacts/analysis/design-intelligence.json;artifacts/analysis/requirements.md"` |
| `qa_score` | string | QA weighted score 0-10 (empty for non-QA tasks) | `"8.5"` |
| `qa_verdict` | enum | `PASSED`, `PASSED_WITH_WARNINGS`, `FIX_REQUIRED` (empty for non-QA) | `"PASSED"` |
| `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.
---
### Role Prefixes
| Role | Prefix | Responsibility Type |
|------|--------|---------------------|
| analyst | ANALYZE | read-only (analysis + design intelligence retrieval) |
| architect | ARCH | orchestration (design token + component spec generation) |
| developer | DEV | code-gen (implementation from specs) |
| qa | QA | validation (5-dimension quality audit) |
---
### Example Data
```csv
id,title,description,role,pipeline_mode,scope,review_type,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,qa_score,qa_verdict,error
"ANALYZE-001","Requirement analysis","PURPOSE: Analyze frontend requirements and retrieve design intelligence via ui-ux-pro-max | Success: design-intelligence.json produced with industry-specific recommendations\nTASK:\n- Detect tech stack and existing design system\n- Retrieve design intelligence\n- Compile design-intelligence.json and requirements.md\nCONTEXT:\n- Session: .workflow/.csv-wave/fe-saas-dashboard-20260308\n- Industry: saas\nEXPECTED: artifacts/analysis/design-intelligence.json + requirements.md","analyst","feature","full","","","","csv-wave","1","pending","","","","",""
"ARCH-001","Design token system + architecture","PURPOSE: Define design token system and component architecture | Success: design-tokens.json + component specs\nTASK:\n- Load design intelligence from analyst\n- Generate design tokens (colors, typography, spacing, shadows)\n- Define component specs\n- Generate project structure\nCONTEXT:\n- Session: .workflow/.csv-wave/fe-saas-dashboard-20260308\n- Upstream: design-intelligence.json\nEXPECTED: artifacts/architecture/design-tokens.json + component-specs/ + project-structure.md","architect","feature","full","","ANALYZE-001","ANALYZE-001","csv-wave","2","pending","","","","",""
"QA-001","Architecture review","PURPOSE: Review architecture before development | Success: Architecture approved with score >= 8\nTASK:\n- Load design intelligence and tokens\n- Execute 5-dimension audit on architecture\n- Calculate score and verdict\nCONTEXT:\n- Session: .workflow/.csv-wave/fe-saas-dashboard-20260308\n- Review type: architecture-review\nEXPECTED: artifacts/qa/audit-001.md","qa","feature","full","architecture-review","ARCH-001","ARCH-001","csv-wave","3","pending","","","","",""
"DEV-001","Frontend implementation","PURPOSE: Implement frontend from architecture artifacts | Success: All planned files implemented\nTASK:\n- Generate CSS custom properties from design tokens\n- Implement components following specs\n- Self-validate: no hardcoded colors, cursor-pointer, focus styles\nCONTEXT:\n- Session: .workflow/.csv-wave/fe-saas-dashboard-20260308\n- Upstream: design-tokens.json, component-specs/\nEXPECTED: src/styles/tokens.css + component files","developer","feature","full","","QA-001","QA-001;ARCH-001","csv-wave","4","pending","","","","",""
"QA-002","Code review","PURPOSE: Execute 5-dimension quality audit | Success: Score >= 8 with 0 critical issues\nTASK:\n- Execute full audit (code quality, accessibility, design compliance, UX, pre-delivery)\n- Calculate weighted score\nCONTEXT:\n- Session: .workflow/.csv-wave/fe-saas-dashboard-20260308\n- Review type: code-review\nEXPECTED: artifacts/qa/audit-002.md","qa","feature","full","code-review","DEV-001","DEV-001","csv-wave","5","pending","","","","",""
```
---
### Column Lifecycle
```
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
--------------------- -------------------- -----------------
id ----------> id ----------> id
title ----------> title ----------> (reads)
description ----------> description ----------> (reads)
role ----------> role ----------> (reads)
pipeline_mode ---------> pipeline_mode ---------> (reads)
scope ----------> scope ----------> (reads)
review_type ----------> review_type ----------> (reads)
deps ----------> deps ----------> (reads)
context_from----------> context_from----------> (reads)
exec_mode ----------> exec_mode ----------> (reads)
wave ----------> (reads)
prev_context ----------> (reads)
status
findings
artifacts_produced
qa_score
qa_verdict
error
```
---
## Output Schema (JSON)
Agent output via `report_agent_job_result` (csv-wave tasks):
```json
{
"id": "ARCH-001",
"status": "completed",
"findings": "Generated design token system with 24 color tokens (light+dark), 7 typography scales, 6 spacing values. Created 3 component specs: Button, Card, Header. Project structure follows Next.js app router convention.",
"artifacts_produced": "artifacts/architecture/design-tokens.json;artifacts/architecture/component-specs/button.md;artifacts/architecture/project-structure.md",
"qa_score": "",
"qa_verdict": "",
"error": ""
}
```
QA agent output example:
```json
{
"id": "QA-001",
"status": "completed",
"findings": "Architecture review: 8.2/10. Color tokens complete, typography scale follows best practices. Minor: missing border-radius for 'pill' variant.",
"artifacts_produced": "artifacts/qa/audit-001.md",
"qa_score": "8.2",
"qa_verdict": "PASSED",
"error": ""
}
```
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
---
## Discovery Types
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `tech_stack_detected` | `data.stack` | `{stack, framework, ui_lib}` | Tech stack identified |
| `design_pattern_found` | `data.pattern_name+data.location` | `{pattern_name, location, description}` | Existing design pattern |
| `token_generated` | `data.category` | `{category, count, supports_dark_mode}` | Design token category created |
| `file_modified` | `data.file` | `{file, change, lines_added}` | File change recorded |
| `issue_found` | `data.file+data.line` | `{file, line, severity, description}` | QA issue discovered |
| `anti_pattern_violation` | `data.pattern+data.file` | `{pattern, file, line, description}` | Industry anti-pattern detected |
| `artifact_produced` | `data.path` | `{name, path, producer, type}` | Deliverable created |
### Discovery NDJSON Format
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"ANALYZE-001","type":"tech_stack_detected","data":{"stack":"react","framework":"nextjs","ui_lib":"shadcn"}}
{"ts":"2026-03-08T10:05:00Z","worker":"ARCH-001","type":"token_generated","data":{"category":"color","count":24,"supports_dark_mode":true}}
{"ts":"2026-03-08T10:10:00Z","worker":"DEV-001","type":"file_modified","data":{"file":"src/styles/tokens.css","change":"Generated CSS custom properties from design tokens","lines_added":85}}
{"ts":"2026-03-08T10:15:00Z","worker":"QA-001","type":"issue_found","data":{"file":"src/components/Button.tsx","line":42,"severity":"high","description":"Missing cursor-pointer on interactive button element"}}
```
> 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 in {pending, completed, failed, skipped} | "Invalid status: {status}" |
| Role valid | role in {analyst, architect, developer, qa} | "Invalid role: {role}" |
| Pipeline mode valid | pipeline_mode in {page, feature, system} | "Invalid pipeline_mode: {mode}" |
| QA verdict valid | qa_verdict in {PASSED, PASSED_WITH_WARNINGS, FIX_REQUIRED, ""} | "Invalid qa_verdict: {verdict}" |
| Cross-mechanism deps | Interactive to CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |

76
.codex/skills/team-frontend/specs/pipelines.md Normal file
View File

@@ -0,0 +1,76 @@
# Frontend Pipeline Definitions
## Pipeline Modes
### Page Mode (4 beats, linear)
```
ANALYZE-001 --> ARCH-001 --> DEV-001 --> QA-001
[analyst] [architect] [developer] [qa]
```
### Feature Mode (5 beats, with architecture review gate)
```
ANALYZE-001 --> ARCH-001 --> QA-001 --> DEV-001 --> QA-002
[analyst] [architect] [qa:arch] [developer] [qa:code]
```
### System Mode (7 beats, dual-track parallel)
```
ANALYZE-001 --> ARCH-001 --> QA-001 --> ARCH-002 ─┐
[analyst] [architect] [qa:arch] [architect] |
DEV-001 ──┘ --> QA-002 --> DEV-002 --> QA-003
[developer:tokens] [qa] [developer] [qa:final]
```
### Generator-Critic Loop (developer <-> qa)
```
developer (Generator) -> QA artifact -> qa (Critic)
<- QA feedback <-
(max 2 rounds)
Convergence: qa.score >= 8 && qa.critical_count === 0
```
## Task Metadata Registry
| Task ID | Role | Pipeline | Dependencies | Description |
|---------|------|----------|-------------|-------------|
| ANALYZE-001 | analyst | all | (none) | Requirement analysis + design intelligence |
| ARCH-001 | architect | all | ANALYZE-001 | Design token system + component architecture |
| ARCH-002 | architect | system | QA-001 | Component specs refinement |
| DEV-001 | developer | all | ARCH-001 or QA-001 | Frontend implementation |
| DEV-002 | developer | system | QA-002 | Component implementation |
| DEV-fix-N | developer | all | QA-N (GC loop trigger) | Fix issues from QA |
| QA-001 | qa | all | ARCH-001 or DEV-001 | Architecture or code review |
| QA-002 | qa | feature/system | DEV-001 | Code review |
| QA-003 | qa | system | DEV-002 | Final quality check |
| QA-recheck-N | qa | all | DEV-fix-N | Re-audit after developer fixes |
## Pipeline Selection Logic
| Score | Pipeline |
|-------|----------|
| 1-2 | page |
| 3-4 | feature |
| 5+ | system |
Default: feature.
## ui-ux-pro-max Integration
Analyst role invokes ui-ux-pro-max via Skill to obtain industry design intelligence:
| Action | Invocation |
|--------|------------|
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
| Domain search | `Skill(skill="ui-ux-pro-max", args="<query> --domain <domain>")` |
| Tech stack guidance | `Skill(skill="ui-ux-pro-max", args="<query> --stack <stack>")` |
**Supported Domains**: product, style, typography, color, landing, chart, ux, web
**Supported Stacks**: html-tailwind, react, nextjs, vue, svelte, shadcn, swiftui, react-native, flutter
**Fallback**: If ui-ux-pro-max skill not installed, degrade to LLM general design knowledge.

84
.codex/skills/team-frontend/specs/team-config.json Normal file
View File

@@ -0,0 +1,84 @@
{
"team_name": "frontend",
"skill_name": "team-frontend",
"team_display_name": "Frontend Development",
"description": "全栈前端开发团队，内置 ui-ux-pro-max 设计智能。具备需求分析、设计系统生成、前端实现、质量保证的完整能力。",
"pipeline_type": "adaptive",
"roles": [
{
"name": "coordinator",
"task_prefix": null,
"responsibility_type": "Orchestration",
"description": "需求澄清、行业识别、流水线编排、进度监控、GC循环控制",
"message_types": ["task_unblocked", "sync_checkpoint", "fix_required", "error", "shutdown"]
},
{
"name": "analyst",
"task_prefix": "ANALYZE",
"responsibility_type": "Read-only analysis",
"description": "需求分析、调用 ui-ux-pro-max 获取设计智能、行业推理规则匹配",
"message_types": ["analyze_ready", "analyze_progress", "error"]
},
{
"name": "architect",
"task_prefix": "ARCH",
"responsibility_type": "Code generation",
"description": "消费设计智能、定义设计令牌系统、组件架构、技术选型",
"message_types": ["arch_ready", "arch_revision", "arch_progress", "error"]
},
{
"name": "developer",
"task_prefix": "DEV",
"responsibility_type": "Code generation",
"description": "消费架构产出、实现前端组件/页面代码",
"message_types": ["dev_complete", "dev_progress", "error"]
},
{
"name": "qa",
"task_prefix": "QA",
"responsibility_type": "Read-only analysis",
"description": "5维度代码审查：代码质量、可访问性、设计合规、UX最佳实践、Pre-Delivery验证",
"message_types": ["qa_passed", "qa_result", "fix_required", "error"]
}
],
"pipelines": {
"page": {
"description": "单页面开发：分析→架构→开发→质检",
"task_chain": ["ANALYZE-001", "ARCH-001", "DEV-001", "QA-001"],
"collaboration_patterns": ["CP-1", "CP-2"],
"complexity": "low"
},
"feature": {
"description": "多组件特性：分析→架构→质检→开发→质检",
"task_chain": ["ANALYZE-001", "ARCH-001", "QA-001", "DEV-001", "QA-002"],
"collaboration_patterns": ["CP-1", "CP-2", "CP-8"],
"complexity": "medium"
},
"system": {
"description": "完整前端系统：分析→架构→[开发令牌 ∥ 架构组件]→质检→开发组件→最终质检",
"task_chain": ["ANALYZE-001", "ARCH-001", "QA-001", "ARCH-002||DEV-001", "QA-002", "DEV-002", "QA-003"],
"sync_points": ["QA-001", "QA-002"],
"collaboration_patterns": ["CP-1", "CP-2", "CP-8", "CP-9"],
"complexity": "high"
}
},
"uipro_config": {
"search_paths": [
"G:/github_lib/ui-ux-pro-max-skill/src/ui-ux-pro-max",
"../ui-ux-pro-max-skill/src/ui-ux-pro-max",
"./ui-ux-pro-max"
],
"fallback": "LLM general design knowledge",
"data_domains": ["product", "style", "typography", "color", "landing", "chart", "ux", "web"],
"supported_stacks": ["html-tailwind", "react", "nextjs", "vue", "svelte", "shadcn"]
},
"shared_memory_schema": {
"design_intelligence": {},
"design_token_registry": {},
"component_inventory": [],
"style_decisions": [],
"qa_history": [],
"industry_context": {}
},
"generated_at": "2026-02-17T00:00:00+08:00"
}

839
.codex/skills/team-issue/SKILL.md
View File

@@ -1,751 +1,166 @@
---
name: team-issue
description: Hybrid team skill for issue resolution. CSV wave primary for exploration, planning, integration, and implementation. Interactive agents for review gates with fix cycles. Supports Quick, Full, and Batch pipelines.
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--mode=quick|full|batch] \"issue-ids or --all-pending\""
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
description: Unified team skill for issue resolution. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team issue".
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__team_msg(*)
---
## Auto Mode
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
# Team Issue Resolution
## Usage
Orchestrate issue resolution pipeline: explore context -> plan solution -> review (optional) -> marshal queue -> implement. Supports Quick, Full, and Batch pipelines with review-fix cycle.
```bash
$team-issue "ISS-20260308-120000 ISS-20260308-120001"
$team-issue -c 4 "ISS-20260308-120000 --mode=full"
$team-issue -y "--all-pending"
$team-issue --continue "issue-auth-fix-20260308"
```
**Flags**:
- `-y, --yes`: Skip all confirmations (auto mode)
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
- `--continue`: Resume existing session
- `--mode=quick|full|batch`: Force pipeline mode (default: auto-detect)
**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
Orchestrate issue resolution pipeline: explore context, plan solution, review (optional), marshal queue, implement. Supports Quick, Full, and Batch pipelines with review-fix cycle.
**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
## Architecture
```
+---------------------------------------------------------------------------+
| TEAM ISSUE RESOLUTION WORKFLOW |
+---------------------------------------------------------------------------+
| |
| Phase 1: Requirement Parsing + Pipeline Selection |
| +-- Parse issue IDs (GH-\d+, ISS-\d{8}-\d{6}, --all-pending) |
| +-- Auto-detect pipeline mode (quick/full/batch) |
| +-- Determine execution method (codex/gemini/auto) |
| +-- 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 (if any) |
| | +-- 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 (if any) |
| | +-- Merge all results into master tasks.csv |
| | +-- Check: any failed? -> skip dependents |
| +-- discoveries.ndjson shared across all modes (append-only) |
| |
| Phase 3: Post-Wave Interactive (Review Gate) |
| +-- Reviewer agent: multi-dimensional review with verdict |
| +-- Fix cycle: rejected -> revise solution -> re-review (max 2) |
| +-- Final aggregation / report |
| |
| Phase 4: 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 |
| |
+---------------------------------------------------------------------------+
Skill(skill="team-issue", args="<issue-ids> [--mode=<mode>]")
|
SKILL.md (this file) = Router
|
+--------------+--------------+
| |
no --role flag --role <name>
| |
Coordinator Worker
roles/coordinator/role.md roles/<name>/role.md
|
+-- clarify -> dispatch -> spawn workers -> STOP
|
+-------+-------+-------+-------+
v v v v v
[explor] [plann] [review] [integ] [imple]
```
---
## Role Registry
## Task Classification Rules
| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
| explorer | [roles/explorer/role.md](roles/explorer/role.md) | EXPLORE-* | false |
| planner | [roles/planner/role.md](roles/planner/role.md) | SOLVE-* | false |
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | AUDIT-* | false |
| integrator | [roles/integrator/role.md](roles/integrator/role.md) | MARSHAL-* | false |
| implementer | [roles/implementer/role.md](roles/implementer/role.md) | BUILD-* | false |
Each task is classified by `exec_mode`:
## Role Router
| 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, review gates |
Parse `$ARGUMENTS`:
- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` -> `roles/coordinator/role.md`, execute entry router
**Classification Decision**:
## Shared Constants
| Task Property | Classification |
|---------------|---------------|
| Codebase exploration (EXPLORE-*) | `csv-wave` |
| Solution planning (SOLVE-*) | `csv-wave` |
| Queue formation / integration (MARSHAL-*) | `csv-wave` |
| Code implementation (BUILD-*) | `csv-wave` |
| Technical review with verdict (AUDIT-*) | `interactive` |
| Solution revision after rejection (SOLVE-fix-*) | `csv-wave` |
- **Session prefix**: `TISL`
- **Session path**: `.workflow/.team/TISL-<slug>-<date>/`
- **Team name**: `issue`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
---
## Worker Spawn Template
## CSV Schema
### tasks.csv (Master State)
```csv
id,title,description,role,issue_ids,exec_mode,execution_method,deps,context_from,wave,status,findings,artifact_path,error
"EXPLORE-001","Context analysis","Analyze issue context and map codebase impact for ISS-20260308-120000","explorer","ISS-20260308-120000","csv-wave","","","","1","pending","","","",""
"SOLVE-001","Solution design","Design solution and decompose into implementation tasks","planner","ISS-20260308-120000","csv-wave","","EXPLORE-001","EXPLORE-001","2","pending","","","",""
"AUDIT-001","Technical review","Review solution for feasibility, risk, and completeness","reviewer","ISS-20260308-120000","interactive","","SOLVE-001","SOLVE-001","3","pending","","","",""
"MARSHAL-001","Queue formation","Form execution queue with conflict detection","integrator","ISS-20260308-120000","csv-wave","","AUDIT-001","SOLVE-001","4","pending","","","",""
"BUILD-001","Implementation","Implement solution plan and verify with tests","implementer","ISS-20260308-120000","csv-wave","gemini","MARSHAL-001","EXPLORE-001;SOLVE-001","5","pending","","","",""
```
**Columns**:
| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (EXPLORE-NNN, SOLVE-NNN, AUDIT-NNN, MARSHAL-NNN, BUILD-NNN) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description |
| `role` | Input | Worker role: explorer, planner, reviewer, integrator, implementer |
| `issue_ids` | Input | Semicolon-separated issue IDs this task covers |
| `exec_mode` | Input | `csv-wave` or `interactive` |
| `execution_method` | Input | codex, gemini, qwen, or empty (for non-BUILD tasks) |
| `deps` | Input | Semicolon-separated dependency task IDs |
| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
| `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) |
| `artifact_path` | Output | Path to generated artifact (context report, solution, queue, etc.) |
| `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 |
|-------|-----------|---------|----------------|----------|
| reviewer | agents/reviewer.md | 2.3 (structured review) | Multi-dimensional solution review with verdict | post-wave (after SOLVE wave) |
> **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 4 |
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
| `context.md` | Human-readable execution report | Created in Phase 4 |
| `explorations/context-{issueId}.json` | Explorer context reports | Created by explorer agents |
| `solutions/solution-{issueId}.json` | Planner solution plans | Created by planner agents |
| `audits/audit-report.json` | Reviewer audit report | Created by reviewer agent |
| `queue/execution-queue.json` | Integrator execution queue | Created by integrator agent |
| `builds/build-{issueId}.json` | Implementer build results | Created by implementer agents |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
---
## Session Structure
Coordinator spawns workers using this template:
```
.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
+-- wave-{N}.csv # Temporary per-wave input (csv-wave only)
+-- explorations/ # Explorer output
| +-- context-{issueId}.json
+-- solutions/ # Planner output
| +-- solution-{issueId}.json
+-- audits/ # Reviewer output
| +-- audit-report.json
+-- queue/ # Integrator output
| +-- execution-queue.json
+-- builds/ # Implementer output
| +-- build-{issueId}.json
+-- interactive/ # Interactive task artifacts
| +-- {id}-result.json
+-- wisdom/ # Cross-task knowledge
+-- learnings.md
+-- decisions.md
+-- conventions.md
+-- issues.md
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: false
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
---
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
## Implementation
**Parallel spawn** (Batch mode, N explorer or M implementer instances):
### Session Initialization
```
spawn_agent({
agent_type: "team_worker",
items: [
{ type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
agent_name: <role>-<N>
inner_loop: false
```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
{ type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },
const requirement = $ARGUMENTS
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
.trim()
// Parse issue IDs
const issueIdPattern = /(?:GH-\d+|ISS-\d{8}-\d{6})/g
let issueIds = requirement.match(issueIdPattern) || []
// Parse mode override
const modeMatch = requirement.match(/--mode=(\w+)/)
let pipelineMode = modeMatch ? modeMatch[1] : null
// Handle --all-pending
if (requirement.includes('--all-pending')) {
const result = Bash("ccw issue list --status registered,pending --json")
issueIds = JSON.parse(result).map(i => i.id)
}
// If no issue IDs, ask user
if (issueIds.length === 0) {
const answer = request_user_input({
questions: [{
question: "No issue IDs found. Please provide issue IDs.",
header: "Issue IDs",
id: "issue_input",
options: [
{ label: "Enter IDs", description: "Provide issue IDs (e.g., ISS-20260308-120000)" },
{ label: "Cancel", description: "Abort the pipeline" }
]
}]
})
if (answer.answers.issue_input.answers[0] === "Cancel") return
issueIds = answer.answers.issue_input.answers[0].match(issueIdPattern) || []
if (issueIds.length === 0) return // abort
}
// Auto-detect pipeline mode
if (!pipelineMode) {
// Load issue priorities
const priorities = []
for (const id of issueIds) {
const info = JSON.parse(Bash(`ccw issue status ${id} --json`))
priorities.push(info.priority || 0)
}
const hasHighPriority = priorities.some(p => p >= 4)
if (issueIds.length <= 2 && !hasHighPriority) pipelineMode = 'quick'
else if (issueIds.length <= 4) pipelineMode = 'full'
else pipelineMode = 'batch'
}
// Execution method selection
let executionMethod = 'gemini' // default
const execMatch = requirement.match(/--exec=(\w+)/)
if (execMatch) executionMethod = execMatch[1]
const slug = issueIds[0].toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = `issue-${slug}-${dateStr}`
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
Bash(`mkdir -p ${sessionFolder}/{explorations,solutions,audits,queue,builds,interactive,wisdom}`)
Write(`${sessionFolder}/discoveries.ndjson`, `# Discovery Board - ${sessionId}\n# Format: NDJSON\n`)
// Initialize wisdom files
Write(`${sessionFolder}/wisdom/learnings.md`, `# Learnings\n\nAccumulated during ${sessionId}\n`)
Write(`${sessionFolder}/wisdom/decisions.md`, `# Decisions\n\n`)
Write(`${sessionFolder}/wisdom/conventions.md`, `# Conventions\n\n`)
Write(`${sessionFolder}/wisdom/issues.md`, `# Issues\n\n`)
// Store session metadata
Write(`${sessionFolder}/session.json`, JSON.stringify({
session_id: sessionId,
pipeline_mode: pipelineMode,
issue_ids: issueIds,
execution_method: executionMethod,
fix_cycles: 0,
max_fix_cycles: 2,
created_at: getUtc8ISOString()
}, null, 2))
{ type: "text", text: `## Upstream Context
<prev_context>` }
]
})
```
---
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
### Phase 1: Requirement -> CSV + Classification
## User Commands
**Objective**: Parse issue IDs, determine pipeline mode, generate tasks.csv with wave and exec_mode assignments.
| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
**Decomposition Rules**:
## Session Directory
| Pipeline | Tasks Generated |
|----------|----------------|
| quick | EXPLORE-001, SOLVE-001, MARSHAL-001, BUILD-001 (4 tasks, waves 1-4) |
| full | EXPLORE-001, SOLVE-001, AUDIT-001, MARSHAL-001, BUILD-001 (5 tasks, waves 1-5) |
| batch | EXPLORE-001..N, SOLVE-001..N, AUDIT-001, MARSHAL-001, BUILD-001..M (N+N+1+1+M tasks) |
**Classification Rules**:
| Task Prefix | Role | exec_mode | Rationale |
|-------------|------|-----------|-----------|
| EXPLORE-* | explorer | csv-wave | One-shot codebase analysis |
| SOLVE-* | planner | csv-wave | One-shot solution design via CLI |
| SOLVE-fix-* | planner | csv-wave | One-shot revision addressing feedback |
| AUDIT-* | reviewer | interactive | Multi-round review with verdict routing |
| MARSHAL-* | integrator | csv-wave | One-shot queue formation |
| BUILD-* | implementer | csv-wave | One-shot implementation via CLI |
**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
**Task Generation by Pipeline Mode**:
Quick pipeline:
```csv
id,title,description,role,issue_ids,exec_mode,execution_method,deps,context_from,wave,status,findings,artifact_path,error
"EXPLORE-001","Context analysis","Analyze issue context and map codebase impact","explorer","<issue-ids>","csv-wave","","","","1","pending","","",""
"SOLVE-001","Solution design","Design solution and decompose into implementation tasks","planner","<issue-ids>","csv-wave","","EXPLORE-001","EXPLORE-001","2","pending","","",""
"MARSHAL-001","Queue formation","Form execution queue with conflict detection and ordering","integrator","<issue-ids>","csv-wave","","SOLVE-001","SOLVE-001","3","pending","","",""
"BUILD-001","Implementation","Implement solution plan and verify with tests","implementer","<issue-ids>","csv-wave","<exec-method>","MARSHAL-001","EXPLORE-001;SOLVE-001","4","pending","","",""
```
.workflow/.team/TISL-<slug>-<date>/
├── session.json # Session metadata + pipeline + fix_cycles
├── task-analysis.json # Coordinator analyze output
├── .msg/
│ ├── messages.jsonl # Message bus log
│ └── meta.json # Session state + cross-role state
├── wisdom/ # Cross-task knowledge
│ ├── learnings.md
│ ├── decisions.md
│ ├── conventions.md
│ └── issues.md
├── explorations/ # Explorer output
│ └── context-<issueId>.json
├── solutions/ # Planner output
│ └── solution-<issueId>.json
├── audits/ # Reviewer output
│ └── audit-report.json
├── queue/ # Integrator output (also .workflow/issues/queue/)
└── builds/ # Implementer output
```
Full pipeline (adds AUDIT-001 as interactive between SOLVE and MARSHAL):
```csv
"AUDIT-001","Technical review","Review solution for feasibility, risk, and completeness","reviewer","<issue-ids>","interactive","","SOLVE-001","SOLVE-001","3","pending","","",""
"MARSHAL-001","Queue formation","...","integrator","<issue-ids>","csv-wave","","AUDIT-001","SOLVE-001","4","pending","","",""
"BUILD-001","Implementation","...","implementer","<issue-ids>","csv-wave","<exec-method>","MARSHAL-001","EXPLORE-001;SOLVE-001","5","pending","","",""
```
## Specs Reference
Batch pipeline (parallel EXPLORE, sequential SOLVE, then AUDIT, MARSHAL, deferred BUILD):
- EXPLORE-001..N with wave=1, no deps
- SOLVE-001..N with wave=2, deps on all EXPLORE-*
- AUDIT-001 with wave=3, deps on all SOLVE-*, interactive
- MARSHAL-001 with wave=4, deps on AUDIT-001
- BUILD-001..M created after MARSHAL completes (deferred)
**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
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
const maxWave = Math.max(...tasks.map(t => parseInt(t.wave)))
let fixCycles = 0
for (let wave = 1; wave <= maxWave; wave++) {
console.log(`\nWave ${wave}/${maxWave}`)
// 1. Separate tasks by exec_mode
const waveTasks = tasks.filter(t => parseInt(t.wave) === wave)
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave' && t.status === 'pending')
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive' && t.status === 'pending')
// 2. Check dependencies - skip if upstream failed
for (const task of waveTasks) {
const depIds = (task.deps || '').split(';').filter(Boolean)
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
task.status = 'skipped'
task.error = `Dependency failed: ${depIds.filter((id, i) =>
['failed','skipped'].includes(depStatuses[i])).join(', ')}`
}
}
// 3. Execute csv-wave tasks
const pendingCsv = csvTasks.filter(t => t.status === 'pending')
if (pendingCsv.length > 0) {
// Build prev_context for each task
for (const task of pendingCsv) {
const contextIds = (task.context_from || '').split(';').filter(Boolean)
const prevFindings = contextIds.map(id => {
const src = tasks.find(t => t.id === id)
if (!src?.findings) return ''
return `## [${src.id}] ${src.title}\n${src.findings}`
}).filter(Boolean).join('\n\n')
task.prev_context = prevFindings
}
// Write wave CSV
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsv))
// Execute
spawn_agents_on_csv({
csv_path: `${sessionFolder}/wave-${wave}.csv`,
id_column: "id",
instruction: Read("~ or <project>/.codex/skills/team-issue/instructions/agent-instruction.md"),
max_concurrency: maxConcurrency,
max_runtime_seconds: 1200,
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
artifact_path: { type: "string" },
error: { type: "string" }
}
}
})
// Merge results
const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
for (const r of results) {
const t = tasks.find(t => t.id === r.id)
if (t) Object.assign(t, r)
}
// Cleanup temp files
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
}
// 4. Execute interactive tasks (post-wave)
const pendingInteractive = interactiveTasks.filter(t => t.status === 'pending')
for (const task of pendingInteractive) {
// Read agent definition
const agentDef = Read(`~ or <project>/.codex/skills/team-issue/agents/reviewer.md`)
// Build context from upstream tasks
const contextIds = (task.context_from || '').split(';').filter(Boolean)
const prevContext = contextIds.map(id => {
const src = tasks.find(t => t.id === id)
if (!src?.findings) return ''
return `## [${src.id}] ${src.title}\n${src.findings}\nArtifact: ${src.artifact_path || 'N/A'}`
}).filter(Boolean).join('\n\n')
const agent = spawn_agent({
message: `## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~ or <project>/.codex/skills/team-issue/agents/reviewer.md (MUST read first)
2. Read: ${sessionFolder}/discoveries.ndjson (shared discoveries)
3. Read: .workflow/project-tech.json (if exists)
---
Goal: ${task.description}
Issue IDs: ${task.issue_ids}
Session: ${sessionFolder}
Scope: Review all solutions in ${sessionFolder}/solutions/ for technical feasibility, risk, and completeness
Deliverables:
- Audit report at ${sessionFolder}/audits/audit-report.json
- Per-issue verdict: approved (>=80), concerns (60-79), rejected (<60)
- Overall verdict
### Previous Context
${prevContext}`
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
if (result.timed_out) {
send_input({ id: agent, message: "Please finalize and output current findings immediately." })
const retry = wait({ ids: [agent], timeout_ms: 120000 })
}
// Store interactive result
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
task_id: task.id,
status: "completed",
findings: "Review completed",
timestamp: getUtc8ISOString()
}))
close_agent({ id: agent })
// Parse review verdict from audit report
let verdict = 'approved'
try {
const auditReport = JSON.parse(Read(`${sessionFolder}/audits/audit-report.json`))
verdict = auditReport.overall_verdict || 'approved'
} catch (e) { /* default to approved */ }
task.status = 'completed'
task.findings = `Review verdict: ${verdict}`
// Handle review-fix cycle
if (verdict === 'rejected' && fixCycles < 2) {
fixCycles++
// Create SOLVE-fix and AUDIT re-review tasks
const fixTask = {
id: `SOLVE-fix-${String(fixCycles).padStart(3, '0')}`,
title: `Revise solution (fix cycle ${fixCycles})`,
description: `Revise solution addressing reviewer feedback. Read audit report for rejection reasons.`,
role: 'planner',
issue_ids: task.issue_ids,
exec_mode: 'csv-wave',
execution_method: '',
deps: task.id,
context_from: task.id,
wave: String(parseInt(task.wave) + 1),
status: 'pending',
findings: '', artifact_path: '', error: ''
}
const reReviewTask = {
id: `AUDIT-${String(fixCycles + 1).padStart(3, '0')}`,
title: `Re-review revised solution (cycle ${fixCycles})`,
description: `Re-review revised solution focusing on previously rejected dimensions.`,
role: 'reviewer',
issue_ids: task.issue_ids,
exec_mode: 'interactive',
execution_method: '',
deps: fixTask.id,
context_from: fixTask.id,
wave: String(parseInt(task.wave) + 2),
status: 'pending',
findings: '', artifact_path: '', error: ''
}
tasks.push(fixTask, reReviewTask)
// Adjust MARSHAL and BUILD waves
for (const t of tasks) {
if (t.id.startsWith('MARSHAL') || t.id.startsWith('BUILD')) {
t.wave = String(parseInt(reReviewTask.wave) + (t.id.startsWith('MARSHAL') ? 1 : 2))
if (t.id.startsWith('MARSHAL')) t.deps = reReviewTask.id
}
}
} else if (verdict === 'rejected' && fixCycles >= 2) {
// Force proceed with warning
console.log(`WARNING: Fix cycle limit (${fixCycles}) reached. Forcing proceed to MARSHAL.`)
}
}
// 5. Merge all results into master CSV
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
// 6. Handle deferred BUILD task creation (batch mode after MARSHAL)
const completedMarshal = tasks.find(t => t.id === 'MARSHAL-001' && t.status === 'completed')
if (completedMarshal && pipelineMode === 'batch') {
try {
const queue = JSON.parse(Read(`${sessionFolder}/queue/execution-queue.json`))
const buildCount = queue.parallel_groups?.length || 1
for (let b = 1; b <= Math.min(buildCount, 3); b++) {
const buildIssues = queue.parallel_groups[b-1]?.issues || issueIds
tasks.push({
id: `BUILD-${String(b).padStart(3, '0')}`,
title: `Implementation group ${b}`,
description: `Implement solutions for issues in parallel group ${b}`,
role: 'implementer',
issue_ids: buildIssues.join(';'),
exec_mode: 'csv-wave',
execution_method: executionMethod,
deps: 'MARSHAL-001',
context_from: 'EXPLORE-001;SOLVE-001',
wave: String(parseInt(completedMarshal.wave) + 1),
status: 'pending',
findings: '', artifact_path: '', error: ''
})
}
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
} catch (e) { /* single BUILD fallback */ }
}
}
```
**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
- Review-fix cycles handled (max 2)
- Deferred BUILD tasks created after MARSHAL (batch mode)
---
### Phase 3: Post-Wave Interactive
**Objective**: Handle any remaining interactive tasks after all waves complete. In most cases, the review gate is handled inline during Phase 2 wave execution.
If any interactive tasks remain unprocessed (e.g., from dynamically added fix cycles), execute them using the same spawn_agent protocol as Phase 2.
**Success Criteria**:
- All interactive tasks completed or skipped
- Fix cycle limit respected
---
### Phase 4: Results Aggregation
**Objective**: Generate final results and human-readable report.
```javascript
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
const completed = tasks.filter(t => t.status === 'completed')
const failed = tasks.filter(t => t.status === 'failed')
const skipped = tasks.filter(t => t.status === 'skipped')
// Export results.csv
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
// Generate context.md
let contextMd = `# Issue Resolution Report\n\n`
contextMd += `**Session**: ${sessionId}\n`
contextMd += `**Pipeline**: ${pipelineMode}\n`
contextMd += `**Issues**: ${issueIds.join(', ')}\n`
contextMd += `**Fix Cycles**: ${fixCycles}/${2}\n\n`
contextMd += `## Summary\n\n`
contextMd += `| Status | Count |\n|--------|-------|\n`
contextMd += `| Completed | ${completed.length} |\n`
contextMd += `| Failed | ${failed.length} |\n`
contextMd += `| Skipped | ${skipped.length} |\n\n`
contextMd += `## Task Details\n\n`
for (const t of tasks) {
const icon = t.status === 'completed' ? '[OK]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
contextMd += `${icon} **${t.id}**: ${t.title} (${t.role})\n`
if (t.findings) contextMd += ` Findings: ${t.findings.substring(0, 200)}\n`
if (t.artifact_path) contextMd += ` Artifact: ${t.artifact_path}\n`
if (t.error) contextMd += ` Error: ${t.error}\n`
contextMd += `\n`
}
contextMd += `## Deliverables\n\n`
contextMd += `| Artifact | Path |\n|----------|------|\n`
contextMd += `| Context Reports | ${sessionFolder}/explorations/ |\n`
contextMd += `| Solution Plans | ${sessionFolder}/solutions/ |\n`
contextMd += `| Audit Report | ${sessionFolder}/audits/audit-report.json |\n`
contextMd += `| Execution Queue | ${sessionFolder}/queue/execution-queue.json |\n`
contextMd += `| Build Results | ${sessionFolder}/builds/ |\n`
Write(`${sessionFolder}/context.md`, contextMd)
// Display summary
console.log(`
Issue Resolution Complete
Pipeline: ${pipelineMode}
Completed: ${completed.length} | Failed: ${failed.length} | Skipped: ${skipped.length}
Fix Cycles Used: ${fixCycles}/2
Output: ${sessionFolder}
`)
```
**Success Criteria**:
- results.csv exported (all tasks, both modes)
- context.md generated
- Summary displayed to user
---
## Shared Discovery Board Protocol
Both csv-wave and interactive agents share the same discoveries.ndjson file:
```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"EXPLORE-001","type":"file_found","data":{"path":"src/auth/handler.ts","relevance":"high","purpose":"Main auth handler"}}
{"ts":"2026-03-08T10:01:00Z","worker":"EXPLORE-001","type":"pattern_found","data":{"pattern":"middleware-chain","location":"src/middleware/","description":"Express middleware chain pattern"}}
{"ts":"2026-03-08T10:05:00Z","worker":"SOLVE-001","type":"solution_approach","data":{"issue_id":"ISS-20260308-120000","approach":"refactor","estimated_files":5}}
{"ts":"2026-03-08T10:10:00Z","worker":"BUILD-001","type":"impl_result","data":{"issue_id":"ISS-20260308-120000","files_changed":3,"tests_pass":true}}
```
**Discovery Types**:
| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `file_found` | `path` | `{path, relevance, purpose}` | Relevant file discovered |
| `pattern_found` | `pattern+location` | `{pattern, location, description}` | Code pattern identified |
| `dependency_found` | `from+to` | `{from, to, type}` | Dependency relationship |
| `solution_approach` | `issue_id` | `{issue_id, approach, estimated_files}` | Solution strategy |
| `conflict_found` | `files` | `{issues, files, resolution}` | File conflict between issues |
| `impl_result` | `issue_id` | `{issue_id, files_changed, tests_pass}` | Implementation outcome |
---
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
## 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 |
| 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 |
| Review rejection exceeds 2 rounds | Force convergence to MARSHAL with warning |
| No issues found for given IDs | Report error, ask user for valid IDs |
| Deferred BUILD count unknown | Read execution-queue.json after MARSHAL completes |
| Continue mode: no session found | List available sessions, prompt user to select |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 1
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
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
---
## Coordinator Role Constraints (Main Agent)
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
- Spawns agents with task assignments
- Waits for agent callbacks
- Merges results and coordinates workflow
- Manages workflow transitions between phases
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
- Wait patiently for `wait()` calls to complete
- NOT skip workflow steps due to perceived delays
- NOT assume agents have failed just because they're taking time
- Trust the timeout mechanisms defined in the skill
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
- Use `send_input()` to ask questions or provide clarification
- NOT skip the agent or move to next phase prematurely
- Give agents opportunity to respond before escalating
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
- Skip phases or stages defined in the workflow
- Bypass required approval or review steps
- Execute dependent tasks before prerequisites complete
- Assume task completion without explicit agent callback
- Make up or fabricate agent results
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
- Total execution time may range from 30-90 minutes or longer
- Each phase may take 10-30 minutes depending on complexity
- The coordinator must remain active and attentive throughout the entire process
- Do not terminate or skip steps due to time concerns
| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |
| Review rejection exceeds 2 rounds | Force convergence to integrator |
| No issues found for given IDs | Coordinator reports error to user |
| Deferred BUILD count unknown | Defer to MARSHAL callback |

204
.codex/skills/team-issue/agents/reviewer.md
View File

@@ -1,204 +0,0 @@
# Reviewer Agent
Technical review agent for issue solutions. Performs multi-dimensional review with scored verdict. Used as interactive agent within the team-issue pipeline when review gates are required (full/batch modes).
## Identity
- **Type**: `interactive`
- **Responsibility**: Multi-dimensional solution review with verdict routing
## Boundaries
### MUST
- Load role definition via MANDATORY FIRST STEPS pattern
- Read all solution artifacts and explorer context before reviewing
- Score across three weighted dimensions: Technical Feasibility (40%), Risk (30%), Completeness (30%)
- Produce structured output with per-issue and overall verdicts
- Include file:line references in findings
- Write audit report to session audits folder
### MUST NOT
- Skip the MANDATORY FIRST STEPS role loading
- Modify solution artifacts or code
- Produce unstructured output
- Review without reading explorer context (when available)
- Skip any scoring dimension
---
## Toolbox
### Available Tools
| Tool | Type | Purpose |
|------|------|---------|
| `Read` | file | Load solution artifacts and context files |
| `Bash` | shell | Run `ccw issue solutions <id> --json` to load bound solutions |
| `Grep` | search | Search codebase for pattern conformance checks |
| `Glob` | search | Find relevant files for coverage validation |
| `Write` | file | Write audit report |
---
## Execution
### Phase 1: Context Loading
**Objective**: Load all inputs needed for review.
**Input**:
| Source | Required | Description |
|--------|----------|-------------|
| Solution artifacts | Yes | `<session>/solutions/solution-<issueId>.json` |
| Explorer context | No | `<session>/explorations/context-<issueId>.json` |
| Bound solutions | Yes | `ccw issue solutions <issueId> --json` |
| Discoveries | No | `<session>/discoveries.ndjson` |
| Wisdom files | No | `<session>/wisdom/` |
**Steps**:
1. Read session folder path from spawn message
2. Extract issue IDs from spawn message
3. Load explorer context reports for each issue
4. Load bound solutions for each issue via CLI
5. Load discoveries for cross-reference
---
### Phase 2: Multi-Dimensional Review
**Objective**: Score each solution across three weighted dimensions.
**Technical Feasibility (40%)**:
| Criterion | Check | Score Impact |
|-----------|-------|-------------|
| File Coverage | Solution covers all affected files from explorer context | High |
| Dependency Awareness | Considers dependency cascade effects | Medium |
| API Compatibility | Maintains backward compatibility | High |
| Pattern Conformance | Follows existing code patterns | Medium |
**Risk Assessment (30%)**:
| Criterion | Check | Score Impact |
|-----------|-------|-------------|
| Scope Creep | Solution stays within issue boundary (task_count <= 10) | High |
| Breaking Changes | No destructive modifications | High |
| Side Effects | No unforeseen side effects | Medium |
| Rollback Path | Can rollback if issues occur | Low |
**Completeness (30%)**:
| Criterion | Check | Score Impact |
|-----------|-------|-------------|
| All Tasks Defined | Task decomposition is complete (count > 0) | High |
| Test Coverage | Includes test plan | Medium |
| Edge Cases | Considers boundary conditions | Low |
**Score Calculation**:
```
total_score = round(
technical_feasibility.score * 0.4 +
risk_assessment.score * 0.3 +
completeness.score * 0.3
)
```
**Verdict Rules**:
| Score | Verdict | Description |
|-------|---------|-------------|
| >= 80 | approved | Solution is ready for implementation |
| 60-79 | concerns | Minor issues noted, proceed with warnings |
| < 60 | rejected | Solution needs revision before proceeding |
---
### Phase 3: Compile Audit Report
**Objective**: Write structured audit report.
**Steps**:
1. Compute per-issue scores and verdicts
2. Compute overall verdict (any rejected -> overall rejected)
3. Write audit report to `<session>/audits/audit-report.json`:
```json
{
"session_id": "<session-id>",
"review_timestamp": "<ISO8601>",
"issues_reviewed": [
{
"issue_id": "<issueId>",
"solution_id": "<solutionId>",
"total_score": 85,
"verdict": "approved",
"technical_feasibility": {
"score": 90,
"findings": ["Good file coverage", "API compatible"]
},
"risk_assessment": {
"score": 80,
"findings": ["No breaking changes", "Rollback via git revert"]
},
"completeness": {
"score": 82,
"findings": ["5 tasks defined", "Test plan included"]
}
}
],
"overall_verdict": "approved",
"overall_score": 85,
"review_count": 1,
"rejection_reasons": [],
"actionable_feedback": []
}
```
4. For rejected solutions: include specific rejection reasons and actionable feedback for SOLVE-fix task
---
## Structured Output Template
```
## Summary
- Review of <N> solutions: <verdict>
## Findings
- Finding 1: specific description with file:line reference
- Finding 2: specific description with file:line reference
## Per-Issue Verdicts
- <issueId>: <score>/100 (<verdict>)
- Technical: <score>/100
- Risk: <score>/100
- Completeness: <score>/100
## Overall Verdict
<approved|concerns|rejected> (score: <N>/100)
## Rejection Feedback (if rejected)
1. Specific concern with remediation suggestion
2. Specific concern with remediation suggestion
## Open Questions
1. Question needing clarification (if any)
```
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Solution file not found | Report in Open Questions, score as 0 for completeness |
| Explorer context missing | Proceed with reduced confidence, note in findings |
| Bound solution not found via CLI | Attempt file-based fallback, report if still missing |
| Processing failure | Output partial results with clear status indicator |
| Timeout approaching | Output current findings with "PARTIAL" status |

198
.codex/skills/team-issue/instructions/agent-instruction.md
View File

@@ -1,198 +0,0 @@
# Agent Instruction -- Team Issue Resolution
CSV agent instruction template for `spawn_agents_on_csv`. Each agent receives this template with its row's column values substituted via `{column_name}` placeholders.
---
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS
1. Read shared discoveries: `.workflow/.csv-wave/{session_id}/discoveries.ndjson` (if exists, skip if not)
2. Read project context: `.workflow/project-tech.json` (if exists)
3. Read wisdom files: `.workflow/.csv-wave/{session_id}/wisdom/` (conventions, learnings)
---
## Your Task
**Task ID**: {id}
**Title**: {title}
**Description**: {description}
**Role**: {role}
**Issue IDs**: {issue_ids}
**Execution Method**: {execution_method}
### Previous Tasks' Findings (Context)
{prev_context}
---
## Execution Protocol
### Role Router
Determine your execution steps based on `{role}`:
| Role | Execution Steps |
|------|----------------|
| explorer | Step A: Codebase Exploration |
| planner | Step B: Solution Design |
| integrator | Step C: Queue Formation |
| implementer | Step D: Implementation |
---
### Step A: Codebase Exploration (explorer role)
1. Extract issue ID from `{issue_ids}` (pattern: `GH-\d+` or `ISS-\d{8}-\d{6}`)
2. Load issue details: `Bash("ccw issue status <issueId> --json")`
3. Assess complexity from issue keywords:
| Signal | Weight |
|--------|--------|
| Structural change (refactor, architect) | +2 |
| Cross-cutting (multiple, across) | +2 |
| Integration (api, database) | +1 |
| High priority (>= 4) | +1 |
4. Explore codebase:
- Use `mcp__ace-tool__search_context` for semantic search based on issue keywords
- Read relevant files to understand context
- Map dependencies and integration points
- Check git log for related changes
5. Write context report:
```bash
# Write to session explorations folder
Write("<session>/explorations/context-<issueId>.json", JSON.stringify({
issue_id: "<issueId>",
issue: { id, title, priority, status, labels, feedback },
relevant_files: [{ path, relevance }],
dependencies: [],
impact_scope: "low|medium|high",
existing_patterns: [],
related_changes: [],
key_findings: [],
complexity_assessment: "Low|Medium|High"
}))
```
6. Share discoveries to board
---
### Step B: Solution Design (planner role)
1. Extract issue ID from `{issue_ids}`
2. Load explorer context (if available): Read upstream artifact from prev_context
3. Check if this is a revision task (SOLVE-fix-*): If yes, read audit report for rejection feedback
4. Generate solution via CLI:
```bash
ccw cli -p "PURPOSE: Design solution for issue <issueId> and decompose into implementation tasks; success = solution with task breakdown
TASK: * Load issue details * Analyze explorer context * Design solution approach * Break into tasks * Generate solution JSON
MODE: analysis
CONTEXT: @**/* | Memory: Issue <issueId>, Explorer findings from prev_context
EXPECTED: Solution JSON with: issue_id, solution_id, approach, tasks[], estimated_files, dependencies
CONSTRAINTS: Follow existing patterns | Minimal changes
" --tool gemini --mode analysis --rule planning-breakdown-task-steps
```
5. Write solution artifact:
```bash
Write("<session>/solutions/solution-<issueId>.json", solutionJson)
```
6. Bind solution to issue: `Bash("ccw issue bind <issueId> <solutionId>")`
---
### Step C: Queue Formation (integrator role)
1. Extract issue IDs from `{issue_ids}`
2. Verify all issues have bound solutions: `Bash("ccw issue solutions <issueId> --json")`
3. Analyze file conflicts between solutions
4. Build dependency graph for execution ordering
5. Determine parallel execution groups
6. Write execution queue:
```bash
Write("<session>/queue/execution-queue.json", JSON.stringify({
queue: [{ issue_id, solution_id, order, depends_on: [], estimated_files: [] }],
conflicts: [{ issues: [], files: [], resolution: "" }],
parallel_groups: [{ group: 0, issues: [] }]
}))
```
---
### Step D: Implementation (implementer role)
1. Extract issue ID from `{issue_ids}`
2. Load bound solution: `Bash("ccw issue solutions <issueId> --json")`
3. Load explorer context (from prev_context or file)
4. Determine execution backend from `{execution_method}`:
| Method | CLI Command |
|--------|-------------|
| codex | `ccw cli --tool codex --mode write --id issue-<issueId>` |
| gemini | `ccw cli --tool gemini --mode write --id issue-<issueId>` |
| qwen | `ccw cli --tool qwen --mode write --id issue-<issueId>` |
5. Execute implementation:
```bash
ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
TASK: <solution.tasks as bullet points>
MODE: write
CONTEXT: @**/* | Memory: Solution plan, explorer context
EXPECTED: Working implementation with code changes, test updates
CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
" --tool <execution_method> --mode write --rule development-implement-feature
```
6. Verify: Run tests, check for errors
7. Update issue status: `Bash("ccw issue update <issueId> --status resolved")`
---
## Share Discoveries (ALL ROLES)
After completing your work, append findings to the shared discovery board:
```bash
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> <session>/discoveries.ndjson
```
**Discovery Types to Share**:
| Type | Data Schema | When to Use |
|------|-------------|-------------|
| `file_found` | `{path, relevance, purpose}` | Explorer: relevant file discovered |
| `pattern_found` | `{pattern, location, description}` | Explorer: code pattern identified |
| `dependency_found` | `{from, to, type}` | Explorer: module dependency found |
| `solution_approach` | `{issue_id, approach, estimated_files}` | Planner: solution strategy |
| `conflict_found` | `{issues, files, resolution}` | Integrator: file conflict |
| `impl_result` | `{issue_id, files_changed, tests_pass}` | Implementer: build outcome |
---
## Output (report_agent_job_result)
Return JSON:
```json
{
"id": "{id}",
"status": "completed | failed",
"findings": "Key discoveries and implementation notes (max 500 chars)",
"artifact_path": "relative path to main artifact file (e.g., explorations/context-ISS-xxx.json)",
"error": ""
}
```
---
## Quality Checklist
Before reporting complete:
- [ ] Mandatory first steps completed (discoveries, project context, wisdom)
- [ ] Role-specific execution steps followed
- [ ] At least 1 discovery shared to board
- [ ] Artifact file written to session folder
- [ ] Findings include file:line references where applicable
- [ ] prev_context findings were incorporated

64
.codex/skills/team-issue/roles/coordinator/commands/analyze.md Normal file
View File

@@ -0,0 +1,64 @@
# Analyze Task
Parse user issue description -> detect required capabilities -> assess complexity -> select pipeline mode.
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
## Signal Detection
| Keywords | Capability | Prefix |
|----------|------------|--------|
| explore, analyze, context, impact, understand | explorer | EXPLORE |
| plan, solve, design, solution, approach | planner | SOLVE |
| review, audit, validate, feasibility | reviewer | AUDIT |
| marshal, integrate, queue, conflict, order | integrator | MARSHAL |
| build, implement, execute, code, develop | implementer | BUILD |
## Dependency Graph
Natural ordering tiers:
- Tier 0: explorer (context analysis -- no dependencies)
- Tier 1: planner (requires explorer output)
- Tier 2: reviewer (requires planner output, full/batch modes only)
- Tier 3: integrator (requires reviewer or planner output)
- Tier 4: implementer (requires integrator output)
## Complexity Scoring
| Factor | Points |
|--------|--------|
| Issue count > 2 | +3 |
| Issue count > 4 | +2 more |
| Any high-priority issue (priority >= 4) | +2 |
| Multiple issue types / cross-cutting | +2 |
| Simple / single issue | -2 |
Results:
- 0-2: Low -> quick (4 tasks: EXPLORE -> SOLVE -> MARSHAL -> BUILD)
- 3-4: Medium -> full (5 tasks: EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD)
- 5+: High -> batch (N+N+1+1+M tasks, parallel exploration and implementation)
## Pipeline Selection
| Complexity | Pipeline | Tasks |
|------------|----------|-------|
| Low | quick | EXPLORE -> SOLVE -> MARSHAL -> BUILD |
| Medium | full | EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD |
| High | batch | EXPLORE-001..N (parallel) -> SOLVE-001..N -> AUDIT -> MARSHAL -> BUILD-001..M (parallel) |
## Output
Write <session>/task-analysis.json:
```json
{
"task_description": "<original>",
"pipeline_type": "<quick|full|batch>",
"issue_ids": ["<id1>", "<id2>"],
"capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
"dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
"complexity": { "score": 0, "level": "Low|Medium|High" },
"parallel_explorers": 1,
"parallel_builders": 1
}
```

273
.codex/skills/team-issue/roles/coordinator/commands/dispatch.md Normal file
View File

@@ -0,0 +1,273 @@
# Dispatch
Create the issue resolution task chain with correct dependencies and structured task descriptions based on selected pipeline mode.
## Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Requirement | From coordinator Phase 1 | Yes |
| Session folder | From coordinator Phase 2 | Yes |
| Pipeline mode | From session.json mode | Yes |
| Issue IDs | From session.json issue_ids | Yes |
| Execution method | From session.json execution_method | Yes |
| Code review | From session.json code_review | No |
1. Load requirement, pipeline mode, issue IDs, and execution method from session.json
2. Determine task chain from pipeline mode
## Task Description Template
Every task is built as a JSON entry in the tasks array:
```json
{
"id": "<TASK-ID>",
"title": "<TASK-ID>",
"description": "PURPOSE: <what this task achieves> | Success: <completion criteria>\nTASK:\n - <step 1>\n - <step 2>\n - <step 3>\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issue-id-list>\n - Upstream artifacts: <artifact-list>\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits>\n---\nInnerLoop: false\nexecution_method: <method>\ncode_review: <setting>",
"status": "pending",
"role": "<role>",
"prefix": "<PREFIX>",
"deps": ["<dependency-list>"],
"findings": "",
"error": ""
}
```
## Pipeline Router
| Mode | Action |
|------|--------|
| quick | Create 4 tasks (EXPLORE -> SOLVE -> MARSHAL -> BUILD) |
| full | Create 5 tasks (EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD) |
| batch | Create N+N+1+1+M tasks (EXPLORE-001..N -> SOLVE-001..N -> AUDIT-001 -> MARSHAL-001 -> BUILD-001..M) |
---
### Quick Pipeline
Build tasks array and write to tasks.json:
**EXPLORE-001** (explorer):
```json
{
"id": "EXPLORE-001",
"title": "EXPLORE-001",
"description": "PURPOSE: Analyze issue context and map codebase impact | Success: Context report with relevant files and dependencies\nTASK:\n - Load issue details via ccw issue status\n - Explore codebase for relevant files and patterns\n - Assess complexity and impact scope\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issue-id-list>\nEXPECTED: <session>/explorations/context-<issueId>.json with relevant files, dependencies, and impact assessment\nCONSTRAINTS: Exploration and analysis only, no solution design\n---\nInnerLoop: false",
"status": "pending",
"role": "explorer",
"prefix": "EXPLORE",
"deps": [],
"findings": "",
"error": ""
}
```
**SOLVE-001** (planner):
```json
{
"id": "SOLVE-001",
"title": "SOLVE-001",
"description": "PURPOSE: Design solution and decompose into implementation tasks | Success: Bound solution with task decomposition\nTASK:\n - Load explorer context report\n - Generate solution plan via CLI\n - Bind solution to issue\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issue-id-list>\n - Upstream artifacts: explorations/context-<issueId>.json\nEXPECTED: <session>/solutions/solution-<issueId>.json with solution plan and task list\nCONSTRAINTS: Solution design only, no code implementation\n---\nInnerLoop: false",
"status": "pending",
"role": "planner",
"prefix": "SOLVE",
"deps": ["EXPLORE-001"],
"findings": "",
"error": ""
}
```
**MARSHAL-001** (integrator):
```json
{
"id": "MARSHAL-001",
"title": "MARSHAL-001",
"description": "PURPOSE: Form execution queue with conflict detection and ordering | Success: Execution queue file with resolved conflicts\nTASK:\n - Verify all issues have bound solutions\n - Detect file conflicts between solutions\n - Produce ordered execution queue with DAG-based parallel groups\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issue-id-list>\n - Upstream artifacts: solutions/solution-<issueId>.json\nEXPECTED: .workflow/issues/queue/execution-queue.json with queue, conflicts, parallel groups\nCONSTRAINTS: Queue formation only, no implementation\n---\nInnerLoop: false",
"status": "pending",
"role": "integrator",
"prefix": "MARSHAL",
"deps": ["SOLVE-001"],
"findings": "",
"error": ""
}
```
**BUILD-001** (implementer):
```json
{
"id": "BUILD-001",
"title": "BUILD-001",
"description": "PURPOSE: Implement solution plan and verify with tests | Success: Code changes committed, tests pass\nTASK:\n - Load bound solution and explorer context\n - Route to execution backend (Auto/Codex/Gemini)\n - Run tests and verify implementation\n - Commit changes\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issue-id-list>\n - Upstream artifacts: explorations/context-<issueId>.json, solutions/solution-<issueId>.json, queue/execution-queue.json\nEXPECTED: <session>/builds/ with implementation results, tests passing\nCONSTRAINTS: Follow solution plan, no scope creep\n---\nInnerLoop: false\nexecution_method: <execution_method>\ncode_review: <code_review>",
"status": "pending",
"role": "implementer",
"prefix": "BUILD",
"deps": ["MARSHAL-001"],
"findings": "",
"error": ""
}
```
---
### Full Pipeline
Creates 5 tasks. EXPLORE-001 and SOLVE-001 same as Quick, then AUDIT gate before MARSHAL and BUILD.
**AUDIT-001** (reviewer):
```json
{
"id": "AUDIT-001",
"title": "AUDIT-001",
"description": "PURPOSE: Review solution for technical feasibility, risk, and completeness | Success: Clear verdict (approved/concerns/rejected) with scores\nTASK:\n - Load explorer context and bound solution\n - Score across 3 dimensions: technical feasibility (40%), risk (30%), completeness (30%)\n - Produce verdict: approved (>=80), concerns (60-79), rejected (<60)\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issue-id-list>\n - Upstream artifacts: explorations/context-<issueId>.json, solutions/solution-<issueId>.json\nEXPECTED: <session>/audits/audit-report.json with per-issue scores and overall verdict\nCONSTRAINTS: Review only, do not modify solutions\n---\nInnerLoop: false",
"status": "pending",
"role": "reviewer",
"prefix": "AUDIT",
"deps": ["SOLVE-001"],
"findings": "",
"error": ""
}
```
**MARSHAL-001**: Same as Quick, but `deps: ["AUDIT-001"]`.
**BUILD-001**: Same as Quick, `deps: ["MARSHAL-001"]`.
---
### Batch Pipeline
Creates tasks in parallel batches. Issue count = N, BUILD tasks = M (from queue parallel groups).
**EXPLORE-001..N** (explorer, parallel):
For each issue in issue_ids (up to 5), create an EXPLORE task with distinct role:
| Issue Count | Role Assignment |
|-------------|-----------------|
| N = 1 | role: "explorer" |
| N > 1 | role: "explorer-1", "explorer-2", ..., "explorer-N" (max 5) |
```json
{
"id": "EXPLORE-<NNN>",
"title": "EXPLORE-<NNN>",
"description": "PURPOSE: Analyze issue <issueId> context and map codebase impact | Success: Context report for <issueId>\nTASK:\n - Load issue details for <issueId>\n - Explore codebase for relevant files\n - Assess complexity and impact scope\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issueId>\nEXPECTED: <session>/explorations/context-<issueId>.json\nCONSTRAINTS: Single issue scope, exploration only\n---\nInnerLoop: false",
"status": "pending",
"role": "explorer-<N>",
"prefix": "EXPLORE",
"deps": [],
"findings": "",
"error": ""
}
```
**SOLVE-001..N** (planner, sequential after all EXPLORE):
```json
{
"id": "SOLVE-<NNN>",
"title": "SOLVE-<NNN>",
"description": "PURPOSE: Design solution for <issueId> | Success: Bound solution with tasks\nTASK:\n - Load explorer context for <issueId>\n - Generate solution plan\n - Bind solution\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issueId>\n - Upstream artifacts: explorations/context-<issueId>.json\nEXPECTED: <session>/solutions/solution-<issueId>.json\nCONSTRAINTS: Solution design only\n---\nInnerLoop: false",
"status": "pending",
"role": "planner",
"prefix": "SOLVE",
"deps": ["EXPLORE-001", "...", "EXPLORE-<N>"],
"findings": "",
"error": ""
}
```
**AUDIT-001** (reviewer, batch review):
```json
{
"id": "AUDIT-001",
"title": "AUDIT-001",
"description": "PURPOSE: Batch review all solutions | Success: Verdict for each solution\nTASK:\n - Load all explorer contexts and bound solutions\n - Score each solution across 3 dimensions\n - Produce per-issue verdicts and overall verdict\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <all-issue-ids>\n - Upstream artifacts: explorations/*.json, solutions/*.json\nEXPECTED: <session>/audits/audit-report.json with batch results\nCONSTRAINTS: Review only\n---\nInnerLoop: false",
"status": "pending",
"role": "reviewer",
"prefix": "AUDIT",
"deps": ["SOLVE-001", "...", "SOLVE-<N>"],
"findings": "",
"error": ""
}
```
**MARSHAL-001** (integrator): `deps: ["AUDIT-001"]`.
**BUILD-001..M** (implementer, DAG parallel):
> Note: In Batch mode, BUILD task count M is not known at dispatch time (depends on MARSHAL queue output). Defer BUILD task creation to handleCallback when MARSHAL completes. Coordinator creates BUILD tasks dynamically after reading execution-queue.json.
When M is known (deferred creation after MARSHAL), assign distinct roles:
| Build Count | Role Assignment |
|-------------|-----------------|
| M <= 2 | role: "implementer" |
| M > 2 | role: "implementer-1", ..., "implementer-M" (max 3) |
```json
{
"id": "BUILD-<NNN>",
"title": "BUILD-<NNN>",
"description": "PURPOSE: Implement solution for <issueId> | Success: Code committed, tests pass\nTASK:\n - Load bound solution and explorer context\n - Execute implementation via <execution_method>\n - Run tests, commit\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <issueId>\n - Upstream artifacts: explorations/context-<issueId>.json, solutions/solution-<issueId>.json, queue/execution-queue.json\nEXPECTED: <session>/builds/ with results\nCONSTRAINTS: Follow solution plan\n---\nInnerLoop: false\nexecution_method: <execution_method>\ncode_review: <code_review>",
"status": "pending",
"role": "implementer-<M>",
"prefix": "BUILD",
"deps": ["MARSHAL-001"],
"findings": "",
"error": ""
}
```
---
### Review-Fix Cycle (Full/Batch modes)
When AUDIT rejects a solution, coordinator creates fix tasks dynamically in handleCallback -- NOT at dispatch time.
**SOLVE-fix-001** (planner, revision) -- added to tasks.json dynamically:
```json
{
"id": "SOLVE-fix-001",
"title": "SOLVE-fix-001",
"description": "PURPOSE: Revise solution addressing reviewer feedback (fix cycle <round>) | Success: Revised solution addressing rejection reasons\nTASK:\n - Read reviewer feedback from audit report\n - Design alternative approach addressing concerns\n - Re-bind revised solution\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <rejected-issue-ids>\n - Upstream artifacts: audits/audit-report.json\n - Reviewer feedback: <rejection-reasons>\nEXPECTED: <session>/solutions/solution-<issueId>.json (revised)\nCONSTRAINTS: Address reviewer concerns specifically\n---\nInnerLoop: false",
"status": "pending",
"role": "planner",
"prefix": "SOLVE",
"deps": ["AUDIT-001"],
"findings": "",
"error": ""
}
```
**AUDIT-002** (reviewer, re-review) -- added to tasks.json dynamically:
```json
{
"id": "AUDIT-002",
"title": "AUDIT-002",
"description": "PURPOSE: Re-review revised solution (fix cycle <round>) | Success: Verdict on revised solution\nTASK:\n - Load revised solution\n - Re-evaluate previously rejected dimensions\n - Produce updated verdict\nCONTEXT:\n - Session: <session-folder>\n - Issue IDs: <rejected-issue-ids>\n - Upstream artifacts: solutions/solution-<issueId>.json (revised), audits/audit-report.json\nEXPECTED: <session>/audits/audit-report.json (updated)\nCONSTRAINTS: Focus on previously rejected dimensions\n---\nInnerLoop: false",
"status": "pending",
"role": "reviewer",
"prefix": "AUDIT",
"deps": ["SOLVE-fix-001"],
"findings": "",
"error": ""
}
```
## Validation
1. Verify all tasks created by reading tasks.json
2. Check dependency chain integrity:
- No circular dependencies
- All deps references exist
- First task(s) have empty deps (EXPLORE tasks)
3. Log task count and pipeline mode
4. Verify mode-specific constraints:
| Mode | Constraint |
|------|-----------|
| quick | Exactly 4 tasks, no AUDIT |
| full | Exactly 5 tasks, includes AUDIT |
| batch | N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + deferred BUILD |

194
.codex/skills/team-issue/roles/coordinator/commands/monitor.md Normal file
View File

@@ -0,0 +1,194 @@
# Monitor Pipeline
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
## Constants
- SPAWN_MODE: spawn_agent
- ONE_STEP_PER_INVOCATION: true
- FAST_ADVANCE_AWARE: true
- WORKER_AGENT: team_worker
- MAX_FIX_CYCLES: 2
## Handler Router
| Source | Handler |
|--------|---------|
| Message contains [explorer], [planner], [reviewer], [integrator], [implementer] | handleCallback |
| "consensus_blocked" | handleConsensus |
| "capability_gap" | handleAdapt |
| "check" or "status" | handleCheck |
| "resume" or "continue" | handleResume |
| All tasks completed | handleComplete |
| Default | handleSpawnNext |
## handleCallback
Worker completed. Process and advance.
1. Parse message to identify role and task ID:
| Message Pattern | Role Detection |
|----------------|---------------|
| `[explorer]` or task ID `EXPLORE-*` | explorer |
| `[planner]` or task ID `SOLVE-*` | planner |
| `[reviewer]` or task ID `AUDIT-*` | reviewer |
| `[integrator]` or task ID `MARSHAL-*` | integrator |
| `[implementer]` or task ID `BUILD-*` | implementer |
2. Mark task as completed: Read tasks.json, update matching entry status to "completed", write back
3. Record completion in session state
4. **Review gate check** (when reviewer completes):
- If completed task is AUDIT-* AND pipeline is full or batch:
- Read audit report from `<session>/audits/audit-report.json`
- Read .msg/meta.json for fix_cycles
| Verdict | fix_cycles < max | Action |
|---------|-----------------|--------|
| rejected | Yes | Increment fix_cycles, create SOLVE-fix + AUDIT re-review tasks (add to tasks.json per dispatch.md Review-Fix Cycle), proceed to handleSpawnNext |
| rejected | No (>= max) | Force proceed -- log warning, unblock MARSHAL |
| concerns | - | Log concerns, proceed to MARSHAL (non-blocking) |
| approved | - | Proceed to MARSHAL via handleSpawnNext |
- Log team_msg with type "review_result" or "fix_required"
- If force proceeding past rejection, mark skipped fix tasks as completed (skip)
5. **Deferred BUILD task creation** (when integrator completes):
- If completed task is MARSHAL-* AND pipeline is batch:
- Read execution queue from `.workflow/issues/queue/execution-queue.json`
- Parse parallel_groups to determine BUILD task count M
- Create BUILD-001..M tasks dynamically (add to tasks.json per dispatch.md Batch Pipeline BUILD section)
- Proceed to handleSpawnNext
6. Close completed agent: `close_agent({ id: <agentId> })`
7. Proceed to handleSpawnNext
## handleCheck
Read-only status report, then STOP.
```
[coordinator] Pipeline Status (<pipeline-mode>)
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] Fix Cycles: <fix_cycles>/<max_fix_cycles>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
## handleResume
1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending"
2. Proceed to handleSpawnNext
## handleSpawnNext
Find ready tasks, spawn workers, STOP.
1. Collect: completedSubjects, inProgressSubjects, readySubjects
2. No ready + work in progress -> report waiting, STOP
3. No ready + nothing in progress -> handleComplete
4. Has ready -> for each:
a. Update tasks.json entry status -> "in_progress"
b. team_msg log -> task_unblocked
c. Spawn team_worker:
```
const agentId = spawn_agent({
agent_type: "team_worker",
items: [{ type: "text", text: `## Role Assignment
role: <role>
role_spec: ~ or <project>/.codex/skills/team-issue/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: issue
requirement: <task-description>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` }]
})
```
d. Collect results: `wait_agent({ ids: [agentId], timeout_ms: 900000 })`
e. Read discoveries from output files
f. Update tasks.json with results
g. Close agent: `close_agent({ id: agentId })`
5. Parallel spawn rules:
| Pipeline | Scenario | Spawn Behavior |
|----------|----------|---------------|
| Quick | All stages | One worker at a time |
| Full | All stages | One worker at a time |
| Batch | EXPLORE-001..N unblocked | Spawn ALL N explorer workers in parallel (max 5) |
| Batch | BUILD-001..M unblocked | Spawn ALL M implementer workers in parallel (max 3) |
| Batch | Other stages | One worker at a time |
**Parallel spawn** (Batch mode with multiple ready tasks for same role):
```
const agentIds = []
for (const task of readyTasks) {
agentIds.push(spawn_agent({
agent_type: "team_worker",
items: [{ type: "text", text: `## Role Assignment
role: <role>
role_spec: ~ or <project>/.codex/skills/team-issue/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: issue
requirement: <task-description>
agent_name: <role>-<N>
inner_loop: false
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery, owner=<role>-<N>) -> role Phase 2-4 -> built-in Phase 5 (report).` }]
}))
}
const results = wait_agent({ ids: agentIds, timeout_ms: 900000 })
// Process results, close agents
for (const id of agentIds) { close_agent({ id }) }
```
6. Update session, output summary, STOP
## handleComplete
Pipeline done. Generate report and completion action.
Completion check by mode:
| Mode | Completion Condition |
|------|---------------------|
| quick | All 4 tasks completed |
| full | All 5 tasks (+ any fix cycle tasks) completed |
| batch | All N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + M BUILD (+ any fix cycle tasks) completed |
1. Verify all tasks completed via reading tasks.json
2. If any tasks not completed, return to handleSpawnNext
3. If all completed -> transition to coordinator Phase 5
## handleConsensus
Handle consensus_blocked signals.
| Severity | Action |
|----------|--------|
| HIGH | Pause pipeline, notify user with findings summary |
| MEDIUM | Log finding, attempt to continue |
| LOW | Log finding, continue pipeline |
## handleAdapt
Capability gap reported mid-pipeline.
1. Parse gap description
2. Check if existing role covers it -> redirect
3. Role count < 6 -> generate dynamic role-spec in <session>/role-specs/
4. Create new task (add to tasks.json), spawn worker
5. Role count >= 6 -> merge or pause
## Fast-Advance Reconciliation
On every coordinator wake:
1. Read team_msg entries with type="fast_advance"
2. Sync active_workers with spawned successors
3. No duplicate spawns

Some files were not shown because too many files have changed in this diff Show More