pi-maestro-flow 0.2.0

package/skills/team-designer/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: team-designer
+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: Agent AskUserQuestion Read Write Edit Bash Glob Grep mcp__maestro__team_msg
+---
+
+# Team Skill Designer
+
+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.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  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
+
+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
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (coding)**: `maestro load --type spec --category coding` — load coding constraints as shared context
+3. **Wiki knowledge**: `maestro search "skill design team architecture" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Execution Flow
+
+```
+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):
+
+| 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 |
+
+## Golden Sample
+
+Generated skills follow the architecture of `~  or <project>/.claude/skills/team-lifecycle-v4/`:
+
+```
+.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
+
+```
+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
+```
+
+## Core Rules
+
+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:
+
+```
+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]
+```
+
+## Error Handling
+
+- **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

package/skills/team-executor/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: team-executor
+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: TeamCreate TeamDelete SendMessage TaskCreate TaskUpdate TaskList TaskGet Agent AskUserQuestion Read Write Edit Bash Glob Grep mcp__maestro__team_msg
+---
+
+# Team Executor
+
+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.
+
+
+## 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]
+```
+
+---
+
+## 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)
+
+### Validation Steps
+
+1. **Check `--session` provided**:
+   - If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
+
+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. **Validation failure**:
+   - Report specific missing component
+   - Suggest re-running team-coordinate or checking path
+
+---
+
+## Role Router
+
+This skill is **executor-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
+
+### Dispatch Logic
+
+| Scenario | Action |
+|----------|--------|
+| No `--session` | **ERROR** immediately |
+| `--session` invalid | **ERROR** with specific reason |
+| Valid session | Orchestration Mode -> executor |
+
+### Orchestration Mode
+
+**Invocation**: `Skill(skill="team-executor", args="--session=<session-folder>")`
+
+**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 -> SendMessage callback -> executor advances next step
+  -> Loop until pipeline complete -> Phase 2 report + completion action
+```
+
+**User Commands** (wake paused executor):
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | Output execution status graph, no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+
+---
+
+## Role Registry
+
+| 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 |
+
+---
+
+## Executor Spawn Template
+
+### v2 Worker Spawn (all roles)
+
+When executor spawns workers, use `team-worker` agent with role-spec path:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## 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>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final SendMessage.
+
+Read role_spec file to load Phase 2-4 domain instructions.`
+})
+```
+
+---
+
+## Completion Action
+
+When pipeline completes (all tasks done), executor presents an interactive choice:
+
+```
+AskUserQuestion({
+  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
+
+| Choice | Steps |
+|--------|-------|
+| Archive & Clean | Update session status="completed" -> TeamDelete -> output final summary with artifact paths |
+| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-executor', args='--session=<path>')" |
+| Export Results | AskUserQuestion(target path) -> copy artifacts to target -> Archive & Clean |
+
+---
+
+## Integration with team-coordinate
+
+| 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
+
+| 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 |
+| task-analysis.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
+| 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 |
+| Fast-advance spawns wrong task | Executor reconciles on next callback |
+| Completion action fails | Default to Keep Active, log warning |

package/skills/team-frontend/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: team-frontend
+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: Agent TaskCreate TaskList TaskGet TaskUpdate TeamCreate TeamDelete SendMessage AskUserQuestion Read Write Edit Bash Glob Grep WebFetch WebSearch mcp__maestro__team_msg
+---
+
+# Team Frontend Development
+
+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.
+
+## Architecture
+
+```
+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
+
+| 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 |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (coding)**: `maestro load --type spec --category coding` — load coding constraints as shared context
+3. **Specs (ui)**: `maestro load --type spec --category ui` — load ui constraints as shared context
+4. **Wiki knowledge**: `maestro search "frontend component UI" --json` — top 5 entries as prior context
+5. All optional — proceed without if unavailable
+## 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**: `FE`
+- **Session path**: `.workflow/.team/FE-<slug>-<date>/`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: "frontend",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: frontend
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final SendMessage.
+
+Read role_spec file (@<skill_root>/roles/<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).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Session Directory
+
+```
+.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
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+
+## Error Handling
+
+| 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 |
+| Worker no response | Report waiting task, suggest user `resume` |
+| Pipeline deadlock | Check blockedBy chain, report blocking point |

package/skills/team-frontend-debug/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: team-frontend-debug
+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: TeamCreate TeamDelete SendMessage TaskCreate TaskUpdate TaskList TaskGet Agent AskUserQuestion Read Write Edit Bash Glob Grep mcp__maestro__team_msg mcp__chrome-devtools__*
+---
+
+# Frontend Debug Team
+
+Dual-mode frontend debugging: feature-list testing or bug-report debugging, powered by Chrome DevTools MCP.
+
+## Architecture
+
+```
+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 | Pipeline | Flow |
+|-------|----------|------|
+| Feature list / 功能清单 | `test-pipeline` | TEST → ANALYZE → FIX → VERIFY |
+| Bug report / 错误描述 | `debug-pipeline` | REPRODUCE → ANALYZE → FIX → VERIFY |
+
+## Role Registry
+
+| 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 |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (debug)**: `maestro load --type spec --category debug` — load debug constraints as shared context
+3. **Specs (ui)**: `maestro load --type spec --category ui` — load ui constraints as shared context
+4. **Wiki knowledge**: `maestro search "frontend debug devtools" --json` — top 5 entries as prior context
+5. All optional — proceed without if unavailable
+## 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**: `TFD`
+- **Session path**: `.workflow/.team/TFD-<slug>-<date>/`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
+
+## Workspace Resolution
+
+Coordinator MUST resolve paths at Phase 2 before TeamCreate:
+
+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)
+
+This ensures workers spawned with `run_in_background: true` always receive an absolute, resolvable path regardless of their working directory.
+
+## Chrome DevTools MCP Tools
+
+All browser inspection operations use Chrome DevTools MCP. Reproducer and Verifier are primary consumers.
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__chrome-devtools__navigate_page` | Navigate to target URL |
+| `mcp__chrome-devtools__take_screenshot` | Capture visual state |
+| `mcp__chrome-devtools__take_snapshot` | Capture DOM/a11y tree |
+| `mcp__chrome-devtools__list_console_messages` | Read console logs |
+| `mcp__chrome-devtools__get_console_message` | Get specific console message |
+| `mcp__chrome-devtools__list_network_requests` | Monitor network activity |
+| `mcp__chrome-devtools__get_network_request` | Inspect request/response detail |
+| `mcp__chrome-devtools__performance_start_trace` | Start performance recording |
+| `mcp__chrome-devtools__performance_stop_trace` | Stop and analyze trace |
+| `mcp__chrome-devtools__click` | Simulate user click |
+| `mcp__chrome-devtools__fill` | Fill form inputs |
+| `mcp__chrome-devtools__hover` | Hover over elements |
+| `mcp__chrome-devtools__evaluate_script` | Execute JavaScript in page |
+| `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 |
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: <team-name>
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final SendMessage.
+
+Read role_spec file (@<skill_root>/roles/<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).`
+})
+```
+
+## 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 |
+| `retry <TASK-ID>` | Re-run a failed task |
+
+## Completion Action
+
+When pipeline completes, coordinator presents:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "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 debugging" },
+      { label: "Export Results", description: "Export debug report and patches" }
+    ]
+  }]
+})
+```
+
+## Specs Reference
+
+- [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
+
+## Session Directory
+
+```
+.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
+```
+
+## Error Handling
+
+| 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 | 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 |