From 73cc2ef3fa00cbbd2256b31987532449d60be616 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 2 Mar 2026 15:57:55 +0800 Subject: [PATCH] Refactor and optimize templates and code structure - Deleted outdated templates for epics, product brief, and requirements PRD. - Introduced lazy loading for locale messages in i18n module to enhance performance. - Updated main application bootstrap to parallelize CSRF token fetching and locale loading. - Implemented code splitting for router configuration to optimize bundle size and loading times. - Added WebSocket connection limits and rate limiting to improve server performance and prevent abuse. - Enhanced input validation with compiled regex patterns for better performance and maintainability. --- .claude/skills/team-coordinate/SKILL.md | 445 ------------ .../coordinator/commands/analyze-task.md | 197 ------ .../roles/coordinator/commands/dispatch.md | 85 --- .../roles/coordinator/commands/monitor.md | 296 -------- .../team-coordinate/roles/coordinator/role.md | 283 -------- .../team-coordinate/specs/role-template.md | 434 ------------ .../subagents/discuss-subagent.md | 133 ---- .../subagents/explore-subagent.md | 120 ---- .claude/skills/team-executor/SKILL.md | 372 ---------- .../roles/executor/commands/monitor.md | 277 -------- .../team-executor/roles/executor/role.md | 202 ------ .../team-executor/specs/session-schema.md | 272 -------- .claude/skills/team-lifecycle-v3/SKILL.md | 384 ----------- .../team-lifecycle-v3/roles/analyst/role.md | 113 --- .../roles/architect/commands/assess.md | 193 ------ .../team-lifecycle-v3/roles/architect/role.md | 103 --- .../roles/coordinator/commands/dispatch.md | 142 ---- .../roles/coordinator/commands/monitor.md | 180 ----- .../roles/coordinator/role.md | 209 ------ .../roles/discussant/commands/critique.md | 136 ---- .../roles/discussant/role.md | 128 ---- .../roles/executor/commands/implement.md | 166 ----- .../team-lifecycle-v3/roles/executor/role.md | 103 --- .../team-lifecycle-v3/roles/explorer/role.md | 91 --- .../roles/fe-developer/role.md | 111 --- .../fe-qa/commands/pre-delivery-checklist.md | 152 ----- .../team-lifecycle-v3/roles/fe-qa/role.md | 113 --- .../roles/planner/commands/explore.md | 154 ----- .../team-lifecycle-v3/roles/planner/role.md | 120 ---- .../roles/reviewer/commands/code-review.md | 163 ----- .../roles/reviewer/commands/spec-quality.md | 202 ------ .../team-lifecycle-v3/roles/reviewer/role.md | 104 --- .../roles/tester/commands/validate.md | 152 ----- .../team-lifecycle-v3/roles/tester/role.md | 108 --- .../roles/writer/commands/generate-doc.md | 187 ----- .../team-lifecycle-v3/roles/writer/role.md | 96 --- .../specs/document-standards.md | 192 ------ .../team-lifecycle-v3/specs/quality-gates.md | 207 ------ .../team-lifecycle-v3/specs/team-config.json | 158 ----- .../templates/architecture-doc.md | 254 ------- .../templates/epics-template.md | 196 ------ .../templates/product-brief.md | 133 ---- .../templates/requirements-prd.md | 224 ------ .claude/skills/team-lifecycle-v4/SKILL.md | 643 ------------------ .../team-lifecycle-v4/roles/analyst/role.md | 174 ----- .../roles/architect/commands/assess.md | 193 ------ .../team-lifecycle-v4/roles/architect/role.md | 103 --- .../roles/coordinator/commands/dispatch.md | 198 ------ .../roles/coordinator/commands/monitor.md | 413 ----------- .../roles/coordinator/role.md | 230 ------- .../roles/executor/commands/implement.md | 166 ----- .../team-lifecycle-v4/roles/executor/role.md | 103 --- .../roles/fe-developer/role.md | 111 --- .../fe-qa/commands/pre-delivery-checklist.md | 152 ----- .../team-lifecycle-v4/roles/fe-qa/role.md | 113 --- .../roles/planner/commands/explore.md | 172 ----- .../team-lifecycle-v4/roles/planner/role.md | 139 ---- .../roles/reviewer/commands/code-review.md | 163 ----- .../roles/reviewer/commands/spec-quality.md | 202 ------ .../team-lifecycle-v4/roles/reviewer/role.md | 150 ---- .../roles/tester/commands/validate.md | 152 ----- .../team-lifecycle-v4/roles/tester/role.md | 108 --- .../roles/writer/commands/generate-doc.md | 192 ------ .../team-lifecycle-v4/roles/writer/role.md | 246 ------- .../specs/document-standards.md | 192 ------ .../team-lifecycle-v4/specs/quality-gates.md | 207 ------ .../team-lifecycle-v4/specs/team-config.json | 200 ------ .../subagents/discuss-subagent.md | 169 ----- .../subagents/doc-generation-subagent.md | 62 -- .../subagents/explore-subagent.md | 172 ----- .../templates/architecture-doc.md | 254 ------- .../templates/epics-template.md | 196 ------ .../templates/product-brief.md | 133 ---- .../templates/requirements-prd.md | 224 ------ ccw/frontend/src/lib/i18n.ts | 12 + ccw/frontend/src/main.tsx | 19 +- ccw/frontend/src/router.tsx | 263 +++++-- ccw/src/core/routes/notification-routes.ts | 23 +- ccw/src/core/websocket.ts | 75 +- 79 files changed, 306 insertions(+), 14108 deletions(-) delete mode 100644 .claude/skills/team-coordinate/SKILL.md delete mode 100644 .claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md delete mode 100644 .claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md delete mode 100644 .claude/skills/team-coordinate/roles/coordinator/commands/monitor.md delete mode 100644 .claude/skills/team-coordinate/roles/coordinator/role.md delete mode 100644 .claude/skills/team-coordinate/specs/role-template.md delete mode 100644 .claude/skills/team-coordinate/subagents/discuss-subagent.md delete mode 100644 .claude/skills/team-coordinate/subagents/explore-subagent.md delete mode 100644 .claude/skills/team-executor/SKILL.md delete mode 100644 .claude/skills/team-executor/roles/executor/commands/monitor.md delete mode 100644 .claude/skills/team-executor/roles/executor/role.md delete mode 100644 .claude/skills/team-executor/specs/session-schema.md delete mode 100644 .claude/skills/team-lifecycle-v3/SKILL.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/analyst/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/architect/commands/assess.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/architect/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/coordinator/commands/dispatch.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/coordinator/commands/monitor.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/coordinator/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/discussant/commands/critique.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/discussant/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/executor/commands/implement.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/executor/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/explorer/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/fe-developer/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/fe-qa/commands/pre-delivery-checklist.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/fe-qa/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/planner/commands/explore.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/planner/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/reviewer/commands/code-review.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/reviewer/commands/spec-quality.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/reviewer/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/tester/commands/validate.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/tester/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/writer/commands/generate-doc.md delete mode 100644 .claude/skills/team-lifecycle-v3/roles/writer/role.md delete mode 100644 .claude/skills/team-lifecycle-v3/specs/document-standards.md delete mode 100644 .claude/skills/team-lifecycle-v3/specs/quality-gates.md delete mode 100644 .claude/skills/team-lifecycle-v3/specs/team-config.json delete mode 100644 .claude/skills/team-lifecycle-v3/templates/architecture-doc.md delete mode 100644 .claude/skills/team-lifecycle-v3/templates/epics-template.md delete mode 100644 .claude/skills/team-lifecycle-v3/templates/product-brief.md delete mode 100644 .claude/skills/team-lifecycle-v3/templates/requirements-prd.md delete mode 100644 .claude/skills/team-lifecycle-v4/SKILL.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/analyst/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/architect/commands/assess.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/architect/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/coordinator/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/executor/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/fe-developer/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/fe-qa/commands/pre-delivery-checklist.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/fe-qa/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/planner/commands/explore.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/planner/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/reviewer/commands/code-review.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/reviewer/commands/spec-quality.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/reviewer/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/tester/commands/validate.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/tester/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/writer/commands/generate-doc.md delete mode 100644 .claude/skills/team-lifecycle-v4/roles/writer/role.md delete mode 100644 .claude/skills/team-lifecycle-v4/specs/document-standards.md delete mode 100644 .claude/skills/team-lifecycle-v4/specs/quality-gates.md delete mode 100644 .claude/skills/team-lifecycle-v4/specs/team-config.json delete mode 100644 .claude/skills/team-lifecycle-v4/subagents/discuss-subagent.md delete mode 100644 .claude/skills/team-lifecycle-v4/subagents/doc-generation-subagent.md delete mode 100644 .claude/skills/team-lifecycle-v4/subagents/explore-subagent.md delete mode 100644 .claude/skills/team-lifecycle-v4/templates/architecture-doc.md delete mode 100644 .claude/skills/team-lifecycle-v4/templates/epics-template.md delete mode 100644 .claude/skills/team-lifecycle-v4/templates/product-brief.md delete mode 100644 .claude/skills/team-lifecycle-v4/templates/requirements-prd.md diff --git a/.claude/skills/team-coordinate/SKILL.md b/.claude/skills/team-coordinate/SKILL.md deleted file mode 100644 index 4ca7a688..00000000 --- a/.claude/skills/team-coordinate/SKILL.md +++ /dev/null @@ -1,445 +0,0 @@ ---- -name: team-coordinate -description: Universal team coordination skill with dynamic role generation. Only coordinator is built-in -- all worker roles are generated at runtime based on task analysis. Beat/cadence model for orchestration. Triggers on "team coordinate". -allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) ---- - -# Team Coordinate - -Universal team coordination skill: analyze task -> generate roles -> dispatch -> execute -> deliver. Only the **coordinator** is built-in. All worker roles are **dynamically generated** based on task analysis. - -## Architecture - -``` -+---------------------------------------------------+ -| Skill(skill="team-coordinate") | -| args="task description" | -| args="--role=coordinator" | -| args="--role= --session=" | -+-------------------+-------------------------------+ - | Role Router - +---- --role present? ----+ - | NO | YES - v v - Orchestration Mode Role Dispatch - (auto -> coordinator) (route to role file) - | | - coordinator +-------+-------+ - (built-in) | --role=coordinator? - | | - YES | | NO - v | v - built-in | Dynamic Role - role.md | /roles/.md - - Subagents (callable by any role, not team members): - [discuss-subagent] - multi-perspective critique (dynamic perspectives) - [explore-subagent] - codebase exploration with cache -``` - -## Role Router - -### Input Parsing - -Parse `$ARGUMENTS` to extract `--role` and `--session`. If no `--role` -> Orchestration Mode (auto route to coordinator). - -### Role Registry - -Only coordinator is statically registered. All other roles are dynamic, stored in `team-session.json#roles`. - -| Role | File | Type | -|------|------|------| -| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | built-in orchestrator | -| (dynamic) | `/roles/.md` | runtime-generated worker | - -> **COMPACT PROTECTION**: Role files are execution documents. After context compression, role instructions become summaries only -- **MUST immediately `Read` the role.md to reload before continuing**. Never execute any Phase based on summaries. - -### Subagent Registry - -| Subagent | Spec | Callable By | Purpose | -|----------|------|-------------|---------| -| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | any role | Multi-perspective critique (dynamic perspectives) | -| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | any role | Codebase exploration with cache | - -### Dispatch - -1. Extract `--role` and `--session` from arguments -2. If no `--role` -> route to coordinator (Orchestration Mode) -3. If `--role=coordinator` -> Read built-in `roles/coordinator/role.md` -> Execute its phases -4. If `--role=`: - - **`--session` is REQUIRED** for dynamic roles. Error if not provided. - - Read `/roles/.md` -> Execute its phases - - If role file not found at path -> Error with expected path - -### Orchestration Mode - -When invoked without `--role`, coordinator auto-starts. 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 roles + initialize session - -> coordinator Phase 3: create task chain from dependency graph - -> coordinator Phase 4: spawn first batch workers (background) -> STOP - -> Worker executes -> SendMessage callback -> coordinator advances next step - -> Loop until pipeline complete -> Phase 5 report -``` - -**User Commands** (wake paused coordinator): - -| Command | Action | -|---------|--------| -| `check` / `status` | Output execution status graph, no advancement | -| `resume` / `continue` | Check worker states, advance next step | - ---- - -## Shared Infrastructure - -The following templates apply to all worker roles. Each generated role.md only needs to define **Phase 2-4** role-specific logic. - -### Worker Phase 1: Task Discovery (all workers shared) - -Each worker on startup executes the same task discovery flow: - -1. Call `TaskList()` to get all tasks -2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty -3. No tasks -> idle wait -4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress - -**Resume Artifact Check** (prevent duplicate output after resume): -- Check if this task's output artifacts already exist -- Artifacts complete -> skip to Phase 5 report completion -- Artifacts incomplete or missing -> normal Phase 2-4 execution - -### Worker Phase 5: Report + Fast-Advance (all workers shared) - -Task completion with optional fast-advance to skip coordinator round-trip: - -1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message - - Params: operation="log", team=****, from=, to="coordinator", type=, summary="[] ", ref= - - **`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name. - - **CLI fallback**: `ccw team log --team --from --to coordinator --type --summary "[] ..." --json` -2. **TaskUpdate**: Mark task completed -3. **Fast-Advance Check**: - - Call `TaskList()`, find pending tasks whose blockedBy are ALL completed - - If exactly 1 ready task AND its owner matches a simple successor pattern -> **spawn it directly** (skip coordinator) - - Otherwise -> **SendMessage** to coordinator for orchestration -4. **Loop**: Back to Phase 1 to check for next task - -**Fast-Advance Rules**: - -| Condition | Action | -|-----------|--------| -| Same-prefix successor (Inner Loop role) | Do not spawn, main agent inner loop (Phase 5-L) | -| 1 ready task, simple linear successor, different prefix | Spawn directly via Task(run_in_background: true) | -| Multiple ready tasks (parallel window) | SendMessage to coordinator (needs orchestration) | -| No ready tasks + others running | SendMessage to coordinator (status update) | -| No ready tasks + nothing running | SendMessage to coordinator (pipeline may be complete) | - -**Fast-advance failure recovery**: If a fast-advanced task fails, the coordinator detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing. See [monitor.md](roles/coordinator/commands/monitor.md). - -### Worker Inner Loop (roles with multiple same-prefix serial tasks) - -When a role has **2+ serial same-prefix tasks**, it loops internally instead of spawning new agents: - -**Inner Loop flow**: - -``` -Phase 1: Discover task (first time) - | - +- Found task -> Phase 2-3: Load context + Execute work - | | - | v - | Phase 4: Validation (+ optional Inline Discuss) - | | - | v - | Phase 5-L: Loop Completion - | | - | +- TaskUpdate completed - | +- team_msg log - | +- Accumulate summary to context_accumulator - | | - | +- More same-prefix tasks? - | | +- YES -> back to Phase 1 (inner loop) - | | +- NO -> Phase 5-F: Final Report - | | - | +- Interrupt conditions? - | +- consensus_blocked HIGH -> SendMessage -> STOP - | +- Errors >= 3 -> SendMessage -> STOP - | - +- Phase 5-F: Final Report - +- SendMessage (all task summaries) - +- STOP -``` - -**Phase 5-L vs Phase 5-F**: - -| Step | Phase 5-L (looping) | Phase 5-F (final) | -|------|---------------------|-------------------| -| TaskUpdate completed | YES | YES | -| team_msg log | YES | YES | -| Accumulate summary | YES | - | -| SendMessage to coordinator | NO | YES (all tasks summary) | -| Fast-Advance to next prefix | - | YES (check cross-prefix successors) | - -### Inline Discuss Protocol (optional for any role) - -After completing primary output, roles may call the discuss subagent inline. Unlike v4's fixed perspective definitions, team-coordinate uses **dynamic perspectives** specified by the coordinator when generating each role. - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss ", - prompt: -}) -``` - -**Consensus handling**: - -| Verdict | Severity | Role Action | -|---------|----------|-------------| -| consensus_reached | - | Include action items in report, proceed to Phase 5 | -| consensus_blocked | HIGH | SendMessage with structured format. Do NOT self-revise. | -| consensus_blocked | MEDIUM | SendMessage with warning. Proceed normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. | - -### Shared Explore Utility - -Any role needing codebase context calls the explore subagent: - -``` -Task({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore ", - prompt: -}) -``` - -**Cache**: Results stored in `explorations/` with `cache-index.json`. Before exploring, always check cache first. - -### Wisdom Accumulation (all roles) - -Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at session init. - -**Directory**: -``` -/wisdom/ -+-- learnings.md # Patterns and insights -+-- decisions.md # Design and strategy decisions -+-- issues.md # Known risks and issues -``` - -**Worker load** (Phase 2): Extract `Session: ` from task description, read wisdom files. -**Worker contribute** (Phase 4/5): Write discoveries to corresponding wisdom files. - -### Role Isolation Rules - -| Allowed | Prohibited | -|---------|-----------| -| Process own prefix tasks | Process other role's prefix tasks | -| SendMessage to coordinator | Directly communicate with other workers | -| Use tools appropriate to responsibility | Create tasks for other roles | -| Call discuss/explore subagents | Modify resources outside own scope | -| Fast-advance simple successors | Spawn parallel worker batches | -| Report capability_gap to coordinator | Attempt work outside scope | - -Coordinator additionally prohibited: directly write/modify deliverable artifacts, call implementation subagents directly, directly execute analysis/test/review. - ---- - -## Cadence Control - -**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP. - -``` -Beat Cycle (single beat) -====================================================================== - Event Coordinator Workers ----------------------------------------------------------------------- - callback/resume --> +- handleCallback -+ - | mark completed | - | check pipeline | - +- handleSpawnNext -+ - | find ready tasks | - | spawn workers ---+--> [Worker A] Phase 1-5 - | (parallel OK) --+--> [Worker B] Phase 1-5 - +- STOP (idle) -----+ | - | - callback <-----------------------------------------+ - (next beat) SendMessage + TaskUpdate(completed) -====================================================================== - - Fast-Advance (skips coordinator for simple linear successors) -====================================================================== - [Worker A] Phase 5 complete - +- 1 ready task? simple successor? --> spawn Worker B directly - +- complex case? --> SendMessage to coordinator -====================================================================== -``` - -**Pipelines are dynamic**: Unlike v4's predefined pipeline beat views (spec-only, impl-only, etc.), team-coordinate pipelines are generated per-task from the dependency graph. The beat model is the same -- only the pipeline shape varies. - ---- - -## Coordinator Spawn Template - -### Standard Worker (single-task role) - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker", - team_name: , - name: "", - run_in_background: true, - prompt: `You are team "" . - -## Primary Instruction -All your work MUST be executed by calling Skill to get role definition: -Skill(skill="team-coordinate", args="--role= --session=") - -Current requirement: -Session: - -## Role Guidelines -- Only process -* tasks, do not execute other role work -- All output prefixed with [] tag -- Only communicate with coordinator -- Do not use TaskCreate to create tasks for other roles -- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) -- After task completion, check for fast-advance opportunity (see SKILL.md Phase 5) - -## Workflow -1. Call Skill -> get role definition and execution logic -2. Follow role.md 5-Phase flow -3. team_msg(team=) + SendMessage results to coordinator -4. TaskUpdate completed -> check next task or fast-advance` -}) -``` - -### Inner Loop Worker (multi-task role) - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker (inner loop)", - team_name: , - name: "", - run_in_background: true, - prompt: `You are team "" . - -## Primary Instruction -All your work MUST be executed by calling Skill to get role definition: -Skill(skill="team-coordinate", args="--role= --session=") - -Current requirement: -Session: - -## Inner Loop Mode -You will handle ALL -* tasks in this session, not just the first one. -After completing each task, loop back to find the next -* task. -Only SendMessage to coordinator when: -- All -* tasks are done -- A consensus_blocked HIGH occurs -- Errors accumulate (>= 3) - -## Role Guidelines -- Only process -* tasks, do not execute other role work -- All output prefixed with [] tag -- Only communicate with coordinator -- Do not use TaskCreate to create tasks for other roles -- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) -- Use subagent calls for heavy work, retain summaries in context` -}) -``` - ---- - -## Session Directory - -``` -.workflow/.team/TC--/ -+-- team-session.json # Session state + dynamic role registry -+-- task-analysis.json # Phase 1 output: capabilities, dependency graph -+-- roles/ # Dynamic role definitions (generated Phase 2) -| +-- .md -| +-- .md -+-- artifacts/ # All MD deliverables from workers -| +-- .md -+-- shared-memory.json # Cross-role state store -+-- wisdom/ # Cross-task knowledge -| +-- learnings.md -| +-- decisions.md -| +-- issues.md -+-- explorations/ # Shared explore cache -| +-- cache-index.json -| +-- explore-.json -+-- discussions/ # Inline discuss records -| +-- .md -+-- .msg/ # Team message bus logs -``` - -### team-session.json Schema - -```json -{ - "session_id": "TC--", - "task_description": "", - "status": "active | paused | completed", - "team_name": "", - "roles": [ - { - "name": "", - "prefix": "", - "responsibility_type": "", - "inner_loop": false, - "role_file": "roles/.md" - } - ], - "pipeline": { - "dependency_graph": {}, - "tasks_total": 0, - "tasks_completed": 0 - }, - "active_workers": [], - "completed_tasks": [], - "created_at": "" -} -``` - ---- - -## Session Resume - -Coordinator supports `--resume` / `--continue` for interrupted sessions: - -1. Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions -2. Multiple matches -> AskUserQuestion for selection -3. Audit TaskList -> reconcile session state <-> task status -4. Reset in_progress -> pending (interrupted tasks) -5. Rebuild team and spawn needed workers only -6. Create missing tasks with correct blockedBy -7. Kick first executable task -> Phase 4 coordination loop - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Unknown --role value | Check if `/roles/.md` exists; error with message if not | -| Missing --role arg | Orchestration Mode -> coordinator | -| Dynamic role file not found | Error with expected path, coordinator may need to regenerate | -| Built-in role file not found | Error with expected path | -| Command file not found | Fallback to inline execution | -| Discuss subagent fails | Role proceeds without discuss, logs warning | -| Explore cache corrupt | Clear cache, re-explore | -| Fast-advance spawns wrong task | Coordinator reconciles on next callback | -| Session path not provided (dynamic role) | Error: `--session` is required for dynamic roles. Coordinator must always pass `--session=` when spawning workers. | -| capability_gap reported | Coordinator generates new role via handleAdapt | diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md b/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md deleted file mode 100644 index 96520c71..00000000 --- a/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md +++ /dev/null @@ -1,197 +0,0 @@ -# Command: analyze-task - -## Purpose - -Parse user task description -> detect required capabilities -> build dependency graph -> design dynamic roles. This replaces v4's static mode selection with intelligent task decomposition. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | User input from Phase 1 | Yes | -| Clarification answers | AskUserQuestion 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. E.g., "research and write a technical article" triggers both `researcher` and `writer`. - -**No match**: If no keywords 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 | `/artifacts/research-findings.md` | -| writer | Written document(s) | `/artifacts/.md` | -| developer | Code implementation | Source files + `/artifacts/implementation-summary.md` | -| designer | Design document | `/artifacts/design-spec.md` | -| analyst | Analysis report | `/artifacts/analysis-report.md` | -| tester | Test results | `/artifacts/test-report.md` | -| planner | Execution plan | `/artifacts/execution-plan.md` | - -### Step 3: Dependency Graph Construction - -Build a DAG of work streams using these inference rules: - -| Pattern | Shape | Example | -|---------|-------|---------| -| Knowledge -> Creation | research blockedBy nothing, creation blockedBy research | RESEARCH-001 -> DRAFT-001 | -| Design -> Build | design first, build after | DESIGN-001 -> IMPL-001 | -| Build -> Validate | build first, test/review after | IMPL-001 -> TEST-001 + ANALYSIS-001 | -| Plan -> Execute | plan first, execute after | PLAN-001 -> IMPL-001 | -| Independent parallel | no dependency between them | DRAFT-001 || IMPL-001 | -| Analysis -> Revise | analysis finds issues, revise artifact | ANALYSIS-001 -> DRAFT-002 | - -**Graph construction algorithm**: - -1. Group capabilities by natural ordering: knowledge-gathering -> design/planning -> creation -> validation -2. Within same tier: capabilities are parallel unless task description implies sequence -3. Between tiers: downstream blockedBy upstream -4. Single-capability tasks: one node, no dependencies - -**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: - -| Rule | Condition | Action | -|------|-----------|--------| -| Absorb trivial | Capability has exactly 1 task AND no explore needed | Merge into nearest related role | -| Merge overlap | Two capabilities share >50% keywords from task description | Combine into single role | -| Cap at 5 | More than 5 roles after initial assignment | Merge lowest-priority pairs (priority: researcher > designer > developer > writer > analyst > planner > tester) | - -**Merge priority** (when two must merge, keep the higher-priority one as the role name): - -1. developer (code-gen is hardest to merge) -2. researcher (context-gathering is foundational) -3. writer (document generation has specific patterns) -4. designer (design has specific outputs) -5. analyst (analysis can be absorbed by reviewer pattern) -6. planner (planning can be merged with researcher or designer) -7. tester (can be absorbed by developer or analyst) - -**IMPORTANT**: Even after merging, coordinator MUST spawn workers for all roles. Single-role tasks still use team architecture. - -## Phase 4: Output - -Write `/task-analysis.json`: - -```json -{ - "task_description": "", - "capabilities": [ - { - "name": "researcher", - "prefix": "RESEARCH", - "responsibility_type": "orchestration", - "tasks": [ - { "id": "RESEARCH-001", "description": "..." } - ], - "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 - }, - { - "name": "writer", - "prefix": "DRAFT", - "responsibility_type": "code-gen (docs)", - "task_count": 1, - "inner_loop": false - } - ], - "complexity": { - "capability_count": 2, - "cross_domain_factor": false, - "parallel_tracks": 0, - "serial_depth": 2, - "total_score": 3, - "level": "low" - }, - "artifacts": [ - { "name": "research-findings.md", "producer": "researcher", "path": "artifacts/research-findings.md" }, - { "name": "article-draft.md", "producer": "writer", "path": "artifacts/article-draft.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 roles, create team, spawn workers | -| Medium (2-3 roles) | Standard team | Generate roles, create team, spawn workers | -| High (3-5 roles) | Full team | Generate roles, create team, spawn workers | - -**All complexity levels use team architecture**: -- Single-role tasks still spawn worker via Skill -- 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 AskUserQuestion | -| All capabilities merge into one | Valid -- single-role execution via team worker | diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md b/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md deleted file mode 100644 index 0fc4948f..00000000 --- a/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md +++ /dev/null @@ -1,85 +0,0 @@ -# Command: dispatch - -## Purpose - -Create task chains from dynamic dependency graphs. Unlike v4's static mode-to-pipeline mapping, team-coordinate builds pipelines from the task-analysis.json produced by Phase 1. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task analysis | `/task-analysis.json` | Yes | -| Session file | `/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 owners exist in role registry -4. **For each task** (in topological order): - -``` -TaskCreate({ - subject: "-", - owner: "", - description: "\nSession: \nScope: \nInnerLoop: ", - blockedBy: [], - status: "pending" -}) -``` - -5. **Update team-session.json** with pipeline and tasks_total -6. **Validate** created chain - -### Task Description Template - -Every task description includes session path and inner loop flag: - -``` - -Session: -Scope: -InnerLoop: -``` - -### 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 owners valid | Every task owner exists in team-session.json#roles | -| All blockedBy valid | Every blockedBy references an existing task subject | -| Session reference | Every task description contains `Session: ` | - -## Phase 4: Validation - -| Check | Criteria | -|-------|----------| -| Task count | Matches dependency_graph node count | -| Dependencies | Every blockedBy references an existing task subject | -| Owner assignment | Each task owner 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 | -| Owner not in role registry | Error, coordinator must fix roles first | -| TaskCreate fails | Log error, report to coordinator | -| Duplicate task subject | Skip creation, log warning | -| Empty dependency graph | Error, task analysis may have failed | diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md b/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md deleted file mode 100644 index 50894c82..00000000 --- a/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md +++ /dev/null @@ -1,296 +0,0 @@ -# Command: monitor - -## Purpose - -Event-driven pipeline coordination with Spawn-and-Stop pattern. Adapted from v4 for dynamic roles -- role names are read from `team-session.json#roles` instead of hardcoded. Includes `handleAdapt` for mid-pipeline capability gap handling. - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` | -| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS | -| FAST_ADVANCE_AWARE | true | Workers may skip coordinator for simple linear successors | - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session file | `/team-session.json` | Yes | -| Task list | `TaskList()` | Yes | -| Active workers | session.active_workers[] | Yes | -| Role registry | session.roles[] | Yes | - -**Dynamic role resolution**: Known worker roles are loaded from `session.roles[].name` rather than a static list. This is the key difference from v4. - -## Phase 3: Handler Routing - -### Wake-up Source Detection - -Parse `$ARGUMENTS` to determine handler: - -| Priority | Condition | Handler | -|----------|-----------|---------| -| 1 | Message contains `[]` from session roles | handleCallback | -| 2 | Contains "capability_gap" | handleAdapt | -| 3 | Contains "check" or "status" | handleCheck | -| 4 | Contains "resume", "continue", or "next" | handleResume | -| 5 | None of the above (initial spawn after dispatch) | handleSpawnNext | - ---- - -### Handler: handleCallback - -Worker completed a task. Verify completion, update state, auto-advance. - -``` -Receive callback from [] - +- 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 - | | +- -> 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 note**: A worker may have already spawned its successor via fast-advance. When processing a callback: -1. Check if the expected next task is already `in_progress` (fast-advanced) -2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker -3. If no -> normal handleSpawnNext - ---- - -### Handler: handleCheck - -Read-only status report. No pipeline advancement. - -**Output format**: - -``` -[coordinator] Pipeline Status -[coordinator] Progress: / (%) - -[coordinator] Execution Graph: - - - done=completed >>>=running o=pending .=not created - -[coordinator] Active Workers: - > () - running [inner-loop: N/M tasks done] - -[coordinator] Ready to spawn: -[coordinator] Commands: 'resume' to advance | 'check' to refresh -``` - -**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=. - -**Graph rendering**: Read dependency_graph from task-analysis.json, render each node with status icon. Show parallel branches side-by-side. - -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 workers in background, update session, STOP. - -``` -Collect task states from TaskList() - +- completedSubjects: status = completed - +- inProgressSubjects: status = in_progress - +- readySubjects: pending + all blockedBy in completedSubjects - -Ready tasks found? - +- NONE + work in progress -> report waiting -> STOP - +- NONE + nothing in progress -> PIPELINE_COMPLETE -> Phase 5 - +- HAS ready tasks -> for each: - +- Is task owner 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 - +- TaskUpdate -> in_progress - +- team_msg log -> task_unblocked (team=, NOT team name) - +- Spawn worker (see spawn tool call below) - +- Add to session.active_workers - Update session file -> output summary -> STOP -``` - -**Spawn worker tool call** (one per ready task): - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker for ", - team_name: , - name: "", - run_in_background: true, - prompt: "" -}) -``` - ---- - -### 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 (per coordinator/role.md). 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: SendMessage to that role's owner -> STOP - | +- NO -> genuine gap, proceed to role 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: - +- Find best-fit role by responsibility_type - +- If merge possible: - +- Update existing role file with new capability - +- Create task assigned to existing role - +- Log via team_msg (type: warning, summary: "Capability merged into existing role") - +- STOP - +- If merge NOT possible: - +- PAUSE session - +- Report to user: - "Role limit (5) reached. Cannot generate new role for: - Options: - 1. Manually extend an existing role - 2. Re-run team-coordinate with refined task to consolidate roles - 3. Accept limitation and continue without this capability" - +- STOP - +- Generate new role: - 1. Read specs/role-template.md - 2. Fill template with capability details from gap description - 3. Write new role file to /roles/.md - 4. Add to session.roles[] - +- Create new task(s): - TaskCreate({ - subject: "-001", - owner: "", - description: "\nSession: \nInnerLoop: false", - blockedBy: [], - status: "pending" - }) - +- Update team-session.json: add role, increment tasks_total - +- Spawn new worker -> STOP -``` - ---- - -### Worker Failure Handling - -When a worker has unexpected status (not completed, not in_progress): - -1. Reset task -> pending via TaskUpdate -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 (task in_progress but no callback and worker gone): - -``` -handleCallback / handleResume detects: - +- Task is in_progress (was fast-advanced by predecessor) - +- No active_worker entry for this task - +- Original fast-advancing worker has already completed and exited - +- Resolution: - 1. TaskUpdate -> reset task to pending - 2. Remove stale active_worker entry (if any) - 3. Log via team_msg (type: error, summary: "Fast-advanced task failed, resetting for retry") - 4. -> handleSpawnNext (will re-spawn the task normally) -``` - -**Detection in handleResume**: - -``` -For each in_progress task in TaskList(): - +- Has matching active_worker? -> normal, skip - +- No matching active_worker? -> orphaned (likely fast-advance failure) - +- Check creation time: if > 5 minutes with no progress callback - +- Reset to pending -> handleSpawnNext -``` - -**Prevention**: Fast-advance failures are self-healing. The coordinator reconciles orphaned tasks on every `resume`/`check` cycle. - -### Consensus-Blocked Handling - -When a worker reports `consensus_blocked` in its callback: - -``` -handleCallback receives message with consensus_blocked flag - +- Extract: divergence_severity, blocked_round, action_recommendation - +- Route by severity: - | - +- severity = HIGH - | +- Create REVISION task: - | +- Same role, same doc type, incremented suffix (e.g., DRAFT-001-R1) - | +- Description includes: divergence details + action items from discuss - | +- blockedBy: none (immediate execution) - | +- Max 1 revision per task (DRAFT-001 -> DRAFT-001-R1, no R2) - | +- If already revised once -> PAUSE, escalate to user - | +- Update session: mark task as "revised", log revision chain - | - +- severity = MEDIUM - | +- Proceed with warning: include divergence in next task's context - | +- Log action items to wisdom/issues.md - | +- Normal handleSpawnNext - | - +- severity = LOW - +- Proceed normally: treat as consensus_reached with notes - +- Normal handleSpawnNext -``` - -## Phase 4: Validation - -| Check | Criteria | -|-------|----------| -| Session state consistent | active_workers matches TaskList in_progress tasks | -| No orphaned tasks | Every in_progress task has an active_worker entry | -| Dynamic roles valid | All task owners 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 | -| Fast-advance orphan check | in_progress tasks without active_worker entry -> reset to pending | - -## 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 | -| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext | -| Dynamic role file not found | Error, coordinator must regenerate from task-analysis | -| capability_gap from completed role | Validate gap, generate role if genuine | -| capability_gap when role limit (5) reached | Attempt merge into existing role, else pause for user | -| consensus_blocked HIGH | Create revision task (max 1) or pause for user | -| consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md | diff --git a/.claude/skills/team-coordinate/roles/coordinator/role.md b/.claude/skills/team-coordinate/roles/coordinator/role.md deleted file mode 100644 index aca17948..00000000 --- a/.claude/skills/team-coordinate/roles/coordinator/role.md +++ /dev/null @@ -1,283 +0,0 @@ -# Coordinator Role - -Orchestrate the team-coordinate workflow: task analysis, dynamic role generation, task dispatching, progress monitoring, session state. The sole built-in role -- all worker roles are generated at runtime. - -## Identity - -- **Name**: `coordinator` | **Tag**: `[coordinator]` -- **Responsibility**: Analyze task -> Generate roles -> Create team -> Dispatch tasks -> Monitor progress -> Report results - -## Boundaries - -### MUST -- Analyze user task to detect capabilities and build dependency graph -- Dynamically generate worker roles from specs/role-template.md -- Create team and spawn worker subagents in background -- Dispatch tasks with proper dependency chains from task-analysis.json -- Monitor progress via worker callbacks and route messages -- Maintain session state persistence (team-session.json) -- Handle capability_gap reports (generate new roles mid-pipeline) -- Handle consensus_blocked HIGH verdicts (create revision tasks or pause) -- Detect fast-advance orphans on resume/check and reset to pending - -### MUST NOT -- Execute task work directly (delegate to workers) -- Modify task output artifacts (workers own their deliverables) -- Call implementation subagents (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 - -> **Core principle**: coordinator is the orchestrator, not the executor. All actual work is delegated to dynamically generated worker roles. - ---- - -## Command Execution Protocol - -When coordinator needs to execute a command (analyze-task, dispatch, monitor): - -1. **Read the command file**: `roles/coordinator/commands/.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 -``` - ---- - -## Entry Router - -When coordinator is invoked, first detect the invocation type: - -| Detection | Condition | Handler | -|-----------|-----------|---------| -| Worker callback | Message 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 | -| 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: 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 -> AskUserQuestion for user selection - -**Session Reconciliation**: -1. Audit TaskList -> get real status of all tasks -2. Reconcile: session.completed_tasks <-> TaskList 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 (TeamCreate + spawn needed workers only) -7. Create missing tasks with correct blockedBy dependencies -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. - -**Workflow**: - -1. **Parse user task description** - -2. **Clarify if ambiguous** via AskUserQuestion: - - 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 - -4. **Output**: Write `/task-analysis.json` - -**Success**: Task analyzed, capabilities detected, dependency graph built, roles designed. - -**CRITICAL - Team Workflow Enforcement**: - -Regardless of complexity score or role count, coordinator MUST: -- ✅ **Always proceed to Phase 2** (generate roles) -- ✅ **Always create team** and spawn workers -- ❌ **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 Roles + Initialize Session - -**Objective**: Create session, generate dynamic role files, initialize shared infrastructure. - -**Workflow**: - -1. **Generate session ID**: `TC--` (slug from first 3 meaningful words of task) - -2. **Create session folder structure**: - ``` - .workflow/.team// - +-- roles/ - +-- artifacts/ - +-- wisdom/ - +-- explorations/ - +-- discussions/ - +-- .msg/ - ``` - -3. **Call TeamCreate** with team name derived from session ID - -4. **Read `specs/role-template.md`** + `task-analysis.json` - -5. **For each role in task-analysis.json#roles**: - - Fill role template with: - - role_name, prefix, responsibility_type from analysis - - Phase 2-4 content from responsibility type reference sections in template - - inner_loop flag from analysis (true if role has 2+ serial tasks) - - Task-specific instructions from task description - - Write generated role file to `/roles/.md` - -6. **Register roles** in team-session.json#roles - -7. **Initialize shared infrastructure**: - - `wisdom/learnings.md`, `wisdom/decisions.md`, `wisdom/issues.md` (empty with headers) - - `explorations/cache-index.json` (`{ "entries": [] }`) - - `shared-memory.json` (`{}`) - - `discussions/` (empty directory) - -8. **Write team-session.json** with: session_id, task_description, status="active", roles, pipeline (empty), active_workers=[], created_at - -**Success**: Session created, role 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. Creates tasks via TaskCreate with correct blockedBy -4. Assigns owner based on role mapping from task-analysis.json -5. Includes `Session: ` 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 in background, then STOP. - -**Design**: Spawn-and-Stop + Callback pattern, with worker fast-advance. -- Spawn workers with `Task(run_in_background: true)` -> immediately return -- Worker completes -> may fast-advance to next task OR SendMessage callback -> auto-advance -- User can use "check" / "resume" to manually advance -- Coordinator does one operation per invocation, then STOPS - -**Workflow**: -1. Load `commands/monitor.md` -2. Find tasks with: status=pending, blockedBy all resolved, owner assigned -3. For each ready task -> spawn worker (see SKILL.md Coordinator Spawn Template) - - Use Standard Worker template for single-task roles - - Use Inner Loop Worker template for multi-task roles -4. Output status summary with execution graph -5. STOP - -**Pipeline advancement** driven by three wake sources: -- Worker callback (automatic) -> Entry Router -> handleCallback -- User "check" -> handleCheck (status only) -- User "resume" -> handleResume (advance) - ---- - -## Phase 5: Report + Next Steps - -**Objective**: Completion report and follow-up options. - -**Workflow**: -1. Load session state -> count completed tasks, duration -2. List all deliverables with output paths in `/artifacts/` -3. Include discussion summaries (if inline discuss was used) -4. Summarize wisdom accumulated during execution -5. Update session status -> "completed" -6. Offer next steps: exit / view artifacts / extend with additional tasks - -**Output format**: - -``` -[coordinator] ============================================ -[coordinator] TASK COMPLETE -[coordinator] -[coordinator] Deliverables: -[coordinator] - () -[coordinator] - () -[coordinator] -[coordinator] Pipeline: / tasks -[coordinator] Roles: -[coordinator] Duration: -[coordinator] -[coordinator] Session: -[coordinator] ============================================ -``` - ---- - -## 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 | AskUserQuestion for clarification | -| Session corruption | Attempt recovery, fallback to manual reconciliation | -| Role generation fails | Fall back to single general-purpose role | -| capability_gap reported | handleAdapt: generate new role, 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 | diff --git a/.claude/skills/team-coordinate/specs/role-template.md b/.claude/skills/team-coordinate/specs/role-template.md deleted file mode 100644 index 1fbd3716..00000000 --- a/.claude/skills/team-coordinate/specs/role-template.md +++ /dev/null @@ -1,434 +0,0 @@ -# Dynamic Role Template - -Template used by coordinator to generate worker role.md files at runtime. Each generated role is written to `/roles/.md`. - -## Template - -```markdown -# Role: - - - -## Identity - -- **Name**: `` | **Tag**: `[]` -- **Task Prefix**: `-*` -- **Responsibility**: - -- **Mode**: Inner Loop (handle all `-*` tasks in single agent) - - -## Boundaries - -### MUST -- Only process `-*` prefixed tasks -- All output (SendMessage, team_msg, logs) must carry `[]` identifier -- Only communicate with coordinator via SendMessage -- Work strictly within responsibility scope -- Use fast-advance for simple linear successors (see SKILL.md Phase 5) -- Produce MD artifacts in `/artifacts/` - -- Use subagent for heavy work (do not execute CLI/generation in main agent context) -- Maintain context_accumulator across tasks within the inner loop -- Loop through all `-*` tasks before reporting to coordinator - - -### MUST NOT -- Execute work outside this role's responsibility scope -- Communicate directly with other worker roles (must go through coordinator) -- Create tasks for other roles (TaskCreate is coordinator-exclusive) -- Modify files or resources outside this role's scope -- Omit `[]` identifier in any output -- Fast-advance when multiple tasks are ready or at checkpoint boundaries - -- Execute heavy work (CLI calls, large document generation) in main agent (delegate to subagent) -- SendMessage to coordinator mid-loop (unless consensus_blocked HIGH or error count >= 3) - - -## Toolbox - -| Tool | Purpose | -|------|---------| - - -## Message Types - -| Type | Direction | Description | -|------|-----------|-------------| -| `_complete` | -> coordinator | Task completed with artifact path | -| `_error` | -> coordinator | Error encountered | -| `capability_gap` | -> coordinator | Work outside role scope discovered | - -## Message Bus - -Before every SendMessage, log via `mcp__ccw-tools__team_msg`: - -``` -mcp__ccw-tools__team_msg({ - operation: "log", - team: , - from: "", - to: "coordinator", - type: , - summary: "[] complete: ", - ref: -}) -``` - -**`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name. - -**CLI fallback** (when MCP unavailable): - -``` -Bash("ccw team log --team --from --to coordinator --type --summary \"[] complete\" --ref --json") -``` - ---- - -## Execution (5-Phase) - -### Phase 1: Task Discovery - -> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery - -Standard task discovery flow: TaskList -> filter by prefix `-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress. - -### Phase 2: - - - -### Phase 3: - - - -### Phase 4: - - - - -### Phase 4b: Inline Discuss (optional) - -After primary work, optionally call discuss subagent: - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss ", - prompt: "## Multi-Perspective Critique: - See subagents/discuss-subagent.md for prompt template. - Perspectives: " -}) -``` - -| Verdict | Severity | Action | -|---------|----------|--------| -| consensus_reached | - | Include action items in report, proceed to Phase 5 | -| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format. Do NOT self-revise. | -| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. | - - - -### Phase 5-L: Loop Completion (Inner Loop) - -When more same-prefix tasks remain: - -1. **TaskUpdate**: Mark current task completed -2. **team_msg**: Log task completion -3. **Accumulate summary**: - ``` - context_accumulator.append({ - task: "", - artifact: "", - key_decisions: , - discuss_verdict: , - summary: - }) - ``` -4. **Interrupt check**: - - consensus_blocked HIGH -> SendMessage -> STOP - - Error count >= 3 -> SendMessage -> STOP -5. **Loop**: Back to Phase 1 - -**Does NOT**: SendMessage to coordinator, Fast-Advance spawn. - -### Phase 5-F: Final Report (Inner Loop) - -When all same-prefix tasks are done: - -1. **TaskUpdate**: Mark last task completed -2. **team_msg**: Log completion -3. **Summary report**: All tasks summary + discuss results + artifact paths -4. **Fast-Advance check**: Check cross-prefix successors -5. **SendMessage** or **spawn successor** - -> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report + Fast-Advance - - -### Phase 5: Report + Fast-Advance - -> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report + Fast-Advance - -Standard report flow: team_msg log -> SendMessage with `[]` prefix -> TaskUpdate completed -> Fast-Advance Check -> Loop to Phase 1 for next task. - - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| No -* tasks available | Idle, wait for coordinator assignment | -| Context file not found | Notify coordinator, request location | -| Subagent fails | Retry once with fallback; still fails -> log error, continue next task | -| Fast-advance spawn fails | Fall back to SendMessage to coordinator | - -| Cumulative 3 task failures | SendMessage to coordinator, STOP inner loop | -| Agent crash mid-loop | Coordinator detects orphan on resume -> re-spawn -> resume from interrupted task | - -| Work outside scope discovered | SendMessage capability_gap to coordinator | -| Critical issue beyond scope | SendMessage fix_required to coordinator | -``` - ---- - -## Phase 2-4 Content by Responsibility Type - -Reference sections for coordinator to fill when generating roles. Select the matching section based on `responsibility_type`. - -### orchestration - -**Phase 2: Context Assessment** - -``` -| Input | Source | Required | -|-------|--------|----------| -| Task description | From TaskGet | Yes | -| Shared memory | /shared-memory.json | No | -| Prior artifacts | /artifacts/ | No | -| Wisdom | /wisdom/ | No | - -Loading steps: -1. Extract session path from task description -2. Read shared-memory.json for cross-role context -3. Read prior artifacts (if any exist from upstream tasks) -4. Load wisdom files for accumulated knowledge -5. Optionally call explore subagent for codebase context -``` - -**Phase 3: Subagent Execution** - -``` -Delegate to appropriate subagent based on task: - -Task({ - subagent_type: "general-purpose", - run_in_background: false, - description: " for ", - prompt: "## Task - - - - Session: - ## Context - - ## Expected Output - Write artifact to: /artifacts/.md - Return JSON summary: { artifact_path, summary, key_decisions[], warnings[] }" -}) -``` - -**Phase 4: Result Aggregation** - -``` -1. Verify subagent output artifact exists -2. Read artifact, validate structure/completeness -3. Update shared-memory.json with key findings -4. Write insights to wisdom/ files -``` - -### code-gen (docs) - -**Phase 2: Load Prior Context** - -``` -| Input | Source | Required | -|-------|--------|----------| -| Task description | From TaskGet | Yes | -| Prior artifacts | /artifacts/ from upstream tasks | Conditional | -| Shared memory | /shared-memory.json | No | -| Wisdom | /wisdom/ | No | - -Loading steps: -1. Extract session path from task description -2. Read upstream artifacts (e.g., research findings for a writer) -3. Read shared-memory.json for cross-role context -4. Load wisdom for accumulated decisions -``` - -**Phase 3: Document Generation** - -``` -Task({ - subagent_type: "universal-executor", - run_in_background: false, - description: "Generate for ", - prompt: "## Task - - Generate: - - Session: - ## Prior Context - - ## Instructions - - ## Expected Output - Write document to: /artifacts/.md - Return JSON: { artifact_path, summary, key_decisions[], sections_generated[], warnings[] }" -}) -``` - -**Phase 4: Structure Validation** - -``` -1. Verify document artifact exists -2. Check document has expected sections -3. Validate no placeholder text remains -4. Update shared-memory.json with document metadata -``` - -### code-gen (code) - -**Phase 2: Load Plan/Specs** - -``` -| Input | Source | Required | -|-------|--------|----------| -| Task description | From TaskGet | Yes | -| Plan/design artifacts | /artifacts/ | Conditional | -| Shared memory | /shared-memory.json | No | -| Wisdom | /wisdom/ | No | - -Loading steps: -1. Extract session path from task description -2. Read plan/design artifacts from upstream -3. Load shared-memory.json for implementation context -4. Load wisdom for conventions and patterns -``` - -**Phase 3: Code Implementation** - -``` -Task({ - subagent_type: "code-developer", - run_in_background: false, - description: "Implement ", - prompt: "## Task - - - - Session: - ## Plan/Design Context - - ## Instructions - - ## Expected Output - Implement code changes. - Write summary to: /artifacts/implementation-summary.md - Return JSON: { artifact_path, summary, files_changed[], key_decisions[], warnings[] }" -}) -``` - -**Phase 4: Syntax Validation** - -``` -1. Run syntax check (tsc --noEmit or equivalent) -2. Verify all planned files exist -3. Check no broken imports -4. If validation fails -> attempt auto-fix (max 2 attempts) -5. Write implementation summary to artifacts/ -``` - -### read-only - -**Phase 2: Target Loading** - -``` -| Input | Source | Required | -|-------|--------|----------| -| Task description | From TaskGet | Yes | -| Target artifacts/files | From task description or upstream | Yes | -| Shared memory | /shared-memory.json | No | - -Loading steps: -1. Extract session path and target files from task description -2. Read target artifacts or source files for analysis -3. Load shared-memory.json for context -``` - -**Phase 3: Multi-Dimension Analysis** - -``` -Task({ - subagent_type: "general-purpose", - run_in_background: false, - description: "Analyze for ", - prompt: "## Task - - Analyze: - - Dimensions: - - Session: - ## Target Content - - ## Expected Output - Write report to: /artifacts/analysis-report.md - Return JSON: { artifact_path, summary, findings[], severity_counts: {critical, high, medium, low} }" -}) -``` - -**Phase 4: Severity Classification** - -``` -1. Verify analysis report exists -2. Classify findings by severity (Critical/High/Medium/Low) -3. Update shared-memory.json with key findings -4. Write issues to wisdom/issues.md -``` - -### validation - -**Phase 2: Environment Detection** - -``` -| Input | Source | Required | -|-------|--------|----------| -| Task description | From TaskGet | Yes | -| Implementation artifacts | Upstream code changes | Yes | - -Loading steps: -1. Detect test framework from project files -2. Get changed files from implementation -3. Identify test command and coverage tool -``` - -**Phase 3: Test-Fix Cycle** - -``` -Task({ - subagent_type: "test-fix-agent", - run_in_background: false, - description: "Test-fix for ", - prompt: "## Task - - Run tests and fix failures - - Session: - - Max iterations: 5 - ## Changed Files - - ## Expected Output - Write report to: /artifacts/test-report.md - Return JSON: { artifact_path, pass_rate, coverage, iterations_used, remaining_failures[] }" -}) -``` - -**Phase 4: Result Analysis** - -``` -1. Check pass rate >= 95% -2. Check coverage meets threshold -3. Generate test report with pass/fail counts -4. Update shared-memory.json with test results -``` diff --git a/.claude/skills/team-coordinate/subagents/discuss-subagent.md b/.claude/skills/team-coordinate/subagents/discuss-subagent.md deleted file mode 100644 index fff00818..00000000 --- a/.claude/skills/team-coordinate/subagents/discuss-subagent.md +++ /dev/null @@ -1,133 +0,0 @@ -# Discuss Subagent - -Lightweight multi-perspective critique engine. Called inline by any role needing peer review. Perspectives are dynamic -- specified by the calling role, not pre-defined. - -## Design - -Unlike team-lifecycle-v4's fixed perspective definitions (product, technical, quality, risk, coverage), team-coordinate uses **dynamic perspectives** passed in the prompt. The calling role decides what viewpoints matter for its artifact. - -## Invocation - -Called by roles after artifact creation: - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss ", - prompt: `## Multi-Perspective Critique: - -### Input -- Artifact: -- Round: -- Session: - -### Perspectives - - -Example: -| Perspective | CLI Tool | Role | Focus Areas | -|-------------|----------|------|-------------| -| Feasibility | gemini | Engineer | Implementation complexity, technical risks, resource needs | -| Clarity | codex | Editor | Readability, logical flow, completeness of explanation | -| Accuracy | gemini | Domain Expert | Factual correctness, source reliability, claim verification | - -### Execution Steps -1. Read artifact from -2. For each perspective, launch CLI analysis in background: - Bash(command="ccw cli -p 'PURPOSE: Analyze from perspective for - TASK: - MODE: analysis - CONTEXT: Artifact content below - EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5) - CONSTRAINTS: Output valid JSON only - - Artifact: - ' --tool --mode analysis", run_in_background=true) -3. Wait for all CLI results -4. Divergence detection: - - High severity: any rating <= 2, critical issue identified - - Medium severity: rating spread (max - min) >= 3, or single perspective rated <= 2 with others >= 3 - - Low severity: minor suggestions only, all ratings >= 3 -5. Consensus determination: - - No high-severity divergences AND average rating >= 3.0 -> consensus_reached - - Otherwise -> consensus_blocked -6. Synthesize: - - Convergent themes (agreed by 2+ perspectives) - - Divergent views (conflicting assessments) - - Action items from suggestions -7. Write discussion record to: /discussions/-discussion.md - -### Discussion Record Format -# Discussion Record: - -**Artifact**: -**Perspectives**: -**Consensus**: reached / blocked -**Average Rating**: /5 - -## Convergent Themes -- - -## Divergent Views -- **** (): - -## Action Items -1. - -## Ratings -| Perspective | Rating | -|-------------|--------| -| | /5 | - -### Return Value - -**When consensus_reached**: -Return a summary string with: -- Verdict: consensus_reached -- Average rating -- Key action items (top 3) -- Discussion record path - -**When consensus_blocked**: -Return a structured summary with: -- Verdict: consensus_blocked -- Severity: HIGH | MEDIUM | LOW -- Average rating -- Divergence summary: top 3 divergent points with perspective attribution -- Action items: prioritized list of required changes -- Recommendation: revise | proceed-with-caution | escalate -- Discussion record path - -### Error Handling -- Single CLI fails -> fallback to direct Claude analysis for that perspective -- All CLI fail -> generate basic discussion from direct artifact reading -- Artifact not found -> return error immediately` -}) -``` - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Complete primary artifact output -2. **Calling**: Invoke discuss subagent with appropriate dynamic perspectives -3. **After calling**: - -| Verdict | Severity | Role Action | -|---------|----------|-------------| -| consensus_reached | - | Include action items in Phase 5 report, proceed normally | -| consensus_blocked | HIGH | Include divergence details in Phase 5 SendMessage. Do NOT self-revise -- coordinator decides. | -| consensus_blocked | MEDIUM | Include warning in Phase 5 SendMessage. Proceed normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. | - -**SendMessage format for consensus_blocked (HIGH or MEDIUM)**: - -``` -[] complete. Discuss : consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -Artifact: -Discussion: -``` diff --git a/.claude/skills/team-coordinate/subagents/explore-subagent.md b/.claude/skills/team-coordinate/subagents/explore-subagent.md deleted file mode 100644 index e934f7ed..00000000 --- a/.claude/skills/team-coordinate/subagents/explore-subagent.md +++ /dev/null @@ -1,120 +0,0 @@ -# Explore Subagent - -Shared codebase exploration utility with centralized caching. Callable by any role needing code context. - -## Invocation - -``` -Task({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore ", - prompt: `Explore codebase for: - -Focus angle: -Keywords: -Session folder: - -## Cache Check -1. Read /explorations/cache-index.json (if exists) -2. Look for entry with matching angle -3. If found AND file exists -> read cached result, return summary -4. If not found -> proceed to exploration - -## Exploration - - -## Output -Write JSON to: /explorations/explore-.json -Update cache-index.json with new entry - -## Output Schema -{ - "angle": "", - "query": "", - "relevant_files": [ - { "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] } - ], - "patterns": [], - "dependencies": [], - "external_refs": [], - "_metadata": { "created_by": "", "timestamp": "...", "cache_key": "..." } -} - -Return summary: file count, pattern count, top 5 files, output path` -}) -``` - -## Cache Mechanism - -### Cache Index Schema - -`/explorations/cache-index.json`: - -```json -{ - "entries": [ - { - "angle": "architecture", - "keywords": ["auth", "middleware"], - "file": "explore-architecture.json", - "created_by": "analyst", - "created_at": "2026-02-27T10:00:00Z", - "file_count": 15 - } - ] -} -``` - -### Cache Lookup Rules - -| Condition | Action | -|-----------|--------| -| Exact angle match exists | Return cached result | -| No match | Execute exploration, cache result | -| Cache file missing but index has entry | Remove stale entry, re-explore | - -### Cache Invalidation - -Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache. - -## Angle Focus Guide - -| Angle | Focus Points | Typical Caller | -|-------|-------------|----------------| -| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | any | -| dependencies | Import chains, external libraries, circular dependencies, shared utilities | any | -| modularity | Module interfaces, separation of concerns, extraction opportunities | any | -| integration-points | API endpoints, data flow between modules, event systems | any | -| security | Auth/authz logic, input validation, sensitive data handling, middleware | any | -| dataflow | Data transformations, state propagation, validation points | any | -| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | any | -| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | any | -| patterns | Code conventions, design patterns, naming conventions, best practices | any | -| testing | Test files, coverage gaps, test patterns, mocking strategies | any | -| general | Broad semantic search for topic-related code | any | - -## Exploration Strategies - -### Low Complexity (direct search) - -For simple queries, use ACE semantic search: - -``` -mcp__ace-tool__search_context(project_root_path="", query="") -``` - -ACE failure fallback: `rg -l '' --type ts` - -### Medium/High Complexity (multi-angle) - -For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles. - -## Search Tool Priority - -| Tool | Priority | Use Case | -|------|----------|----------| -| mcp__ace-tool__search_context | P0 | Semantic search | -| Grep / Glob | P1 | Pattern matching | -| cli-explore-agent | Deep | Multi-angle exploration | -| WebSearch | P3 | External docs | diff --git a/.claude/skills/team-executor/SKILL.md b/.claude/skills/team-executor/SKILL.md deleted file mode 100644 index 2c108a28..00000000 --- a/.claude/skills/team-executor/SKILL.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -name: team-executor -description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. 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(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) ---- - -# Team Executor - -Lightweight session execution skill: load session -> reconcile state -> spawn workers -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions. - -## Architecture - -``` -+---------------------------------------------------+ -| Skill(skill="team-executor") | -| args="--session=" [REQUIRED] | -| args="--role=" (for worker dispatch) | -+-------------------+-------------------------------+ - | Session Validation - +---- --session valid? ----+ - | NO | YES - v v - Error immediately Role Router - (no session) | - +-------+-------+ - | --role present? - | | - YES | | NO - v | v - Route to | Orchestration Mode - session | -> executor - role.md | -``` - ---- - -## Session Validation (BEFORE routing) - -**CRITICAL**: Session validation MUST occur before any role routing. - -### Parse Arguments - -Extract from `$ARGUMENTS`: -- `--session=`: Path to team-coordinate session folder (REQUIRED) -- `--role=`: Role to dispatch (optional, defaults to orchestration mode) - -### Validation Steps - -1. **Check `--session` provided**: - - If missing -> **ERROR**: "Session required. Usage: --session=" - - Do NOT proceed - -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 - - `roles/` directory has at least one `.md` file - - Each role in `team-session.json#roles` has corresponding `.md` file in `roles/` - -3. **Validation failure**: - - Report specific missing component - - Suggest re-running team-coordinate or checking path - - Do NOT proceed - -### Validation Checklist - -``` -Session Validation Checklist: -[ ] --session argument provided -[ ] Directory exists at path -[ ] team-session.json exists and parses -[ ] task-analysis.json exists and parses -[ ] roles/ directory has >= 1 .md files -[ ] All session.roles[] have corresponding roles/.md -``` - ---- - -## Role Router - -### Dispatch Logic - -| Scenario | Action | -|----------|--------| -| No `--session` | **ERROR** immediately | -| `--session` invalid | **ERROR** with specific reason | -| No `--role` | Orchestration Mode -> executor | -| `--role=executor` | Read built-in `roles/executor/role.md` | -| `--role=` | Read `/roles/.md` | - -### Orchestration Mode - -When invoked without `--role`, executor auto-starts. - -**Invocation**: `Skill(skill="team-executor", args="--session=")` - -**Lifecycle**: -``` -Validate session - -> executor Phase 0: Reconcile state (reset interrupted, detect orphans) - -> executor Phase 1: Spawn first batch workers (background) -> STOP - -> Worker executes -> SendMessage callback -> executor advances next step - -> Loop until pipeline complete -> Phase 2 report -``` - -**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) | `/roles/.md` | loaded from session | - -> **COMPACT PROTECTION**: Role files are execution documents. After context compression, role instructions become summaries only -- **MUST immediately `Read` the role.md to reload before continuing**. Never execute any Phase based on summaries. - ---- - -## Shared Infrastructure - -The following templates apply to all worker roles. Each loaded role.md follows the same structure. - -### Worker Phase 1: Task Discovery (all workers shared) - -Each worker on startup executes the same task discovery flow: - -1. Call `TaskList()` to get all tasks -2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty -3. No tasks -> idle wait -4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress - -**Resume Artifact Check** (prevent duplicate output after resume): -- Check if this task's output artifacts already exist -- Artifacts complete -> skip to Phase 5 report completion -- Artifacts incomplete or missing -> normal Phase 2-4 execution - -### Worker Phase 5: Report + Fast-Advance (all workers shared) - -Task completion with optional fast-advance to skip executor round-trip: - -1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message - - Params: operation="log", team=****, from=, to="executor", type=, summary="[] ", ref= - - **`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name. - - **CLI fallback**: `ccw team log --team --from --to executor --type --summary "[] ..." --json` -2. **TaskUpdate**: Mark task completed -3. **Fast-Advance Check**: - - Call `TaskList()`, find pending tasks whose blockedBy are ALL completed - - If exactly 1 ready task AND its owner matches a simple successor pattern -> **spawn it directly** (skip executor) - - Otherwise -> **SendMessage** to executor for orchestration -4. **Loop**: Back to Phase 1 to check for next task - -**Fast-Advance Rules**: - -| Condition | Action | -|-----------|--------| -| Same-prefix successor (Inner Loop role) | Do not spawn, main agent inner loop (Phase 5-L) | -| 1 ready task, simple linear successor, different prefix | Spawn directly via Task(run_in_background: true) | -| Multiple ready tasks (parallel window) | SendMessage to executor (needs orchestration) | -| No ready tasks + others running | SendMessage to executor (status update) | -| No ready tasks + nothing running | SendMessage to executor (pipeline may be complete) | - -**Fast-advance failure recovery**: If a fast-advanced task fails, the executor detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing. See [monitor.md](roles/executor/commands/monitor.md). - -### Worker Inner Loop (roles with multiple same-prefix serial tasks) - -When a role has **2+ serial same-prefix tasks**, it loops internally instead of spawning new agents: - -**Inner Loop flow**: - -``` -Phase 1: Discover task (first time) - | - +- Found task -> Phase 2-3: Load context + Execute work - | | - | v - | Phase 4: Validation (+ optional Inline Discuss) - | | - | v - | Phase 5-L: Loop Completion - | | - | +- TaskUpdate completed - | +- team_msg log - | +- Accumulate summary to context_accumulator - | | - | +- More same-prefix tasks? - | | +- YES -> back to Phase 1 (inner loop) - | | +- NO -> Phase 5-F: Final Report - | | - | +- Interrupt conditions? - | +- consensus_blocked HIGH -> SendMessage -> STOP - | +- Errors >= 3 -> SendMessage -> STOP - | - +- Phase 5-F: Final Report - +- SendMessage (all task summaries) - +- STOP -``` - -**Phase 5-L vs Phase 5-F**: - -| Step | Phase 5-L (looping) | Phase 5-F (final) | -|------|---------------------|-------------------| -| TaskUpdate completed | YES | YES | -| team_msg log | YES | YES | -| Accumulate summary | YES | - | -| SendMessage to executor | NO | YES (all tasks summary) | -| Fast-Advance to next prefix | - | YES (check cross-prefix successors) | - -### Wisdom Accumulation (all roles) - -Cross-task knowledge accumulation. Loaded from session at startup. - -**Directory**: -``` -/wisdom/ -+-- learnings.md # Patterns and insights -+-- decisions.md # Design and strategy decisions -+-- issues.md # Known risks and issues -``` - -**Worker load** (Phase 2): Extract `Session: ` from task description, read wisdom files. -**Worker contribute** (Phase 4/5): Write discoveries to corresponding wisdom files. - -### Role Isolation Rules - -| Allowed | Prohibited | -|---------|-----------| -| Process own prefix tasks | Process other role's prefix tasks | -| SendMessage to executor | Directly communicate with other workers | -| Use tools appropriate to responsibility | Create tasks for other roles | -| Fast-advance simple successors | Spawn parallel worker batches | -| Report capability_gap to executor | Attempt work outside scope | - -Executor additionally prohibited: directly write/modify deliverable artifacts, call implementation subagents directly, directly execute analysis/test/review, generate new roles. - ---- - -## Cadence Control - -**Beat model**: Event-driven, each beat = executor wake -> process -> spawn -> STOP. - -``` -Beat Cycle (single beat) -====================================================================== - Event Executor Workers ----------------------------------------------------------------------- - callback/resume --> +- handleCallback -+ - | mark completed | - | check pipeline | - +- handleSpawnNext -+ - | find ready tasks | - | spawn workers ---+--> [Worker A] Phase 1-5 - | (parallel OK) --+--> [Worker B] Phase 1-5 - +- STOP (idle) -----+ | - | - callback <-----------------------------------------+ - (next beat) SendMessage + TaskUpdate(completed) -====================================================================== - - Fast-Advance (skips executor for simple linear successors) -====================================================================== - [Worker A] Phase 5 complete - +- 1 ready task? simple successor? --> spawn Worker B directly - +- complex case? --> SendMessage to executor -====================================================================== -``` - ---- - -## Executor Spawn Template - -### Standard Worker (single-task role) - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker", - team_name: , - name: "", - run_in_background: true, - prompt: `You are team "" . - -## Primary Instruction -All your work MUST be executed by calling Skill to get role definition: -Skill(skill="team-executor", args="--role= --session=") - -Current requirement: -Session: - -## Role Guidelines -- Only process -* tasks, do not execute other role work -- All output prefixed with [] tag -- Only communicate with executor -- Do not use TaskCreate to create tasks for other roles -- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) -- After task completion, check for fast-advance opportunity (see SKILL.md Phase 5) - -## Workflow -1. Call Skill -> get role definition and execution logic -2. Follow role.md 5-Phase flow -3. team_msg(team=) + SendMessage results to executor -4. TaskUpdate completed -> check next task or fast-advance` -}) -``` - -### Inner Loop Worker (multi-task role) - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker (inner loop)", - team_name: , - name: "", - run_in_background: true, - prompt: `You are team "" . - -## Primary Instruction -All your work MUST be executed by calling Skill to get role definition: -Skill(skill="team-executor", args="--role= --session=") - -Current requirement: -Session: - -## Inner Loop Mode -You will handle ALL -* tasks in this session, not just the first one. -After completing each task, loop back to find the next -* task. -Only SendMessage to executor when: -- All -* tasks are done -- A consensus_blocked HIGH occurs -- Errors accumulate (>= 3) - -## Role Guidelines -- Only process -* tasks, do not execute other role work -- All output prefixed with [] tag -- Only communicate with executor -- Do not use TaskCreate to create tasks for other roles -- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) -- Use subagent calls for heavy work, retain summaries in context` -}) -``` - ---- - -## 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 roles in session | ERROR, session incomplete, suggest re-run team-coordinate | -| Role file not found | ERROR with expected path | -| capability_gap reported | Warn only, cannot generate new roles (see monitor.md handleAdapt) | -| Fast-advance spawns wrong task | Executor reconciles on next callback | diff --git a/.claude/skills/team-executor/roles/executor/commands/monitor.md b/.claude/skills/team-executor/roles/executor/commands/monitor.md deleted file mode 100644 index ddccd6e9..00000000 --- a/.claude/skills/team-executor/roles/executor/commands/monitor.md +++ /dev/null @@ -1,277 +0,0 @@ -# Command: monitor - -## Purpose - -Event-driven pipeline coordination with Spawn-and-Stop pattern for team-executor. Adapted from team-coordinate monitor.md -- role names are read from `team-session.json#roles` instead of hardcoded. **handleAdapt is LIMITED**: only warns, cannot generate new roles. - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` | -| ONE_STEP_PER_INVOCATION | true | Executor does one operation then STOPS | -| FAST_ADVANCE_AWARE | true | Workers may skip executor for simple linear successors | -| ROLE_GENERATION | disabled | handleAdapt cannot generate new roles | - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session file | `/team-session.json` | Yes | -| Task list | `TaskList()` | Yes | -| Active workers | session.active_workers[] | Yes | -| Role registry | session.roles[] | Yes | - -**Dynamic role resolution**: Known worker roles are loaded from `session.roles[].name`. This is the same pattern as team-coordinate. - -## Phase 3: Handler Routing - -### Wake-up Source Detection - -Parse `$ARGUMENTS` to determine handler: - -| Priority | Condition | Handler | -|----------|-----------|---------| -| 1 | Message contains `[]` from session roles | handleCallback | -| 2 | Contains "capability_gap" | handleAdapt | -| 3 | Contains "check" or "status" | handleCheck | -| 4 | Contains "resume", "continue", or "next" | handleResume | -| 5 | None of the above (initial spawn after dispatch) | handleSpawnNext | - ---- - -### Handler: handleCallback - -Worker completed a task. Verify completion, update state, auto-advance. - -``` -Receive callback from [] - +- 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 - | | +- -> 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 note**: A worker may have already spawned its successor via fast-advance. When processing a callback: -1. Check if the expected next task is already `in_progress` (fast-advanced) -2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker -3. If no -> normal handleSpawnNext - ---- - -### Handler: handleCheck - -Read-only status report. No pipeline advancement. - -**Output format**: - -``` -[executor] Pipeline Status -[executor] Progress: / (%) - -[executor] Execution Graph: - - - done=completed >>>=running o=pending .=not created - -[executor] Active Workers: - > () - running [inner-loop: N/M tasks done] - -[executor] Ready to spawn: -[executor] Commands: 'resume' to advance | 'check' to refresh -``` - -**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=. - -**Graph rendering**: Read dependency_graph from task-analysis.json, render each node with status icon. Show parallel branches side-by-side. - -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 workers in background, update session, STOP. - -``` -Collect task states from TaskList() - +- completedSubjects: status = completed - +- inProgressSubjects: status = in_progress - +- readySubjects: pending + all blockedBy in completedSubjects - -Ready tasks found? - +- NONE + work in progress -> report waiting -> STOP - +- NONE + nothing in progress -> PIPELINE_COMPLETE -> Phase 2 - +- HAS ready tasks -> for each: - +- Is task owner 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 - +- TaskUpdate -> in_progress - +- team_msg log -> task_unblocked (team=, NOT team name) - +- Spawn worker (see spawn tool call below) - +- Add to session.active_workers - Update session file -> output summary -> STOP -``` - -**Spawn worker tool call** (one per ready task): - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker for ", - team_name: , - name: "", - run_in_background: true, - prompt: "" -}) -``` - ---- - -### Handler: handleAdapt (LIMITED) - -Handle mid-pipeline capability gap discovery. **UNLIKE team-coordinate, executor CANNOT generate new roles.** - -``` -Receive capability_gap from [] - +- Log via team_msg (type: warning) - +- Report to user: - "Capability gap detected: - - team-executor cannot generate new roles. - Options: - 1. Continue with existing roles (worker will skip gap work) - 2. Re-run team-coordinate with --resume= to extend session - 3. Manually add role to /roles/ and retry" - +- Extract: gap_description, requesting_role, suggested_capability - +- Validate gap is genuine: - +- Check existing roles in session.roles -> does any role cover this? - | +- YES -> redirect: SendMessage to that role's owner -> STOP - | +- NO -> genuine gap, report to user (cannot fix) - +- Do NOT generate new role - +- Continue execution with existing roles -``` - -**Key difference from team-coordinate**: -| Aspect | team-coordinate | team-executor | -|--------|-----------------|---------------| -| handleAdapt | Generates new role, creates tasks, spawns worker | Only warns, cannot fix | -| Recovery | Automatic | Manual (re-run team-coordinate) | - ---- - -### Worker Failure Handling - -When a worker has unexpected status (not completed, not in_progress): - -1. Reset task -> pending via TaskUpdate -2. Log via team_msg (type: error) -3. Report to user: task reset, will retry on next resume - -### Fast-Advance Failure Recovery - -When executor detects a fast-advanced task has failed (task in_progress but no callback and worker gone): - -``` -handleCallback / handleResume detects: - +- Task is in_progress (was fast-advanced by predecessor) - +- No active_worker entry for this task - +- Original fast-advancing worker has already completed and exited - +- Resolution: - 1. TaskUpdate -> reset task to pending - 2. Remove stale active_worker entry (if any) - 3. Log via team_msg (type: error, summary: "Fast-advanced task failed, resetting for retry") - 4. -> handleSpawnNext (will re-spawn the task normally) -``` - -**Detection in handleResume**: - -``` -For each in_progress task in TaskList(): - +- Has matching active_worker? -> normal, skip - +- No matching active_worker? -> orphaned (likely fast-advance failure) - +- Check creation time: if > 5 minutes with no progress callback - +- Reset to pending -> handleSpawnNext -``` - -**Prevention**: Fast-advance failures are self-healing. The executor reconciles orphaned tasks on every `resume`/`check` cycle. - -### Consensus-Blocked Handling - -When a worker reports `consensus_blocked` in its callback: - -``` -handleCallback receives message with consensus_blocked flag - +- Extract: divergence_severity, blocked_round, action_recommendation - +- Route by severity: - | - +- severity = HIGH - | +- Create REVISION task: - | +- Same role, same doc type, incremented suffix (e.g., DRAFT-001-R1) - | +- Description includes: divergence details + action items from discuss - | +- blockedBy: none (immediate execution) - | +- Max 1 revision per task (DRAFT-001 -> DRAFT-001-R1, no R2) - | +- If already revised once -> PAUSE, escalate to user - | +- Update session: mark task as "revised", log revision chain - | - +- severity = MEDIUM - | +- Proceed with warning: include divergence in next task's context - | +- Log action items to wisdom/issues.md - | +- Normal handleSpawnNext - | - +- severity = LOW - +- Proceed normally: treat as consensus_reached with notes - +- Normal handleSpawnNext -``` - -## Phase 4: Validation - -| Check | Criteria | -|-------|----------| -| Session state consistent | active_workers matches TaskList in_progress tasks | -| No orphaned tasks | Every in_progress task has an active_worker entry | -| Dynamic roles valid | All task owners 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 | -| Fast-advance orphan check | in_progress tasks without active_worker entry -> reset to pending | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Session file not found | Error, suggest re-run team-coordinate | -| 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 | Executor reconciles, no duplicate spawns | -| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext | -| Dynamic role file not found | Error, cannot proceed without role definition | -| capability_gap from role | WARN only, cannot generate new roles | -| consensus_blocked HIGH | Create revision task (max 1) or pause for user | -| consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md | diff --git a/.claude/skills/team-executor/roles/executor/role.md b/.claude/skills/team-executor/roles/executor/role.md deleted file mode 100644 index afaf9729..00000000 --- a/.claude/skills/team-executor/roles/executor/role.md +++ /dev/null @@ -1,202 +0,0 @@ -# Executor Role - -Orchestrate the team-executor workflow: session validation, state reconciliation, worker dispatch, progress monitoring, session state. The sole built-in role -- all worker roles are loaded from the session. - -## Identity - -- **Name**: `executor` | **Tag**: `[executor]` -- **Responsibility**: Validate session -> Reconcile state -> Create team -> Dispatch tasks -> Monitor progress -> Report results - -## Boundaries - -### MUST -- Validate session structure before any execution -- Reconcile session state with TaskList on startup -- Reset in_progress tasks to pending (interrupted tasks) -- Detect fast-advance orphans and reset to pending -- Spawn worker subagents in background -- Monitor progress via worker callbacks and route messages -- Maintain session state persistence (team-session.json) -- Handle capability_gap reports with warning only (cannot generate roles) - -### MUST NOT -- Execute task work directly (delegate to workers) -- Modify task output artifacts (workers own their deliverables) -- Call implementation subagents (code-developer, etc.) directly -- Generate new roles (use existing session roles only) -- Skip session validation -- Override consensus_blocked HIGH without user confirmation - -> **Core principle**: executor is the orchestrator, not the executor. All actual work is delegated to session-defined worker roles. Unlike team-coordinate coordinator, executor CANNOT generate new roles. - ---- - -## Entry Router - -When executor is invoked, first detect the invocation type: - -| Detection | Condition | Handler | -|-----------|-----------|---------| -| Worker callback | Message 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 | -| New execution | None of above | -> Phase 0 | - -For callback/check/resume/adapt: 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. - -**Workflow**: - -### Step 1: Session Validation - -Validate session structure (see SKILL.md Session Validation): -- [ ] Directory exists at session path -- [ ] `team-session.json` exists and parses -- [ ] `task-analysis.json` exists and parses -- [ ] `roles/` directory has >= 1 .md files -- [ ] All roles in team-session.json#roles have corresponding .md files - -If validation fails -> ERROR with specific reason -> STOP - -### Step 2: Load Session State - -```javascript -session = Read(/team-session.json) -taskAnalysis = Read(/task-analysis.json) -``` - -### Step 3: Reconcile with TaskList - -``` -Call TaskList() -> get real status of all tasks -Compare with session.completed_tasks: - +- Tasks in TaskList.completed but not in session -> add to session.completed_tasks - +- Tasks in session.completed_tasks but not TaskList.completed -> remove from session.completed_tasks (anomaly, log warning) - +- Tasks in TaskList.in_progress -> candidate for reset -``` - -### Step 4: Reset Interrupted Tasks - -``` -For each task in TaskList.in_progress: - +- Reset to pending via TaskUpdate - +- Log via team_msg (type: warning, summary: "Task reset from interrupted state") -``` - -### Step 5: Detect Fast-Advance Orphans - -``` -For each task in TaskList.in_progress: - +- Check if has matching active_worker entry - +- No matching active_worker + created > 5 minutes ago -> orphan - +- Reset to pending via TaskUpdate - +- Log via team_msg (type: error, summary: "Fast-advance orphan reset") -``` - -### Step 6: Create Missing Tasks (if needed) - -``` -For each task in task-analysis.json#tasks: - +- Check if exists in TaskList - +- Not exists -> create via TaskCreate with correct blockedBy -``` - -### Step 7: Update Session File - -``` -Write updated team-session.json with: - +- reconciled completed_tasks - +- cleared active_workers (will be rebuilt on spawn) - +- status = "active" -``` - -### Step 8: Team Setup - -``` -Check if team exists (via TaskList with team_name filter) - +- Not exists -> TeamCreate with team_name from session - +- Exists -> continue with existing team -``` - -**Success**: Session validated, state reconciled, team ready -> Phase 1 - ---- - -## Phase 1: Spawn-and-Stop - -**Objective**: Spawn first batch of ready workers in background, then STOP. - -**Design**: Spawn-and-Stop + Callback pattern, with worker fast-advance. -- Spawn workers with `Task(run_in_background: true)` -> immediately return -- Worker completes -> may fast-advance to next task OR SendMessage callback -> auto-advance -- User can use "check" / "resume" to manually advance -- Executor does one operation per invocation, then STOPS - -**Workflow**: -1. Load `commands/monitor.md` -2. Find tasks with: status=pending, blockedBy all resolved, owner assigned -3. For each ready task -> spawn worker (see SKILL.md Executor Spawn Template) - - Use Standard Worker template for single-task roles - - Use Inner Loop Worker template for multi-task roles -4. Output status summary with execution graph -5. STOP - -**Pipeline advancement** driven by three wake sources: -- Worker callback (automatic) -> Entry Router -> handleCallback -- User "check" -> handleCheck (status only) -- User "resume" -> handleResume (advance) - ---- - -## Phase 2: Report + Next Steps - -**Objective**: Completion report and follow-up options. - -**Workflow**: -1. Load session state -> count completed tasks, duration -2. List all deliverables with output paths in `/artifacts/` -3. Include discussion summaries (if inline discuss was used) -4. Summarize wisdom accumulated during execution -5. Update session status -> "completed" -6. Offer next steps: exit / view artifacts / extend with additional tasks - -**Output format**: - -``` -[executor] ============================================ -[executor] TASK COMPLETE -[executor] -[executor] Deliverables: -[executor] - () -[executor] - () -[executor] -[executor] Pipeline: / tasks -[executor] Roles: -[executor] Duration: -[executor] -[executor] Session: -[executor] ============================================ -``` - ---- - -## 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 | Respawn worker, reassign task | -| Session corruption | Attempt recovery, fallback to manual reconciliation | -| capability_gap reported | handleAdapt: WARN only, cannot generate new roles | -| 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 | Executor reconciles, no duplicate spawns | -| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext | -| Role file not found | ERROR, cannot proceed without role definition | diff --git a/.claude/skills/team-executor/specs/session-schema.md b/.claude/skills/team-executor/specs/session-schema.md deleted file mode 100644 index 260f7831..00000000 --- a/.claude/skills/team-executor/specs/session-schema.md +++ /dev/null @@ -1,272 +0,0 @@ -# Session Schema - -Required session structure for team-executor. All components MUST exist for valid execution. - -## Directory Structure - -``` -/ -+-- team-session.json # Session state + dynamic role registry (REQUIRED) -+-- task-analysis.json # Task analysis output: capabilities, dependency graph (REQUIRED) -+-- roles/ # Dynamic role definitions (REQUIRED, >= 1 .md file) -| +-- .md -| +-- .md -+-- artifacts/ # All MD deliverables from workers -| +-- .md -+-- shared-memory.json # Cross-role state store -+-- wisdom/ # Cross-task knowledge -| +-- learnings.md -| +-- decisions.md -| +-- issues.md -+-- explorations/ # Shared explore cache -| +-- cache-index.json -| +-- explore-.json -+-- discussions/ # Inline discuss records -| +-- .md -+-- .msg/ # Team message bus logs -``` - -## Validation Checklist - -team-executor validates the following before execution: - -### Required Components - -| Component | Validation | Error Message | -|-----------|------------|---------------| -| `--session` argument | Must be provided | "Session required. Usage: --session=" | -| Directory | Must exist at path | "Session directory not found: " | -| `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" | -| `roles/` directory | Must exist and contain >= 1 .md file | "Invalid session: no role files in roles/" | -| Role file mapping | Each role in team-session.json#roles must have .md file | "Role file not found: roles/.md" | -| Role file structure | Each role .md must contain required headers | "Invalid role file: roles/.md missing required section:
" | - -### Validation Algorithm - -``` -1. Parse --session= from arguments - +- Not provided -> ERROR: "Session required. Usage: --session=" - -2. Check directory exists - +- Not exists -> ERROR: "Session directory not found: " - -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/invalid -> ERROR: "team-session.json missing required field: session_id" - +- task_description (string) -> missing -> ERROR: "team-session.json missing required field: task_description" - +- status (string: active|paused|completed) -> missing/invalid -> ERROR: "team-session.json has invalid status" - +- team_name (string) -> missing -> ERROR: "team-session.json missing required field: team_name" - +- roles (array) -> missing/empty -> ERROR: "team-session.json missing or empty roles array" - -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: "task-analysis.json missing required field: capabilities" - +- dependency_graph (object) -> missing -> ERROR: "task-analysis.json missing required field: dependency_graph" - +- roles (array) -> missing/empty -> ERROR: "task-analysis.json missing or empty roles array" - +- tasks (array) -> missing/empty -> ERROR: "task-analysis.json missing or empty tasks array" - -5. Check roles/ directory - +- Not exists -> ERROR: "Invalid session: roles/ directory missing" - +- No .md files -> ERROR: "Invalid session: no role files in roles/" - -6. Check role file mapping and structure - +- For each role in team-session.json#roles: - +- Check roles/.md exists - +- Not exists -> ERROR: "Role file not found: roles/.md" - +- Validate role file structure (see Role File Structure Validation): - +- Check for required headers: "# Role:", "## Identity", "## Boundaries", "## Execution" - +- Missing header -> ERROR: "Invalid role file: roles/.md missing required section:
" - -7. All checks pass -> proceed to Phase 0 -``` - ---- - -## team-session.json Schema - -```json -{ - "session_id": "TC--", - "task_description": "", - "status": "active | paused | completed", - "team_name": "", - "roles": [ - { - "name": "", - "prefix": "", - "responsibility_type": "", - "inner_loop": false, - "role_file": "roles/.md" - } - ], - "pipeline": { - "dependency_graph": {}, - "tasks_total": 0, - "tasks_completed": 0 - }, - "active_workers": [], - "completed_tasks": [], - "created_at": "" -} -``` - -### Required Fields - -| Field | Type | Description | -|-------|------|-------------| -| `session_id` | string | Unique session identifier (e.g., "TC-auth-feature-2026-02-27") | -| `task_description` | string | Original task description from user | -| `status` | string | One of: "active", "paused", "completed" | -| `team_name` | string | Team name for Task tool | -| `roles` | array | List of role definitions | -| `roles[].name` | string | Role name (must match .md filename) | -| `roles[].prefix` | string | Task prefix for this role (e.g., "SPEC", "IMPL") | -| `roles[].role_file` | string | Relative path to role file | - -### Optional Fields - -| Field | Type | Description | -|-------|------|-------------| -| `pipeline` | object | Pipeline metadata | -| `active_workers` | array | Currently running workers | -| `completed_tasks` | array | List of completed task IDs | -| `created_at` | string | ISO timestamp | - ---- - -## task-analysis.json Schema - -```json -{ - "capabilities": [ - { - "name": "", - "description": "", - "artifact_type": "" - } - ], - "dependency_graph": { - "": { - "depends_on": [""], - "role": "" - } - }, - "roles": [ - { - "name": "", - "prefix": "", - "responsibility_type": "", - "inner_loop": false - } - ], - "tasks": [ - { - "id": "", - "subject": "", - "owner": "", - "blockedBy": [""] - } - ], - "complexity_score": 0 -} -``` - -### Required Fields - -| Field | Type | Description | -|-------|------|-------------| -| `capabilities` | array | Detected capabilities | -| `dependency_graph` | object | Task dependency DAG | -| `roles` | array | Role definitions | -| `tasks` | array | Task definitions | - ---- - -## Role File Schema - -Each role file in `roles/.md` must follow the structure defined in `team-coordinate/specs/role-template.md`. - -### Minimum Required Sections - -| Section | Description | -|---------|-------------| -| `# Role: ` | Header with role name | -| `## Identity` | Name, tag, prefix, responsibility | -| `## Boundaries` | MUST and MUST NOT rules | -| `## Execution (5-Phase)` | Phase 1-5 workflow | - -### Role File Structure Validation - -Role files MUST be validated for structure before execution. This catches malformed role files early and provides actionable error messages. - -**Required Sections** (must be present in order): - -| Section | Pattern | Purpose | -|---------|---------|---------| -| Role Header | `# Role: ` | Identifies the role definition | -| Identity | `## Identity` | Defines name, tag, prefix, responsibility | -| Boundaries | `## Boundaries` | Defines MUST and MUST NOT rules | -| Execution | `## Execution` | Defines the 5-Phase workflow | - -**Validation Algorithm**: - -``` -For each role file in roles/.md: - 1. Read file content - 2. Check for "# Role:" header - +- Not found -> ERROR: "Invalid role file: roles/.md missing role header" - 3. Check for "## Identity" section - +- Not found -> ERROR: "Invalid role file: roles/.md missing required section: Identity" - 4. Check for "## Boundaries" section - +- Not found -> ERROR: "Invalid role file: roles/.md missing required section: Boundaries" - 5. Check for "## Execution" section (or "## Execution (5-Phase)") - +- Not found -> ERROR: "Invalid role file: roles/.md missing required section: Execution" - 6. All checks pass -> role file valid -``` - -**Benefits**: -- Early detection of malformed role files -- Clear error messages for debugging -- Prevents runtime failures during worker execution - ---- - -## 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 -+-- roles/ -| +-- spec-writer.md # Role file for SPEC-* tasks -| +-- implementer.md # Role file for IMPL-* tasks -| +-- tester.md # Role file for TEST-* tasks -+-- artifacts/ # (may be empty) -+-- shared-memory.json # Valid JSON (may be {}) -+-- wisdom/ -| +-- learnings.md -| +-- decisions.md -| +-- issues.md -+-- explorations/ -| +-- cache-index.json -+-- discussions/ # (may be empty) -+-- .msg/ # (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 files**: Re-run team-coordinate with --resume -4. **Corrupt JSON**: Manual inspection or re-run team-coordinate - -**team-executor cannot fix invalid sessions** -- it can only report errors and suggest recovery steps. diff --git a/.claude/skills/team-lifecycle-v3/SKILL.md b/.claude/skills/team-lifecycle-v3/SKILL.md deleted file mode 100644 index 619a1aaa..00000000 --- a/.claude/skills/team-lifecycle-v3/SKILL.md +++ /dev/null @@ -1,384 +0,0 @@ ---- -name: team-lifecycle-v3 -description: Unified team skill for full lifecycle - spec/impl/test. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team lifecycle". -allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) ---- - -# Team Lifecycle v3 - -Unified team skill: specification → implementation → testing → review. All team members invoke with `--role=xxx` to route to role-specific execution. - -## Architecture - -``` -┌───────────────────────────────────────────────────┐ -│ Skill(skill="team-lifecycle-v3") │ -│ args="任务描述" 或 args="--role=xxx" │ -└───────────────────┬───────────────────────────────┘ - │ Role Router - ┌──── --role present? ────┐ - │ NO │ YES - ↓ ↓ - Orchestration Mode Role Dispatch - (auto → coordinator) (route to role.md) - │ - ┌────┴────┬───────┬───────┬───────┬───────┬───────┬───────┐ - ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ - coordinator analyst writer discussant planner executor tester reviewer - ↑ ↑ - on-demand by coordinator - ┌──────────┐ ┌─────────┐ - │ explorer │ │architect│ - └──────────┘ └─────────┘ - ┌──────────────┐ ┌──────┐ - │ fe-developer │ │fe-qa │ - └──────────────┘ └──────┘ -``` - -## Role Router - -### Input Parsing - -Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto route to coordinator). - -### Role Registry - -| Role | File | Task Prefix | Type | Compact | -|------|------|-------------|------|---------| -| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | **⚠️ 压缩后必须重读** | -| analyst | [roles/analyst/role.md](roles/analyst/role.md) | RESEARCH-* | pipeline | 压缩后必须重读 | -| writer | [roles/writer/role.md](roles/writer/role.md) | DRAFT-* | pipeline | 压缩后必须重读 | -| discussant | [roles/discussant/role.md](roles/discussant/role.md) | DISCUSS-* | pipeline | 压缩后必须重读 | -| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | pipeline | 压缩后必须重读 | -| executor | [roles/executor/role.md](roles/executor/role.md) | IMPL-* | pipeline | 压缩后必须重读 | -| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | pipeline | 压缩后必须重读 | -| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-* + QUALITY-* | pipeline | 压缩后必须重读 | -| explorer | [roles/explorer/role.md](roles/explorer/role.md) | EXPLORE-* | service (on-demand) | 压缩后必须重读 | -| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | consulting (on-demand) | 压缩后必须重读 | -| fe-developer | [roles/fe-developer/role.md](roles/fe-developer/role.md) | DEV-FE-* | frontend pipeline | 压缩后必须重读 | -| fe-qa | [roles/fe-qa/role.md](roles/fe-qa/role.md) | QA-FE-* | frontend pipeline | 压缩后必须重读 | - -> **⚠️ COMPACT PROTECTION**: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，**必须立即 `Read` 对应 role.md 重新加载后再继续执行**。不得基于摘要执行任何 Phase。 - -### Dispatch - -1. Extract `--role` from arguments -2. If no `--role` → route to coordinator (Orchestration Mode) -3. Look up role in registry → Read the role file → Execute its phases - -### Orchestration Mode - -When invoked without `--role`, coordinator auto-starts. User just provides task description. - -**Invocation**: `Skill(skill="team-lifecycle-v3", args="任务描述")` - -**Lifecycle**: -``` -用户提供任务描述 - → coordinator Phase 1-3: 需求澄清 → TeamCreate → 创建任务链 - → coordinator Phase 4: spawn 首批 worker (后台) → STOP - → Worker 执行 → SendMessage 回调 → coordinator 推进下一步 - → 循环直到 pipeline 完成 → Phase 5 汇报 -``` - -**User Commands** (唤醒已暂停的 coordinator): - -| Command | Action | -|---------|--------| -| `check` / `status` | 输出执行状态图，不推进 | -| `resume` / `continue` | 检查 worker 状态，推进下一步 | - ---- - -## Shared Infrastructure - -以下模板适用于所有 worker 角色。每个 role.md 只需写 **Phase 2-4** 的角色特有逻辑。 - -### Worker Phase 1: Task Discovery (所有 worker 共享) - -每个 worker 启动后执行相同的任务发现流程： - -1. 调用 `TaskList()` 获取所有任务 -2. 筛选: subject 匹配本角色前缀 + owner 是本角色 + status 为 pending + blockedBy 为空 -3. 无任务 → idle 等待 -4. 有任务 → `TaskGet` 获取详情 → `TaskUpdate` 标记 in_progress - -**Resume Artifact Check** (防止恢复后重复产出): -- 检查本任务的输出产物是否已存在 -- 产物完整 → 跳到 Phase 5 报告完成 -- 产物不完整或不存在 → 正常执行 Phase 2-4 - -### Worker Phase 5: Report (所有 worker 共享) - -任务完成后的标准报告流程: - -1. **Message Bus**: 调用 `mcp__ccw-tools__team_msg` 记录消息 - - 参数: operation="log", team=, from=, to="coordinator", type=<消息类型>, summary="[] <摘要>", ref=<产物路径> - - **注意**: `team` 必须是 **session ID** (如 `TLS-project-2026-02-27`), 不是 team name. 从任务描述的 `Session:` 字段提取. - - **CLI fallback**: 当 MCP 不可用时 → `ccw team log --team --from --to coordinator --type --summary "[] ..." --json` -2. **SendMessage**: 发送结果给 coordinator (content 和 summary 都带 `[]` 前缀) -3. **TaskUpdate**: 标记任务 completed -4. **Loop**: 回到 Phase 1 检查下一个任务 - -### Wisdom Accumulation (所有角色) - -跨任务知识积累。Coordinator 在 session 初始化时创建 `wisdom/` 目录。 - -**目录**: -``` -/wisdom/ -├── learnings.md # 模式和洞察 -├── decisions.md # 架构和设计决策 -├── conventions.md # 代码库约定 -└── issues.md # 已知风险和问题 -``` - -**Worker 加载** (Phase 2): 从 task description 提取 `Session: `, 读取 wisdom 目录下各文件。 -**Worker 贡献** (Phase 4/5): 将本任务发现写入对应 wisdom 文件。 - -### Role Isolation Rules - -| 允许 | 禁止 | -|------|------| -| 处理自己前缀的任务 | 处理其他角色前缀的任务 | -| SendMessage 给 coordinator | 直接与其他 worker 通信 | -| 使用 Toolbox 中声明的工具 | 为其他角色创建任务 | -| 委派给 commands/ 中的命令 | 修改不属于本职责的资源 | - -Coordinator 额外禁止: 直接编写/修改代码、调用实现类 subagent、直接执行分析/测试/审查。 - ---- - -## Pipeline Definitions - -### Spec-only (12 tasks) - -``` -RESEARCH-001 → DISCUSS-001 → DRAFT-001 → DISCUSS-002 -→ DRAFT-002 → DISCUSS-003 → DRAFT-003 → DISCUSS-004 -→ DRAFT-004 → DISCUSS-005 → QUALITY-001 → DISCUSS-006 -``` - -### Impl-only / Backend (4 tasks) - -``` -PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001 -``` - -### Full-lifecycle (16 tasks) - -``` -[Spec pipeline] → PLAN-001(blockedBy: DISCUSS-006) → IMPL-001 → TEST-001 + REVIEW-001 -``` - -### Frontend Pipelines - -``` -FE-only: PLAN-001 → DEV-FE-001 → QA-FE-001 - (GC loop: QA-FE verdict=NEEDS_FIX → DEV-FE-002 → QA-FE-002, max 2 rounds) - -Fullstack: PLAN-001 → IMPL-001 ∥ DEV-FE-001 → TEST-001 ∥ QA-FE-001 → REVIEW-001 - -Full + FE: [Spec pipeline] → PLAN-001 → IMPL-001 ∥ DEV-FE-001 → TEST-001 ∥ QA-FE-001 → REVIEW-001 -``` - -### Cadence Control - -**节拍模型**: 事件驱动，每个 beat = coordinator 唤醒 → 处理 → spawn → STOP。 - -``` -Beat Cycle (单次节拍) -═══════════════════════════════════════════════════════════ - Event Coordinator Workers -─────────────────────────────────────────────────────────── - callback/resume ──→ ┌─ handleCallback ─┐ - │ mark completed │ - │ check pipeline │ - ├─ handleSpawnNext ─┤ - │ find ready tasks │ - │ spawn workers ───┼──→ [Worker A] Phase 1-5 - │ (parallel OK) ──┼──→ [Worker B] Phase 1-5 - └─ STOP (idle) ─────┘ │ - │ - callback ←─────────────────────────────────────────┘ - (next beat) SendMessage + TaskUpdate(completed) -═══════════════════════════════════════════════════════════ -``` - -**Pipeline 节拍视图**: - -``` -Spec-only (12 beats, 严格串行) -────────────────────────────────────────────────────────── -Beat 1 2 3 4 5 6 7 8 9 10 11 12 - │ │ │ │ │ │ │ │ │ │ │ │ - R1 → D1 → W1 → D2 → W2 → D3 → W3 → D4 → W4 → D5 → Q1 → D6 - ▲ ▲ - pipeline sign-off - start pause - -R=RESEARCH D=DISCUSS W=DRAFT(writer) Q=QUALITY - -Impl-only (3 beats, 含并行窗口) -────────────────────────────────────────────────────────── -Beat 1 2 3 - │ │ ┌────┴────┐ - PLAN → IMPL ──→ TEST ∥ REVIEW ← 并行窗口 - └────┬────┘ - pipeline - done - -Full-lifecycle (15 beats, spec→impl 过渡含检查点) -────────────────────────────────────────────────────────── -Beat 1-12: [Spec pipeline 同上] - │ -Beat 12 (D6 完成): ⏸ CHECKPOINT ── 用户确认后 resume - │ -Beat 13 14 15 - PLAN → IMPL → TEST ∥ REVIEW - -Fullstack (含双并行窗口) -────────────────────────────────────────────────────────── -Beat 1 2 3 4 - │ ┌────┴────┐ ┌────┴────┐ │ - PLAN → IMPL ∥ DEV-FE → TEST ∥ QA-FE → REVIEW - ▲ ▲ ▲ - 并行窗口 1 并行窗口 2 同步屏障 -``` - -**检查点 (Checkpoint)**: - -| 触发条件 | 位置 | 行为 | -|----------|------|------| -| Spec→Impl 过渡 | DISCUSS-006 完成后 | ⏸ 暂停，等待用户 `resume` 确认 | -| GC 循环上限 | QA-FE max 2 rounds | 超出轮次 → 停止迭代，报告当前状态 | -| Pipeline 停滞 | 无 ready + 无 running | 检查缺失任务，报告用户 | - -**Stall 检测** (coordinator `handleCheck` 时执行): - -| 检查项 | 条件 | 处理 | -|--------|------|------| -| Worker 无响应 | in_progress 任务无回调 | 报告等待中的任务列表，建议用户 `resume` | -| Pipeline 死锁 | 无 ready + 无 running + 有 pending | 检查 blockedBy 依赖链，报告卡点 | -| GC 循环超限 | DEV-FE / QA-FE 迭代 > max_rounds | 终止循环，输出最新 QA 报告 | - -### Task Metadata Registry - -| Task ID | Role | Phase | Dependencies | Description | -|---------|------|-------|-------------|-------------| -| RESEARCH-001 | analyst | spec | (none) | Seed analysis and context gathering | -| DISCUSS-001 | discussant | spec | RESEARCH-001 | Critique research findings | -| DRAFT-001 | writer | spec | DISCUSS-001 | Generate Product Brief | -| DISCUSS-002 | discussant | spec | DRAFT-001 | Critique Product Brief | -| DRAFT-002 | writer | spec | DISCUSS-002 | Generate Requirements/PRD | -| DISCUSS-003 | discussant | spec | DRAFT-002 | Critique Requirements/PRD | -| DRAFT-003 | writer | spec | DISCUSS-003 | Generate Architecture Document | -| DISCUSS-004 | discussant | spec | DRAFT-003 | Critique Architecture Document | -| DRAFT-004 | writer | spec | DISCUSS-004 | Generate Epics & Stories | -| DISCUSS-005 | discussant | spec | DRAFT-004 | Critique Epics | -| QUALITY-001 | reviewer | spec | DISCUSS-005 | 5-dimension spec quality validation | -| DISCUSS-006 | discussant | spec | QUALITY-001 | Final review discussion and sign-off | -| PLAN-001 | planner | impl | (none or DISCUSS-006) | Multi-angle exploration and planning | -| IMPL-001 | executor | impl | PLAN-001 | Code implementation | -| TEST-001 | tester | impl | IMPL-001 | Test-fix cycles | -| REVIEW-001 | reviewer | impl | IMPL-001 | 4-dimension code review | -| DEV-FE-001 | fe-developer | impl | PLAN-001 | Frontend implementation | -| QA-FE-001 | fe-qa | impl | DEV-FE-001 | 5-dimension frontend QA | - -## Coordinator Spawn Template - -When coordinator spawns workers, use background mode (Spawn-and-Stop): - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker", - team_name: , - name: "", - run_in_background: true, - prompt: `你是 team "" 的 . - -## 首要指令 -你的所有工作必须通过调用 Skill 获取角色定义后执行： -Skill(skill="team-lifecycle-v3", args="--role=") - -当前需求: -Session: - -## 角色准则 -- 只处理 -* 任务，不执行其他角色工作 -- 所有输出带 [] 标识前缀 -- 仅与 coordinator 通信 -- 不使用 TaskCreate 为其他角色创建任务 -- 每次 SendMessage 前先调用 mcp__ccw-tools__team_msg 记录 - -## 工作流程 -1. 调用 Skill → 获取角色定义和执行逻辑 -2. 按 role.md 5-Phase 流程执行 -3. team_msg + SendMessage 结果给 coordinator -4. TaskUpdate completed → 检查下一个任务` -}) -``` - -## Session Directory - -``` -.workflow/.team/TLS--/ -├── team-session.json # Session state -├── spec/ # Spec artifacts -│ ├── spec-config.json -│ ├── discovery-context.json -│ ├── product-brief.md -│ ├── requirements/ -│ ├── architecture/ -│ ├── epics/ -│ ├── readiness-report.md -│ └── spec-summary.md -├── discussions/ # Discussion records -├── plan/ # Plan artifacts -│ ├── plan.json -│ └── .task/TASK-*.json -├── explorations/ # Explorer output (cached) -├── architecture/ # Architect assessments + design-tokens.json -├── analysis/ # analyst design-intelligence.json (UI mode) -├── qa/ # QA audit reports -├── wisdom/ # Cross-task knowledge -│ ├── learnings.md -│ ├── decisions.md -│ ├── conventions.md -│ └── issues.md -├── .msg/ # Team message bus logs (messages.jsonl) -└── shared-memory.json # Cross-role state -``` - -## Session Resume - -Coordinator supports `--resume` / `--continue` for interrupted sessions: - -1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions -2. Multiple matches → AskUserQuestion for selection -3. Audit TaskList → reconcile session state ↔ task status -4. Reset in_progress → pending (interrupted tasks) -5. Rebuild team and spawn needed workers only -6. Create missing tasks with correct blockedBy -7. Kick first executable task → Phase 4 coordination loop - -## Shared Spec Resources - -| Resource | Path | Usage | -|----------|------|-------| -| Document Standards | [specs/document-standards.md](specs/document-standards.md) | YAML frontmatter, naming, structure | -| Quality Gates | [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gates | -| Product Brief Template | [templates/product-brief.md](templates/product-brief.md) | DRAFT-001 | -| Requirements Template | [templates/requirements-prd.md](templates/requirements-prd.md) | DRAFT-002 | -| Architecture Template | [templates/architecture-doc.md](templates/architecture-doc.md) | DRAFT-003 | -| Epics Template | [templates/epics-template.md](templates/epics-template.md) | DRAFT-004 | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Unknown --role value | Error with available role list | -| Missing --role arg | Orchestration Mode → coordinator | -| Role file not found | Error with expected path | -| Command file not found | Fallback to inline execution | diff --git a/.claude/skills/team-lifecycle-v3/roles/analyst/role.md b/.claude/skills/team-lifecycle-v3/roles/analyst/role.md deleted file mode 100644 index c73a857b..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/analyst/role.md +++ /dev/null @@ -1,113 +0,0 @@ -# Role: analyst - -Seed analysis, codebase exploration, and multi-dimensional context gathering. Maps to spec-generator Phase 1 (Discovery). - -## Identity - -- **Name**: `analyst` | **Prefix**: `RESEARCH-*` | **Tag**: `[analyst]` -- **Responsibility**: Seed Analysis → Codebase Exploration → Context Packaging → Report - -## Boundaries - -### MUST -- Only process RESEARCH-* tasks -- Communicate only with coordinator -- Generate discovery-context.json and spec-config.json -- Support file reference input (@ prefix or .md/.txt extension) - -### MUST NOT -- Create tasks for other roles -- Directly contact other workers -- Modify spec documents (only create discovery artifacts) -- Skip seed analysis step - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| research_ready | → coordinator | Research complete | -| research_progress | → coordinator | Long research progress update | -| error | → coordinator | Unrecoverable error | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| ccw cli --tool gemini --mode analysis | Seed analysis | -| mcp__ace-tool__search_context | Codebase semantic search | - ---- - -## Phase 2: Seed Analysis - -**Objective**: Extract structured seed information from the topic/idea. - -**Workflow**: -1. Extract session folder from task description (`Session: `) -2. Parse topic from task description (first non-metadata line) -3. If topic starts with `@` or ends with `.md`/`.txt` → Read the referenced file as topic content -4. Run Gemini CLI seed analysis: - -``` -Bash({ - command: `ccw cli -p "PURPOSE: Analyze topic and extract structured seed information. -TASK: • Extract problem statement • Identify target users • Determine domain context -• List constraints and assumptions • Identify 3-5 exploration dimensions • Assess complexity -TOPIC: -MODE: analysis -EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis`, - run_in_background: true -}) -``` - -5. Wait for CLI result, parse seed analysis JSON - -**Success**: Seed analysis parsed with problem statement, dimensions, complexity. - ---- - -## Phase 3: Codebase Exploration (conditional) - -**Objective**: Gather codebase context if an existing project is detected. - -| Condition | Action | -|-----------|--------| -| package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore codebase | -| No project files | Skip → codebase context = null | - -**When project detected**: -1. Report progress: "种子分析完成, 开始代码库探索" -2. ACE semantic search for architecture patterns related to topic -3. Detect tech stack from package files -4. Build codebase context: tech_stack, architecture_patterns, conventions, integration_points - ---- - -## Phase 4: Context Packaging - -**Objective**: Generate spec-config.json and discovery-context.json. - -**spec-config.json** → `/spec/spec-config.json`: -- session_id, topic, status="research_complete", complexity, depth, focus_areas, mode="interactive" - -**discovery-context.json** → `/spec/discovery-context.json`: -- session_id, phase=1, seed_analysis (all fields), codebase_context (or null), recommendations - -**design-intelligence.json** → `/analysis/design-intelligence.json` (UI mode only): -- Produced when frontend keywords detected (component, page, UI, React, Vue, CSS, 前端) in seed_analysis -- Fields: industry, style_direction, ux_patterns, color_strategy, typography, component_patterns -- Consumed by architect (for design-tokens.json) and fe-developer - -**Report**: complexity, codebase presence, problem statement, exploration dimensions, output paths. - -**Success**: Both JSON files created; design-intelligence.json created if UI mode. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Gemini CLI failure | Fallback to direct Claude analysis | -| Codebase detection failed | Continue as new project | -| Topic too vague | Report with clarification questions | diff --git a/.claude/skills/team-lifecycle-v3/roles/architect/commands/assess.md b/.claude/skills/team-lifecycle-v3/roles/architect/commands/assess.md deleted file mode 100644 index 8c6bc967..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/architect/commands/assess.md +++ /dev/null @@ -1,193 +0,0 @@ -# Command: assess - -## Purpose - -Multi-mode architecture assessment. Auto-detects consultation mode from task subject prefix, runs mode-specific analysis, and produces a verdict with concerns and recommendations. - -## Phase 2: Context Loading - -### Common Context (all modes) - -| Input | Source | Required | -|-------|--------|----------| -| Session folder | Task description `Session:` field | Yes | -| Wisdom | `/wisdom/` (all files) | No | -| Project tech | `.workflow/project-tech.json` | No | -| Explorations | `/explorations/` | No | - -### Mode-Specific Context - -| Mode | Task Pattern | Additional Context | -|------|-------------|-------------------| -| spec-review | ARCH-SPEC-* | `spec/architecture/_index.md`, `spec/architecture/ADR-*.md` | -| plan-review | ARCH-PLAN-* | `plan/plan.json`, `plan/.task/TASK-*.json` | -| code-review | ARCH-CODE-* | `git diff --name-only`, changed file contents | -| consult | ARCH-CONSULT-* | Question extracted from task description | -| feasibility | ARCH-FEASIBILITY-* | Proposal from task description, codebase search results | - -## Phase 3: Mode-Specific Assessment - -### Mode: spec-review - -Review architecture documents for technical soundness across 4 dimensions. - -**Assessment dimensions**: - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Consistency | 25% | ADR decisions align with each other and with architecture index | -| Scalability | 25% | Design supports growth, no single-point bottlenecks | -| Security | 25% | Auth model, data protection, API security addressed | -| Tech fitness | 25% | Technology choices match project-tech.json and problem domain | - -**Checks**: -- Read architecture index and all ADR files -- Cross-reference ADR decisions for contradictions -- Verify tech choices align with project-tech.json -- Score each dimension 0-100 - ---- - -### Mode: plan-review - -Review implementation plan for architectural soundness. - -**Checks**: - -| Check | What | Severity if Failed | -|-------|------|-------------------| -| Dependency cycles | Build task graph, detect cycles via DFS | High | -| Task granularity | Flag tasks touching >8 files | Medium | -| Convention compliance | Verify plan follows wisdom/conventions.md | Medium | -| Architecture alignment | Verify plan doesn't contradict wisdom/decisions.md | High | - -**Dependency cycle detection flow**: -1. Parse all TASK-*.json files -> extract id and depends_on -2. Build directed graph -3. DFS traversal -> flag any node visited twice in same stack -4. Report cycle path if found - ---- - -### Mode: code-review - -Assess architectural impact of code changes. - -**Checks**: - -| Check | Method | Severity if Found | -|-------|--------|-------------------| -| Layer violations | Detect upward imports (deeper layer importing shallower) | High | -| New dependencies | Parse package.json diff for added deps | Medium | -| Module boundary changes | Flag index.ts/index.js modifications | Medium | -| Architectural impact | Score based on file count and boundary changes | Info | - -**Impact scoring**: - -| Condition | Impact Level | -|-----------|-------------| -| Changed files > 10 | High | -| index.ts/index.js or package.json modified | Medium | -| All other cases | Low | - -**Detection example** (find changed files): - -```bash -Bash(command="git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached") -``` - ---- - -### Mode: consult - -Answer architecture decision questions. Route by question complexity. - -**Complexity detection**: - -| Condition | Classification | -|-----------|---------------| -| Question > 200 chars OR matches: architect, design, pattern, refactor, migrate, scalab | Complex | -| All other questions | Simple | - -**Complex questions** -> delegate to CLI exploration: - -```bash -Bash(command="ccw cli -p \"PURPOSE: Architecture consultation for: -TASK: Search codebase for relevant patterns, analyze architectural implications, provide options with trade-offs -MODE: analysis -CONTEXT: @**/* -EXPECTED: Options with trade-offs, file references, architectural implications -CONSTRAINTS: Advisory only, provide options not decisions\" --tool gemini --mode analysis --rule analysis-review-architecture", timeout=300000) -``` - -**Simple questions** -> direct analysis using available context (wisdom, project-tech, codebase search). - ---- - -### Mode: feasibility - -Evaluate technical feasibility of a proposal. - -**Assessment areas**: - -| Area | Method | Output | -|------|--------|--------| -| Tech stack compatibility | Compare proposal needs against project-tech.json | Compatible / Requires additions | -| Codebase readiness | Search for integration points using Grep/Glob | Touch-point count | -| Effort estimation | Based on touch-point count (see table below) | Low / Medium / High | -| Risk assessment | Based on effort + tech compatibility | Risks + mitigations | - -**Effort estimation**: - -| Touch Points | Effort | Implication | -|-------------|--------|-------------| -| <= 5 | Low | Straightforward implementation | -| 6 - 20 | Medium | Moderate refactoring needed | -| > 20 | High | Significant refactoring, consider phasing | - -**Verdict for feasibility**: - -| Condition | Verdict | -|-----------|---------| -| Low/medium effort, compatible stack | FEASIBLE | -| High touch-points OR new tech required | RISKY | -| Fundamental incompatibility or unreasonable effort | INFEASIBLE | - ---- - -### Verdict Routing (all modes except feasibility) - -| Verdict | Criteria | -|---------|----------| -| BLOCK | >= 2 high-severity concerns | -| CONCERN | >= 1 high-severity OR >= 3 medium-severity concerns | -| APPROVE | All other cases | - -## Phase 4: Validation - -### Output Format - -Write assessment to `/architecture/arch-.json`. - -**Report content sent to coordinator**: - -| Field | Description | -|-------|-------------| -| mode | Consultation mode used | -| verdict | APPROVE / CONCERN / BLOCK (or FEASIBLE / RISKY / INFEASIBLE) | -| concern_count | Number of concerns by severity | -| recommendations | Actionable suggestions with trade-offs | -| output_path | Path to full assessment file | - -**Wisdom contribution**: Append significant decisions to `/wisdom/decisions.md`. - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Architecture docs not found | Assess from available context, note limitation in report | -| Plan file missing | Report to coordinator via arch_concern | -| Git diff fails (no commits) | Use staged changes or skip code-review mode | -| CLI exploration timeout | Provide partial assessment, flag as incomplete | -| Exploration results unparseable | Fall back to direct analysis without exploration | -| Insufficient context | Request explorer assistance via coordinator | diff --git a/.claude/skills/team-lifecycle-v3/roles/architect/role.md b/.claude/skills/team-lifecycle-v3/roles/architect/role.md deleted file mode 100644 index a2cc6c5e..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/architect/role.md +++ /dev/null @@ -1,103 +0,0 @@ -# Role: architect - -Architecture consultant. Advice on decisions, feasibility, design patterns. - -## Identity - -- **Name**: `architect` | **Prefix**: `ARCH-*` | **Tag**: `[architect]` -- **Type**: Consulting (on-demand, advisory only) -- **Responsibility**: Context loading → Mode detection → Analysis → Report - -## Boundaries - -### MUST -- Only process ARCH-* tasks -- Auto-detect mode from task subject prefix -- Provide options with trade-offs (not final decisions) - -### MUST NOT -- Modify source code -- Make final decisions (advisory only) -- Execute implementation or testing - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| arch_ready | → coordinator | Assessment complete | -| arch_concern | → coordinator | Significant risk found | -| error | → coordinator | Analysis failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/assess.md | Multi-mode assessment | -| cli-explore-agent | Deep architecture exploration | -| ccw cli --tool gemini --mode analysis | Architecture analysis | - ---- - -## Consultation Modes - -| Task Pattern | Mode | Focus | -|-------------|------|-------| -| ARCH-SPEC-* | spec-review | Review architecture docs | -| ARCH-PLAN-* | plan-review | Review plan soundness | -| ARCH-CODE-* | code-review | Assess code change impact | -| ARCH-CONSULT-* | consult | Answer architecture questions | -| ARCH-FEASIBILITY-* | feasibility | Technical feasibility | - ---- - -## Phase 2: Context Loading - -**Common**: session folder, wisdom, project-tech.json, explorations - -**Mode-specific**: - -| Mode | Additional Context | -|------|-------------------| -| spec-review | architecture/_index.md, ADR-*.md | -| plan-review | plan/plan.json | -| code-review | git diff, changed files | -| consult | Question from task description | -| feasibility | Requirements + codebase | - ---- - -## Phase 3: Assessment - -Delegate to `commands/assess.md`. Output: mode, verdict (APPROVE/CONCERN/BLOCK), dimensions[], concerns[], recommendations[]. - -For complex questions → Gemini CLI with architecture review rule. - ---- - -## Phase 4: Report - -Output to `/architecture/arch-.json`. Contribute decisions to wisdom/decisions.md. - -**Frontend project outputs** (when frontend tech stack detected in shared-memory or discovery-context): -- `/architecture/design-tokens.json` — color, spacing, typography, shadow tokens -- `/architecture/component-specs/*.md` — per-component design spec - -**Report**: mode, verdict, concern count, recommendations, output path(s). - ---- - -## Coordinator Integration - -| Timing | Task | -|--------|------| -| After DRAFT-003 | ARCH-SPEC-001: 架构文档评审 | -| After PLAN-001 | ARCH-PLAN-001: 计划架构审查 | -| On-demand | ARCH-CONSULT-001: 架构咨询 | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Docs not found | Assess from available context | -| CLI timeout | Partial assessment | -| Insufficient context | Request explorer via coordinator | diff --git a/.claude/skills/team-lifecycle-v3/roles/coordinator/commands/dispatch.md b/.claude/skills/team-lifecycle-v3/roles/coordinator/commands/dispatch.md deleted file mode 100644 index 721c6c5e..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/coordinator/commands/dispatch.md +++ /dev/null @@ -1,142 +0,0 @@ -# Command: dispatch - -## Purpose - -Create task chains based on execution mode. Each mode maps to a predefined pipeline from SKILL.md Task Metadata Registry. Tasks are created with proper dependency chains, owner assignments, and session references. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Mode | Phase 1 requirements (spec-only, impl-only, etc.) | Yes | -| Session folder | `` from Phase 2 | Yes | -| Scope | User requirements description | Yes | -| Spec file | User-provided path (impl-only mode only) | Conditional | - -## Phase 3: Task Chain Creation - -### Mode-to-Pipeline Routing - -| Mode | Tasks | Pipeline | First Task | -|------|-------|----------|------------| -| spec-only | 12 | Spec pipeline | RESEARCH-001 | -| impl-only | 4 | Impl pipeline | PLAN-001 | -| fe-only | 3 | FE pipeline | PLAN-001 | -| fullstack | 6 | Fullstack pipeline | PLAN-001 | -| full-lifecycle | 16 | Spec + Impl | RESEARCH-001 | -| full-lifecycle-fe | 18 | Spec + Fullstack | RESEARCH-001 | - ---- - -### Spec Pipeline (12 tasks) - -Used by: spec-only, full-lifecycle, full-lifecycle-fe - -| # | Subject | Owner | BlockedBy | Description | -|---|---------|-------|-----------|-------------| -| 1 | RESEARCH-001 | analyst | (none) | Seed analysis and context gathering | -| 2 | DISCUSS-001 | discussant | RESEARCH-001 | Critique research findings | -| 3 | DRAFT-001 | writer | DISCUSS-001 | Generate Product Brief | -| 4 | DISCUSS-002 | discussant | DRAFT-001 | Critique Product Brief | -| 5 | DRAFT-002 | writer | DISCUSS-002 | Generate Requirements/PRD | -| 6 | DISCUSS-003 | discussant | DRAFT-002 | Critique Requirements/PRD | -| 7 | DRAFT-003 | writer | DISCUSS-003 | Generate Architecture Document | -| 8 | DISCUSS-004 | discussant | DRAFT-003 | Critique Architecture Document | -| 9 | DRAFT-004 | writer | DISCUSS-004 | Generate Epics | -| 10 | DISCUSS-005 | discussant | DRAFT-004 | Critique Epics | -| 11 | QUALITY-001 | reviewer | DISCUSS-005 | 5-dimension spec quality validation | -| 12 | DISCUSS-006 | discussant | QUALITY-001 | Final review discussion and sign-off | - -### Impl Pipeline (4 tasks) - -Used by: impl-only, full-lifecycle (PLAN-001 blockedBy DISCUSS-006) - -| # | Subject | Owner | BlockedBy | Description | -|---|---------|-------|-----------|-------------| -| 1 | PLAN-001 | planner | (none) | Multi-angle exploration and planning | -| 2 | IMPL-001 | executor | PLAN-001 | Code implementation | -| 3 | TEST-001 | tester | IMPL-001 | Test-fix cycles | -| 4 | REVIEW-001 | reviewer | IMPL-001 | 4-dimension code review | - -### FE Pipeline (3 tasks) - -Used by: fe-only - -| # | Subject | Owner | BlockedBy | Description | -|---|---------|-------|-----------|-------------| -| 1 | PLAN-001 | planner | (none) | Planning (frontend focus) | -| 2 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation | -| 3 | QA-FE-001 | fe-qa | DEV-FE-001 | 5-dimension frontend QA | - -GC loop (max 2 rounds): QA-FE verdict=NEEDS_FIX → create DEV-FE-002 + QA-FE-002 dynamically. - -### Fullstack Pipeline (6 tasks) - -Used by: fullstack, full-lifecycle-fe (PLAN-001 blockedBy DISCUSS-006) - -| # | Subject | Owner | BlockedBy | Description | -|---|---------|-------|-----------|-------------| -| 1 | PLAN-001 | planner | (none) | Fullstack planning | -| 2 | IMPL-001 | executor | PLAN-001 | Backend implementation | -| 3 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation | -| 4 | TEST-001 | tester | IMPL-001 | Backend test-fix cycles | -| 5 | QA-FE-001 | fe-qa | DEV-FE-001 | Frontend QA | -| 6 | REVIEW-001 | reviewer | TEST-001, QA-FE-001 | Full code review | - -### Composite Modes - -| Mode | Construction | PLAN-001 BlockedBy | -|------|-------------|-------------------| -| full-lifecycle | Spec (12) + Impl (4) | DISCUSS-006 | -| full-lifecycle-fe | Spec (12) + Fullstack (6) | DISCUSS-006 | - ---- - -### Impl-Only Pre-check - -Before creating impl-only tasks, verify specification exists: - -``` -Spec exists? - ├─ YES → read spec path → proceed with task creation - └─ NO → error: "impl-only requires existing spec, use spec-only or full-lifecycle" -``` - -### Task Description Template - -Every task description includes session and scope context: - -``` -TaskCreate({ - subject: "", - owner: "", - description: "\nSession: \nScope: ", - blockedBy: [], - status: "pending" -}) -``` - -### Execution Method - -| Method | Behavior | -|--------|----------| -| sequential | One task active at a time; next activated after predecessor completes | -| parallel | Tasks with all deps met run concurrently (e.g., TEST-001 + REVIEW-001) | - -## Phase 4: Validation - -| Check | Criteria | -|-------|----------| -| Task count | Matches mode total from routing table | -| Dependencies | Every blockedBy references an existing task subject | -| Owner assignment | Each task owner matches SKILL.md Role Registry prefix | -| Session reference | Every task description contains `Session: ` | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Unknown mode | Reject with supported mode list | -| Missing spec for impl-only | Error, suggest spec-only or full-lifecycle | -| TaskCreate fails | Log error, report to user | -| Duplicate task subject | Skip creation, log warning | diff --git a/.claude/skills/team-lifecycle-v3/roles/coordinator/commands/monitor.md b/.claude/skills/team-lifecycle-v3/roles/coordinator/commands/monitor.md deleted file mode 100644 index fc70fbdf..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/coordinator/commands/monitor.md +++ /dev/null @@ -1,180 +0,0 @@ -# Command: monitor - -## Purpose - -Event-driven pipeline coordination with Spawn-and-Stop pattern. Three wake-up sources drive pipeline advancement: worker callbacks (auto-advance), user `check` (status report), user `resume` (manual advance). - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` | -| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS | - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session file | `/team-session.json` | Yes | -| Task list | `TaskList()` | Yes | -| Active workers | session.active_workers[] | Yes | -| Pipeline mode | session.mode | Yes | - -## Phase 3: Handler Routing - -### Wake-up Source Detection - -Parse `$ARGUMENTS` to determine handler: - -| Priority | Condition | Handler | -|----------|-----------|---------| -| 1 | Message contains `[]` from known worker role | handleCallback | -| 2 | Contains "check" or "status" | handleCheck | -| 3 | Contains "resume", "continue", or "next" | handleResume | -| 4 | None of the above (initial spawn after dispatch) | handleSpawnNext | - -Known worker roles: analyst, writer, discussant, planner, executor, tester, reviewer, explorer, architect, fe-developer, fe-qa. - ---- - -### Handler: handleCallback - -Worker completed a task. Verify completion, update state, auto-advance. - -``` -Receive callback from [] - ├─ Find matching active worker by role - ├─ Task status = completed? - │ ├─ YES → remove from active_workers → update session - │ │ ├─ Handle checkpoints (see below) - │ │ └─ → 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 -``` - ---- - -### Handler: handleCheck - -Read-only status report. No pipeline advancement. - -**Output format**: - -``` -[coordinator] Pipeline Status -[coordinator] Mode: | Progress: / (%) - -[coordinator] Execution Graph: - Spec Phase: (if applicable) - [ RESEARCH-001] → [ DISCUSS-001] → ... - Impl Phase: (if applicable) - [ PLAN-001] - ├─ BE: [ IMPL-001] → [ TEST-001] → [ REVIEW-001] - └─ FE: [ DEV-FE-001] → [ QA-FE-001] - - done=completed >>>=running o=pending .=not created - -[coordinator] Active Workers: - > () - running - -[coordinator] Ready to spawn: -[coordinator] Commands: 'resume' to advance | 'check' to refresh -``` - -**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=. - -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 workers in background, update session, STOP. - -``` -Collect task states from TaskList() - ├─ completedSubjects: status = completed - ├─ inProgressSubjects: status = in_progress - └─ readySubjects: pending + all blockedBy in completedSubjects - -Ready tasks found? - ├─ NONE + work in progress → report waiting → STOP - ├─ NONE + nothing in progress → PIPELINE_COMPLETE → Phase 5 - └─ HAS ready tasks → for each: - ├─ TaskUpdate → in_progress - ├─ team_msg log → task_unblocked - ├─ Spawn worker (see tool call below) - └─ Add to session.active_workers - Update session file → output summary → STOP -``` - -**Spawn worker tool call** (one per ready task): - -```bash -Task({ - subagent_type: "general-purpose", - description: "Spawn worker for ", - team_name: , - name: "", - run_in_background: true, - prompt: "" -}) -``` - ---- - -### Checkpoints - -| Completed Task | Mode Condition | Action | -|---------------|----------------|--------| -| DISCUSS-006 | full-lifecycle or full-lifecycle-fe | Output "SPEC PHASE COMPLETE" checkpoint, pause for user review before impl | - ---- - -### Worker Failure Handling - -When a worker has unexpected status (not completed, not in_progress): - -1. Reset task → pending via TaskUpdate -2. Log via team_msg (type: error) -3. Report to user: task reset, will retry on next resume - -## Phase 4: Validation - -| Check | Criteria | -|-------|----------| -| Session state consistent | active_workers matches TaskList in_progress tasks | -| No orphaned tasks | Every in_progress task has an active_worker entry | -| Pipeline completeness | All expected tasks exist per mode | -| Completion detection | readySubjects=0 + inProgressSubjects=0 → PIPELINE_COMPLETE | - -## 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 | diff --git a/.claude/skills/team-lifecycle-v3/roles/coordinator/role.md b/.claude/skills/team-lifecycle-v3/roles/coordinator/role.md deleted file mode 100644 index 13d58946..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/coordinator/role.md +++ /dev/null @@ -1,209 +0,0 @@ -# Coordinator Role - -Orchestrate the team-lifecycle workflow: team creation, task dispatching, progress monitoring, session state. - -## Identity - -- **Name**: `coordinator` | **Tag**: `[coordinator]` -- **Responsibility**: Parse requirements → Create team → Dispatch tasks → Monitor progress → Report results - -## Boundaries - -### MUST -- Parse user requirements and clarify ambiguous inputs via AskUserQuestion -- Create team and spawn worker subagents in background -- Dispatch tasks with proper dependency chains (see SKILL.md Task Metadata Registry) -- Monitor progress via worker callbacks and route messages -- Maintain session state persistence (team-session.json) - -### MUST NOT -- Execute spec/impl/research work directly (delegate to workers) -- Modify task outputs (workers own their deliverables) -- Call implementation subagents (code-developer, etc.) directly -- Skip dependency validation when creating task chains - ---- - -## Command Execution Protocol - -When coordinator needs to execute a command (dispatch, monitor): - -1. **Read the command file**: `roles/coordinator/commands/.md` -2. **Follow the workflow** defined in the command file (Phase 2-4 structure) -3. **Commands are inline execution guides** - NOT separate agents or subprocesses -4. **Execute synchronously** - complete the command workflow before proceeding - -Example: -``` -Phase 3 needs task dispatch - -> Read roles/coordinator/commands/dispatch.md - -> Execute Phase 2 (Context Loading) - -> Execute Phase 3 (Task Chain Creation) - -> Execute Phase 4 (Validation) - -> Continue to Phase 4 -``` - ---- - -## Entry Router - -When coordinator is invoked, first detect the invocation type: - -| Detection | Condition | Handler | -|-----------|-----------|---------| -| Worker callback | Message contains `[role-name]` tag from a known worker role | → handleCallback: auto-advance pipeline | -| Status check | Arguments contain "check" or "status" | → handleCheck: output execution graph, no advancement | -| Manual resume | Arguments contain "resume" or "continue" | → handleResume: check worker states, advance pipeline | -| Interrupted session | Active/paused session exists in `.workflow/.team/TLS-*` | → Phase 0 (Session Resume Check) | -| New session | None of the above | → Phase 1 (Requirement Clarification) | - -For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP. - -### Router Implementation - -1. **Load session context** (if exists): - - Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions - - If found, extract known worker roles from session or SKILL.md Role Registry - -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 Requirement Clarification below - ---- - -## Phase 0: Session Resume Check - -**Objective**: Detect and resume interrupted sessions before creating new ones. - -**Workflow**: -1. Scan `.workflow/.team/TLS-*/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 → AskUserQuestion for user selection - -**Session Reconciliation**: -1. Audit TaskList → get real status of all tasks -2. Reconcile: session.completed_tasks ↔ TaskList status (bidirectional sync) -3. Reset any in_progress tasks → pending (they were interrupted) -4. Determine remaining pipeline from reconciled state -5. Rebuild team if disbanded (TeamCreate + spawn needed workers only) -6. Create missing tasks with correct blockedBy dependencies -7. Verify dependency chain integrity -8. Update session file with reconciled state -9. Kick first executable task's worker → Phase 4 - ---- - -## Phase 1: Requirement Clarification - -**Objective**: Parse user input and gather execution parameters. - -**Workflow**: - -1. **Parse arguments** for explicit settings: mode, scope, focus areas, depth - -2. **Ask for missing parameters** via AskUserQuestion: - - Mode: spec-only / impl-only / full-lifecycle / fe-only / fullstack / full-lifecycle-fe - - Scope: project description - - Execution method: sequential / parallel - -3. **Frontend auto-detection** (for impl-only and full-lifecycle modes): - - | Signal | Detection | Pipeline Upgrade | - |--------|----------|-----------------| - | FE keywords (component, page, UI, React, Vue, CSS...) | Keyword match in description | impl-only → fe-only or fullstack | - | BE keywords also present (API, database, server...) | Both FE + BE keywords | impl-only → fullstack | - | FE framework in package.json | grep react/vue/svelte/next | full-lifecycle → full-lifecycle-fe | - -4. **Store requirements**: mode, scope, focus, depth, executionMethod - -**Success**: All parameters captured, mode finalized. - ---- - -## Phase 2: Create Team + Initialize Session - -**Objective**: Initialize team, session file, and wisdom directory. - -**Workflow**: -1. Generate session ID: `TLS--` -2. Create session folder: `.workflow/.team//` -3. Call TeamCreate with team name -4. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md) -5. Write team-session.json with: session_id, mode, scope, status="active", tasks_total, tasks_completed=0 - -**Task counts by mode**: - -| Mode | Tasks | -|------|-------| -| spec-only | 12 | -| impl-only | 4 | -| fe-only | 3 | -| fullstack | 6 | -| full-lifecycle | 16 | -| full-lifecycle-fe | 18 | - -**Success**: Team created, session file written, wisdom initialized. - ---- - -## Phase 3: Create Task Chain - -**Objective**: Dispatch tasks based on mode with proper dependencies. - -Delegate to `commands/dispatch.md` which creates the full task chain: -1. Reads SKILL.md Task Metadata Registry for task definitions -2. Creates tasks via TaskCreate with correct blockedBy -3. Assigns owner based on role mapping -4. Includes `Session: ` in every task description - ---- - -## Phase 4: Spawn-and-Stop - -**Objective**: Spawn first batch of ready workers in background, then STOP. - -**Design**: Spawn-and-Stop + Callback pattern. -- Spawn workers with `Task(run_in_background: true)` → immediately return -- Worker completes → SendMessage callback → auto-advance -- User can use "check" / "resume" to manually advance -- Coordinator does one operation per invocation, then STOPS - -**Workflow**: -1. Load `commands/monitor.md` -2. Find tasks with: status=pending, blockedBy all resolved, owner assigned -3. For each ready task → spawn worker (see SKILL.md Spawn Template) -4. Output status summary -5. STOP - -**Pipeline advancement** driven by three wake sources: -- Worker callback (automatic) → Entry Router → handleCallback -- User "check" → handleCheck (status only) -- User "resume" → handleResume (advance) - ---- - -## Phase 5: Report + Next Steps - -**Objective**: Completion report and follow-up options. - -**Workflow**: -1. Load session state → count completed tasks, duration -2. List deliverables with output paths -3. Update session status → "completed" -4. Offer next steps: 退出 / 查看产物 / 扩展任务 / 生成 lite-plan / 创建 Issue - ---- - -## Error Handling - -| Error | Resolution | -|-------|------------| -| Task timeout | Log, mark failed, ask user to retry or skip | -| Worker crash | Respawn worker, reassign task | -| Dependency cycle | Detect, report to user, halt | -| Invalid mode | Reject with error, ask to clarify | -| Session corruption | Attempt recovery, fallback to manual reconciliation | diff --git a/.claude/skills/team-lifecycle-v3/roles/discussant/commands/critique.md b/.claude/skills/team-lifecycle-v3/roles/discussant/commands/critique.md deleted file mode 100644 index a503490f..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/discussant/commands/critique.md +++ /dev/null @@ -1,136 +0,0 @@ -# Command: critique - -## Purpose - -Multi-perspective CLI critique: launch parallel analyses from assigned perspectives, collect structured ratings, detect divergences, and synthesize consensus. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Round config | DISCUSS-NNN → look up round in role.md table | Yes | -| Artifact | `/` from round config | Yes | -| Perspectives | Round config perspectives column | Yes | -| Discovery context | `/spec/discovery-context.json` | For coverage perspective | -| Prior discussions | `/discussions/` | No | - -## Phase 3: Multi-Perspective Critique - -### Perspective Routing - -| Perspective | CLI Tool | Role | Focus Areas | -|-------------|----------|------|-------------| -| Product | gemini | Product Manager | Market fit, user value, business viability, competitive differentiation | -| Technical | codex | Tech Lead | Feasibility, tech debt, performance, security, maintainability | -| Quality | claude | QA Lead | Completeness, testability, consistency, standards compliance | -| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes, mitigation | -| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context, gap detection, scope creep | - -### Execution Flow - -``` -For each perspective in round config: - ├─ Build prompt with perspective focus + artifact content - ├─ Launch CLI analysis (background) - │ Bash(command="ccw cli -p '' --tool --mode analysis", run_in_background=true) - └─ Collect result via hook callback -``` - -### CLI Call Template - -```bash -Bash(command="ccw cli -p 'PURPOSE: Analyze from perspective for -TASK: -MODE: analysis -CONTEXT: Artifact content below -EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5) -CONSTRAINTS: Output valid JSON only - -Artifact: -' --tool --mode analysis", run_in_background=true) -``` - -### Extra Fields by Perspective - -| Perspective | Additional Output Fields | -|-------------|------------------------| -| Risk | `risk_level`: low / medium / high / critical | -| Coverage | `covered_requirements[]`, `partial_requirements[]`, `missing_requirements[]`, `scope_creep[]` | - ---- - -### Divergence Detection - -After all perspectives return, scan results for critical signals: - -| Signal | Condition | Severity | -|--------|-----------|----------| -| Coverage gap | `missing_requirements` non-empty | High | -| High risk | `risk_level` is high or critical | High | -| Low rating | Any perspective rating <= 2 | Medium | -| Rating spread | Max rating - min rating >= 3 | Medium | - -### Consensus Determination - -| Condition | Verdict | -|-----------|---------| -| No high-severity divergences AND average rating >= 3.0 | consensus_reached | -| Any high-severity divergence OR average rating < 3.0 | consensus_blocked | - -### Synthesis Process - -``` -Collect all perspective results - ├─ Extract convergent themes (agreed by 2+ perspectives) - ├─ Extract divergent views (conflicting assessments) - ├─ Check coverage gaps from coverage result - ├─ Compile action items from all suggestions - └─ Determine consensus per table above -``` - -## Phase 4: Validation - -### Discussion Record - -Write to `/discussions/-discussion.md`: - -``` -# Discussion Record: - -**Artifact**: -**Perspectives**: -**Consensus**: reached / blocked - -## Convergent Themes -- - -## Divergent Views -- **** (): - -## Action Items -1. - -## Ratings -| Perspective | Rating | -|-------------|--------| -| | /5 | - -**Average**: /5 -``` - -### Result Routing - -| Outcome | Message Type | Content | -|---------|-------------|---------| -| Consensus reached | discussion_ready | Action items, record path, average rating | -| Consensus blocked | discussion_blocked | Divergence points, severity, record path | -| Artifact not found | error | Missing artifact path | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Artifact not found | Report error to coordinator | -| Single CLI perspective fails | Fallback to direct Claude analysis for that perspective | -| All CLI analyses fail | Generate basic discussion from direct artifact reading | -| All perspectives diverge | Report as discussion_blocked with all divergence points | diff --git a/.claude/skills/team-lifecycle-v3/roles/discussant/role.md b/.claude/skills/team-lifecycle-v3/roles/discussant/role.md deleted file mode 100644 index 0df0f144..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/discussant/role.md +++ /dev/null @@ -1,128 +0,0 @@ -# Role: discussant - -Multi-perspective critique, consensus building, and conflict escalation. Ensures quality feedback between each phase transition. - -## Identity - -- **Name**: `discussant` | **Prefix**: `DISCUSS-*` | **Tag**: `[discussant]` -- **Responsibility**: Load Artifact → Multi-Perspective Critique → Synthesize Consensus → Report - -## Boundaries - -### MUST -- Only process DISCUSS-* tasks -- Execute multi-perspective critique via CLI tools -- Detect coverage gaps from coverage perspective -- Synthesize consensus with convergent/divergent analysis -- Write discussion records to `discussions/` folder - -### MUST NOT -- Create tasks -- Contact other workers directly -- Modify spec documents directly -- Skip perspectives defined in round config -- Ignore critical divergences - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| discussion_ready | → coordinator | Consensus reached | -| discussion_blocked | → coordinator | Cannot reach consensus | -| error | → coordinator | Input artifact missing | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/critique.md | Multi-perspective CLI critique | -| gemini CLI | Product, Risk, Coverage perspectives | -| codex CLI | Technical perspective | -| claude CLI | Quality perspective | - ---- - -## Perspective Model - -| Perspective | Focus | CLI Tool | -|-------------|-------|----------| -| Product | Market fit, user value, business viability | gemini | -| Technical | Feasibility, tech debt, performance, security | codex | -| Quality | Completeness, testability, consistency | claude | -| Risk | Risk identification, dependency analysis, failure modes | gemini | -| Coverage | Requirement completeness vs original intent, gap detection | gemini | - -## Round Configuration - -| Round | Artifact | Perspectives | Focus | -|-------|----------|-------------|-------| -| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | Scope confirmation | -| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | Positioning, feasibility | -| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | Completeness, priority | -| DISCUSS-004 | spec/architecture/_index.md | technical, risk | Tech choices, security | -| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | MVP scope, estimation | -| DISCUSS-006 | spec/readiness-report.md | all 5 | Final sign-off | - ---- - -## Phase 2: Artifact Loading - -**Objective**: Load target artifact and determine discussion parameters. - -**Workflow**: -1. Extract session folder and round number from task subject (`DISCUSS-`) -2. Look up round config from table above -3. Load target artifact from `/` -4. Create `/discussions/` directory -5. Load prior discussion records for continuity - ---- - -## Phase 3: Multi-Perspective Critique - -**Objective**: Run parallel CLI analyses from each required perspective. - -Delegate to `commands/critique.md` -- launches parallel CLI calls per perspective with focused prompts and designated tools. - ---- - -## Phase 4: Consensus Synthesis - -**Objective**: Synthesize into consensus with actionable outcomes. - -**Synthesis process**: -1. Extract convergent themes (agreed by 2+ perspectives) -2. Extract divergent views (conflicting perspectives, with severity) -3. Check coverage gaps from coverage perspective -4. Compile action items and open questions - -**Consensus routing**: - -| Condition | Status | Report | -|-----------|--------|--------| -| No high-severity divergences | consensus_reached | Action items, open questions, record path | -| Any high-severity divergences | consensus_blocked | Escalate divergence points to coordinator | - -Write discussion record to `/discussions/`. - -**Output file naming convention**: - -| Round | Output File | -|-------|------------| -| DISCUSS-001 | discuss-001-scope.md | -| DISCUSS-002 | discuss-002-brief.md | -| DISCUSS-003 | discuss-003-requirements.md | -| DISCUSS-004 | discuss-004-architecture.md | -| DISCUSS-005 | discuss-005-epics.md | -| DISCUSS-006 | discuss-006-signoff.md | - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Target artifact not found | Notify coordinator | -| CLI perspective failure | Fallback to direct Claude analysis | -| All CLI analyses fail | Generate basic discussion from direct reading | -| All perspectives diverge | Escalate as discussion_blocked | diff --git a/.claude/skills/team-lifecycle-v3/roles/executor/commands/implement.md b/.claude/skills/team-lifecycle-v3/roles/executor/commands/implement.md deleted file mode 100644 index 26501c5e..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/executor/commands/implement.md +++ /dev/null @@ -1,166 +0,0 @@ -# Command: implement - -## Purpose - -Multi-backend code implementation: route tasks to appropriate execution backend (direct edit, subagent, or CLI), build focused prompts, execute with retry and fallback. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Plan | `/plan/plan.json` | Yes | -| Task files | `/plan/.task/TASK-*.json` | Yes | -| Backend | Task metadata / plan default / auto-select | Yes | -| Working directory | task.metadata.working_dir or project root | No | -| Wisdom | `/wisdom/` | No | - -## Phase 3: Implementation - -### Backend Selection - -Priority order (first match wins): - -| Priority | Source | Method | -|----------|--------|--------| -| 1 | Task metadata | `task.metadata.executor` field | -| 2 | Plan default | "Execution Backend:" line in plan.json | -| 3 | Auto-select | See auto-select table below | - -**Auto-select routing**: - -| Condition | Backend | -|-----------|---------| -| Description < 200 chars AND no refactor/architecture keywords AND single target file | agent (direct edit) | -| Description < 200 chars AND simple scope | agent (subagent) | -| Complex scope OR architecture keywords | codex | -| Analysis-heavy OR multi-module integration | gemini | - -### Execution Paths - -``` -Backend selected - ├─ agent (direct edit) - │ └─ Read target file → Edit directly → no subagent overhead - ├─ agent (subagent) - │ └─ Task({ subagent_type: "code-developer", run_in_background: false }) - ├─ codex (CLI) - │ └─ Bash(command="ccw cli ... --tool codex --mode write", run_in_background=true) - └─ gemini (CLI) - └─ Bash(command="ccw cli ... --tool gemini --mode write", run_in_background=true) -``` - -### Path 1: Direct Edit (agent, simple task) - -```bash -Read(file_path="") -Edit(file_path="", old_string="", new_string="") -``` - -### Path 2: Subagent (agent, moderate task) - -``` -Task({ - subagent_type: "code-developer", - run_in_background: false, - description: "Implement ", - prompt: "" -}) -``` - -### Path 3: CLI Backend (codex or gemini) - -```bash -Bash(command="ccw cli -p '' --tool --mode write --cd ", run_in_background=true) -``` - -### Execution Prompt Template - -All backends receive the same structured prompt: - -``` -# Implementation Task: - -## Task Description - - -## Acceptance Criteria -1. - -## Context from Plan - - - - -## Files to Modify - - -## Constraints -- Follow existing code style and patterns -- Preserve backward compatibility -- Add appropriate error handling -- Include inline comments for complex logic -``` - -### Batch Execution - -When multiple IMPL tasks exist, execute in dependency order: - -``` -Topological sort by task.depends_on - ├─ Batch 1: Tasks with no dependencies → execute - ├─ Batch 2: Tasks depending on batch 1 → execute - └─ Batch N: Continue until all tasks complete - -Progress update per batch (when > 1 batch): - → team_msg: "Processing batch /: " -``` - -### Retry and Fallback - -**Retry** (max 3 attempts per task): - -``` -Attempt 1 → failure - ├─ team_msg: "Retry 1/3 after error: " - └─ Attempt 2 → failure - ├─ team_msg: "Retry 2/3 after error: " - └─ Attempt 3 → failure → fallback - -``` - -**Fallback** (when primary backend fails after retries): - -| Primary Backend | Fallback | -|----------------|----------| -| codex | agent (subagent) | -| gemini | agent (subagent) | -| agent (subagent) | Report failure to coordinator | -| agent (direct edit) | agent (subagent) | - -## Phase 4: Validation - -### Self-Validation Steps - -| Step | Method | Pass Criteria | -|------|--------|--------------| -| Syntax check | `Bash(command="tsc --noEmit", timeout=30000)` | Exit code 0 | -| Acceptance match | Check criteria keywords vs modified files | All criteria addressed | -| Test detection | Search for .test.ts/.spec.ts matching modified files | Tests identified | -| File changes | `Bash(command="git diff --name-only HEAD")` | At least 1 file modified | - -### Result Routing - -| Outcome | Message Type | Content | -|---------|-------------|---------| -| All tasks pass validation | impl_complete | Task ID, files modified, backend used | -| Batch progress | impl_progress | Batch index, total batches, current task | -| Validation failure after retries | error | Task ID, error details, retry count | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Syntax errors after implementation | Retry with error context (max 3) | -| Backend unavailable | Fallback to agent | -| Missing dependencies | Request from coordinator | -| All retries + fallback exhausted | Report failure with full error log | diff --git a/.claude/skills/team-lifecycle-v3/roles/executor/role.md b/.claude/skills/team-lifecycle-v3/roles/executor/role.md deleted file mode 100644 index 0cd3296f..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/executor/role.md +++ /dev/null @@ -1,103 +0,0 @@ -# Role: executor - -Code implementation following approved plans. Multi-backend execution with self-validation. - -## Identity - -- **Name**: `executor` | **Prefix**: `IMPL-*` | **Tag**: `[executor]` -- **Responsibility**: Load plan → Route to backend → Implement → Self-validate → Report - -## Boundaries - -### MUST -- Only process IMPL-* tasks -- Follow approved plan exactly -- Use declared execution backends -- Self-validate all implementations - -### MUST NOT -- Create tasks -- Contact other workers directly -- Modify plan files -- Skip self-validation - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| impl_complete | → coordinator | Implementation success | -| impl_progress | → coordinator | Batch progress | -| error | → coordinator | Implementation failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/implement.md | Multi-backend implementation | -| code-developer agent | Simple tasks (synchronous) | -| ccw cli --tool codex --mode write | Complex tasks | -| ccw cli --tool gemini --mode write | Alternative backend | - ---- - -## Phase 2: Task & Plan Loading - -**Objective**: Load plan and determine execution strategy. - -1. Load plan.json and .task/TASK-*.json from `/plan/` - -**Backend selection** (priority order): - -| Priority | Source | Method | -|----------|--------|--------| -| 1 | Task metadata | task.metadata.executor field | -| 2 | Plan default | "Execution Backend:" in plan | -| 3 | Auto-select | Simple (< 200 chars, no refactor) → agent; Complex → codex | - -**Code review selection**: - -| Priority | Source | Method | -|----------|--------|--------| -| 1 | Task metadata | task.metadata.code_review field | -| 2 | Plan default | "Code Review:" in plan | -| 3 | Auto-select | Critical keywords (auth, security, payment) → enabled | - ---- - -## Phase 3: Code Implementation - -**Objective**: Execute implementation across batches. - -**Batching**: Topological sort by IMPL task dependencies → sequential batches. - -Delegate to `commands/implement.md` for prompt building and backend routing: - -| Backend | Invocation | Use Case | -|---------|-----------|----------| -| agent | Task({ subagent_type: "code-developer", run_in_background: false }) | Simple, direct edits | -| codex | ccw cli --tool codex --mode write (background) | Complex, architecture | -| gemini | ccw cli --tool gemini --mode write (background) | Analysis-heavy | - ---- - -## Phase 4: Self-Validation - -| Step | Method | Pass Criteria | -|------|--------|--------------| -| Syntax check | `tsc --noEmit` (30s) | Exit code 0 | -| Acceptance criteria | Match criteria keywords vs implementation | All addressed | -| Test detection | Find .test.ts/.spec.ts for modified files | Tests identified | -| Code review (optional) | gemini analysis or codex review | No blocking issues | - -**Report**: task ID, status, files modified, validation results, backend used. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Syntax errors | Retry with error context (max 3) | -| Missing dependencies | Request from coordinator | -| Backend unavailable | Fallback to agent | -| Circular dependencies | Abort, report graph | diff --git a/.claude/skills/team-lifecycle-v3/roles/explorer/role.md b/.claude/skills/team-lifecycle-v3/roles/explorer/role.md deleted file mode 100644 index ab069ad8..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/explorer/role.md +++ /dev/null @@ -1,91 +0,0 @@ -# Role: explorer - -Code search, pattern discovery, dependency tracing. Service role, on-demand. - -## Identity - -- **Name**: `explorer` | **Prefix**: `EXPLORE-*` | **Tag**: `[explorer]` -- **Type**: Service (on-demand, not on main pipeline) -- **Responsibility**: Parse request → Multi-strategy search → Package results - -## Boundaries - -### MUST -- Only process EXPLORE-* tasks -- Output structured JSON -- Cache results in `/explorations/` - -### MUST NOT -- Create tasks or modify source code -- Execute analysis, planning, or implementation -- Make architectural decisions (only discover patterns) - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| explore_ready | → coordinator | Search complete | -| task_failed | → coordinator | Search failure | - -## Search Tools (priority order) - -| Tool | Priority | Use Case | -|------|----------|----------| -| mcp__ace-tool__search_context | P0 | Semantic search | -| Grep / Glob | P1 | Pattern matching | -| cli-explore-agent | Deep | Multi-angle exploration | -| WebSearch | P3 | External docs | - ---- - -## Phase 2: Request Parsing - -Parse from task description: - -| Field | Pattern | Default | -|-------|---------|---------| -| Session | `Session: ` | .workflow/.tmp | -| Mode | `Mode: codebase\|external\|hybrid` | codebase | -| Angles | `Angles: ` | general | -| Keywords | `Keywords: ` | from subject | -| Requester | `Requester: ` | coordinator | - ---- - -## Phase 3: Multi-Strategy Search - -Execute strategies in priority order, accumulating findings: - -1. **ACE (P0)**: Per keyword → semantic search → relevant_files -2. **Grep (P1)**: Per keyword → class/function/export definitions → relevant_files -3. **Dependency trace**: Top 10 files → Read imports → dependencies -4. **Deep exploration** (multi-angle): Per angle → cli-explore-agent → merge -5. **External (P3)** (external/hybrid mode): Top 3 keywords → WebSearch - -Deduplicate by path. - ---- - -## Phase 4: Package Results - -Write JSON to `/explore-.json`: -- relevant_files[], patterns[], dependencies[], external_refs[], _metadata - -**Report**: file count, pattern count, top files, output path. - ---- - -## Coordinator Integration - -| Trigger | Example Task | -|---------|-------------| -| RESEARCH needs context | EXPLORE-001: 代码库搜索 | -| PLAN needs exploration | EXPLORE-002: 实现代码探索 | -| DISCUSS needs practices | EXPLORE-003: 外部文档 | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| ACE unavailable | Fallback to Grep | -| No results | Report empty, suggest broader keywords | diff --git a/.claude/skills/team-lifecycle-v3/roles/fe-developer/role.md b/.claude/skills/team-lifecycle-v3/roles/fe-developer/role.md deleted file mode 100644 index b23f4f1d..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/fe-developer/role.md +++ /dev/null @@ -1,111 +0,0 @@ -# Role: fe-developer - -Frontend development. Consumes plan/architecture output, implements components, pages, styles. - -## Identity - -- **Name**: `fe-developer` | **Prefix**: `DEV-FE-*` | **Tag**: `[fe-developer]` -- **Type**: Frontend pipeline worker -- **Responsibility**: Context loading → Design token consumption → Component implementation → Report - -## Boundaries - -### MUST -- Only process DEV-FE-* tasks -- Follow existing design tokens and component specs (if available) -- Generate accessible frontend code (semantic HTML, ARIA, keyboard nav) -- Follow project's frontend tech stack - -### MUST NOT -- Modify backend code or API interfaces -- Contact other workers directly -- Introduce new frontend dependencies without architecture review - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| dev_fe_complete | → coordinator | Implementation done | -| dev_fe_progress | → coordinator | Long task progress | -| error | → coordinator | Implementation failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| code-developer agent | Component implementation | -| ccw cli --tool gemini --mode write | Complex frontend generation | - ---- - -## Phase 2: Context Loading - -**Inputs to load**: -- Plan: `/plan/plan.json` -- Design tokens: `/architecture/design-tokens.json` (optional) -- Design intelligence: `/analysis/design-intelligence.json` (optional) -- Component specs: `/architecture/component-specs/*.md` (optional) -- Shared memory, wisdom - -**Tech stack detection**: - -| Signal | Framework | Styling | -|--------|-----------|---------| -| react/react-dom in deps | react | - | -| vue in deps | vue | - | -| next in deps | nextjs | - | -| tailwindcss in deps | - | tailwind | -| @shadcn/ui in deps | - | shadcn | - ---- - -## Phase 3: Frontend Implementation - -**Step 1**: Generate design token CSS (if tokens available) -- Convert design-tokens.json → CSS custom properties (`:root { --color-*, --space-*, --text-* }`) -- Include dark mode overrides via `@media (prefers-color-scheme: dark)` -- Write to `src/styles/tokens.css` - -**Step 2**: Implement components - -| Task Size | Strategy | -|-----------|----------| -| Simple (≤ 3 files, single component) | code-developer agent (synchronous) | -| Complex (system, multi-component) | ccw cli --tool gemini --mode write (background) | - -**Coding standards** (include in agent/CLI prompt): -- Use design token CSS variables, never hardcode colors/spacing -- Interactive elements: cursor: pointer -- Transitions: 150-300ms -- Text contrast: minimum 4.5:1 -- Include focus-visible styles -- Support prefers-reduced-motion -- Responsive: mobile-first -- No emoji as functional icons - ---- - -## Phase 4: Self-Validation - -| Check | What | -|-------|------| -| hardcoded-color | No #hex outside tokens.css | -| cursor-pointer | Interactive elements have cursor: pointer | -| focus-styles | Interactive elements have focus styles | -| responsive | Has responsive breakpoints | -| reduced-motion | Animations respect prefers-reduced-motion | -| emoji-icon | No emoji as functional icons | - -Contribute to wisdom/conventions.md. Update shared-memory.json with component inventory. - -**Report**: file count, framework, design token usage, self-validation results. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Design tokens not found | Use project defaults | -| Tech stack undetected | Default HTML + CSS | -| Subagent failure | Fallback to CLI write mode | diff --git a/.claude/skills/team-lifecycle-v3/roles/fe-qa/commands/pre-delivery-checklist.md b/.claude/skills/team-lifecycle-v3/roles/fe-qa/commands/pre-delivery-checklist.md deleted file mode 100644 index c742380d..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/fe-qa/commands/pre-delivery-checklist.md +++ /dev/null @@ -1,152 +0,0 @@ -# Command: pre-delivery-checklist - -## Purpose - -CSS-level pre-delivery checks for frontend files. Validates accessibility, interaction, design compliance, and layout patterns before final delivery. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Changed frontend files | git diff --name-only (filtered to .tsx, .jsx, .css, .scss) | Yes | -| File contents | Read each changed file | Yes | -| Design tokens path | `src/styles/tokens.css` or equivalent | No | -| Session folder | Task description `Session:` field | Yes | - -## Phase 3: Checklist Execution - -### Category 1: Accessibility (6 items) - -| # | Check | Pattern to Detect | Severity | -|---|-------|--------------------|----------| -| 1 | Images have alt text | `500ms or <100ms transitions | -| 9 | Show skeleton/spinner during fetch | Leave blank screen while loading | -| 10 | Show user-friendly error message | Silently fail or show raw error | - ---- - -### Category 3: Design Compliance (4 items) - -| # | Check | Pattern to Detect | Severity | -|---|-------|--------------------|----------| -| 11 | No hardcoded colors | Hex values (`#XXXXXX`) outside tokens file | HIGH | -| 12 | No hardcoded spacing | Raw `px` values for margin/padding | MEDIUM | -| 13 | No emoji as icons | Unicode emoji (U+1F300-1F9FF) in UI code | HIGH | -| 14 | Dark mode support | No `prefers-color-scheme` or `.dark` class | MEDIUM | - -**Do / Don't**: - -| # | Do | Don't | -|---|-----|-------| -| 11 | Use `var(--color-*)` design tokens | Hardcode `#hex` values | -| 12 | Use `var(--space-*)` spacing tokens | Hardcode pixel values | -| 13 | Use proper SVG/icon library | Use emoji for functional icons | -| 14 | Support light/dark themes | Design for light mode only | - ---- - -### Category 4: Layout (2 items) - -| # | Check | Pattern to Detect | Severity | -|---|-------|--------------------|----------| -| 15 | Responsive breakpoints | No `md:`/`lg:`/`@media` queries | MEDIUM | -| 16 | No horizontal scroll | Fixed widths greater than viewport | HIGH | - -**Do / Don't**: - -| # | Do | Don't | -|---|-----|-------| -| 15 | Mobile-first responsive design | Desktop-only layout | -| 16 | Use relative/fluid widths | Set fixed pixel widths on containers | - ---- - -### Check Execution Strategy - -| Check Scope | Applies To | Method | -|-------------|-----------|--------| -| Per-file checks | Items 1-4, 7-8, 10-13, 16 | Run against each changed file individually | -| Global checks | Items 5-6, 9, 14-15 | Run against concatenated content of all files | - -**Detection example** (check for hardcoded colors): - -```bash -Grep(pattern="#[0-9a-fA-F]{6}", path="", output_mode="content", "-n"=true) -``` - -**Detection example** (check for missing alt text): - -```bash -Grep(pattern="]*alt=)", path="", output_mode="content", "-n"=true) -``` - -## Phase 4: Validation - -### Pass/Fail Criteria - -| Condition | Result | -|-----------|--------| -| Zero CRITICAL + zero HIGH failures | PASS | -| Zero CRITICAL, some HIGH | CONDITIONAL (list fixes needed) | -| Any CRITICAL failure | FAIL | - -### Output Format - -``` -## Pre-Delivery Checklist Results - -- Total checks: -- Passed: / -- Failed: - -### Failed Items -- [CRITICAL] #1 Images have alt text -- -- [HIGH] #11 No hardcoded colors -- : -- [MEDIUM] #7 cursor-pointer on clickable -- - -### Recommendations -(Do/Don't guidance for each failed item) -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| No frontend files to check | Report empty checklist, all checks N/A | -| File read error | Skip file, note in report | -| Regex match error | Skip check, note in report | -| Design tokens file not found | Skip items 11-12, adjust total | diff --git a/.claude/skills/team-lifecycle-v3/roles/fe-qa/role.md b/.claude/skills/team-lifecycle-v3/roles/fe-qa/role.md deleted file mode 100644 index 8e91131c..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/fe-qa/role.md +++ /dev/null @@ -1,113 +0,0 @@ -# Role: fe-qa - -Frontend quality assurance. 5-dimension review + Generator-Critic loop. - -## Identity - -- **Name**: `fe-qa` | **Prefix**: `QA-FE-*` | **Tag**: `[fe-qa]` -- **Type**: Frontend pipeline worker -- **Responsibility**: Context loading → 5-dimension review → GC feedback → Report - -## Boundaries - -### MUST -- Only process QA-FE-* tasks -- Execute 5-dimension review -- Support Generator-Critic loop (max 2 rounds) -- Provide actionable fix suggestions (Do/Don't format) - -### MUST NOT -- Modify source code directly (review only) -- Contact other workers directly -- Mark pass when score below threshold - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| qa_fe_passed | → coordinator | All dimensions pass | -| qa_fe_result | → coordinator | Review complete (may have issues) | -| fix_required | → coordinator | Critical issues found | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/pre-delivery-checklist.md | CSS-level delivery checks | -| ccw cli --tool gemini --mode analysis | Frontend code review | -| ccw cli --tool codex --mode review | Git-aware code review | - ---- - -## Review Dimensions - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Code Quality | 25% | TypeScript types, component structure, error handling | -| Accessibility | 25% | Semantic HTML, ARIA, keyboard nav, contrast, focus-visible | -| Design Compliance | 20% | Token usage, no hardcoded colors, no emoji icons | -| UX Best Practices | 15% | Loading/error/empty states, cursor-pointer, responsive | -| Pre-Delivery | 15% | No console.log, dark mode, i18n readiness | - ---- - -## Phase 2: Context Loading - -**Inputs**: design tokens, design intelligence, shared memory, previous QA results (for GC round tracking), changed frontend files via git diff. - -Determine GC round from previous QA results count. Max 2 rounds. - ---- - -## Phase 3: 5-Dimension Review - -For each changed frontend file, check against all 5 dimensions. Score each dimension 0-10, deducting for issues found. - -**Scoring deductions**: - -| Severity | Deduction | -|----------|-----------| -| High | -2 to -3 | -| Medium | -1 to -1.5 | -| Low | -0.5 | - -**Overall score** = weighted sum of dimension scores. - -**Verdict routing**: - -| Condition | Verdict | -|-----------|---------| -| Score ≥ 8 AND no critical issues | PASS | -| GC round ≥ max AND score ≥ 6 | PASS_WITH_WARNINGS | -| GC round ≥ max AND score < 6 | FAIL | -| Otherwise | NEEDS_FIX | - ---- - -## Phase 4: Report - -Write audit to `/qa/audit-fe--r.json`. Update wisdom and shared memory. - -**Report**: round, verdict, overall score, dimension scores, critical issues with Do/Don't format, action required (if NEEDS_FIX). - ---- - -## Generator-Critic Loop - -Orchestrated by coordinator: -``` -Round 1: DEV-FE-001 → QA-FE-001 - if NEEDS_FIX → coordinator creates DEV-FE-002 + QA-FE-002 -Round 2: DEV-FE-002 → QA-FE-002 - if still NEEDS_FIX → PASS_WITH_WARNINGS or FAIL (max 2) -``` - -**Convergence**: score ≥ 8 AND critical_count = 0 - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| No changed files | Report empty, score N/A | -| Design tokens not found | Skip design compliance, adjust weights | -| Max GC rounds exceeded | Force verdict | diff --git a/.claude/skills/team-lifecycle-v3/roles/planner/commands/explore.md b/.claude/skills/team-lifecycle-v3/roles/planner/commands/explore.md deleted file mode 100644 index f85b92f0..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/planner/commands/explore.md +++ /dev/null @@ -1,154 +0,0 @@ -# Command: explore - -## Purpose - -Complexity-driven codebase exploration: assess task complexity, select exploration angles by category, execute parallel exploration agents, and produce structured exploration results for plan generation. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | PLAN-* task subject/description | Yes | -| Session folder | Task description `Session:` field | Yes | -| Spec context | `/spec/` (if exists) | No | -| Plan directory | `/plan/` | Yes (create if missing) | -| Project tech | `.workflow/project-tech.json` | No | - -## Phase 3: Exploration - -### Complexity Assessment - -Score the task description against keyword indicators: - -| Indicator | Keywords | Score | -|-----------|----------|-------| -| Structural change | refactor, architect, restructure, modular | +2 | -| Multi-scope | multiple, across, cross-cutting | +2 | -| Integration | integrate, api, database | +1 | -| Non-functional | security, performance, auth | +1 | - -**Complexity routing**: - -| Score | Level | Strategy | Angle Count | -|-------|-------|----------|-------------| -| 0-1 | Low | ACE semantic search only | 1 | -| 2-3 | Medium | cli-explore-agent per angle | 2-3 | -| 4+ | High | cli-explore-agent per angle | 3-5 | - -### Angle Presets - -Select preset by dominant keyword match, then take first N angles per complexity: - -| Preset | Trigger Keywords | Angles (priority order) | -|--------|-----------------|------------------------| -| architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points | -| security | security, auth, permission, access | security, auth-patterns, dataflow, validation | -| performance | performance, slow, optimize, cache | performance, bottlenecks, caching, data-access | -| bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases | -| feature | (default) | patterns, integration-points, testing, dependencies | - -### Low Complexity: Direct Search - -```bash -mcp__ace-tool__search_context(project_root_path="", query="") -``` - -Transform results into exploration JSON and write to `/exploration-.json`. - -**ACE failure fallback**: - -```bash -Bash(command="rg -l '' --type ts", timeout=30000) -``` - -### Medium/High Complexity: Parallel Exploration - -For each selected angle, launch an exploration agent: - -``` -Task({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore: ", - prompt: "## Task Objective -Execute exploration for task planning context. - -## Output Location -Output File: /exploration-.json - -## Assigned Context -- Exploration Angle: -- Task Description: -- Spec Context: - -## Mandatory First Steps -1. rg -l '' --type ts -2. cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json -3. Read .workflow/project-tech.json (if exists) - -## Exploration Focus - - -## Output -Write JSON to: /exploration-.json -Each file in relevant_files MUST have: rationale (>10 chars), role, discovery_source, key_symbols" -}) -``` - -### Angle Focus Guide - -| Angle | Focus Points | -|-------|-------------| -| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | -| dependencies | Import chains, external libraries, circular dependencies, shared utilities | -| modularity | Module interfaces, separation of concerns, extraction opportunities | -| integration-points | API endpoints, data flow between modules, event systems, service integrations | -| security | Auth/authz logic, input validation, sensitive data handling, middleware | -| auth-patterns | Auth flows (login/refresh), session management, token validation, permissions | -| dataflow | Data transformations, state propagation, validation points, mutation paths | -| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | -| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | -| patterns | Code conventions, design patterns, naming conventions, best practices | -| testing | Test files, coverage gaps, test patterns (unit/integration/e2e), mocking | - -### Explorations Manifest - -After all explorations complete, write manifest to `/explorations-manifest.json`: - -``` -{ - "task_description": "", - "complexity": "", - "exploration_count": , - "explorations": [ - { "angle": "", "file": "exploration-.json" } - ] -} -``` - -## Phase 4: Validation - -### Output Files - -``` -/plan/ - ├─ exploration-.json (per angle) - └─ explorations-manifest.json (summary) -``` - -### Success Criteria - -| Check | Criteria | Required | -|-------|----------|----------| -| At least 1 exploration | Non-empty exploration file exists | Yes | -| Manifest written | explorations-manifest.json exists | Yes | -| File roles assigned | Every relevant_file has role + rationale | Yes | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Single exploration agent fails | Skip angle, remove from manifest, continue | -| All explorations fail | Proceed to plan generation with task description only | -| ACE search fails (Low) | Fallback to ripgrep keyword search | -| Schema file not found | Use inline schema from Output section | diff --git a/.claude/skills/team-lifecycle-v3/roles/planner/role.md b/.claude/skills/team-lifecycle-v3/roles/planner/role.md deleted file mode 100644 index 7d42a980..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/planner/role.md +++ /dev/null @@ -1,120 +0,0 @@ -# Role: planner - -Multi-angle code exploration and structured implementation planning. Submits plans to coordinator for approval. - -## Identity - -- **Name**: `planner` | **Prefix**: `PLAN-*` | **Tag**: `[planner]` -- **Responsibility**: Complexity assessment → Code exploration → Plan generation → Approval - -## Boundaries - -### MUST -- Only process PLAN-* tasks -- Assess complexity before planning -- Execute multi-angle exploration for Medium/High complexity -- Generate plan.json + .task/TASK-*.json -- Load spec context in full-lifecycle mode -- Submit plan for coordinator approval - -### MUST NOT -- Create tasks for other roles -- Implement code -- Modify spec documents -- Skip complexity assessment - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| plan_ready | → coordinator | Plan complete | -| plan_revision | → coordinator | Plan revised per feedback | -| error | → coordinator | Exploration or planning failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/explore.md | Multi-angle codebase exploration | -| cli-explore-agent | Per-angle exploration | -| cli-lite-planning-agent | Plan generation | - ---- - -## Phase 1.5: Load Spec Context (Full-Lifecycle) - -If `/spec/` exists → load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise → impl-only mode. - ---- - -## Phase 2: Multi-Angle Exploration - -**Objective**: Explore codebase to inform planning. - -**Complexity routing**: - -| Complexity | Criteria | Strategy | -|------------|----------|----------| -| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only | -| Medium | 200-500 chars or moderate scope | 2-3 angle cli-explore-agent | -| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle cli-explore-agent | - -Delegate to `commands/explore.md` for angle selection and parallel execution. - ---- - -## Phase 3: Plan Generation - -**Objective**: Generate structured implementation plan. - -| Complexity | Strategy | -|------------|----------| -| Low | Direct planning → single TASK-001 with plan.json | -| Medium/High | cli-lite-planning-agent with exploration results | - -**Agent call** (Medium/High): - -``` -Task({ - subagent_type: "cli-lite-planning-agent", - run_in_background: false, - description: "Generate implementation plan", - prompt: "Generate plan. -Output: /plan.json + /.task/TASK-*.json -Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json -Task: -Explorations: -Complexity: -Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on" -}) -``` - -**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition. - ---- - -## Phase 4: Submit for Approval - -1. Read plan.json and TASK-*.json -2. Report to coordinator: complexity, task count, task list, approach, plan location -3. Wait for response: approved → complete; revision → update and resubmit - -**Session files**: -``` -/plan/ -├── exploration-.json -├── explorations-manifest.json -├── plan.json -└── .task/TASK-*.json -``` - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Exploration agent failure | Plan from description only | -| Planning agent failure | Fallback to direct planning | -| Plan rejected 3+ times | Notify coordinator, suggest alternative | -| Schema not found | Use basic structure | diff --git a/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/code-review.md b/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/code-review.md deleted file mode 100644 index 874c4f98..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/code-review.md +++ /dev/null @@ -1,163 +0,0 @@ -# Command: code-review - -## Purpose - -4-dimension code review analyzing quality, security, architecture, and requirements compliance. Produces a verdict (BLOCK/CONDITIONAL/APPROVE) with categorized findings. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Plan file | `/plan/plan.json` | Yes | -| Git diff | `git diff HEAD~1` or `git diff --cached` | Yes | -| Modified files | From git diff --name-only | Yes | -| Test results | Tester output (if available) | No | -| Wisdom | `/wisdom/` | No | - -## Phase 3: 4-Dimension Review - -### Dimension Overview - -| Dimension | Focus | Weight | -|-----------|-------|--------| -| Quality | Code correctness, type safety, clean code | Equal | -| Security | Vulnerability patterns, secret exposure | Equal | -| Architecture | Module structure, coupling, file size | Equal | -| Requirements | Acceptance criteria coverage, completeness | Equal | - ---- - -### Dimension 1: Quality - -Scan each modified file for quality anti-patterns. - -| Severity | Pattern | What to Detect | -|----------|---------|----------------| -| Critical | Empty catch blocks | `catch(e) {}` with no handling | -| High | @ts-ignore without justification | Suppression comment < 10 chars explanation | -| High | `any` type in public APIs | `any` outside comments and generic definitions | -| High | console.log in production | `console.(log\|debug\|info)` outside test files | -| Medium | Magic numbers | Numeric literals > 1 digit, not in const/comment | -| Medium | Duplicate code | Identical lines (>30 chars) appearing 3+ times | - -**Detection example** (Grep for console statements): - -```bash -Grep(pattern="console\\.(log|debug|info)", path="", output_mode="content", "-n"=true) -``` - ---- - -### Dimension 2: Security - -Scan for vulnerability patterns across all modified files. - -| Severity | Pattern | What to Detect | -|----------|---------|----------------| -| Critical | Hardcoded secrets | `api_key=`, `password=`, `secret=`, `token=` with string values (20+ chars) | -| Critical | SQL injection | String concatenation in `query()`/`execute()` calls | -| High | eval/exec usage | `eval()`, `new Function()`, `setTimeout(string)` | -| High | XSS vectors | `innerHTML`, `dangerouslySetInnerHTML` | -| Medium | Insecure random | `Math.random()` in security context (token/key/password/session) | -| Low | Missing input validation | Functions with parameters but no validation in first 5 lines | - ---- - -### Dimension 3: Architecture - -Assess structural health of modified files. - -| Severity | Pattern | What to Detect | -|----------|---------|----------------| -| Critical | Circular dependencies | File A imports B, B imports A | -| High | Excessive parent imports | Import traverses >2 parent directories (`../../../`) | -| Medium | Large files | Files exceeding 500 lines | -| Medium | Tight coupling | >5 imports from same base module | -| Medium | Long functions | Functions exceeding 50 lines | -| Medium | Module boundary changes | Modifications to index.ts/index.js files | - -**Detection example** (check for deep parent imports): - -```bash -Grep(pattern="from\\s+['\"](\\.\\./){3,}", path="", output_mode="content", "-n"=true) -``` - ---- - -### Dimension 4: Requirements - -Verify implementation against plan acceptance criteria. - -| Severity | Check | Method | -|----------|-------|--------| -| High | Unmet acceptance criteria | Extract criteria from plan, check keyword overlap (threshold: 70%) | -| High | Missing error handling | Plan mentions "error handling" but no try/catch in code | -| Medium | Partially met criteria | Keyword overlap 40-69% | -| Medium | Missing tests | Plan mentions "test" but no test files in modified set | - -**Verification flow**: -1. Read plan file → extract acceptance criteria section -2. For each criterion → extract keywords (4+ char meaningful words) -3. Search modified files for keyword matches -4. Score: >= 70% match = met, 40-69% = partial, < 40% = unmet - ---- - -### Verdict Routing - -| Verdict | Criteria | Action | -|---------|----------|--------| -| BLOCK | Any critical-severity issues found | Must fix before merge | -| CONDITIONAL | High or medium issues, no critical | Should address, can merge with tracking | -| APPROVE | Only low issues or none | Ready to merge | - -## Phase 4: Validation - -### Report Format - -The review report follows this structure: - -``` -# Code Review Report - -**Verdict**: - -## Blocking Issues (if BLOCK) -- **** (:): - -## Review Dimensions - -### Quality Issues -**CRITICAL** () -- (:) - -### Security Issues -(same format per severity) - -### Architecture Issues -(same format per severity) - -### Requirements Issues -(same format per severity) - -## Recommendations -1. -``` - -### Summary Counts - -| Field | Description | -|-------|-------------| -| Total issues | Sum across all dimensions and severities | -| Critical count | Must be 0 for APPROVE | -| Blocking issues | Listed explicitly in report header | -| Dimensions covered | Must be 4/4 | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Plan file not found | Skip requirements dimension, note in report | -| Git diff empty | Report no changes to review | -| File read fails | Skip file, note in report | -| No modified files | Report empty review | diff --git a/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/spec-quality.md b/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/spec-quality.md deleted file mode 100644 index 3dfddc6f..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/spec-quality.md +++ /dev/null @@ -1,202 +0,0 @@ -# Command: spec-quality - -## Purpose - -5-dimension spec quality check with weighted scoring, quality gate determination, and readiness report generation. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Spec documents | `/spec/` (all .md files) | Yes | -| Original requirements | Product brief objectives section | Yes | -| Quality gate config | specs/quality-gates.md | No | -| Session folder | Task description `Session:` field | Yes | - -**Spec document phases** (matched by filename/directory): - -| Phase | Expected Path | Required | -|-------|--------------|---------| -| product-brief | spec/product-brief.md | Yes | -| prd | spec/requirements/*.md | Yes | -| architecture | spec/architecture/_index.md + ADR-*.md | Yes | -| user-stories | spec/epics/*.md | Yes | -| implementation-plan | plan/plan.json | No (impl-only/full-lifecycle) | -| test-strategy | spec/test-strategy.md | No (optional, not generated by pipeline) | - -## Phase 3: 5-Dimension Scoring - -### Dimension Weights - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Completeness | 25% | All required sections present with substance | -| Consistency | 20% | Terminology, format, references, naming | -| Traceability | 25% | Goals -> Reqs -> Components -> Stories chain | -| Depth | 20% | AC testable, ADRs justified, stories estimable | -| Coverage | 10% | Original requirements mapped to spec | - ---- - -### Dimension 1: Completeness (25%) - -Check each spec document for required sections. - -**Required sections by phase**: - -| Phase | Required Sections | -|-------|------------------| -| product-brief | Vision Statement, Problem Statement, Target Audience, Success Metrics, Constraints | -| prd | Goals, Requirements, User Stories, Acceptance Criteria, Non-Functional Requirements | -| architecture | System Overview, Component Design, Data Models, API Specifications, Technology Stack | -| user-stories | Story List, Acceptance Criteria, Priority, Estimation | -| implementation-plan | Task Breakdown, Dependencies, Timeline, Resource Allocation | - -> **Note**: `test-strategy` is optional — skip scoring if `spec/test-strategy.md` is absent. Do not penalize completeness score for missing optional phases. - -**Scoring formula**: -- Section present: 50% credit -- Section has substantial content (>100 chars beyond header): additional 50% credit -- Per-document score = (present_ratio * 50) + (substantial_ratio * 50) -- Overall = average across all documents - ---- - -### Dimension 2: Consistency (20%) - -Check cross-document consistency across four areas. - -| Area | What to Check | Severity | -|------|--------------|----------| -| Terminology | Same concept with different casing/spelling across docs | Medium | -| Format | Mixed header styles at same level across docs | Low | -| References | Broken links (`./` or `../` paths that don't resolve) | High | -| Naming | Mixed naming conventions (camelCase vs snake_case vs kebab-case) | Low | - -**Scoring**: -- Penalty weights: High = 10, Medium = 5, Low = 2 -- Score = max(0, 100 - (total_penalty / 100) * 100) - ---- - -### Dimension 3: Traceability (25%) - -Build and validate traceability chains: Goals -> Requirements -> Components -> Stories. - -**Chain building flow**: -1. Extract goals from product-brief (pattern: `- Goal: `) -2. Extract requirements from PRD (pattern: `- REQ-NNN: `) -3. Extract components from architecture (pattern: `- Component: `) -4. Extract stories from user-stories (pattern: `- US-NNN: `) -5. Link by keyword overlap (threshold: 30% keyword match) - -**Chain completeness**: A chain is complete when a goal links to at least one requirement, one component, and one story. - -**Scoring**: (complete chains / total chains) * 100 - -**Weak link identification**: For each incomplete chain, report which link is missing (no requirements, no components, or no stories). - ---- - -### Dimension 4: Depth (20%) - -Assess the analytical depth of spec content across four sub-dimensions. - -| Sub-dimension | Source | Testable Criteria | -|---------------|--------|-------------------| -| AC Testability | PRD / User Stories | Contains measurable verbs (display, return, validate) or Given/When/Then or numbers | -| ADR Justification | Architecture | Contains rationale, alternatives, consequences, or trade-offs | -| Story Estimability | User Stories | Has "As a/I want/So that" + AC, or explicit estimate | -| Technical Detail | Architecture + Plan | Contains code blocks, API terms, HTTP methods, DB terms | - -**Scoring**: Average of sub-dimension scores (each 0-100%) - ---- - -### Dimension 5: Coverage (10%) - -Map original requirements to spec requirements. - -**Flow**: -1. Extract original requirements from product-brief objectives section -2. Extract spec requirements from all documents (pattern: `- REQ-NNN:` or `- Requirement:` or `- Feature:`) -3. For each original requirement, check keyword overlap with any spec requirement (threshold: 40%) -4. Score = (covered_count / total_original) * 100 - ---- - -### Quality Gate Decision Table - -| Gate | Criteria | Message | -|------|----------|---------| -| PASS | Overall score >= 80% AND coverage >= 70% | Ready for implementation | -| FAIL | Overall score < 60% OR coverage < 50% | Major revisions required | -| REVIEW | All other cases | Improvements needed, may proceed with caution | - -## Phase 4: Validation - -### Readiness Report Format - -Write to `/spec/readiness-report.md`: - -``` -# Specification Readiness Report - -**Generated**: -**Overall Score**: % -**Quality Gate**: - -**Recommended Action**: - -## Dimension Scores - -| Dimension | Score | Weight | Weighted Score | -|-----------|-------|--------|----------------| -| Completeness | % | 25% | % | -| Consistency | % | 20% | % | -| Traceability | % | 25% | % | -| Depth | % | 20% | % | -| Coverage | % | 10% | % | - -## Completeness Analysis -(per-phase breakdown: sections present/expected, missing sections) - -## Consistency Analysis -(issues by area: terminology, format, references, naming) - -## Traceability Analysis -(complete chains / total, weak links) - -## Depth Analysis -(per sub-dimension scores) - -## Requirement Coverage -(covered / total, uncovered requirements list) -``` - -### Spec Summary Format - -Write to `/spec/spec-summary.md`: - -``` -# Specification Summary - -**Overall Quality Score**: % -**Quality Gate**: - -## Documents Reviewed -(per document: phase, path, size, section list) - -## Key Findings -### Strengths (dimensions scoring >= 80%) -### Areas for Improvement (dimensions scoring < 70%) -### Recommendations -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Spec folder empty | FAIL gate, report no documents found | -| Missing phase document | Score 0 for that phase in completeness, note in report | -| No original requirements found | Score coverage at 100% (nothing to cover) | -| Broken references | Flag in consistency, do not fail entire review | diff --git a/.claude/skills/team-lifecycle-v3/roles/reviewer/role.md b/.claude/skills/team-lifecycle-v3/roles/reviewer/role.md deleted file mode 100644 index 3f7456f9..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/reviewer/role.md +++ /dev/null @@ -1,104 +0,0 @@ -# Role: reviewer - -Dual-mode review: code review (REVIEW-*) and spec quality validation (QUALITY-*). Auto-switches by task prefix. - -## Identity - -- **Name**: `reviewer` | **Prefix**: `REVIEW-*` + `QUALITY-*` | **Tag**: `[reviewer]` -- **Responsibility**: Branch by Prefix → Review/Score → Report - -## Boundaries - -### MUST -- Process REVIEW-* and QUALITY-* tasks -- Generate readiness-report.md for QUALITY tasks -- Cover all required dimensions per mode - -### MUST NOT -- Create tasks -- Modify source code -- Skip quality dimensions -- Approve without verification - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| review_result | → coordinator | Code review complete | -| quality_result | → coordinator | Spec quality complete | -| fix_required | → coordinator | Critical issues found | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/code-review.md | 4-dimension code review | -| commands/spec-quality.md | 5-dimension spec quality | - ---- - -## Mode Detection - -| Task Prefix | Mode | Dimensions | -|-------------|------|-----------| -| REVIEW-* | Code Review | quality, security, architecture, requirements | -| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage | - ---- - -## Code Review (REVIEW-*) - -**Inputs**: Plan file, git diff, modified files, test results (if available) - -**4 dimensions** (delegate to commands/code-review.md): - -| Dimension | Critical Issues | -|-----------|----------------| -| Quality | Empty catch, any in public APIs, @ts-ignore, console.log | -| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML | -| Architecture | Circular deps, parent imports >2 levels, files >500 lines | -| Requirements | Missing core functionality, incomplete acceptance criteria | - -**Verdict**: - -| Verdict | Criteria | -|---------|----------| -| BLOCK | Critical issues present | -| CONDITIONAL | High/medium only | -| APPROVE | Low or none | - ---- - -## Spec Quality (QUALITY-*) - -**Inputs**: All spec docs in session folder, quality gate config - -**5 dimensions** (delegate to commands/spec-quality.md): - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Completeness | 25% | All sections present with substance | -| Consistency | 20% | Terminology, format, references | -| Traceability | 25% | Goals → Reqs → Arch → Stories chain | -| Depth | 20% | AC testable, ADRs justified, stories estimable | -| Coverage | 10% | Original requirements mapped | - -**Quality gate**: - -| Gate | Criteria | -|------|----------| -| PASS | Score ≥ 80% AND coverage ≥ 70% | -| REVIEW | Score 60-79% OR coverage 50-69% | -| FAIL | Score < 60% OR coverage < 50% | - -**Artifacts**: readiness-report.md + spec-summary.md - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Missing context | Request from coordinator | -| Invalid mode | Abort with error | -| Analysis failure | Retry, then fallback template | diff --git a/.claude/skills/team-lifecycle-v3/roles/tester/commands/validate.md b/.claude/skills/team-lifecycle-v3/roles/tester/commands/validate.md deleted file mode 100644 index 8016d78a..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/tester/commands/validate.md +++ /dev/null @@ -1,152 +0,0 @@ -# Command: validate - -## Purpose - -Test-fix cycle with strategy engine: detect framework, run tests, classify failures, select fix strategy, iterate until pass rate target is met or max iterations exhausted. - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| MAX_ITERATIONS | 10 | Maximum test-fix cycle attempts | -| PASS_RATE_TARGET | 95% | Minimum pass rate to succeed | -| AFFECTED_TESTS_FIRST | true | Run affected tests before full suite | - -## Phase 2: Context Loading - -Load from task description and executor output: - -| Input | Source | Required | -|-------|--------|----------| -| Framework | Auto-detected (see below) | Yes | -| Modified files | Executor task output / git diff | Yes | -| Affected tests | Derived from modified files | No | -| Session folder | Task description `Session:` field | Yes | -| Wisdom | `/wisdom/` | No | - -**Framework detection** (priority order): - -| Priority | Method | Check | -|----------|--------|-------| -| 1 | package.json devDependencies | vitest, jest, mocha, pytest | -| 2 | package.json scripts.test | Command contains framework name | -| 3 | Config file existence | vitest.config.*, jest.config.*, pytest.ini | - -**Affected test discovery** from modified files: -- For each modified file `.`, search: - `.test.ts`, `.spec.ts`, `tests/.test.ts`, `__tests__/.test.ts` - -## Phase 3: Test-Fix Cycle - -### Test Command Table - -| Framework | Affected Tests | Full Suite | -|-----------|---------------|------------| -| vitest | `vitest run --reporter=verbose` | `vitest run --reporter=verbose` | -| jest | `jest --no-coverage --verbose` | `jest --no-coverage --verbose` | -| mocha | `mocha --reporter spec` | `mocha --reporter spec` | -| pytest | `pytest -v --tb=short` | `pytest -v --tb=short` | - -### Iteration Flow - -``` -Iteration 1 - ├─ Run affected tests (or full suite if none) - ├─ Parse results → pass rate - ├─ Pass rate >= 95%? - │ ├─ YES + affected-only → run full suite to confirm - │ │ ├─ Full suite passes → SUCCESS - │ │ └─ Full suite fails → continue with full results - │ └─ YES + full suite → SUCCESS - └─ NO → classify failures → select strategy → apply fixes - -Iteration 2..10 - ├─ Re-run tests - ├─ Track best pass rate across iterations - ├─ Pass rate >= 95% → SUCCESS - ├─ No failures to fix → STOP (anomaly) - └─ Failures remain → classify → select strategy → apply fixes - -After iteration 10 - └─ FAIL: max iterations reached, report best pass rate -``` - -**Progress update**: When iteration > 5, send progress to coordinator with current pass rate and iteration count. - -### Strategy Selection Matrix - -| Condition | Strategy | Behavior | -|-----------|----------|----------| -| Iteration <= 3 OR pass rate >= 80% | Conservative | Fix one failure at a time, highest severity first | -| Critical failures exist AND count < 5 | Surgical | Identify common error pattern, fix all matching occurrences | -| Pass rate < 50% OR iteration > 7 | Aggressive | Fix all critical + high failures in batch | -| Default (no other match) | Conservative | Safe fallback | - -### Failure Classification Table - -| Severity | Error Patterns | -|----------|---------------| -| Critical | SyntaxError, cannot find module, is not defined | -| High | Assertion mismatch (expected/received), toBe/toEqual failures | -| Medium | Timeout, async errors | -| Low | Warnings, deprecation notices | - -### Fix Approach by Error Type - -| Error Type | Pattern | Fix Approach | -|------------|---------|-------------| -| missing_import | "Cannot find module ''" | Add import statement, resolve relative path from modified files | -| undefined_variable | " is not defined" | Check source for renamed/moved exports, update reference | -| assertion_mismatch | "Expected: X, Received: Y" | Read test file at failure line, update expected value if behavior change is intentional | -| timeout | "Timeout" | Increase timeout or add async/await | -| syntax_error | "SyntaxError" | Read source at error line, fix syntax | - -### Tool Call Example - -Run tests with framework-appropriate command: - -```bash -Bash(command="vitest run src/utils/__tests__/parser.test.ts --reporter=verbose", timeout=120000) -``` - -Read test file to analyze failure: - -```bash -Read(file_path="") -``` - -Apply fix via Edit: - -```bash -Edit(file_path="", old_string="", new_string="") -``` - -## Phase 4: Validation - -### Success Criteria - -| Check | Criteria | Required | -|-------|----------|----------| -| Pass rate | >= 95% | Yes | -| Full suite run | At least one full suite pass | Yes | -| No critical failures | Zero critical-severity failures remaining | Yes | -| Best pass rate tracked | Reported in final result | Yes | - -### Result Routing - -| Outcome | Message Type | Content | -|---------|-------------|---------| -| Pass rate >= target | test_result | Success, iterations count, full suite confirmed | -| Max iterations, pass rate < target | fix_required | Best pass rate, remaining failures, iteration count | -| No tests found | error | Framework detected but no test files | -| Framework not detected | error | Detection methods exhausted | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Framework not detected | Report error to coordinator, list detection attempts | -| No test files found | Report to coordinator, suggest manual test path | -| Test command fails (exit code != 0/1) | Check stderr for environment issues, retry once | -| Fix application fails | Skip fix, try next iteration with different strategy | -| Infinite loop (same failures repeat) | Abort after 3 identical result sets | diff --git a/.claude/skills/team-lifecycle-v3/roles/tester/role.md b/.claude/skills/team-lifecycle-v3/roles/tester/role.md deleted file mode 100644 index afdfd887..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/tester/role.md +++ /dev/null @@ -1,108 +0,0 @@ -# Role: tester - -Adaptive test execution with fix cycles and quality gates. - -## Identity - -- **Name**: `tester` | **Prefix**: `TEST-*` | **Tag**: `[tester]` -- **Responsibility**: Detect Framework → Run Tests → Fix Cycle → Report - -## Boundaries - -### MUST -- Only process TEST-* tasks -- Detect test framework before running -- Run affected tests before full suite -- Use strategy engine for fix cycles - -### MUST NOT -- Create tasks -- Contact other workers directly -- Modify production code beyond test fixes -- Skip framework detection - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| test_result | → coordinator | Tests pass or final result | -| fix_required | → coordinator | Failures after max iterations | -| error | → coordinator | Framework not detected | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/validate.md | Test-fix cycle with strategy engine | - ---- - -## Phase 2: Framework Detection & Test Discovery - -**Framework detection** (priority order): - -| Priority | Method | Frameworks | -|----------|--------|-----------| -| 1 | package.json devDependencies | vitest, jest, mocha, pytest | -| 2 | package.json scripts.test | vitest, jest, mocha, pytest | -| 3 | Config files | vitest.config.*, jest.config.*, pytest.ini | - -**Affected test discovery** from executor's modified files: -- Search variants: `.test.ts`, `.spec.ts`, `tests/.test.ts`, `__tests__/.test.ts` - ---- - -## Phase 3: Test Execution & Fix Cycle - -**Config**: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true - -Delegate to `commands/validate.md`: -1. Run affected tests → parse results -2. Pass rate met → run full suite -3. Failures → select strategy → fix → re-run → repeat - -**Strategy selection**: - -| Condition | Strategy | Behavior | -|-----------|----------|----------| -| Iteration ≤ 3 or pass ≥ 80% | Conservative | Fix one critical failure at a time | -| Critical failures < 5 | Surgical | Fix specific pattern everywhere | -| Pass < 50% or iteration > 7 | Aggressive | Fix all failures in batch | - -**Test commands**: - -| Framework | Affected | Full Suite | -|-----------|---------|------------| -| vitest | `vitest run ` | `vitest run` | -| jest | `jest --no-coverage` | `jest --no-coverage` | -| pytest | `pytest -v` | `pytest -v` | - ---- - -## Phase 4: Result Analysis - -**Failure classification**: - -| Severity | Patterns | -|----------|----------| -| Critical | SyntaxError, cannot find module, undefined | -| High | Assertion failures, toBe/toEqual | -| Medium | Timeout, async errors | -| Low | Warnings, deprecations | - -**Report routing**: - -| Condition | Type | -|-----------|------| -| Pass rate ≥ target | test_result (success) | -| Pass rate < target after max iterations | fix_required | - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Framework not detected | Prompt user | -| No tests found | Report to coordinator | -| Infinite fix loop | Abort after MAX_ITERATIONS | diff --git a/.claude/skills/team-lifecycle-v3/roles/writer/commands/generate-doc.md b/.claude/skills/team-lifecycle-v3/roles/writer/commands/generate-doc.md deleted file mode 100644 index 9f7341a0..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/writer/commands/generate-doc.md +++ /dev/null @@ -1,187 +0,0 @@ -# Command: generate-doc - -## Purpose - -Multi-CLI document generation for 4 document types. Each uses parallel or staged CLI analysis, then synthesizes into templated documents. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Document standards | `../../specs/document-standards.md` | Yes | -| Template | From routing table below | Yes | -| Spec config | `/spec/spec-config.json` | Yes | -| Discovery context | `/spec/discovery-context.json` | Yes | -| Discussion feedback | `/discussions/` | If exists | -| Session folder | Task description `Session:` field | Yes | - -### Document Type Routing - -| Doc Type | Task | Template | Discussion Input | Output | -|----------|------|----------|-----------------|--------| -| product-brief | DRAFT-001 | templates/product-brief.md | discuss-001-scope.md | spec/product-brief.md | -| requirements | DRAFT-002 | templates/requirements-prd.md | discuss-002-brief.md | spec/requirements/_index.md | -| architecture | DRAFT-003 | templates/architecture-doc.md | discuss-003-requirements.md | spec/architecture/_index.md | -| epics | DRAFT-004 | templates/epics-template.md | discuss-004-architecture.md | spec/epics/_index.md | - -### Progressive Dependencies - -Each doc type requires all prior docs: discovery-context → product-brief → requirements/_index → architecture/_index. - -## Phase 3: Document Generation - -### Shared Context Block - -Built from spec-config and discovery-context for all CLI prompts: - -``` -SEED: -PROBLEM: -TARGET USERS: -DOMAIN: -CONSTRAINTS: -FOCUS AREAS: -CODEBASE CONTEXT: (if discovery-context exists) -``` - ---- - -### DRAFT-001: Product Brief - -**Strategy**: 3-way parallel CLI analysis, then synthesize. - -| Perspective | CLI Tool | Focus | -|-------------|----------|-------| -| Product | gemini | Vision, market fit, success metrics, scope | -| Technical | codex | Feasibility, constraints, integration complexity | -| User | claude | Personas, journey maps, pain points, UX | - -**CLI call template** (one per perspective, all `run_in_background: true`): - -```bash -Bash(command="ccw cli -p \"PURPOSE: analysis for specification.\n\nTASK: \nMODE: analysis\nEXPECTED: \nCONSTRAINTS: \" --tool --mode analysis", run_in_background=true) -``` - -**Synthesis flow** (after all 3 return): - -``` -3 CLI outputs received - ├─ Identify convergent themes (2+ perspectives agree) - ├─ Identify conflicts (e.g., product wants X, technical says infeasible) - ├─ Extract unique insights per perspective - ├─ Integrate discussion feedback (if exists) - └─ Fill template → Write to spec/product-brief.md -``` - -**Template sections**: Vision, Problem Statement, Target Users, Goals, Scope, Success Criteria, Assumptions. - ---- - -### DRAFT-002: Requirements/PRD - -**Strategy**: Single CLI expansion, then structure into individual requirement files. - -| Step | Tool | Action | -|------|------|--------| -| 1 | gemini | Generate functional (REQ-NNN) and non-functional (NFR-type-NNN) requirements | -| 2 | (local) | Integrate discussion feedback | -| 3 | (local) | Write individual files + _index.md | - -**CLI prompt focus**: For each product-brief goal, generate 3-7 functional requirements with user stories, acceptance criteria, and MoSCoW priority. Generate NFR categories: performance, security, scalability, usability. - -**Output structure**: - -``` -spec/requirements/ - ├─ _index.md (summary table + MoSCoW breakdown) - ├─ REQ-001-.md (individual functional requirement) - ├─ REQ-002-.md - ├─ NFR-perf-001-.md (non-functional) - └─ NFR-sec-001-.md -``` - -Each requirement file has: YAML frontmatter (id, title, priority, status, traces), description, user story, acceptance criteria. - ---- - -### DRAFT-003: Architecture - -**Strategy**: 2-stage CLI (design + critical review). - -| Stage | Tool | Purpose | -|-------|------|---------| -| 1 | gemini | Architecture design: style, components, tech stack, ADRs, data model, security | -| 2 | codex | Critical review: challenge ADRs, identify bottlenecks, rate quality 1-5 | - -Stage 2 runs after stage 1 completes (sequential dependency). - -**After both complete**: -1. Integrate discussion feedback -2. Map codebase integration points (from discovery-context.relevant_files) -3. Write individual ADR files + _index.md - -**Output structure**: - -``` -spec/architecture/ - ├─ _index.md (overview, component diagram, tech stack, data model, API, security) - ├─ ADR-001-.md (individual decision record) - └─ ADR-002-.md -``` - -Each ADR file has: YAML frontmatter (id, title, status, traces), context, decision, alternatives with pros/cons, consequences, review feedback. - ---- - -### DRAFT-004: Epics & Stories - -**Strategy**: Single CLI decomposition, then structure into individual epic files. - -| Step | Tool | Action | -|------|------|--------| -| 1 | gemini | Decompose requirements into 3-7 Epics with Stories, dependency map, MVP subset | -| 2 | (local) | Integrate discussion feedback | -| 3 | (local) | Write individual EPIC files + _index.md | - -**CLI prompt focus**: Group requirements by domain, generate EPIC-NNN with STORY-EPIC-NNN children, define MVP subset, create Mermaid dependency diagram, recommend execution order. - -**Output structure**: - -``` -spec/epics/ - ├─ _index.md (overview table, dependency map, execution order, MVP scope) - ├─ EPIC-001-.md (individual epic with stories) - └─ EPIC-002-.md -``` - -Each epic file has: YAML frontmatter (id, title, priority, mvp, size, requirements, architecture, dependencies), stories with user stories and acceptance criteria. - -All generated documents include YAML frontmatter: session_id, phase, document_type, status=draft, generated_at, version, dependencies. - -## Phase 4: Validation - -| Check | What to Verify | -|-------|---------------| -| has_frontmatter | Document starts with valid YAML frontmatter | -| sections_complete | All template sections present in output | -| cross_references | session_id matches spec-config | -| discussion_integrated | Feedback reflected (if feedback exists) | -| files_written | All expected files exist (individual + _index.md) | - -### Result Routing - -| Outcome | Message Type | Content | -|---------|-------------|---------| -| All checks pass | draft_ready | Doc type, output path, summary | -| Validation issues | draft_ready (with warnings) | Doc type, output path, issues list | -| Critical failure | error | Missing template, CLI failure | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Prior doc not found | Notify coordinator, request prerequisite task completion | -| Template not found | Error, report missing template path | -| CLI tool fails | Retry with fallback tool (gemini → codex → claude) | -| Discussion contradicts prior docs | Note conflict in document, flag for next discussion round | -| Partial CLI output | Use available data, note gaps in document | diff --git a/.claude/skills/team-lifecycle-v3/roles/writer/role.md b/.claude/skills/team-lifecycle-v3/roles/writer/role.md deleted file mode 100644 index ef5b157c..00000000 --- a/.claude/skills/team-lifecycle-v3/roles/writer/role.md +++ /dev/null @@ -1,96 +0,0 @@ -# Role: writer - -Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation. Maps to spec-generator Phases 2-5. - -## Identity - -- **Name**: `writer` | **Prefix**: `DRAFT-*` | **Tag**: `[writer]` -- **Responsibility**: Load Context → Generate Document → Incorporate Feedback → Report - -## Boundaries - -### MUST -- Only process DRAFT-* tasks -- Read templates before generating (from `../../templates/`) -- Follow document-standards.md (from `../../specs/`) -- Integrate discussion feedback when available -- Generate proper YAML frontmatter - -### MUST NOT -- Create tasks for other roles -- Skip template loading -- Modify discussion records - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| draft_ready | → coordinator | Document writing complete | -| draft_revision | → coordinator | Document revised per feedback | -| error | → coordinator | Template missing, insufficient context | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/generate-doc.md | Multi-CLI document generation | -| gemini, codex, claude CLI | Multi-perspective content generation | - ---- - -## Phase 2: Context & Discussion Loading - -**Objective**: Load all required inputs for document generation. - -**Document type routing**: - -| Task Subject Contains | Doc Type | Template | Discussion Input | -|----------------------|----------|----------|-----------------| -| Product Brief | product-brief | templates/product-brief.md | discuss-001-scope.md | -| Requirements / PRD | requirements | templates/requirements-prd.md | discuss-002-brief.md | -| Architecture | architecture | templates/architecture-doc.md | discuss-003-requirements.md | -| Epics | epics | templates/epics-template.md | discuss-004-architecture.md | - -**Progressive dependency loading**: - -| Doc Type | Requires | -|----------|----------| -| product-brief | discovery-context.json | -| requirements | + product-brief.md | -| architecture | + requirements/_index.md | -| epics | + architecture/_index.md | - -**Success**: Template loaded, discussion feedback loaded (if exists), prior docs loaded. - ---- - -## Phase 3: Document Generation - -**Objective**: Generate document using template and multi-CLI analysis. - -Delegate to `commands/generate-doc.md` with: doc type, session folder, spec config, discussion feedback, prior docs. - ---- - -## Phase 4: Self-Validation - -**Objective**: Verify document meets standards. - -| Check | What to Verify | -|-------|---------------| -| has_frontmatter | Starts with YAML frontmatter | -| sections_complete | All template sections present | -| cross_references | session_id included | -| discussion_integrated | Reflects feedback (if exists) | - -**Report**: doc type, validation status, summary, output path. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Prior doc not found | Notify coordinator, request prerequisite | -| CLI failure | Retry with fallback tool | -| Discussion contradicts prior docs | Note conflict, flag for next discussion | diff --git a/.claude/skills/team-lifecycle-v3/specs/document-standards.md b/.claude/skills/team-lifecycle-v3/specs/document-standards.md deleted file mode 100644 index 2820cd98..00000000 --- a/.claude/skills/team-lifecycle-v3/specs/document-standards.md +++ /dev/null @@ -1,192 +0,0 @@ -# Document Standards - -Defines format conventions, YAML frontmatter schema, naming rules, and content structure for all spec-generator outputs. - -## When to Use - -| Phase | Usage | Section | -|-------|-------|---------| -| All Phases | Frontmatter format | YAML Frontmatter Schema | -| All Phases | File naming | Naming Conventions | -| Phase 2-5 | Document structure | Content Structure | -| Phase 6 | Validation reference | All sections | - ---- - -## YAML Frontmatter Schema - -Every generated document MUST begin with YAML frontmatter: - -```yaml ---- -session_id: SPEC-{slug}-{YYYY-MM-DD} -phase: {1-6} -document_type: {product-brief|requirements|architecture|epics|readiness-report|spec-summary} -status: draft|review|complete -generated_at: {ISO8601 timestamp} -stepsCompleted: [] -version: 1 -dependencies: - - {list of input documents used} ---- -``` - -### Field Definitions - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `session_id` | string | Yes | Session identifier matching spec-config.json | -| `phase` | number | Yes | Phase number that generated this document (1-6) | -| `document_type` | string | Yes | One of: product-brief, requirements, architecture, epics, readiness-report, spec-summary | -| `status` | enum | Yes | draft (initial), review (user reviewed), complete (finalized) | -| `generated_at` | string | Yes | ISO8601 timestamp of generation | -| `stepsCompleted` | array | Yes | List of step IDs completed during generation | -| `version` | number | Yes | Document version, incremented on re-generation | -| `dependencies` | array | No | List of input files this document depends on | - -### Status Transitions - -``` -draft -> review -> complete - | ^ - +-------------------+ (direct promotion in auto mode) -``` - -- **draft**: Initial generation, not yet user-reviewed -- **review**: User has reviewed and provided feedback -- **complete**: Finalized, ready for downstream consumption - -In auto mode (`-y`), documents are promoted directly from `draft` to `complete`. - ---- - -## Naming Conventions - -### Session ID Format - -``` -SPEC-{slug}-{YYYY-MM-DD} -``` - -- **slug**: Lowercase, alphanumeric + Chinese characters, hyphens as separators, max 40 chars -- **date**: UTC+8 date in YYYY-MM-DD format - -Examples: -- `SPEC-task-management-system-2026-02-11` -- `SPEC-user-auth-oauth-2026-02-11` - -### Output Files - -| File | Phase | Description | -|------|-------|-------------| -| `spec-config.json` | 1 | Session configuration and state | -| `discovery-context.json` | 1 | Codebase exploration results (optional) | -| `product-brief.md` | 2 | Product brief document | -| `requirements.md` | 3 | PRD document | -| `architecture.md` | 4 | Architecture decisions document | -| `epics.md` | 5 | Epic/Story breakdown document | -| `readiness-report.md` | 6 | Quality validation report | -| `spec-summary.md` | 6 | One-page executive summary | - -### Output Directory - -``` -.workflow/.spec/{session-id}/ -``` - ---- - -## Content Structure - -### Heading Hierarchy - -- `#` (H1): Document title only (one per document) -- `##` (H2): Major sections -- `###` (H3): Subsections -- `####` (H4): Detail items (use sparingly) - -Maximum depth: 4 levels. Prefer flat structures. - -### Section Ordering - -Every document follows this general pattern: - -1. **YAML Frontmatter** (mandatory) -2. **Title** (H1) -3. **Executive Summary** (2-3 sentences) -4. **Core Content Sections** (H2, document-specific) -5. **Open Questions / Risks** (if applicable) -6. **References / Traceability** (links to upstream/downstream docs) - -### Formatting Rules - -| Element | Format | Example | -|---------|--------|---------| -| Requirements | `REQ-{NNN}` prefix | REQ-001: User login | -| Acceptance criteria | Checkbox list | `- [ ] User can log in with email` | -| Architecture decisions | `ADR-{NNN}` prefix | ADR-001: Use PostgreSQL | -| Epics | `EPIC-{NNN}` prefix | EPIC-001: Authentication | -| Stories | `STORY-{EPIC}-{NNN}` prefix | STORY-001-001: Login form | -| Priority tags | MoSCoW labels | `[Must]`, `[Should]`, `[Could]`, `[Won't]` | -| Mermaid diagrams | Fenced code blocks | ````mermaid ... ``` `` | -| Code examples | Language-tagged blocks | ````typescript ... ``` `` | - -### Cross-Reference Format - -Use relative references between documents: - -```markdown -See [Product Brief](product-brief.md#section-name) for details. -Derived from [REQ-001](requirements.md#req-001). -``` - -### Language - -- Document body: Follow user's input language (Chinese or English) -- Technical identifiers: Always English (REQ-001, ADR-001, EPIC-001) -- YAML frontmatter keys: Always English - ---- - -## spec-config.json Schema - -```json -{ - "session_id": "string (required)", - "seed_input": "string (required) - original user input", - "input_type": "text|file (required)", - "timestamp": "ISO8601 (required)", - "mode": "interactive|auto (required)", - "complexity": "simple|moderate|complex (required)", - "depth": "light|standard|comprehensive (required)", - "focus_areas": ["string array"], - "seed_analysis": { - "problem_statement": "string", - "target_users": ["string array"], - "domain": "string", - "constraints": ["string array"], - "dimensions": ["string array - 3-5 exploration dimensions"] - }, - "has_codebase": "boolean", - "phasesCompleted": [ - { - "phase": "number (1-6)", - "name": "string (phase name)", - "output_file": "string (primary output file)", - "completed_at": "ISO8601" - } - ] -} -``` - ---- - -## Validation Checklist - -- [ ] Every document starts with valid YAML frontmatter -- [ ] `session_id` matches across all documents in a session -- [ ] `status` field reflects current document state -- [ ] All cross-references resolve to valid targets -- [ ] Heading hierarchy is correct (no skipped levels) -- [ ] Technical identifiers use correct prefixes -- [ ] Output files are in the correct directory diff --git a/.claude/skills/team-lifecycle-v3/specs/quality-gates.md b/.claude/skills/team-lifecycle-v3/specs/quality-gates.md deleted file mode 100644 index ae968436..00000000 --- a/.claude/skills/team-lifecycle-v3/specs/quality-gates.md +++ /dev/null @@ -1,207 +0,0 @@ -# Quality Gates - -Per-phase quality gate criteria and scoring dimensions for spec-generator outputs. - -## When to Use - -| Phase | Usage | Section | -|-------|-------|---------| -| Phase 2-5 | Post-generation self-check | Per-Phase Gates | -| Phase 6 | Cross-document validation | Cross-Document Validation | -| Phase 6 | Final scoring | Scoring Dimensions | - ---- - -## Quality Thresholds - -| Gate | Score | Action | -|------|-------|--------| -| **Pass** | >= 80% | Continue to next phase | -| **Review** | 60-79% | Log warnings, continue with caveats | -| **Fail** | < 60% | Must address issues before continuing | - -In auto mode (`-y`), Review-level issues are logged but do not block progress. - ---- - -## Scoring Dimensions - -### 1. Completeness (25%) - -All required sections present with substantive content. - -| Score | Criteria | -|-------|----------| -| 100% | All template sections filled with detailed content | -| 75% | All sections present, some lack detail | -| 50% | Major sections present but minor sections missing | -| 25% | Multiple major sections missing or empty | -| 0% | Document is a skeleton only | - -### 2. Consistency (25%) - -Terminology, formatting, and references are uniform across documents. - -| Score | Criteria | -|-------|----------| -| 100% | All terms consistent, all references valid, formatting uniform | -| 75% | Minor terminology variations, all references valid | -| 50% | Some inconsistent terms, 1-2 broken references | -| 25% | Frequent inconsistencies, multiple broken references | -| 0% | Documents contradict each other | - -### 3. Traceability (25%) - -Requirements, architecture decisions, and stories trace back to goals. - -| Score | Criteria | -|-------|----------| -| 100% | Every story traces to a requirement, every requirement traces to a goal | -| 75% | Most items traceable, few orphans | -| 50% | Partial traceability, some disconnected items | -| 25% | Weak traceability, many orphan items | -| 0% | No traceability between documents | - -### 4. Depth (25%) - -Content provides sufficient detail for execution teams. - -| Score | Criteria | -|-------|----------| -| 100% | Acceptance criteria specific and testable, architecture decisions justified, stories estimable | -| 75% | Most items detailed enough, few vague areas | -| 50% | Mix of detailed and vague content | -| 25% | Mostly high-level, lacking actionable detail | -| 0% | Too abstract for execution | - ---- - -## Per-Phase Quality Gates - -### Phase 1: Discovery - -| Check | Criteria | Severity | -|-------|----------|----------| -| Session ID valid | Matches `SPEC-{slug}-{date}` format | Error | -| Problem statement exists | Non-empty, >= 20 characters | Error | -| Target users identified | >= 1 user group | Error | -| Dimensions generated | 3-5 exploration dimensions | Warning | -| Constraints listed | >= 0 (can be empty with justification) | Info | - -### Phase 2: Product Brief - -| Check | Criteria | Severity | -|-------|----------|----------| -| Vision statement | Clear, 1-3 sentences | Error | -| Problem statement | Specific and measurable | Error | -| Target users | >= 1 persona with needs described | Error | -| Goals defined | >= 2 measurable goals | Error | -| Success metrics | >= 2 quantifiable metrics | Warning | -| Scope boundaries | In-scope and out-of-scope listed | Warning | -| Multi-perspective | >= 2 CLI perspectives synthesized | Info | - -### Phase 3: Requirements (PRD) - -| Check | Criteria | Severity | -|-------|----------|----------| -| Functional requirements | >= 3 with REQ-NNN IDs | Error | -| Acceptance criteria | Every requirement has >= 1 criterion | Error | -| MoSCoW priority | Every requirement tagged | Error | -| Non-functional requirements | >= 1 (performance, security, etc.) | Warning | -| User stories | >= 1 per Must-have requirement | Warning | -| Traceability | Requirements trace to product brief goals | Warning | - -### Phase 4: Architecture - -| Check | Criteria | Severity | -|-------|----------|----------| -| Component diagram | Present (Mermaid or ASCII) | Error | -| Tech stack specified | Languages, frameworks, key libraries | Error | -| ADR present | >= 1 Architecture Decision Record | Error | -| ADR has alternatives | Each ADR lists >= 2 options considered | Warning | -| Integration points | External systems/APIs identified | Warning | -| Data model | Key entities and relationships described | Warning | -| Codebase mapping | Mapped to existing code (if has_codebase) | Info | - -### Phase 5: Epics & Stories - -| Check | Criteria | Severity | -|-------|----------|----------| -| Epics defined | 3-7 epics with EPIC-NNN IDs | Error | -| MVP subset | >= 1 epic tagged as MVP | Error | -| Stories per epic | 2-5 stories per epic | Error | -| Story format | "As a...I want...So that..." pattern | Warning | -| Dependency map | Cross-epic dependencies documented | Warning | -| Estimation hints | Relative sizing (S/M/L/XL) per story | Info | -| Traceability | Stories trace to requirements | Warning | - -### Phase 6: Readiness Check - -| Check | Criteria | Severity | -|-------|----------|----------| -| All documents exist | product-brief, requirements, architecture, epics | Error | -| Frontmatter valid | All YAML frontmatter parseable and correct | Error | -| Cross-references valid | All document links resolve | Error | -| Overall score >= 60% | Weighted average across 4 dimensions | Error | -| No unresolved Errors | All Error-severity issues addressed | Error | -| Summary generated | spec-summary.md created | Warning | - ---- - -## Cross-Document Validation - -Checks performed during Phase 6 across all documents: - -### Completeness Matrix - -``` -Product Brief goals -> Requirements (each goal has >= 1 requirement) -Requirements -> Architecture (each Must requirement has design coverage) -Requirements -> Epics (each Must requirement appears in >= 1 story) -Architecture ADRs -> Epics (tech choices reflected in implementation stories) -``` - -### Consistency Checks - -| Check | Documents | Rule | -|-------|-----------|------| -| Terminology | All | Same term used consistently (no synonyms for same concept) | -| User personas | Brief + PRD + Epics | Same user names/roles throughout | -| Scope | Brief + PRD | PRD scope does not exceed brief scope | -| Tech stack | Architecture + Epics | Stories reference correct technologies | - -### Traceability Matrix Format - -```markdown -| Goal | Requirements | Architecture | Epics | -|------|-------------|--------------|-------| -| G-001: ... | REQ-001, REQ-002 | ADR-001 | EPIC-001 | -| G-002: ... | REQ-003 | ADR-002 | EPIC-002, EPIC-003 | -``` - ---- - -## Issue Classification - -### Error (Must Fix) - -- Missing required document or section -- Broken cross-references -- Contradictory information between documents -- Empty acceptance criteria on Must-have requirements -- No MVP subset defined in epics - -### Warning (Should Fix) - -- Vague acceptance criteria -- Missing non-functional requirements -- No success metrics defined -- Incomplete traceability -- Missing architecture review notes - -### Info (Nice to Have) - -- Could add more detailed personas -- Consider additional ADR alternatives -- Story estimation hints missing -- Mermaid diagrams could be more detailed diff --git a/.claude/skills/team-lifecycle-v3/specs/team-config.json b/.claude/skills/team-lifecycle-v3/specs/team-config.json deleted file mode 100644 index f0f6f941..00000000 --- a/.claude/skills/team-lifecycle-v3/specs/team-config.json +++ /dev/null @@ -1,158 +0,0 @@ -{ - "team_name": "team-lifecycle", - "team_display_name": "Team Lifecycle", - "description": "Unified team skill covering spec-to-dev-to-test full lifecycle", - "version": "2.0.0", - "architecture": "folder-based", - "role_structure": "roles/{name}/role.md + roles/{name}/commands/*.md", - - "roles": { - "coordinator": { - "task_prefix": null, - "responsibility": "Pipeline orchestration, requirement clarification, task chain creation, message dispatch", - "message_types": ["plan_approved", "plan_revision", "task_unblocked", "fix_required", "error", "shutdown"] - }, - "analyst": { - "task_prefix": "RESEARCH", - "responsibility": "Seed analysis, codebase exploration, multi-dimensional context gathering", - "message_types": ["research_ready", "research_progress", "error"] - }, - "writer": { - "task_prefix": "DRAFT", - "responsibility": "Product Brief / PRD / Architecture / Epics document generation", - "message_types": ["draft_ready", "draft_revision", "impl_progress", "error"] - }, - "discussant": { - "task_prefix": "DISCUSS", - "responsibility": "Multi-perspective critique, consensus building, conflict escalation", - "message_types": ["discussion_ready", "discussion_blocked", "impl_progress", "error"] - }, - "planner": { - "task_prefix": "PLAN", - "responsibility": "Multi-angle code exploration, structured implementation planning", - "message_types": ["plan_ready", "plan_revision", "impl_progress", "error"] - }, - "executor": { - "task_prefix": "IMPL", - "responsibility": "Code implementation following approved plans", - "message_types": ["impl_complete", "impl_progress", "error"] - }, - "tester": { - "task_prefix": "TEST", - "responsibility": "Adaptive test-fix cycles, progressive testing, quality gates", - "message_types": ["test_result", "impl_progress", "fix_required", "error"] - }, - "reviewer": { - "task_prefix": "REVIEW", - "additional_prefixes": ["QUALITY"], - "responsibility": "Code review (REVIEW-*) + Spec quality validation (QUALITY-*)", - "message_types": ["review_result", "quality_result", "fix_required", "error"] - }, - "explorer": { - "task_prefix": "EXPLORE", - "responsibility": "Code search, pattern discovery, dependency tracing. Service role — on-demand by coordinator", - "role_type": "service", - "message_types": ["explore_ready", "explore_progress", "task_failed"] - }, - "architect": { - "task_prefix": "ARCH", - "responsibility": "Architecture assessment, tech feasibility, design pattern review. Consulting role — on-demand by coordinator", - "role_type": "consulting", - "consultation_modes": ["spec-review", "plan-review", "code-review", "consult", "feasibility"], - "message_types": ["arch_ready", "arch_concern", "arch_progress", "error"] - }, - "fe-developer": { - "task_prefix": "DEV-FE", - "responsibility": "Frontend component/page implementation, design token consumption, responsive UI", - "role_type": "frontend-pipeline", - "message_types": ["dev_fe_complete", "dev_fe_progress", "error"] - }, - "fe-qa": { - "task_prefix": "QA-FE", - "responsibility": "5-dimension frontend review (quality, a11y, design compliance, UX, pre-delivery), GC loop", - "role_type": "frontend-pipeline", - "message_types": ["qa_fe_passed", "qa_fe_result", "fix_required", "error"] - } - }, - - "pipelines": { - "spec-only": { - "description": "Specification pipeline: research → discuss → draft → quality", - "task_chain": [ - "RESEARCH-001", - "DISCUSS-001", "DRAFT-001", "DISCUSS-002", - "DRAFT-002", "DISCUSS-003", "DRAFT-003", "DISCUSS-004", - "DRAFT-004", "DISCUSS-005", "QUALITY-001", "DISCUSS-006" - ] - }, - "impl-only": { - "description": "Implementation pipeline: plan → implement → test + review", - "task_chain": ["PLAN-001", "IMPL-001", "TEST-001", "REVIEW-001"] - }, - "full-lifecycle": { - "description": "Full lifecycle: spec pipeline → implementation pipeline", - "task_chain": "spec-only + impl-only (PLAN-001 blockedBy DISCUSS-006)" - }, - "fe-only": { - "description": "Frontend-only pipeline: plan → frontend dev → frontend QA", - "task_chain": ["PLAN-001", "DEV-FE-001", "QA-FE-001"], - "gc_loop": { "max_rounds": 2, "convergence": "score >= 8 && critical === 0" } - }, - "fullstack": { - "description": "Fullstack pipeline: plan → backend + frontend parallel → test + QA", - "task_chain": ["PLAN-001", "IMPL-001||DEV-FE-001", "TEST-001||QA-FE-001", "REVIEW-001"], - "sync_points": ["REVIEW-001"] - }, - "full-lifecycle-fe": { - "description": "Full lifecycle with frontend: spec → plan → backend + frontend → test + QA", - "task_chain": "spec-only + fullstack (PLAN-001 blockedBy DISCUSS-006)" - } - }, - - "frontend_detection": { - "keywords": ["component", "page", "UI", "前端", "frontend", "CSS", "HTML", "React", "Vue", "Tailwind", "组件", "页面", "样式", "layout", "responsive", "Svelte", "Next.js", "Nuxt", "shadcn", "设计系统", "design system"], - "file_patterns": ["*.tsx", "*.jsx", "*.vue", "*.svelte", "*.css", "*.scss", "*.html"], - "routing_rules": { - "frontend_only": "All tasks match frontend keywords, no backend/API mentions", - "fullstack": "Mix of frontend and backend tasks", - "backend_only": "No frontend keywords detected (default impl-only)" - } - }, - - "ui_ux_pro_max": { - "skill_name": "ui-ux-pro-max", - "install_command": "/plugin install ui-ux-pro-max@ui-ux-pro-max-skill", - "invocation": "Skill(skill=\"ui-ux-pro-max\", args=\"...\")", - "domains": ["product", "style", "typography", "color", "landing", "chart", "ux", "web"], - "stacks": ["html-tailwind", "react", "nextjs", "vue", "svelte", "shadcn", "swiftui", "react-native", "flutter"], - "fallback": "llm-general-knowledge", - "design_intelligence_chain": ["analyst → design-intelligence.json", "architect → design-tokens.json", "fe-developer → tokens.css", "fe-qa → anti-pattern audit"] - }, - - "shared_memory": { - "file": "shared-memory.json", - "schema": { - "design_intelligence": "From analyst via ui-ux-pro-max", - "design_token_registry": "From architect, consumed by fe-developer/fe-qa", - "component_inventory": "From fe-developer, list of implemented components", - "style_decisions": "Accumulated design decisions", - "qa_history": "From fe-qa, audit trail", - "industry_context": "Industry + strictness config" - } - }, - - "collaboration_patterns": ["CP-1", "CP-2", "CP-4", "CP-5", "CP-6", "CP-10"], - - "session_dirs": { - "base": ".workflow/.team/TLS-{slug}-{YYYY-MM-DD}/", - "spec": "spec/", - "discussions": "discussions/", - "plan": "plan/", - "explorations": "explorations/", - "architecture": "architecture/", - "analysis": "analysis/", - "qa": "qa/", - "wisdom": "wisdom/", - "messages": ".msg/" - } -} diff --git a/.claude/skills/team-lifecycle-v3/templates/architecture-doc.md b/.claude/skills/team-lifecycle-v3/templates/architecture-doc.md deleted file mode 100644 index 5106de03..00000000 --- a/.claude/skills/team-lifecycle-v3/templates/architecture-doc.md +++ /dev/null @@ -1,254 +0,0 @@ -# Architecture Document Template (Directory Structure) - -Template for generating architecture decision documents as a directory of individual ADR files in Phase 4. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 4 (Architecture) | Generate `architecture/` directory from requirements analysis | -| Output Location | `{workDir}/architecture/` | - -## Output Structure - -``` -{workDir}/architecture/ -├── _index.md # Overview, components, tech stack, data model, security -├── ADR-001-{slug}.md # Individual Architecture Decision Record -├── ADR-002-{slug}.md -└── ... -``` - ---- - -## Template: _index.md - -```markdown ---- -session_id: {session_id} -phase: 4 -document_type: architecture-index -status: draft -generated_at: {timestamp} -version: 1 -dependencies: - - ../spec-config.json - - ../product-brief.md - - ../requirements/_index.md ---- - -# Architecture: {product_name} - -{executive_summary - high-level architecture approach and key decisions} - -## System Overview - -### Architecture Style -{description of chosen architecture style: microservices, monolith, serverless, etc.} - -### System Context Diagram - -```mermaid -C4Context - title System Context Diagram - Person(user, "User", "Primary user") - System(system, "{product_name}", "Core system") - System_Ext(ext1, "{external_system}", "{description}") - Rel(user, system, "Uses") - Rel(system, ext1, "Integrates with") -``` - -## Component Architecture - -### Component Diagram - -```mermaid -graph TD - subgraph "{product_name}" - A[Component A] --> B[Component B] - B --> C[Component C] - A --> D[Component D] - end - B --> E[External Service] -``` - -### Component Descriptions - -| Component | Responsibility | Technology | Dependencies | -|-----------|---------------|------------|--------------| -| {component_name} | {what it does} | {tech stack} | {depends on} | - -## Technology Stack - -### Core Technologies - -| Layer | Technology | Version | Rationale | -|-------|-----------|---------|-----------| -| Frontend | {technology} | {version} | {why chosen} | -| Backend | {technology} | {version} | {why chosen} | -| Database | {technology} | {version} | {why chosen} | -| Infrastructure | {technology} | {version} | {why chosen} | - -### Key Libraries & Frameworks - -| Library | Purpose | License | -|---------|---------|---------| -| {library_name} | {purpose} | {license} | - -## Architecture Decision Records - -| ADR | Title | Status | Key Choice | -|-----|-------|--------|------------| -| [ADR-001](ADR-001-{slug}.md) | {title} | Accepted | {one-line summary} | -| [ADR-002](ADR-002-{slug}.md) | {title} | Accepted | {one-line summary} | -| [ADR-003](ADR-003-{slug}.md) | {title} | Proposed | {one-line summary} | - -## Data Architecture - -### Data Model - -```mermaid -erDiagram - ENTITY_A ||--o{ ENTITY_B : "has many" - ENTITY_A { - string id PK - string name - datetime created_at - } - ENTITY_B { - string id PK - string entity_a_id FK - string value - } -``` - -### Data Storage Strategy - -| Data Type | Storage | Retention | Backup | -|-----------|---------|-----------|--------| -| {type} | {storage solution} | {retention policy} | {backup strategy} | - -## API Design - -### API Overview - -| Endpoint | Method | Purpose | Auth | -|----------|--------|---------|------| -| {/api/resource} | {GET/POST/etc} | {purpose} | {auth type} | - -## Security Architecture - -### Security Controls - -| Control | Implementation | Requirement | -|---------|---------------|-------------| -| Authentication | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | -| Authorization | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | -| Data Protection | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | - -## Infrastructure & Deployment - -### Deployment Architecture - -{description of deployment model: containers, serverless, VMs, etc.} - -### Environment Strategy - -| Environment | Purpose | Configuration | -|-------------|---------|---------------| -| Development | Local development | {config} | -| Staging | Pre-production testing | {config} | -| Production | Live system | {config} | - -## Codebase Integration - -{if has_codebase is true:} - -### Existing Code Mapping - -| New Component | Existing Module | Integration Type | Notes | -|--------------|----------------|------------------|-------| -| {component} | {existing module path} | Extend/Replace/New | {notes} | - -### Migration Notes -{any migration considerations for existing code} - -## Quality Attributes - -| Attribute | Target | Measurement | ADR Reference | -|-----------|--------|-------------|---------------| -| Performance | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | -| Scalability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | -| Reliability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | - -## Risks & Mitigations - -| Risk | Impact | Probability | Mitigation | -|------|--------|-------------|------------| -| {risk} | High/Medium/Low | High/Medium/Low | {mitigation approach} | - -## Open Questions - -- [ ] {architectural question 1} -- [ ] {architectural question 2} - -## References - -- Derived from: [Requirements](../requirements/_index.md), [Product Brief](../product-brief.md) -- Next: [Epics & Stories](../epics/_index.md) -``` - ---- - -## Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record) - -```markdown ---- -id: ADR-{NNN} -status: Accepted -traces_to: [{REQ-NNN}, {NFR-X-NNN}] -date: {timestamp} ---- - -# ADR-{NNN}: {decision_title} - -## Context - -{what is the situation that motivates this decision} - -## Decision - -{what is the chosen approach} - -## Alternatives Considered - -| Option | Pros | Cons | -|--------|------|------| -| {option_1 - chosen} | {pros} | {cons} | -| {option_2} | {pros} | {cons} | -| {option_3} | {pros} | {cons} | - -## Consequences - -- **Positive**: {positive outcomes} -- **Negative**: {tradeoffs accepted} -- **Risks**: {risks to monitor} - -## Traces - -- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md) -- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5) -``` - ---- - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | product-brief.md | Product/feature name | -| `{NNN}` | Auto-increment | ADR/requirement number | -| `{slug}` | Auto-generated | Kebab-case from decision title | -| `{has_codebase}` | spec-config.json | Whether existing codebase exists | diff --git a/.claude/skills/team-lifecycle-v3/templates/epics-template.md b/.claude/skills/team-lifecycle-v3/templates/epics-template.md deleted file mode 100644 index 939d933c..00000000 --- a/.claude/skills/team-lifecycle-v3/templates/epics-template.md +++ /dev/null @@ -1,196 +0,0 @@ -# Epics & Stories Template (Directory Structure) - -Template for generating epic/story breakdown as a directory of individual Epic files in Phase 5. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 5 (Epics & Stories) | Generate `epics/` directory from requirements decomposition | -| Output Location | `{workDir}/epics/` | - -## Output Structure - -``` -{workDir}/epics/ -├── _index.md # Overview table + dependency map + MVP scope + execution order -├── EPIC-001-{slug}.md # Individual Epic with its Stories -├── EPIC-002-{slug}.md -└── ... -``` - ---- - -## Template: _index.md - -```markdown ---- -session_id: {session_id} -phase: 5 -document_type: epics-index -status: draft -generated_at: {timestamp} -version: 1 -dependencies: - - ../spec-config.json - - ../product-brief.md - - ../requirements/_index.md - - ../architecture/_index.md ---- - -# Epics & Stories: {product_name} - -{executive_summary - overview of epic structure and MVP scope} - -## Epic Overview - -| Epic ID | Title | Priority | MVP | Stories | Est. Size | -|---------|-------|----------|-----|---------|-----------| -| [EPIC-001](EPIC-001-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} | -| [EPIC-002](EPIC-002-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} | -| [EPIC-003](EPIC-003-{slug}.md) | {title} | Should | No | {n} | {S/M/L/XL} | - -## Dependency Map - -```mermaid -graph LR - EPIC-001 --> EPIC-002 - EPIC-001 --> EPIC-003 - EPIC-002 --> EPIC-004 - EPIC-003 --> EPIC-005 -``` - -### Dependency Notes -{explanation of why these dependencies exist and suggested execution order} - -### Recommended Execution Order -1. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - foundational} -2. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - depends on #1} -3. ... - -## MVP Scope - -### MVP Epics -{list of epics included in MVP with justification, linking to each} - -### MVP Definition of Done -- [ ] {MVP completion criterion 1} -- [ ] {MVP completion criterion 2} -- [ ] {MVP completion criterion 3} - -## Traceability Matrix - -| Requirement | Epic | Stories | Architecture | -|-------------|------|---------|--------------| -| [REQ-001](../requirements/REQ-001-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-001, STORY-001-002 | [ADR-001](../architecture/ADR-001-{slug}.md) | -| [REQ-002](../requirements/REQ-002-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-003 | Component B | -| [REQ-003](../requirements/REQ-003-{slug}.md) | [EPIC-002](EPIC-002-{slug}.md) | STORY-002-001 | [ADR-002](../architecture/ADR-002-{slug}.md) | - -## Estimation Summary - -| Size | Meaning | Count | -|------|---------|-------| -| S | Small - well-understood, minimal risk | {n} | -| M | Medium - some complexity, moderate risk | {n} | -| L | Large - significant complexity, should consider splitting | {n} | -| XL | Extra Large - high complexity, must split before implementation | {n} | - -## Risks & Considerations - -| Risk | Affected Epics | Mitigation | -|------|---------------|------------| -| {risk description} | [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) | {mitigation} | - -## Open Questions - -- [ ] {question about scope or implementation 1} -- [ ] {question about scope or implementation 2} - -## References - -- Derived from: [Requirements](../requirements/_index.md), [Architecture](../architecture/_index.md) -- Handoff to: execution workflows (lite-plan, plan, req-plan) -``` - ---- - -## Template: EPIC-NNN-{slug}.md (Individual Epic) - -```markdown ---- -id: EPIC-{NNN} -priority: {Must|Should|Could} -mvp: {true|false} -size: {S|M|L|XL} -requirements: [REQ-{NNN}] -architecture: [ADR-{NNN}] -dependencies: [EPIC-{NNN}] -status: draft ---- - -# EPIC-{NNN}: {epic_title} - -**Priority**: {Must|Should|Could} -**MVP**: {Yes|No} -**Estimated Size**: {S|M|L|XL} - -## Description - -{detailed epic description} - -## Requirements - -- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title} -- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title} - -## Architecture - -- [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md): {title} -- Component: {component_name} - -## Dependencies - -- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (blocking): {reason} -- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (soft): {reason} - -## Stories - -### STORY-{EPIC}-001: {story_title} - -**User Story**: As a {persona}, I want to {action} so that {benefit}. - -**Acceptance Criteria**: -- [ ] {criterion 1} -- [ ] {criterion 2} -- [ ] {criterion 3} - -**Size**: {S|M|L|XL} -**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md) - ---- - -### STORY-{EPIC}-002: {story_title} - -**User Story**: As a {persona}, I want to {action} so that {benefit}. - -**Acceptance Criteria**: -- [ ] {criterion 1} -- [ ] {criterion 2} - -**Size**: {S|M|L|XL} -**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md) -``` - ---- - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | product-brief.md | Product/feature name | -| `{EPIC}` | Auto-increment | Epic number (3 digits) | -| `{NNN}` | Auto-increment | Story/requirement number | -| `{slug}` | Auto-generated | Kebab-case from epic/story title | -| `{S\|M\|L\|XL}` | CLI analysis | Relative size estimate | diff --git a/.claude/skills/team-lifecycle-v3/templates/product-brief.md b/.claude/skills/team-lifecycle-v3/templates/product-brief.md deleted file mode 100644 index ffbdf437..00000000 --- a/.claude/skills/team-lifecycle-v3/templates/product-brief.md +++ /dev/null @@ -1,133 +0,0 @@ -# Product Brief Template - -Template for generating product brief documents in Phase 2. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 2 (Product Brief) | Generate product-brief.md from multi-CLI analysis | -| Output Location | `{workDir}/product-brief.md` | - ---- - -## Template - -```markdown ---- -session_id: {session_id} -phase: 2 -document_type: product-brief -status: draft -generated_at: {timestamp} -stepsCompleted: [] -version: 1 -dependencies: - - spec-config.json ---- - -# Product Brief: {product_name} - -{executive_summary - 2-3 sentences capturing the essence of the product/feature} - -## Vision - -{vision_statement - clear, aspirational 1-3 sentence statement of what success looks like} - -## Problem Statement - -### Current Situation -{description of the current state and pain points} - -### Impact -{quantified impact of the problem - who is affected, how much, how often} - -## Target Users - -{for each user persona:} - -### {Persona Name} -- **Role**: {user's role/context} -- **Needs**: {primary needs related to this product} -- **Pain Points**: {current frustrations} -- **Success Criteria**: {what success looks like for this user} - -## Goals & Success Metrics - -| Goal ID | Goal | Success Metric | Target | -|---------|------|----------------|--------| -| G-001 | {goal description} | {measurable metric} | {specific target} | -| G-002 | {goal description} | {measurable metric} | {specific target} | - -## Scope - -### In Scope -- {feature/capability 1} -- {feature/capability 2} -- {feature/capability 3} - -### Out of Scope -- {explicitly excluded item 1} -- {explicitly excluded item 2} - -### Assumptions -- {key assumption 1} -- {key assumption 2} - -## Competitive Landscape - -| Aspect | Current State | Proposed Solution | Advantage | -|--------|--------------|-------------------|-----------| -| {aspect} | {how it's done now} | {our approach} | {differentiator} | - -## Constraints & Dependencies - -### Technical Constraints -- {constraint 1} -- {constraint 2} - -### Business Constraints -- {constraint 1} - -### Dependencies -- {external dependency 1} -- {external dependency 2} - -## Multi-Perspective Synthesis - -### Product Perspective -{summary of product/market analysis findings} - -### Technical Perspective -{summary of technical feasibility and constraints} - -### User Perspective -{summary of user journey and UX considerations} - -### Convergent Themes -{themes where all perspectives agree} - -### Conflicting Views -{areas where perspectives differ, with notes on resolution approach} - -## Open Questions - -- [ ] {unresolved question 1} -- [ ] {unresolved question 2} - -## References - -- Derived from: [spec-config.json](spec-config.json) -- Next: [Requirements PRD](requirements.md) -``` - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | Seed analysis | Product/feature name | -| `{executive_summary}` | CLI synthesis | 2-3 sentence summary | -| `{vision_statement}` | CLI product perspective | Aspirational vision | -| All `{...}` fields | CLI analysis outputs | Filled from multi-perspective analysis | diff --git a/.claude/skills/team-lifecycle-v3/templates/requirements-prd.md b/.claude/skills/team-lifecycle-v3/templates/requirements-prd.md deleted file mode 100644 index 0b1dbf28..00000000 --- a/.claude/skills/team-lifecycle-v3/templates/requirements-prd.md +++ /dev/null @@ -1,224 +0,0 @@ -# Requirements PRD Template (Directory Structure) - -Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion | -| Output Location | `{workDir}/requirements/` | - -## Output Structure - -``` -{workDir}/requirements/ -├── _index.md # Summary + MoSCoW table + traceability matrix + links -├── REQ-001-{slug}.md # Individual functional requirement -├── REQ-002-{slug}.md -├── NFR-P-001-{slug}.md # Non-functional: Performance -├── NFR-S-001-{slug}.md # Non-functional: Security -├── NFR-SC-001-{slug}.md # Non-functional: Scalability -├── NFR-U-001-{slug}.md # Non-functional: Usability -└── ... -``` - ---- - -## Template: _index.md - -```markdown ---- -session_id: {session_id} -phase: 3 -document_type: requirements-index -status: draft -generated_at: {timestamp} -version: 1 -dependencies: - - ../spec-config.json - - ../product-brief.md ---- - -# Requirements: {product_name} - -{executive_summary - brief overview of what this PRD covers and key decisions} - -## Requirement Summary - -| Priority | Count | Coverage | -|----------|-------|----------| -| Must Have | {n} | {description of must-have scope} | -| Should Have | {n} | {description of should-have scope} | -| Could Have | {n} | {description of could-have scope} | -| Won't Have | {n} | {description of explicitly excluded} | - -## Functional Requirements - -| ID | Title | Priority | Traces To | -|----|-------|----------|-----------| -| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) | -| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) | -| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) | - -## Non-Functional Requirements - -### Performance - -| ID | Title | Target | -|----|-------|--------| -| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} | - -### Security - -| ID | Title | Standard | -|----|-------|----------| -| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} | - -### Scalability - -| ID | Title | Target | -|----|-------|--------| -| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} | - -### Usability - -| ID | Title | Target | -|----|-------|--------| -| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} | - -## Data Requirements - -### Data Entities - -| Entity | Description | Key Attributes | -|--------|-------------|----------------| -| {entity_name} | {description} | {attr1, attr2, attr3} | - -### Data Flows - -{description of key data flows, optionally with Mermaid diagram} - -## Integration Requirements - -| System | Direction | Protocol | Data Format | Notes | -|--------|-----------|----------|-------------|-------| -| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} | - -## Constraints & Assumptions - -### Constraints -- {technical or business constraint 1} -- {technical or business constraint 2} - -### Assumptions -- {assumption 1 - must be validated} -- {assumption 2 - must be validated} - -## Priority Rationale - -{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries} - -## Traceability Matrix - -| Goal | Requirements | -|------|-------------| -| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) | -| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) | - -## Open Questions - -- [ ] {unresolved question 1} -- [ ] {unresolved question 2} - -## References - -- Derived from: [Product Brief](../product-brief.md) -- Next: [Architecture](../architecture/_index.md) -``` - ---- - -## Template: REQ-NNN-{slug}.md (Individual Functional Requirement) - -```markdown ---- -id: REQ-{NNN} -type: functional -priority: {Must|Should|Could|Won't} -traces_to: [G-{NNN}] -status: draft ---- - -# REQ-{NNN}: {requirement_title} - -**Priority**: {Must|Should|Could|Won't} - -## Description - -{detailed requirement description} - -## User Story - -As a {persona}, I want to {action} so that {benefit}. - -## Acceptance Criteria - -- [ ] {specific, testable criterion 1} -- [ ] {specific, testable criterion 2} -- [ ] {specific, testable criterion 3} - -## Traces - -- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics) -- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable) -- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5) -``` - ---- - -## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement) - -```markdown ---- -id: NFR-{type}-{NNN} -type: non-functional -category: {Performance|Security|Scalability|Usability} -priority: {Must|Should|Could} -status: draft ---- - -# NFR-{type}-{NNN}: {requirement_title} - -**Category**: {Performance|Security|Scalability|Usability} -**Priority**: {Must|Should|Could} - -## Requirement - -{detailed requirement description} - -## Metric & Target - -| Metric | Target | Measurement Method | -|--------|--------|--------------------| -| {metric} | {target value} | {how measured} | - -## Traces - -- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics) -- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable) -``` - ---- - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | product-brief.md | Product/feature name | -| `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) | -| `{slug}` | Auto-generated | Kebab-case from requirement title | -| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) | -| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag | diff --git a/.claude/skills/team-lifecycle-v4/SKILL.md b/.claude/skills/team-lifecycle-v4/SKILL.md deleted file mode 100644 index d07fbcb7..00000000 --- a/.claude/skills/team-lifecycle-v4/SKILL.md +++ /dev/null @@ -1,643 +0,0 @@ ---- -name: team-lifecycle-v4 -description: Unified team skill for full lifecycle - spec/impl/test. Optimized cadence with inline discuss subagent and shared explore. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team lifecycle". -allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) ---- - -# Team Lifecycle v4 - -Unified team skill: specification -> implementation -> testing -> review. Optimized from v3 with **inline discuss subagent** and **shared explore utility**, halving spec pipeline beats from 12 to 6. - -## Architecture - -``` -+---------------------------------------------------+ -| Skill(skill="team-lifecycle-v4") | -| args="task description" or args="--role=xxx" | -+-------------------+-------------------------------+ - | Role Router - +---- --role present? ----+ - | NO | YES - v v - Orchestration Mode Role Dispatch - (auto -> coordinator) (route to role.md) - | - +----+----+-------+-------+-------+-------+ - v v v v v v - coordinator analyst writer planner executor tester - ^ ^ - on-demand by coordinator - +---------+ +--------+ - |architect| |reviewer| - +---------+ +--------+ - +-------------+ +-----+ - |fe-developer | |fe-qa| - +-------------+ +-----+ - - Subagents (callable by any role, not team members): - [discuss-subagent] - multi-perspective critique - [explore-subagent] - codebase exploration with cache -``` - -## Role Router - -### Input Parsing - -Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (auto route to coordinator). - -### Role Registry - -| Role | File | Task Prefix | Type | Compact | -|------|------|-------------|------|---------| -| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | compact must re-read | -| analyst | [roles/analyst/role.md](roles/analyst/role.md) | RESEARCH-* | pipeline | compact must re-read | -| writer | [roles/writer/role.md](roles/writer/role.md) | DRAFT-* | pipeline | compact must re-read | -| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | pipeline | compact must re-read | -| executor | [roles/executor/role.md](roles/executor/role.md) | IMPL-* | pipeline | compact must re-read | -| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | pipeline | compact must re-read | -| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-* + QUALITY-* | pipeline | compact must re-read | -| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | consulting (on-demand) | compact must re-read | -| fe-developer | [roles/fe-developer/role.md](roles/fe-developer/role.md) | DEV-FE-* | frontend pipeline | compact must re-read | -| fe-qa | [roles/fe-qa/role.md](roles/fe-qa/role.md) | QA-FE-* | frontend pipeline | compact must re-read | - -> **COMPACT PROTECTION**: Role files are execution documents. After context compression, role instructions become summaries only -- **MUST immediately `Read` the role.md to reload before continuing**. Never execute any Phase based on summaries. - -### Subagent Registry - -| Subagent | Spec | Callable By | Purpose | -|----------|------|-------------|---------| -| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | analyst, writer, reviewer | Multi-perspective critique | -| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | analyst, planner, any role | Codebase exploration with cache | -| doc-generation | [subagents/doc-generation-subagent.md](subagents/doc-generation-subagent.md) | writer | Document generation (CLI execution) | - -### Dispatch - -1. Extract `--role` from arguments -2. If no `--role` -> route to coordinator (Orchestration Mode) -3. Look up role in registry -> Read the role file -> Execute its phases - -### Orchestration Mode - -When invoked without `--role`, coordinator auto-starts. User just provides task description. - -**Invocation**: `Skill(skill="team-lifecycle-v4", args="task description")` - -**Lifecycle**: -``` -User provides task description - -> coordinator Phase 1-3: requirement clarification -> TeamCreate -> create task chain - -> coordinator Phase 4: spawn first batch workers (background) -> STOP - -> Worker executes -> SendMessage callback -> coordinator advances next step - -> Loop until pipeline complete -> Phase 5 report -``` - -**User Commands** (wake paused coordinator): - -| Command | Action | -|---------|--------| -| `check` / `status` | Output execution status graph, no advancement | -| `resume` / `continue` | Check worker states, advance next step | -| `revise [feedback]` | Create revision task for specified document + cascade downstream | -| `feedback ` | Analyze feedback impact, create targeted revision chain | -| `recheck` | Re-run QUALITY-001 quality check (after manual edits) | -| `improve [dimension]` | Auto-improve weakest dimension from readiness-report | - ---- - -## Shared Infrastructure - -The following templates apply to all worker roles. Each role.md only needs to write **Phase 2-4** role-specific logic. - -### Worker Phase 1: Task Discovery (all workers shared) - -Each worker on startup executes the same task discovery flow: - -1. Call `TaskList()` to get all tasks -2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty -3. No tasks -> idle wait -4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress - -**Resume Artifact Check** (prevent duplicate output after resume): -- Check if this task's output artifacts already exist -- Artifacts complete -> skip to Phase 5 report completion -- Artifacts incomplete or missing -> normal Phase 2-4 execution - -### Worker Phase 5: Report + Fast-Advance (all workers shared) - -Task completion with optional fast-advance to skip coordinator round-trip: - -1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message - - Params: operation="log", team=****, from=, to="coordinator", type=, summary="[] ", ref= - - **`team` must be session ID** (e.g., `TLS-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field → take folder name. - - **CLI fallback**: `ccw team log --team --from --to coordinator --type --summary "[] ..." --json` -2. **TaskUpdate**: Mark task completed -3. **Fast-Advance Check**: - - Call `TaskList()`, find pending tasks whose blockedBy are ALL completed - - If exactly 1 ready task AND its owner matches a simple successor pattern -> **spawn it directly** (skip coordinator) - - Otherwise -> **SendMessage** to coordinator for orchestration -4. **Loop**: Back to Phase 1 to check for next task - -**Fast-Advance Rules**: - -| Condition | Action | -|-----------|--------| -| 同前缀后续任务 (Inner Loop 角色) | 不 spawn，主 agent 内循环 (Phase 5-L) | -| 1 ready task, simple linear successor, 不同前缀 | Spawn directly via Task(run_in_background: true) | -| Multiple ready tasks (parallel window) | SendMessage to coordinator (needs orchestration) | -| No ready tasks + others running | SendMessage to coordinator (status update) | -| No ready tasks + nothing running | SendMessage to coordinator (pipeline may be complete) | -| Checkpoint task (e.g., spec->impl transition) | SendMessage to coordinator (needs user confirmation) | - -**Fast-advance failure recovery**: If a fast-advanced task fails (worker exits without completing), the coordinator detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing, no manual intervention required. See [monitor.md](roles/coordinator/commands/monitor.md) Fast-Advance Failure Recovery. - -### Worker Inner Loop (同前缀多任务角色) - -适用角色：writer (DRAFT-*)、planner (PLAN-*)、executor (IMPL-*) - -当一个角色拥有**同前缀的多个串行任务**时，不再每完成一个就 spawn 新 agent，而是在同一 agent 内循环处理： - -**Inner Loop 流程**： - -``` -Phase 1: 发现任务 (首次) - │ - ├─ 找到任务 → Phase 2-3: 加载上下文 + Subagent 执行 - │ │ - │ v - │ Phase 4: 验证 (+ Inline Discuss if applicable) - │ │ - │ v - │ Phase 5-L: 轻量完成 (Loop variant) - │ │ - │ ├─ TaskUpdate 标完成 - │ ├─ team_msg 记录 - │ ├─ 累积摘要到 context_accumulator - │ │ - │ ├─ 检查：还有同前缀待处理任务？ - │ │ ├─ YES → 回到 Phase 1 (内循环) - │ │ └─ NO → Phase 5-F: 最终报告 - │ │ - │ └─ 异常中断条件？ - │ ├─ consensus_blocked HIGH → SendMessage → STOP - │ └─ 错误累计 ≥ 3 → SendMessage → STOP - │ - └─ Phase 5-F: 最终报告 (Final) - ├─ SendMessage (含全部任务摘要) - └─ STOP -``` - -**context_accumulator** (主 agent 上下文中维护，不写文件): - -每个 subagent 返回后，主 agent 将结果压缩为摘要追加到 accumulator： - -``` -context_accumulator = [] - -# DRAFT-001 subagent 返回后 -context_accumulator.append({ - task: "DRAFT-001", - artifact: "spec/product-brief.md", - key_decisions: ["聚焦 B2B 场景", "MVP 不含移动端"], - discuss_verdict: "consensus_reached", - discuss_rating: 4.2 -}) - -# DRAFT-002 subagent 返回后 -context_accumulator.append({ - task: "DRAFT-002", - artifact: "spec/requirements/_index.md", - key_decisions: ["REQ-003 降级为 P2", "NFR-perf 新增 SLA"], - discuss_verdict: "consensus_reached", - discuss_rating: 3.8 -}) -``` - -后续 subagent 调用时，将 accumulator 摘要作为 CONTEXT 传入，实现知识传递。 - -**Phase 5-L vs Phase 5-F 区别**： - -| 步骤 | Phase 5-L (循环中) | Phase 5-F (最终) | -|------|-------------------|-----------------| -| TaskUpdate completed | YES | YES | -| team_msg log | YES | YES | -| 累积摘要 | YES | - | -| SendMessage to coordinator | NO | YES (含所有任务汇总) | -| Fast-Advance 到下一前缀 | - | YES (检查跨前缀后续) | - -**中断恢复**： - -如果 Inner Loop agent 在 DRAFT-003 崩溃： -1. DRAFT-001, DRAFT-002 已落盘 + 已标完成 → 安全 -2. DRAFT-003 状态为 in_progress → coordinator resume 时检测到无 active_worker → 重置为 pending -3. 重新 spawn writer → Phase 1 找到 DRAFT-003 → Resume Artifact Check: - - DRAFT-003 产物不存在 → 正常执行 - - DRAFT-003 产物已写但未标完成 → 验证后标完成 -4. 新 writer 从 DRAFT-003 开始循环，丢失的只是 001+002 的隐性摘要（可从磁盘重建基础信息） - -**恢复增强** (可选)：在每个 Phase 5-L 后将 context_accumulator 写入 `/shared-memory.json` 的 `context_accumulator` 字段，crash 后可读回。 - -### Inline Discuss Protocol (produce roles: analyst, writer, reviewer) - -After completing their primary output, produce roles call the discuss subagent inline: - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss ", - prompt: -}) -``` - -**Discussion round mapping** (which role runs which discuss round): - -| Role | After Task | Discuss Round | Perspectives | -|------|-----------|---------------|-------------| -| analyst | RESEARCH-001 | DISCUSS-001 | product, risk, coverage | -| writer | DRAFT-001 | DISCUSS-002 | product, technical, quality, coverage | -| writer | DRAFT-002 | DISCUSS-003 | quality, product, coverage | -| writer | DRAFT-003 | DISCUSS-004 | technical, risk | -| writer | DRAFT-004 | DISCUSS-005 | product, technical, quality, coverage | -| reviewer | QUALITY-001 | DISCUSS-006 | all 5 | - -The discuss subagent writes its record to `discussions/` and returns the verdict. The calling role includes the discuss result in its Phase 5 report. - -**Consensus-blocked handling** (produce role responsibility): - -| Verdict | Severity | Role Action | -|---------|----------|-------------| -| consensus_reached | - | Include action items in report, proceed to Phase 5 | -| consensus_blocked | HIGH | SendMessage with `consensus_blocked=true, severity=HIGH`, include divergence details + action items. Coordinator creates revision task or pauses. | -| consensus_blocked | MEDIUM | SendMessage with `consensus_blocked=true, severity=MEDIUM`. Proceed to Phase 5 normally. Coordinator logs warning to wisdom. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. | - -**SendMessage format for consensus_blocked**: - -``` -[] complete. Discuss : consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -``` - -**Coordinator response** (see monitor.md Consensus-Blocked Handling for full flow): -- HIGH -> revision task (max 1 per task) or pause for user decision -- MEDIUM -> proceed with warning, log to wisdom/issues.md -- DISCUSS-006 HIGH -> always pause for user (final sign-off gate) - -### Shared Explore Utility - -Any role needing codebase context calls the explore subagent: - -``` -Task({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore ", - prompt: -}) -``` - -**Cache**: Results stored in `explorations/` with `cache-index.json`. Before exploring, always check cache first. See [subagents/explore-subagent.md](subagents/explore-subagent.md). - -### Wisdom Accumulation (all roles) - -Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at session init. - -**Directory**: -``` -/wisdom/ -+-- learnings.md # Patterns and insights -+-- decisions.md # Architecture and design decisions -+-- conventions.md # Codebase conventions -+-- issues.md # Known risks and issues -``` - -**Worker load** (Phase 2): Extract `Session: ` from task description, read wisdom files. -**Worker contribute** (Phase 4/5): Write discoveries to corresponding wisdom files. - -### Role Isolation Rules - -| Allowed | Prohibited | -|---------|-----------| -| Process own prefix tasks | Process other role's prefix tasks | -| SendMessage to coordinator | Directly communicate with other workers | -| Use tools declared in Toolbox | Create tasks for other roles | -| Call discuss/explore subagents | Modify resources outside own scope | -| Fast-advance simple successors | Spawn parallel worker batches | - -Coordinator additionally prohibited: directly write/modify code, call implementation subagents, directly execute analysis/test/review. - ---- - -## Pipeline Definitions - -### Spec-only (6 tasks, was 12 in v3) - -``` -RESEARCH-001(+D1) -> DRAFT-001(+D2) -> DRAFT-002(+D3) -> DRAFT-003(+D4) -> DRAFT-004(+D5) -> QUALITY-001(+D6) -``` - -Each task includes inline discuss. `(+DN)` = inline discuss round N. - -### Impl-only / Backend (4 tasks) - -``` -PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001 -``` - -### Full-lifecycle (10 tasks, was 16 in v3) - -``` -[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001 -``` - -### Frontend Pipelines - -``` -FE-only: PLAN-001 -> DEV-FE-001 -> QA-FE-001 - (GC loop: QA-FE verdict=NEEDS_FIX -> DEV-FE-002 -> QA-FE-002, max 2 rounds) - -Fullstack: PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001 - -Full + FE: [Spec pipeline] -> PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001 -``` - -### Cadence Control - -**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP. - -``` -Beat Cycle (single beat) -====================================================================== - Event Coordinator Workers ----------------------------------------------------------------------- - callback/resume --> +- handleCallback -+ - | mark completed | - | check pipeline | - +- handleSpawnNext -+ - | find ready tasks | - | spawn workers ---+--> [Worker A] Phase 1-5 - | (parallel OK) --+--> [Worker B] Phase 1-5 - +- STOP (idle) -----+ | - | - callback <-----------------------------------------+ - (next beat) SendMessage + TaskUpdate(completed) -====================================================================== - - Fast-Advance (skips coordinator for simple linear successors) -====================================================================== - [Worker A] Phase 5 complete - +- 1 ready task? simple successor? --> spawn Worker B directly - +- complex case? --> SendMessage to coordinator -====================================================================== -``` - -**Pipeline beat view (v4 optimized)**: - -``` -Spec-only (6 beats, was 12 in v3) -------------------------------------------------------- -Beat 1 2 3 4 5 6 - | | | | | | - R1+D1 --> W1+D2 --> W2+D3 --> W3+D4 --> W4+D5 --> Q1+D6 - ^ ^ - pipeline sign-off - start pause - -R=RESEARCH W=DRAFT(writer) Q=QUALITY D=DISCUSS(inline) - -Impl-only (3 beats, with parallel window) -------------------------------------------------------- -Beat 1 2 3 - | | +----+----+ - PLAN --> IMPL --> TEST || REVIEW <-- parallel window - +----+----+ - pipeline - done - -Full-lifecycle (9 beats, was 15 in v3) -------------------------------------------------------- -Beat 1-6: [Spec pipeline as above] - | -Beat 6 (Q1+D6 done): PAUSE CHECKPOINT -- user confirms then resume - | -Beat 7 8 9 - PLAN --> IMPL --> TEST || REVIEW - -Fullstack (with dual parallel windows) -------------------------------------------------------- -Beat 1 2 3 4 - | +----+----+ +----+----+ | - PLAN --> IMPL || DEV-FE --> TEST || QA-FE --> REVIEW - ^ ^ ^ - parallel 1 parallel 2 sync barrier -``` - -**Checkpoints**: - -| Trigger | Position | Behavior | -|---------|----------|----------| -| Spec->Impl transition | QUALITY-001 completed | Read readiness-report.md, extract gate + scores, display Checkpoint Output Template, pause for user action | -| GC loop max | QA-FE max 2 rounds | Stop iteration, report current state | -| Pipeline stall | No ready + no running | Check missing tasks, report to user | - -**Checkpoint Output Template** (QUALITY-001 completion): - -Coordinator reads `/spec/readiness-report.md`, extracts gate + dimension scores, displays: - -``` -[coordinator] ══════════════════════════════════════════ -[coordinator] SPEC PHASE COMPLETE -[coordinator] Quality Gate: (%) -[coordinator] -[coordinator] Dimension Scores: -[coordinator] Completeness: % -[coordinator] Consistency: % -[coordinator] Traceability: % -[coordinator] Depth: % -[coordinator] Coverage: % -[coordinator] -[coordinator] Available Actions: -[coordinator] resume → Proceed to implementation -[coordinator] improve → Auto-improve weakest dimension -[coordinator] improve → Improve specific dimension -[coordinator] revise → Revise specific document -[coordinator] recheck → Re-run quality check -[coordinator] feedback → Inject feedback, create revision -[coordinator] ══════════════════════════════════════════ -``` - -Gate-specific guidance: -- PASS: All actions available, resume is primary suggestion -- REVIEW: Recommend improve/revise before resume, warn on resume -- FAIL: Recommend improve/revise, do not suggest resume (user can force) - -**Stall detection** (coordinator `handleCheck`): - -| Check | Condition | Resolution | -|-------|-----------|-----------| -| Worker unresponsive | in_progress task with no callback | Report waiting tasks, suggest `resume` | -| Pipeline deadlock | no ready + no running + has pending | Check blockedBy chain, report blockage | -| GC loop exceeded | DEV-FE / QA-FE iteration > max_rounds | Terminate loop, output latest QA report | - -### Task Metadata Registry - -| Task ID | Role | Phase | Dependencies | Description | Inline Discuss | -|---------|------|-------|-------------|-------------|---------------| -| RESEARCH-001 | analyst | spec | (none) | Seed analysis and context gathering | DISCUSS-001 | -| DRAFT-001 | writer | spec | RESEARCH-001 | Generate Product Brief | DISCUSS-002 | -| DRAFT-002 | writer | spec | DRAFT-001 | Generate Requirements/PRD | DISCUSS-003 | -| DRAFT-003 | writer | spec | DRAFT-002 | Generate Architecture Document | DISCUSS-004 | -| DRAFT-004 | writer | spec | DRAFT-003 | Generate Epics & Stories | DISCUSS-005 | -| QUALITY-001 | reviewer | spec | DRAFT-004 | 5-dimension spec quality + sign-off | DISCUSS-006 | -| PLAN-001 | planner | impl | (none or QUALITY-001) | Multi-angle exploration and planning | - | -| IMPL-001 | executor | impl | PLAN-001 | Code implementation | - | -| TEST-001 | tester | impl | IMPL-001 | Test-fix cycles | - | -| REVIEW-001 | reviewer | impl | IMPL-001 | 4-dimension code review | - | -| DEV-FE-001 | fe-developer | impl | PLAN-001 | Frontend implementation | - | -| QA-FE-001 | fe-qa | impl | DEV-FE-001 | 5-dimension frontend QA | - | - -## Coordinator Spawn Template - -### 标准 Worker (单任务角色: analyst, tester, reviewer, architect) - -When coordinator spawns workers, use background mode (Spawn-and-Stop): - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker", - team_name: , - name: "", - run_in_background: true, - prompt: `You are team "" . - -## Primary Instruction -All your work MUST be executed by calling Skill to get role definition: -Skill(skill="team-lifecycle-v4", args="--role=") - -Current requirement: -Session: - -## Role Guidelines -- Only process -* tasks, do not execute other role work -- All output prefixed with [] tag -- Only communicate with coordinator -- Do not use TaskCreate to create tasks for other roles -- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) -- After task completion, check for fast-advance opportunity (see SKILL.md Phase 5) - -## Workflow -1. Call Skill -> get role definition and execution logic -2. Follow role.md 5-Phase flow -3. team_msg(team=) + SendMessage results to coordinator -4. TaskUpdate completed -> check next task or fast-advance` -}) -``` - -### Inner Loop Worker (多任务角色: writer, planner, executor) - -``` -Task({ - subagent_type: "general-purpose", - description: "Spawn worker (inner loop)", - team_name: , - name: "", - run_in_background: true, - prompt: `You are team "" . - -## Primary Instruction -All your work MUST be executed by calling Skill to get role definition: -Skill(skill="team-lifecycle-v4", args="--role=") - -Current requirement: -Session: - -## Inner Loop Mode -You will handle ALL -* tasks in this session, not just the first one. -After completing each task, loop back to find the next -* task. -Only SendMessage to coordinator when: -- All -* tasks are done -- A consensus_blocked HIGH occurs -- Errors accumulate (≥ 3) - -## Role Guidelines -- Only process -* tasks, do not execute other role work -- All output prefixed with [] tag -- Only communicate with coordinator -- Do not use TaskCreate to create tasks for other roles -- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) -- Use subagent calls for heavy work, retain summaries in context` -}) -``` - -## Session Directory - -``` -.workflow/.team/TLS--/ -+-- team-session.json # Session state -+-- spec/ # Spec artifacts -| +-- spec-config.json -| +-- discovery-context.json -| +-- product-brief.md -| +-- requirements/ -| +-- architecture/ -| +-- epics/ -| +-- readiness-report.md -| +-- spec-summary.md -+-- discussions/ # Discussion records (written by discuss subagent) -+-- plan/ # Plan artifacts -| +-- plan.json -| +-- .task/TASK-*.json -+-- explorations/ # Shared explore cache -| +-- cache-index.json # { angle+keywords_hash -> file_path } -| +-- explore-.json -+-- architecture/ # Architect assessments + design-tokens.json -+-- analysis/ # Analyst design-intelligence.json (UI mode) -+-- qa/ # QA audit reports -+-- wisdom/ # Cross-task knowledge -| +-- learnings.md -| +-- decisions.md -| +-- conventions.md -| +-- issues.md -+-- .msg/ # Team message bus logs (messages.jsonl) -+-- shared-memory.json # Cross-role state -``` - -## Session Resume - -Coordinator supports `--resume` / `--continue` for interrupted sessions: - -1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions -2. Multiple matches -> AskUserQuestion for selection -3. Audit TaskList -> reconcile session state <-> task status -4. Reset in_progress -> pending (interrupted tasks) -5. Rebuild team and spawn needed workers only -6. Create missing tasks with correct blockedBy -7. Kick first executable task -> Phase 4 coordination loop - -## Shared Spec Resources - -| Resource | Path | Usage | -|----------|------|-------| -| Document Standards | [specs/document-standards.md](specs/document-standards.md) | YAML frontmatter, naming, structure | -| Quality Gates | [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gates | -| Product Brief Template | [templates/product-brief.md](templates/product-brief.md) | DRAFT-001 | -| Requirements Template | [templates/requirements-prd.md](templates/requirements-prd.md) | DRAFT-002 | -| Architecture Template | [templates/architecture-doc.md](templates/architecture-doc.md) | DRAFT-003 | -| Epics Template | [templates/epics-template.md](templates/epics-template.md) | DRAFT-004 | -| Discuss Subagent | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | Inline discuss protocol | -| Explore Subagent | [subagents/explore-subagent.md](subagents/explore-subagent.md) | Shared exploration utility | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Unknown --role value | Error with available role list | -| Missing --role arg | Orchestration Mode -> coordinator | -| Role file not found | Error with expected path | -| Command file not found | Fallback to inline execution | -| Discuss subagent fails | Role proceeds without discuss, logs warning | -| Explore cache corrupt | Clear cache, re-explore | -| Fast-advance spawns wrong task | Coordinator reconciles on next callback | diff --git a/.claude/skills/team-lifecycle-v4/roles/analyst/role.md b/.claude/skills/team-lifecycle-v4/roles/analyst/role.md deleted file mode 100644 index cbe19a1f..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/analyst/role.md +++ /dev/null @@ -1,174 +0,0 @@ -# Role: analyst - -Seed analysis, codebase exploration (via shared explore subagent), and multi-dimensional context gathering. Includes inline discuss (DISCUSS-001) after research output. - -## Identity - -- **Name**: `analyst` | **Prefix**: `RESEARCH-*` | **Tag**: `[analyst]` -- **Responsibility**: Seed Analysis -> Codebase Exploration -> Context Packaging -> **Inline Discuss** -> Report - -## Boundaries - -### MUST -- Only process RESEARCH-* tasks -- Communicate only with coordinator -- Generate discovery-context.json and spec-config.json -- Support file reference input (@ prefix or .md/.txt extension) -- Call discuss subagent for DISCUSS-001 after output -- Use shared explore subagent for codebase exploration (cache-aware) - -### MUST NOT -- Create tasks for other roles -- Directly contact other workers -- Modify spec documents (only create discovery artifacts) -- Skip seed analysis step - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| research_ready | -> coordinator | Research + discuss complete | -| research_progress | -> coordinator | Long research progress update | -| error | -> coordinator | Unrecoverable error | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| ccw cli --tool gemini --mode analysis | Seed analysis | -| Explore subagent | Codebase exploration (shared cache) | -| discuss subagent | Inline DISCUSS-001 critique | - ---- - -## Phase 2: Seed Analysis - -**Objective**: Extract structured seed information from the topic/idea. - -**Workflow**: -1. Extract session folder from task description (`Session: `) -2. Parse topic from task description (first non-metadata line) -3. If topic starts with `@` or ends with `.md`/`.txt` -> Read the referenced file as topic content -4. Run Gemini CLI seed analysis: - -``` -Bash({ - command: `ccw cli -p "PURPOSE: Analyze topic and extract structured seed information. -TASK: * Extract problem statement * Identify target users * Determine domain context -* List constraints and assumptions * Identify 3-5 exploration dimensions * Assess complexity -TOPIC: -MODE: analysis -EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis`, - run_in_background: true -}) -``` - -5. Wait for CLI result, parse seed analysis JSON - -**Success**: Seed analysis parsed with problem statement, dimensions, complexity. - ---- - -## Phase 3: Codebase Exploration (conditional) - -**Objective**: Gather codebase context if an existing project is detected. - -| Condition | Action | -|-----------|--------| -| package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore codebase | -| No project files | Skip -> codebase context = null | - -**When project detected** (uses shared explore subagent): -1. Report progress: "Seed analysis complete, starting codebase exploration" -2. Call explore subagent with `angle: general`, `keywords: ` - -``` -Task({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore general context", - prompt: "Explore codebase for: -Focus angle: general -Keywords: -Session folder: -..." -}) -``` - -3. Use exploration results to build codebase context: tech_stack, architecture_patterns, conventions, integration_points - ---- - -## Phase 4: Context Packaging + Inline Discuss - -**Objective**: Generate spec-config.json and discovery-context.json, then run DISCUSS-001. - -### 4a: Context Packaging - -**spec-config.json** -> `/spec/spec-config.json`: -- session_id, topic, status="research_complete", complexity, depth, focus_areas, mode="interactive" - -**discovery-context.json** -> `/spec/discovery-context.json`: -- session_id, phase=1, seed_analysis (all fields), codebase_context (or null), recommendations - -**design-intelligence.json** -> `/analysis/design-intelligence.json` (UI mode only): -- Produced when frontend keywords detected in seed_analysis -- Fields: industry, style_direction, ux_patterns, color_strategy, typography, component_patterns -- Consumed by architect (for design-tokens.json) and fe-developer - -### 4b: Inline Discuss (DISCUSS-001) - -After packaging, call discuss subagent: - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss DISCUSS-001", - prompt: `## Multi-Perspective Critique: DISCUSS-001 - -### Input -- Artifact: /spec/discovery-context.json -- Round: DISCUSS-001 -- Perspectives: product, risk, coverage -- Session: -- Discovery Context: /spec/discovery-context.json - -` -}) -``` - -**Discuss result handling**: - -| Verdict | Severity | Action | -|---------|----------|--------| -| consensus_reached | - | Include action items in report, proceed to Phase 5 | -| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format (see below). Do NOT self-revise. | -| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. | - -**consensus_blocked SendMessage format**: -``` -[analyst] RESEARCH-001 complete. Discuss DISCUSS-001: consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -Artifact: /spec/discovery-context.json -Discussion: /discussions/DISCUSS-001-discussion.md -``` - -**Report**: complexity, codebase presence, problem statement, exploration dimensions, discuss verdict + severity, output paths. - -**Success**: Both JSON files created; discuss record written; design-intelligence.json created if UI mode. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Gemini CLI failure | Fallback to direct Claude analysis | -| Codebase detection failed | Continue as new project | -| Topic too vague | Report with clarification questions | -| Explore subagent fails | Continue without codebase context | -| Discuss subagent fails | Proceed without discuss, log warning in report | diff --git a/.claude/skills/team-lifecycle-v4/roles/architect/commands/assess.md b/.claude/skills/team-lifecycle-v4/roles/architect/commands/assess.md deleted file mode 100644 index 8c6bc967..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/architect/commands/assess.md +++ /dev/null @@ -1,193 +0,0 @@ -# Command: assess - -## Purpose - -Multi-mode architecture assessment. Auto-detects consultation mode from task subject prefix, runs mode-specific analysis, and produces a verdict with concerns and recommendations. - -## Phase 2: Context Loading - -### Common Context (all modes) - -| Input | Source | Required | -|-------|--------|----------| -| Session folder | Task description `Session:` field | Yes | -| Wisdom | `/wisdom/` (all files) | No | -| Project tech | `.workflow/project-tech.json` | No | -| Explorations | `/explorations/` | No | - -### Mode-Specific Context - -| Mode | Task Pattern | Additional Context | -|------|-------------|-------------------| -| spec-review | ARCH-SPEC-* | `spec/architecture/_index.md`, `spec/architecture/ADR-*.md` | -| plan-review | ARCH-PLAN-* | `plan/plan.json`, `plan/.task/TASK-*.json` | -| code-review | ARCH-CODE-* | `git diff --name-only`, changed file contents | -| consult | ARCH-CONSULT-* | Question extracted from task description | -| feasibility | ARCH-FEASIBILITY-* | Proposal from task description, codebase search results | - -## Phase 3: Mode-Specific Assessment - -### Mode: spec-review - -Review architecture documents for technical soundness across 4 dimensions. - -**Assessment dimensions**: - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Consistency | 25% | ADR decisions align with each other and with architecture index | -| Scalability | 25% | Design supports growth, no single-point bottlenecks | -| Security | 25% | Auth model, data protection, API security addressed | -| Tech fitness | 25% | Technology choices match project-tech.json and problem domain | - -**Checks**: -- Read architecture index and all ADR files -- Cross-reference ADR decisions for contradictions -- Verify tech choices align with project-tech.json -- Score each dimension 0-100 - ---- - -### Mode: plan-review - -Review implementation plan for architectural soundness. - -**Checks**: - -| Check | What | Severity if Failed | -|-------|------|-------------------| -| Dependency cycles | Build task graph, detect cycles via DFS | High | -| Task granularity | Flag tasks touching >8 files | Medium | -| Convention compliance | Verify plan follows wisdom/conventions.md | Medium | -| Architecture alignment | Verify plan doesn't contradict wisdom/decisions.md | High | - -**Dependency cycle detection flow**: -1. Parse all TASK-*.json files -> extract id and depends_on -2. Build directed graph -3. DFS traversal -> flag any node visited twice in same stack -4. Report cycle path if found - ---- - -### Mode: code-review - -Assess architectural impact of code changes. - -**Checks**: - -| Check | Method | Severity if Found | -|-------|--------|-------------------| -| Layer violations | Detect upward imports (deeper layer importing shallower) | High | -| New dependencies | Parse package.json diff for added deps | Medium | -| Module boundary changes | Flag index.ts/index.js modifications | Medium | -| Architectural impact | Score based on file count and boundary changes | Info | - -**Impact scoring**: - -| Condition | Impact Level | -|-----------|-------------| -| Changed files > 10 | High | -| index.ts/index.js or package.json modified | Medium | -| All other cases | Low | - -**Detection example** (find changed files): - -```bash -Bash(command="git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached") -``` - ---- - -### Mode: consult - -Answer architecture decision questions. Route by question complexity. - -**Complexity detection**: - -| Condition | Classification | -|-----------|---------------| -| Question > 200 chars OR matches: architect, design, pattern, refactor, migrate, scalab | Complex | -| All other questions | Simple | - -**Complex questions** -> delegate to CLI exploration: - -```bash -Bash(command="ccw cli -p \"PURPOSE: Architecture consultation for: -TASK: Search codebase for relevant patterns, analyze architectural implications, provide options with trade-offs -MODE: analysis -CONTEXT: @**/* -EXPECTED: Options with trade-offs, file references, architectural implications -CONSTRAINTS: Advisory only, provide options not decisions\" --tool gemini --mode analysis --rule analysis-review-architecture", timeout=300000) -``` - -**Simple questions** -> direct analysis using available context (wisdom, project-tech, codebase search). - ---- - -### Mode: feasibility - -Evaluate technical feasibility of a proposal. - -**Assessment areas**: - -| Area | Method | Output | -|------|--------|--------| -| Tech stack compatibility | Compare proposal needs against project-tech.json | Compatible / Requires additions | -| Codebase readiness | Search for integration points using Grep/Glob | Touch-point count | -| Effort estimation | Based on touch-point count (see table below) | Low / Medium / High | -| Risk assessment | Based on effort + tech compatibility | Risks + mitigations | - -**Effort estimation**: - -| Touch Points | Effort | Implication | -|-------------|--------|-------------| -| <= 5 | Low | Straightforward implementation | -| 6 - 20 | Medium | Moderate refactoring needed | -| > 20 | High | Significant refactoring, consider phasing | - -**Verdict for feasibility**: - -| Condition | Verdict | -|-----------|---------| -| Low/medium effort, compatible stack | FEASIBLE | -| High touch-points OR new tech required | RISKY | -| Fundamental incompatibility or unreasonable effort | INFEASIBLE | - ---- - -### Verdict Routing (all modes except feasibility) - -| Verdict | Criteria | -|---------|----------| -| BLOCK | >= 2 high-severity concerns | -| CONCERN | >= 1 high-severity OR >= 3 medium-severity concerns | -| APPROVE | All other cases | - -## Phase 4: Validation - -### Output Format - -Write assessment to `/architecture/arch-.json`. - -**Report content sent to coordinator**: - -| Field | Description | -|-------|-------------| -| mode | Consultation mode used | -| verdict | APPROVE / CONCERN / BLOCK (or FEASIBLE / RISKY / INFEASIBLE) | -| concern_count | Number of concerns by severity | -| recommendations | Actionable suggestions with trade-offs | -| output_path | Path to full assessment file | - -**Wisdom contribution**: Append significant decisions to `/wisdom/decisions.md`. - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Architecture docs not found | Assess from available context, note limitation in report | -| Plan file missing | Report to coordinator via arch_concern | -| Git diff fails (no commits) | Use staged changes or skip code-review mode | -| CLI exploration timeout | Provide partial assessment, flag as incomplete | -| Exploration results unparseable | Fall back to direct analysis without exploration | -| Insufficient context | Request explorer assistance via coordinator | diff --git a/.claude/skills/team-lifecycle-v4/roles/architect/role.md b/.claude/skills/team-lifecycle-v4/roles/architect/role.md deleted file mode 100644 index a2cc6c5e..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/architect/role.md +++ /dev/null @@ -1,103 +0,0 @@ -# Role: architect - -Architecture consultant. Advice on decisions, feasibility, design patterns. - -## Identity - -- **Name**: `architect` | **Prefix**: `ARCH-*` | **Tag**: `[architect]` -- **Type**: Consulting (on-demand, advisory only) -- **Responsibility**: Context loading → Mode detection → Analysis → Report - -## Boundaries - -### MUST -- Only process ARCH-* tasks -- Auto-detect mode from task subject prefix -- Provide options with trade-offs (not final decisions) - -### MUST NOT -- Modify source code -- Make final decisions (advisory only) -- Execute implementation or testing - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| arch_ready | → coordinator | Assessment complete | -| arch_concern | → coordinator | Significant risk found | -| error | → coordinator | Analysis failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/assess.md | Multi-mode assessment | -| cli-explore-agent | Deep architecture exploration | -| ccw cli --tool gemini --mode analysis | Architecture analysis | - ---- - -## Consultation Modes - -| Task Pattern | Mode | Focus | -|-------------|------|-------| -| ARCH-SPEC-* | spec-review | Review architecture docs | -| ARCH-PLAN-* | plan-review | Review plan soundness | -| ARCH-CODE-* | code-review | Assess code change impact | -| ARCH-CONSULT-* | consult | Answer architecture questions | -| ARCH-FEASIBILITY-* | feasibility | Technical feasibility | - ---- - -## Phase 2: Context Loading - -**Common**: session folder, wisdom, project-tech.json, explorations - -**Mode-specific**: - -| Mode | Additional Context | -|------|-------------------| -| spec-review | architecture/_index.md, ADR-*.md | -| plan-review | plan/plan.json | -| code-review | git diff, changed files | -| consult | Question from task description | -| feasibility | Requirements + codebase | - ---- - -## Phase 3: Assessment - -Delegate to `commands/assess.md`. Output: mode, verdict (APPROVE/CONCERN/BLOCK), dimensions[], concerns[], recommendations[]. - -For complex questions → Gemini CLI with architecture review rule. - ---- - -## Phase 4: Report - -Output to `/architecture/arch-.json`. Contribute decisions to wisdom/decisions.md. - -**Frontend project outputs** (when frontend tech stack detected in shared-memory or discovery-context): -- `/architecture/design-tokens.json` — color, spacing, typography, shadow tokens -- `/architecture/component-specs/*.md` — per-component design spec - -**Report**: mode, verdict, concern count, recommendations, output path(s). - ---- - -## Coordinator Integration - -| Timing | Task | -|--------|------| -| After DRAFT-003 | ARCH-SPEC-001: 架构文档评审 | -| After PLAN-001 | ARCH-PLAN-001: 计划架构审查 | -| On-demand | ARCH-CONSULT-001: 架构咨询 | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Docs not found | Assess from available context | -| CLI timeout | Partial assessment | -| Insufficient context | Request explorer via coordinator | diff --git a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md deleted file mode 100644 index bbb2c0de..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +++ /dev/null @@ -1,198 +0,0 @@ -# Command: dispatch - -## Purpose - -Create task chains based on execution mode. v4 optimized: spec pipeline reduced from 12 to 6 tasks by inlining discuss rounds into produce roles. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Mode | Phase 1 requirements (spec-only, impl-only, etc.) | Yes | -| Session folder | `` from Phase 2 | Yes | -| Scope | User requirements description | Yes | -| Spec file | User-provided path (impl-only mode only) | Conditional | - -## Phase 3: Task Chain Creation - -### Mode-to-Pipeline Routing - -| Mode | Tasks | Pipeline | First Task | -|------|-------|----------|------------| -| spec-only | 6 | Spec pipeline | RESEARCH-001 | -| impl-only | 4 | Impl pipeline | PLAN-001 | -| fe-only | 3 | FE pipeline | PLAN-001 | -| fullstack | 6 | Fullstack pipeline | PLAN-001 | -| full-lifecycle | 10 | Spec + Impl | RESEARCH-001 | -| full-lifecycle-fe | 12 | Spec + Fullstack | RESEARCH-001 | - ---- - -### Spec Pipeline (6 tasks, was 12 in v3) - -Used by: spec-only, full-lifecycle, full-lifecycle-fe - -| # | Subject | Owner | BlockedBy | Description | Inline Discuss | -|---|---------|-------|-----------|-------------|---------------| -| 1 | RESEARCH-001 | analyst | (none) | Seed analysis and context gathering | DISCUSS-001 | -| 2 | DRAFT-001 | writer | RESEARCH-001 | Generate Product Brief | DISCUSS-002 | -| 3 | DRAFT-002 | writer | DRAFT-001 | Generate Requirements/PRD | DISCUSS-003 | -| 4 | DRAFT-003 | writer | DRAFT-002 | Generate Architecture Document | DISCUSS-004 | -| 5 | DRAFT-004 | writer | DRAFT-003 | Generate Epics & Stories | DISCUSS-005 | -| 6 | QUALITY-001 | reviewer | DRAFT-004 | 5-dimension spec quality + sign-off | DISCUSS-006 | - -**Key change from v3**: No separate DISCUSS-* tasks. Each produce role calls the discuss subagent inline after completing its primary output. - -### Impl Pipeline (4 tasks) - -Used by: impl-only, full-lifecycle (PLAN-001 blockedBy QUALITY-001) - -| # | Subject | Owner | BlockedBy | Description | -|---|---------|-------|-----------|-------------| -| 1 | PLAN-001 | planner | (none) | Multi-angle exploration and planning | -| 2 | IMPL-001 | executor | PLAN-001 | Code implementation | -| 3 | TEST-001 | tester | IMPL-001 | Test-fix cycles | -| 4 | REVIEW-001 | reviewer | IMPL-001 | 4-dimension code review | - -### FE Pipeline (3 tasks) - -Used by: fe-only - -| # | Subject | Owner | BlockedBy | Description | -|---|---------|-------|-----------|-------------| -| 1 | PLAN-001 | planner | (none) | Planning (frontend focus) | -| 2 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation | -| 3 | QA-FE-001 | fe-qa | DEV-FE-001 | 5-dimension frontend QA | - -GC loop (max 2 rounds): QA-FE verdict=NEEDS_FIX -> create DEV-FE-002 + QA-FE-002 dynamically. - -### Fullstack Pipeline (6 tasks) - -Used by: fullstack, full-lifecycle-fe (PLAN-001 blockedBy QUALITY-001) - -| # | Subject | Owner | BlockedBy | Description | -|---|---------|-------|-----------|-------------| -| 1 | PLAN-001 | planner | (none) | Fullstack planning | -| 2 | IMPL-001 | executor | PLAN-001 | Backend implementation | -| 3 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation | -| 4 | TEST-001 | tester | IMPL-001 | Backend test-fix cycles | -| 5 | QA-FE-001 | fe-qa | DEV-FE-001 | Frontend QA | -| 6 | REVIEW-001 | reviewer | TEST-001, QA-FE-001 | Full code review | - -### Composite Modes - -| Mode | Construction | PLAN-001 BlockedBy | -|------|-------------|-------------------| -| full-lifecycle | Spec (6) + Impl (4) | QUALITY-001 | -| full-lifecycle-fe | Spec (6) + Fullstack (6) | QUALITY-001 | - ---- - -### Impl-Only Pre-check - -Before creating impl-only tasks, verify specification exists: - -``` -Spec exists? - +- YES -> read spec path -> proceed with task creation - +- NO -> error: "impl-only requires existing spec, use spec-only or full-lifecycle" -``` - -### Task Description Template - -Every task description includes session, scope, and inline discuss metadata: - -``` -TaskCreate({ - subject: "", - owner: "", - description: "\nSession: \nScope: \nInlineDiscuss: \nInnerLoop: ", - blockedBy: [], - status: "pending" -}) -``` - -**InnerLoop Flag Rules**: - -| Role | InnerLoop | -|------|-----------| -| writer (DRAFT-*) | true | -| planner (PLAN-*) | true | -| executor (IMPL-*) | true | -| analyst, tester, reviewer, architect, fe-developer, fe-qa | false | - -### Execution Method - -| Method | Behavior | -|--------|----------| -| sequential | One task active at a time; next activated after predecessor completes | -| parallel | Tasks with all deps met run concurrently (e.g., TEST-001 + REVIEW-001) | - -## Phase 4: Validation - -| Check | Criteria | -|-------|----------| -| Task count | Matches mode total from routing table | -| Dependencies | Every blockedBy references an existing task subject | -| Owner assignment | Each task owner matches SKILL.md Role Registry prefix | -| Session reference | Every task description contains `Session: ` | -| Inline discuss | Spec tasks have InlineDiscuss field matching round config | - -### Revision Task Template - -When handleRevise/handleFeedback creates revision tasks: - -``` -TaskCreate({ - subject: "-R1", - owner: "", - description: " revision of .\n - Session: \n - Original artifact: \n - User feedback: \n - Revision scope: \n - InlineDiscuss: \n - InnerLoop: ", - status: "pending", - blockedBy: [] -}) -``` - -**Revision naming**: `-R1` (max 1 revision per task; second revision -> `-R2`; third -> escalate to user) - -**Cascade blockedBy chain example** (revise DRAFT-002): -- DRAFT-002-R1 (no blockedBy) -- DRAFT-003-R1 (blockedBy: DRAFT-002-R1) -- DRAFT-004-R1 (blockedBy: DRAFT-003-R1) -- QUALITY-001-R1 (blockedBy: DRAFT-004-R1) - -### Improvement Task Template - -When handleImprove creates improvement tasks: - -``` -TaskCreate({ - subject: "IMPROVE--001", - owner: "writer", - description: "Quality improvement: .\n - Session: \n - Current score: %\n - Target: 80%\n - Readiness report: /spec/readiness-report.md\n - Weak areas: \n - Strategy: \n - InnerLoop: true", - status: "pending" -}) -``` - -Improvement tasks are always followed by a QUALITY-001-R1 recheck (blockedBy: IMPROVE task). - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Unknown mode | Reject with supported mode list | -| Missing spec for impl-only | Error, suggest spec-only or full-lifecycle | -| TaskCreate fails | Log error, report to user | -| Duplicate task subject | Skip creation, log warning | diff --git a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md deleted file mode 100644 index b5c240f2..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +++ /dev/null @@ -1,413 +0,0 @@ -# Command: monitor - -## Purpose - -Event-driven pipeline coordination with Spawn-and-Stop pattern. v4 enhanced with worker fast-advance awareness. Three wake-up sources: worker callbacks (auto-advance), user `check` (status report), user `resume` (manual advance). - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` | -| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS | -| FAST_ADVANCE_AWARE | true | Workers may skip coordinator for simple linear successors | - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session file | `/team-session.json` | Yes | -| Task list | `TaskList()` | Yes | -| Active workers | session.active_workers[] | Yes | -| Pipeline mode | session.mode | Yes | - -## Phase 3: Handler Routing - -### Wake-up Source Detection - -Parse `$ARGUMENTS` to determine handler: - -| Priority | Condition | Handler | -|----------|-----------|---------| -| 1 | Message contains `[]` from known worker role | handleCallback | -| 2 | Contains "check" or "status" | handleCheck | -| 3 | Contains "resume", "continue", or "next" | handleResume | -| 4 | None of the above (initial spawn after dispatch) | handleSpawnNext | -| 5 | Contains "revise" + task ID pattern | handleRevise | -| 6 | Contains "feedback" + quoted/unquoted text | handleFeedback | -| 7 | Contains "recheck" | handleRecheck | -| 8 | Contains "improve" (optionally + dimension name) | handleImprove | - -Known worker roles: analyst, writer, planner, executor, tester, reviewer, architect, fe-developer, fe-qa. - -> **Note**: `discussant` and `explorer` are no longer worker roles in v4. They are subagents called inline by produce roles. - ---- - -### Handler: handleCallback - -Worker completed a task. Verify completion, update state, auto-advance. - -``` -Receive callback from [] - +- Find matching active worker by role - +- 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 - | | +- Handle checkpoints (see below) - | | +- -> 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 note**: A worker may have already spawned its successor via fast-advance. When processing a callback: -1. Check if the expected next task is already `in_progress` (fast-advanced) -2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker -3. If no -> normal handleSpawnNext - ---- - -### Handler: handleCheck - -Read-only status report. No pipeline advancement. - -**Output format**: - -``` -[coordinator] Pipeline Status (v4) -[coordinator] Mode: | Progress: / (%) - -[coordinator] Execution Graph: - Spec Phase: (if applicable) - [ RESEARCH-001(+D1)] -> [ DRAFT-001(+D2)] -> [ DRAFT-002(+D3)] - -> [ DRAFT-003(+D4)] -> [ DRAFT-004(+D5)] -> [ QUALITY-001(+D6)] - Impl Phase: (if applicable) - [ PLAN-001] - +- BE: [ IMPL-001] -> [ TEST-001] -> [ REVIEW-001] - +- FE: [ DEV-FE-001] -> [ QA-FE-001] - - done=completed >>>=running o=pending .=not created - -[coordinator] Active Workers: - > () - running [inner-loop: N/M tasks done] - -[coordinator] Ready to spawn: -[coordinator] Commands: 'resume' to advance | 'check' to refresh -``` - -**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=. - -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 workers in background, update session, STOP. - -``` -Collect task states from TaskList() - +- completedSubjects: status = completed - +- inProgressSubjects: status = in_progress - +- readySubjects: pending + all blockedBy in completedSubjects - -Ready tasks found? - +- NONE + work in progress -> report waiting -> STOP - +- NONE + nothing in progress -> PIPELINE_COMPLETE -> Phase 5 - +- HAS ready tasks -> for each: - +- Is task owner 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 - +- TaskUpdate -> in_progress - +- team_msg log -> task_unblocked - +- Spawn worker (see tool call below) - +- Add to session.active_workers - Update session file -> output summary -> STOP -``` - -**Spawn worker tool call** (one per ready task): - -```bash -Task({ - subagent_type: "general-purpose", - description: "Spawn worker for ", - team_name: , - name: "", - run_in_background: true, - prompt: "" -}) -``` - ---- - -### Handler: handleRevise - -User requests targeted revision of a completed task. - -``` -Parse: revise [feedback-text] - +- Validate TASK-ID exists and is completed - | +- NOT completed -> error: "Task is not completed, cannot revise" - +- Determine role and doc type from TASK-ID prefix - +- Create revision task: - | TaskCreate({ - | subject: "-R1", - | owner: "", - | description: "User-requested revision of .\n - | Session: \n - | Original artifact: \n - | User feedback: \n - | Revision scope: targeted\n - | InlineDiscuss: \n - | InnerLoop: true", - | status: "pending" - | }) - +- Cascade check (auto): - | +- Find all completed tasks downstream of TASK-ID - | +- For each downstream completed task -> create -R1 - | +- Chain blockedBy: each R1 blockedBy its predecessor R1 - | +- Always end with QUALITY-001-R1 (recheck) - +- Spawn worker for first revision task -> STOP -``` - -**Cascade Rules**: - -| Revised Task | Downstream (auto-cascade) | -|-------------|--------------------------| -| RESEARCH-001 | DRAFT-001~004-R1, QUALITY-001-R1 | -| DRAFT-001 | DRAFT-002~004-R1, QUALITY-001-R1 | -| DRAFT-002 | DRAFT-003~004-R1, QUALITY-001-R1 | -| DRAFT-003 | DRAFT-004-R1, QUALITY-001-R1 | -| DRAFT-004 | QUALITY-001-R1 | -| QUALITY-001 | (no cascade, just recheck) | - -**Cascade depth control**: Only cascade tasks that are already completed. Pending/in_progress tasks will naturally pick up changes. - ---- - -### Handler: handleFeedback - -User injects feedback into pipeline context. - -``` -Parse: feedback - +- Determine pipeline state: - | +- Spec phase in progress -> find earliest affected DRAFT task - | +- Spec phase complete (at checkpoint) -> analyze full impact - | +- Impl phase in progress -> log to wisdom/decisions.md, no revision - +- Analyze feedback impact: - | +- Keyword match against doc types: - | "vision/market/MVP/scope" -> DRAFT-001 (product-brief) - | "requirement/feature/NFR/user story" -> DRAFT-002 (requirements) - | "architecture/ADR/component/tech stack" -> DRAFT-003 (architecture) - | "epic/story/sprint/priority" -> DRAFT-004 (epics) - | +- If unclear -> default to earliest incomplete or most recent completed - +- Write feedback to wisdom/decisions.md - +- Create revision chain (same as handleRevise from determined start point) - +- Spawn worker -> STOP -``` - ---- - -### Handler: handleRecheck - -Re-run quality check after manual edits or revisions. - -``` -Parse: recheck - +- Validate QUALITY-001 exists and is completed - | +- NOT completed -> error: "Quality check hasn't run yet" - +- Create recheck task: - | TaskCreate({ - | subject: "QUALITY-001-R1", - | owner: "reviewer", - | description: "Re-run spec quality check.\n - | Session: \n - | Scope: full recheck\n - | InlineDiscuss: DISCUSS-006", - | status: "pending" - | }) - +- Spawn reviewer -> STOP -``` - ---- - -### Handler: handleImprove - -Quality-driven improvement based on readiness report dimensions. - -``` -Parse: improve [dimension] - +- Read /spec/readiness-report.md - | +- NOT found -> error: "No readiness report. Run quality check first." - +- Extract dimension scores - +- Select target: - | +- dimension specified -> use it - | +- not specified -> pick lowest scoring dimension - +- Map dimension to improvement strategy: - | - | | Dimension | Strategy | Target Tasks | - | |-----------|----------|-------------| - | | completeness | Fill missing sections | DRAFT with missing sections | - | | consistency | Unify terminology/format | All DRAFT (batch) | - | | traceability | Strengthen Goals->Reqs->Arch->Stories chain | DRAFT-002, DRAFT-003, DRAFT-004 | - | | depth | Enhance AC/ADR detail | Weakest sub-dimension's DRAFT | - | | coverage | Add uncovered requirements | DRAFT-002 | - | - +- Create improvement task: - | TaskCreate({ - | subject: "IMPROVE--001", - | owner: "writer", - | description: "Quality improvement: .\n - | Session: \n - | Current score: %\n - | Target: 80%\n - | Weak areas: \n - | Strategy: \n - | InnerLoop: true", - | status: "pending" - | }) - +- Create QUALITY-001-R1 (blockedBy: IMPROVE task) - +- Spawn writer -> STOP -``` - ---- - -### Checkpoints - -| Completed Task | Mode Condition | Action | -|---------------|----------------|--------| -| QUALITY-001 | full-lifecycle or full-lifecycle-fe | Read readiness-report.md -> extract gate + scores -> output Checkpoint Output Template (see SKILL.md) -> pause for user action | - ---- - -### Worker Failure Handling - -When a worker has unexpected status (not completed, not in_progress): - -1. Reset task -> pending via TaskUpdate -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 (task in_progress but no callback and worker gone): - -``` -handleCallback / handleResume detects: - +- Task is in_progress (was fast-advanced by predecessor) - +- No active_worker entry for this task - +- Original fast-advancing worker has already completed and exited - +- Resolution: - 1. TaskUpdate -> reset task to pending - 2. Remove stale active_worker entry (if any) - 3. Log via team_msg (type: error, summary: "Fast-advanced task failed, resetting for retry") - 4. -> handleSpawnNext (will re-spawn the task normally) -``` - -**Detection in handleResume**: - -``` -For each in_progress task in TaskList(): - +- Has matching active_worker? -> normal, skip - +- No matching active_worker? -> orphaned (likely fast-advance failure) - +- Check creation time: if > 5 minutes with no progress callback - +- Reset to pending -> handleSpawnNext -``` - -**Prevention**: Fast-advance failures are self-healing. The coordinator reconciles orphaned tasks on every `resume`/`check` cycle. No manual intervention required unless the same task fails repeatedly (3+ resets -> escalate to user). - -### Consensus-Blocked Handling - -When a produce role reports `consensus_blocked` in its callback: - -``` -handleCallback receives message with consensus_blocked flag - +- Extract: divergence_severity, blocked_round, action_recommendation - +- Route by severity: - | - +- severity = HIGH (rating <= 2 or critical risk) - | +- Is this DISCUSS-006 (final sign-off)? - | | +- YES -> PAUSE: output warning, wait for user `resume` with decision - | | +- NO -> Create REVISION task: - | | +- Same role, same doc type, incremented suffix (e.g., DRAFT-001-R1) - | | +- Description includes: divergence details + action items from discuss - | | +- blockedBy: none (immediate execution) - | | +- Max 1 revision per task (DRAFT-001 -> DRAFT-001-R1, no R2) - | | +- If already revised once -> PAUSE, escalate to user - | +- Update session: mark task as "revised", log revision chain - | - +- severity = MEDIUM (rating spread or single low rating) - | +- Proceed with warning: include divergence in next task's context - | +- Log action items to wisdom/issues.md for downstream awareness - | +- Normal handleSpawnNext - | - +- severity = LOW (minor suggestions only) - +- Proceed normally: treat as consensus_reached with notes - +- Normal handleSpawnNext -``` - -**Revision task template** (for HIGH severity): - -``` -TaskCreate({ - subject: "-R1", - description: "Revision of : address consensus-blocked divergences.\n - Session: \n - Original artifact: \n - Divergences:\n\n - Action items:\n\n - InlineDiscuss: ", - owner: "", - status: "pending" -}) -``` - -## Phase 4: Validation - -| Check | Criteria | -|-------|----------| -| Session state consistent | active_workers matches TaskList in_progress tasks | -| No orphaned tasks | Every in_progress task has an active_worker entry | -| Pipeline completeness | All expected tasks exist per mode | -| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE | -| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers | -| Fast-advance orphan check | in_progress tasks without active_worker entry -> reset to pending | -| Consensus-blocked routing | HIGH -> revision/pause, MEDIUM -> warn+proceed, LOW -> proceed | - -## 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 | -| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext | -| consensus_blocked HIGH | Create revision task (max 1) or pause for user | -| consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md | -| Revision task also blocked | Escalate to user, pause pipeline | diff --git a/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md b/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md deleted file mode 100644 index bba5a362..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md +++ /dev/null @@ -1,230 +0,0 @@ -# Coordinator Role - -Orchestrate the team-lifecycle workflow: team creation, task dispatching, progress monitoring, session state. Optimized for v4 reduced pipeline with inline discuss and shared explore. - -## Identity - -- **Name**: `coordinator` | **Tag**: `[coordinator]` -- **Responsibility**: Parse requirements -> Create team -> Dispatch tasks -> Monitor progress -> Report results - -## Boundaries - -### MUST -- Parse user requirements and clarify ambiguous inputs via AskUserQuestion -- Create team and spawn worker subagents in background -- Dispatch tasks with proper dependency chains (see SKILL.md Task Metadata Registry) -- Monitor progress via worker callbacks and route messages -- Maintain session state persistence (team-session.json) - -### MUST NOT -- Execute spec/impl/research work directly (delegate to workers) -- Modify task outputs (workers own their deliverables) -- Call implementation subagents (code-developer, etc.) directly -- Skip dependency validation when creating task chains - ---- - -## Command Execution Protocol - -When coordinator needs to execute a command (dispatch, monitor): - -1. **Read the command file**: `roles/coordinator/commands/.md` -2. **Follow the workflow** defined in the command file (Phase 2-4 structure) -3. **Commands are inline execution guides** - NOT separate agents or subprocesses -4. **Execute synchronously** - complete the command workflow before proceeding - -Example: -``` -Phase 3 needs task dispatch - -> Read roles/coordinator/commands/dispatch.md - -> Execute Phase 2 (Context Loading) - -> Execute Phase 3 (Task Chain Creation) - -> Execute Phase 4 (Validation) - -> Continue to Phase 4 -``` - ---- - -## Entry Router - -When coordinator is invoked, first detect the invocation type: - -| Detection | Condition | Handler | -|-----------|-----------|---------| -| Worker callback | Message contains `[role-name]` tag from a known worker role | -> handleCallback: auto-advance pipeline | -| Status check | Arguments contain "check" or "status" | -> handleCheck: output execution graph, no advancement | -| Manual resume | Arguments contain "resume" or "continue" | -> handleResume: check worker states, advance pipeline | -| Interrupted session | Active/paused session exists in `.workflow/.team/TLS-*` | -> Phase 0 (Session Resume Check) | -| New session | None of the above | -> Phase 1 (Requirement Clarification) | - -For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP. - -### Router Implementation - -1. **Load session context** (if exists): - - Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions - - If found, extract known worker roles from session or SKILL.md Role Registry - -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 Requirement Clarification below - ---- - -## Phase 0: Session Resume Check - -**Objective**: Detect and resume interrupted sessions before creating new ones. - -**Workflow**: -1. Scan `.workflow/.team/TLS-*/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 -> AskUserQuestion for user selection - -**Session Reconciliation**: -1. Audit TaskList -> get real status of all tasks -2. Reconcile: session.completed_tasks <-> TaskList status (bidirectional sync) -3. Reset any in_progress tasks -> pending (they were interrupted) -4. Determine remaining pipeline from reconciled state -5. Rebuild team if disbanded (TeamCreate + spawn needed workers only) -6. Create missing tasks with correct blockedBy dependencies -7. Verify dependency chain integrity -8. Update session file with reconciled state -9. Kick first executable task's worker -> Phase 4 - ---- - -## Phase 1: Requirement Clarification - -**Objective**: Parse user input and gather execution parameters. - -**Workflow**: - -1. **Parse arguments** for explicit settings: mode, scope, focus areas, depth - -2. **Ask for missing parameters** via AskUserQuestion: - - Mode: spec-only / impl-only / full-lifecycle / fe-only / fullstack / full-lifecycle-fe - - Scope: project description - - Execution method: sequential / parallel - -3. **Frontend auto-detection** (for impl-only and full-lifecycle modes): - - | Signal | Detection | Pipeline Upgrade | - |--------|----------|-----------------| - | FE keywords (component, page, UI, React, Vue, CSS...) | Keyword match in description | impl-only -> fe-only or fullstack | - | BE keywords also present (API, database, server...) | Both FE + BE keywords | impl-only -> fullstack | - | FE framework in package.json | grep react/vue/svelte/next | full-lifecycle -> full-lifecycle-fe | - -4. **Store requirements**: mode, scope, focus, depth, executionMethod - -**Success**: All parameters captured, mode finalized. - ---- - -## Phase 2: Create Team + Initialize Session - -**Objective**: Initialize team, session file, and wisdom directory. - -**Workflow**: -1. Generate session ID: `TLS--` -2. Create session folder: `.workflow/.team//` -3. Call TeamCreate with team name -4. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md) -5. Initialize explorations directory with empty cache-index.json -6. Write team-session.json with: session_id, mode, scope, status="active", tasks_total, tasks_completed=0 - -**Task counts by mode (v4)**: - -| Mode | Tasks | v3 Tasks | Savings | -|------|-------|----------|---------| -| spec-only | 6 | 12 | -6 (discuss inlined) | -| impl-only | 4 | 4 | 0 | -| fe-only | 3 | 3 | 0 | -| fullstack | 6 | 6 | 0 | -| full-lifecycle | 10 | 16 | -6 (discuss inlined) | -| full-lifecycle-fe | 12 | 18 | -6 (discuss inlined) | - -**Success**: Team created, session file written, wisdom and explorations initialized. - ---- - -## Phase 3: Create Task Chain - -**Objective**: Dispatch tasks based on mode with proper dependencies. - -Delegate to `commands/dispatch.md` which creates the full task chain: -1. Reads SKILL.md Task Metadata Registry for task definitions -2. Creates tasks via TaskCreate with correct blockedBy -3. Assigns owner based on role mapping -4. Includes `Session: ` in every task description -5. Marks inline discuss round in task description (e.g., `InlineDiscuss: DISCUSS-002`) - ---- - -## Phase 4: Spawn-and-Stop - -**Objective**: Spawn first batch of ready workers in background, then STOP. - -**Design**: Spawn-and-Stop + Callback pattern, with worker fast-advance. -- Spawn workers with `Task(run_in_background: true)` -> immediately return -- Worker completes -> may fast-advance to next task OR SendMessage callback -> auto-advance -- User can use "check" / "resume" to manually advance -- Coordinator does one operation per invocation, then STOPS - -**Workflow**: -1. Load `commands/monitor.md` -2. Find tasks with: status=pending, blockedBy all resolved, owner assigned -3. For each ready task -> spawn worker (see SKILL.md Spawn Template) -4. Output status summary -5. STOP - -**Pipeline advancement** driven by three wake sources: -- Worker callback (automatic) -> Entry Router -> handleCallback -- User "check" -> handleCheck (status only) -- User "resume" -> handleResume (advance) - -### Checkpoint Gate Handling - -When QUALITY-001 completes (spec->impl transition checkpoint): - -1. Read `/spec/readiness-report.md` -2. Parse quality gate: extract `Quality Gate:` line -> PASS/REVIEW/FAIL + score -3. Parse dimension scores: extract `Dimension Scores` table -4. Output Checkpoint Output Template (see SKILL.md Checkpoints) with gate-specific guidance -5. Write gate result to team-session.json: `checkpoint_gate: { gate, score, dimensions }` -6. Pause and wait for user command - -**Gate-specific behavior**: - -| Gate | Primary Suggestion | Warning | -|------|-------------------|---------| -| PASS (>=80%) | `resume` to proceed | None | -| REVIEW (60-79%) | `improve` or `revise` first | Warn on `resume`: "Quality below target, proceed at risk" | -| FAIL (<60%) | `improve` or `revise` required | Block `resume` suggestion, user can force | - ---- - -## Phase 5: Report + Next Steps - -**Objective**: Completion report and follow-up options. - -**Workflow**: -1. Load session state -> count completed tasks, duration -2. List deliverables with output paths -3. Update session status -> "completed" -4. Offer next steps: exit / view artifacts / extend tasks / generate lite-plan / create Issue - ---- - -## Error Handling - -| Error | Resolution | -|-------|------------| -| Task timeout | Log, mark failed, ask user to retry or skip | -| Worker crash | Respawn worker, reassign task | -| Dependency cycle | Detect, report to user, halt | -| Invalid mode | Reject with error, ask to clarify | -| Session corruption | Attempt recovery, fallback to manual reconciliation | diff --git a/.claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md b/.claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md deleted file mode 100644 index 26501c5e..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md +++ /dev/null @@ -1,166 +0,0 @@ -# Command: implement - -## Purpose - -Multi-backend code implementation: route tasks to appropriate execution backend (direct edit, subagent, or CLI), build focused prompts, execute with retry and fallback. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Plan | `/plan/plan.json` | Yes | -| Task files | `/plan/.task/TASK-*.json` | Yes | -| Backend | Task metadata / plan default / auto-select | Yes | -| Working directory | task.metadata.working_dir or project root | No | -| Wisdom | `/wisdom/` | No | - -## Phase 3: Implementation - -### Backend Selection - -Priority order (first match wins): - -| Priority | Source | Method | -|----------|--------|--------| -| 1 | Task metadata | `task.metadata.executor` field | -| 2 | Plan default | "Execution Backend:" line in plan.json | -| 3 | Auto-select | See auto-select table below | - -**Auto-select routing**: - -| Condition | Backend | -|-----------|---------| -| Description < 200 chars AND no refactor/architecture keywords AND single target file | agent (direct edit) | -| Description < 200 chars AND simple scope | agent (subagent) | -| Complex scope OR architecture keywords | codex | -| Analysis-heavy OR multi-module integration | gemini | - -### Execution Paths - -``` -Backend selected - ├─ agent (direct edit) - │ └─ Read target file → Edit directly → no subagent overhead - ├─ agent (subagent) - │ └─ Task({ subagent_type: "code-developer", run_in_background: false }) - ├─ codex (CLI) - │ └─ Bash(command="ccw cli ... --tool codex --mode write", run_in_background=true) - └─ gemini (CLI) - └─ Bash(command="ccw cli ... --tool gemini --mode write", run_in_background=true) -``` - -### Path 1: Direct Edit (agent, simple task) - -```bash -Read(file_path="") -Edit(file_path="", old_string="", new_string="") -``` - -### Path 2: Subagent (agent, moderate task) - -``` -Task({ - subagent_type: "code-developer", - run_in_background: false, - description: "Implement ", - prompt: "" -}) -``` - -### Path 3: CLI Backend (codex or gemini) - -```bash -Bash(command="ccw cli -p '' --tool --mode write --cd ", run_in_background=true) -``` - -### Execution Prompt Template - -All backends receive the same structured prompt: - -``` -# Implementation Task: - -## Task Description - - -## Acceptance Criteria -1. - -## Context from Plan - - - - -## Files to Modify - - -## Constraints -- Follow existing code style and patterns -- Preserve backward compatibility -- Add appropriate error handling -- Include inline comments for complex logic -``` - -### Batch Execution - -When multiple IMPL tasks exist, execute in dependency order: - -``` -Topological sort by task.depends_on - ├─ Batch 1: Tasks with no dependencies → execute - ├─ Batch 2: Tasks depending on batch 1 → execute - └─ Batch N: Continue until all tasks complete - -Progress update per batch (when > 1 batch): - → team_msg: "Processing batch /: " -``` - -### Retry and Fallback - -**Retry** (max 3 attempts per task): - -``` -Attempt 1 → failure - ├─ team_msg: "Retry 1/3 after error: " - └─ Attempt 2 → failure - ├─ team_msg: "Retry 2/3 after error: " - └─ Attempt 3 → failure → fallback - -``` - -**Fallback** (when primary backend fails after retries): - -| Primary Backend | Fallback | -|----------------|----------| -| codex | agent (subagent) | -| gemini | agent (subagent) | -| agent (subagent) | Report failure to coordinator | -| agent (direct edit) | agent (subagent) | - -## Phase 4: Validation - -### Self-Validation Steps - -| Step | Method | Pass Criteria | -|------|--------|--------------| -| Syntax check | `Bash(command="tsc --noEmit", timeout=30000)` | Exit code 0 | -| Acceptance match | Check criteria keywords vs modified files | All criteria addressed | -| Test detection | Search for .test.ts/.spec.ts matching modified files | Tests identified | -| File changes | `Bash(command="git diff --name-only HEAD")` | At least 1 file modified | - -### Result Routing - -| Outcome | Message Type | Content | -|---------|-------------|---------| -| All tasks pass validation | impl_complete | Task ID, files modified, backend used | -| Batch progress | impl_progress | Batch index, total batches, current task | -| Validation failure after retries | error | Task ID, error details, retry count | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Syntax errors after implementation | Retry with error context (max 3) | -| Backend unavailable | Fallback to agent | -| Missing dependencies | Request from coordinator | -| All retries + fallback exhausted | Report failure with full error log | diff --git a/.claude/skills/team-lifecycle-v4/roles/executor/role.md b/.claude/skills/team-lifecycle-v4/roles/executor/role.md deleted file mode 100644 index 0cd3296f..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/executor/role.md +++ /dev/null @@ -1,103 +0,0 @@ -# Role: executor - -Code implementation following approved plans. Multi-backend execution with self-validation. - -## Identity - -- **Name**: `executor` | **Prefix**: `IMPL-*` | **Tag**: `[executor]` -- **Responsibility**: Load plan → Route to backend → Implement → Self-validate → Report - -## Boundaries - -### MUST -- Only process IMPL-* tasks -- Follow approved plan exactly -- Use declared execution backends -- Self-validate all implementations - -### MUST NOT -- Create tasks -- Contact other workers directly -- Modify plan files -- Skip self-validation - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| impl_complete | → coordinator | Implementation success | -| impl_progress | → coordinator | Batch progress | -| error | → coordinator | Implementation failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/implement.md | Multi-backend implementation | -| code-developer agent | Simple tasks (synchronous) | -| ccw cli --tool codex --mode write | Complex tasks | -| ccw cli --tool gemini --mode write | Alternative backend | - ---- - -## Phase 2: Task & Plan Loading - -**Objective**: Load plan and determine execution strategy. - -1. Load plan.json and .task/TASK-*.json from `/plan/` - -**Backend selection** (priority order): - -| Priority | Source | Method | -|----------|--------|--------| -| 1 | Task metadata | task.metadata.executor field | -| 2 | Plan default | "Execution Backend:" in plan | -| 3 | Auto-select | Simple (< 200 chars, no refactor) → agent; Complex → codex | - -**Code review selection**: - -| Priority | Source | Method | -|----------|--------|--------| -| 1 | Task metadata | task.metadata.code_review field | -| 2 | Plan default | "Code Review:" in plan | -| 3 | Auto-select | Critical keywords (auth, security, payment) → enabled | - ---- - -## Phase 3: Code Implementation - -**Objective**: Execute implementation across batches. - -**Batching**: Topological sort by IMPL task dependencies → sequential batches. - -Delegate to `commands/implement.md` for prompt building and backend routing: - -| Backend | Invocation | Use Case | -|---------|-----------|----------| -| agent | Task({ subagent_type: "code-developer", run_in_background: false }) | Simple, direct edits | -| codex | ccw cli --tool codex --mode write (background) | Complex, architecture | -| gemini | ccw cli --tool gemini --mode write (background) | Analysis-heavy | - ---- - -## Phase 4: Self-Validation - -| Step | Method | Pass Criteria | -|------|--------|--------------| -| Syntax check | `tsc --noEmit` (30s) | Exit code 0 | -| Acceptance criteria | Match criteria keywords vs implementation | All addressed | -| Test detection | Find .test.ts/.spec.ts for modified files | Tests identified | -| Code review (optional) | gemini analysis or codex review | No blocking issues | - -**Report**: task ID, status, files modified, validation results, backend used. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Syntax errors | Retry with error context (max 3) | -| Missing dependencies | Request from coordinator | -| Backend unavailable | Fallback to agent | -| Circular dependencies | Abort, report graph | diff --git a/.claude/skills/team-lifecycle-v4/roles/fe-developer/role.md b/.claude/skills/team-lifecycle-v4/roles/fe-developer/role.md deleted file mode 100644 index b23f4f1d..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/fe-developer/role.md +++ /dev/null @@ -1,111 +0,0 @@ -# Role: fe-developer - -Frontend development. Consumes plan/architecture output, implements components, pages, styles. - -## Identity - -- **Name**: `fe-developer` | **Prefix**: `DEV-FE-*` | **Tag**: `[fe-developer]` -- **Type**: Frontend pipeline worker -- **Responsibility**: Context loading → Design token consumption → Component implementation → Report - -## Boundaries - -### MUST -- Only process DEV-FE-* tasks -- Follow existing design tokens and component specs (if available) -- Generate accessible frontend code (semantic HTML, ARIA, keyboard nav) -- Follow project's frontend tech stack - -### MUST NOT -- Modify backend code or API interfaces -- Contact other workers directly -- Introduce new frontend dependencies without architecture review - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| dev_fe_complete | → coordinator | Implementation done | -| dev_fe_progress | → coordinator | Long task progress | -| error | → coordinator | Implementation failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| code-developer agent | Component implementation | -| ccw cli --tool gemini --mode write | Complex frontend generation | - ---- - -## Phase 2: Context Loading - -**Inputs to load**: -- Plan: `/plan/plan.json` -- Design tokens: `/architecture/design-tokens.json` (optional) -- Design intelligence: `/analysis/design-intelligence.json` (optional) -- Component specs: `/architecture/component-specs/*.md` (optional) -- Shared memory, wisdom - -**Tech stack detection**: - -| Signal | Framework | Styling | -|--------|-----------|---------| -| react/react-dom in deps | react | - | -| vue in deps | vue | - | -| next in deps | nextjs | - | -| tailwindcss in deps | - | tailwind | -| @shadcn/ui in deps | - | shadcn | - ---- - -## Phase 3: Frontend Implementation - -**Step 1**: Generate design token CSS (if tokens available) -- Convert design-tokens.json → CSS custom properties (`:root { --color-*, --space-*, --text-* }`) -- Include dark mode overrides via `@media (prefers-color-scheme: dark)` -- Write to `src/styles/tokens.css` - -**Step 2**: Implement components - -| Task Size | Strategy | -|-----------|----------| -| Simple (≤ 3 files, single component) | code-developer agent (synchronous) | -| Complex (system, multi-component) | ccw cli --tool gemini --mode write (background) | - -**Coding standards** (include in agent/CLI prompt): -- Use design token CSS variables, never hardcode colors/spacing -- Interactive elements: cursor: pointer -- Transitions: 150-300ms -- Text contrast: minimum 4.5:1 -- Include focus-visible styles -- Support prefers-reduced-motion -- Responsive: mobile-first -- No emoji as functional icons - ---- - -## Phase 4: Self-Validation - -| Check | What | -|-------|------| -| hardcoded-color | No #hex outside tokens.css | -| cursor-pointer | Interactive elements have cursor: pointer | -| focus-styles | Interactive elements have focus styles | -| responsive | Has responsive breakpoints | -| reduced-motion | Animations respect prefers-reduced-motion | -| emoji-icon | No emoji as functional icons | - -Contribute to wisdom/conventions.md. Update shared-memory.json with component inventory. - -**Report**: file count, framework, design token usage, self-validation results. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Design tokens not found | Use project defaults | -| Tech stack undetected | Default HTML + CSS | -| Subagent failure | Fallback to CLI write mode | diff --git a/.claude/skills/team-lifecycle-v4/roles/fe-qa/commands/pre-delivery-checklist.md b/.claude/skills/team-lifecycle-v4/roles/fe-qa/commands/pre-delivery-checklist.md deleted file mode 100644 index c742380d..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/fe-qa/commands/pre-delivery-checklist.md +++ /dev/null @@ -1,152 +0,0 @@ -# Command: pre-delivery-checklist - -## Purpose - -CSS-level pre-delivery checks for frontend files. Validates accessibility, interaction, design compliance, and layout patterns before final delivery. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Changed frontend files | git diff --name-only (filtered to .tsx, .jsx, .css, .scss) | Yes | -| File contents | Read each changed file | Yes | -| Design tokens path | `src/styles/tokens.css` or equivalent | No | -| Session folder | Task description `Session:` field | Yes | - -## Phase 3: Checklist Execution - -### Category 1: Accessibility (6 items) - -| # | Check | Pattern to Detect | Severity | -|---|-------|--------------------|----------| -| 1 | Images have alt text | `500ms or <100ms transitions | -| 9 | Show skeleton/spinner during fetch | Leave blank screen while loading | -| 10 | Show user-friendly error message | Silently fail or show raw error | - ---- - -### Category 3: Design Compliance (4 items) - -| # | Check | Pattern to Detect | Severity | -|---|-------|--------------------|----------| -| 11 | No hardcoded colors | Hex values (`#XXXXXX`) outside tokens file | HIGH | -| 12 | No hardcoded spacing | Raw `px` values for margin/padding | MEDIUM | -| 13 | No emoji as icons | Unicode emoji (U+1F300-1F9FF) in UI code | HIGH | -| 14 | Dark mode support | No `prefers-color-scheme` or `.dark` class | MEDIUM | - -**Do / Don't**: - -| # | Do | Don't | -|---|-----|-------| -| 11 | Use `var(--color-*)` design tokens | Hardcode `#hex` values | -| 12 | Use `var(--space-*)` spacing tokens | Hardcode pixel values | -| 13 | Use proper SVG/icon library | Use emoji for functional icons | -| 14 | Support light/dark themes | Design for light mode only | - ---- - -### Category 4: Layout (2 items) - -| # | Check | Pattern to Detect | Severity | -|---|-------|--------------------|----------| -| 15 | Responsive breakpoints | No `md:`/`lg:`/`@media` queries | MEDIUM | -| 16 | No horizontal scroll | Fixed widths greater than viewport | HIGH | - -**Do / Don't**: - -| # | Do | Don't | -|---|-----|-------| -| 15 | Mobile-first responsive design | Desktop-only layout | -| 16 | Use relative/fluid widths | Set fixed pixel widths on containers | - ---- - -### Check Execution Strategy - -| Check Scope | Applies To | Method | -|-------------|-----------|--------| -| Per-file checks | Items 1-4, 7-8, 10-13, 16 | Run against each changed file individually | -| Global checks | Items 5-6, 9, 14-15 | Run against concatenated content of all files | - -**Detection example** (check for hardcoded colors): - -```bash -Grep(pattern="#[0-9a-fA-F]{6}", path="", output_mode="content", "-n"=true) -``` - -**Detection example** (check for missing alt text): - -```bash -Grep(pattern="]*alt=)", path="", output_mode="content", "-n"=true) -``` - -## Phase 4: Validation - -### Pass/Fail Criteria - -| Condition | Result | -|-----------|--------| -| Zero CRITICAL + zero HIGH failures | PASS | -| Zero CRITICAL, some HIGH | CONDITIONAL (list fixes needed) | -| Any CRITICAL failure | FAIL | - -### Output Format - -``` -## Pre-Delivery Checklist Results - -- Total checks: -- Passed: / -- Failed: - -### Failed Items -- [CRITICAL] #1 Images have alt text -- -- [HIGH] #11 No hardcoded colors -- : -- [MEDIUM] #7 cursor-pointer on clickable -- - -### Recommendations -(Do/Don't guidance for each failed item) -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| No frontend files to check | Report empty checklist, all checks N/A | -| File read error | Skip file, note in report | -| Regex match error | Skip check, note in report | -| Design tokens file not found | Skip items 11-12, adjust total | diff --git a/.claude/skills/team-lifecycle-v4/roles/fe-qa/role.md b/.claude/skills/team-lifecycle-v4/roles/fe-qa/role.md deleted file mode 100644 index 8e91131c..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/fe-qa/role.md +++ /dev/null @@ -1,113 +0,0 @@ -# Role: fe-qa - -Frontend quality assurance. 5-dimension review + Generator-Critic loop. - -## Identity - -- **Name**: `fe-qa` | **Prefix**: `QA-FE-*` | **Tag**: `[fe-qa]` -- **Type**: Frontend pipeline worker -- **Responsibility**: Context loading → 5-dimension review → GC feedback → Report - -## Boundaries - -### MUST -- Only process QA-FE-* tasks -- Execute 5-dimension review -- Support Generator-Critic loop (max 2 rounds) -- Provide actionable fix suggestions (Do/Don't format) - -### MUST NOT -- Modify source code directly (review only) -- Contact other workers directly -- Mark pass when score below threshold - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| qa_fe_passed | → coordinator | All dimensions pass | -| qa_fe_result | → coordinator | Review complete (may have issues) | -| fix_required | → coordinator | Critical issues found | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/pre-delivery-checklist.md | CSS-level delivery checks | -| ccw cli --tool gemini --mode analysis | Frontend code review | -| ccw cli --tool codex --mode review | Git-aware code review | - ---- - -## Review Dimensions - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Code Quality | 25% | TypeScript types, component structure, error handling | -| Accessibility | 25% | Semantic HTML, ARIA, keyboard nav, contrast, focus-visible | -| Design Compliance | 20% | Token usage, no hardcoded colors, no emoji icons | -| UX Best Practices | 15% | Loading/error/empty states, cursor-pointer, responsive | -| Pre-Delivery | 15% | No console.log, dark mode, i18n readiness | - ---- - -## Phase 2: Context Loading - -**Inputs**: design tokens, design intelligence, shared memory, previous QA results (for GC round tracking), changed frontend files via git diff. - -Determine GC round from previous QA results count. Max 2 rounds. - ---- - -## Phase 3: 5-Dimension Review - -For each changed frontend file, check against all 5 dimensions. Score each dimension 0-10, deducting for issues found. - -**Scoring deductions**: - -| Severity | Deduction | -|----------|-----------| -| High | -2 to -3 | -| Medium | -1 to -1.5 | -| Low | -0.5 | - -**Overall score** = weighted sum of dimension scores. - -**Verdict routing**: - -| Condition | Verdict | -|-----------|---------| -| Score ≥ 8 AND no critical issues | PASS | -| GC round ≥ max AND score ≥ 6 | PASS_WITH_WARNINGS | -| GC round ≥ max AND score < 6 | FAIL | -| Otherwise | NEEDS_FIX | - ---- - -## Phase 4: Report - -Write audit to `/qa/audit-fe--r.json`. Update wisdom and shared memory. - -**Report**: round, verdict, overall score, dimension scores, critical issues with Do/Don't format, action required (if NEEDS_FIX). - ---- - -## Generator-Critic Loop - -Orchestrated by coordinator: -``` -Round 1: DEV-FE-001 → QA-FE-001 - if NEEDS_FIX → coordinator creates DEV-FE-002 + QA-FE-002 -Round 2: DEV-FE-002 → QA-FE-002 - if still NEEDS_FIX → PASS_WITH_WARNINGS or FAIL (max 2) -``` - -**Convergence**: score ≥ 8 AND critical_count = 0 - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| No changed files | Report empty, score N/A | -| Design tokens not found | Skip design compliance, adjust weights | -| Max GC rounds exceeded | Force verdict | diff --git a/.claude/skills/team-lifecycle-v4/roles/planner/commands/explore.md b/.claude/skills/team-lifecycle-v4/roles/planner/commands/explore.md deleted file mode 100644 index e95f32d4..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/planner/commands/explore.md +++ /dev/null @@ -1,172 +0,0 @@ -# Command: explore - -## Purpose - -Complexity-driven codebase exploration using shared explore subagent with centralized cache. v4 optimized: checks cache before exploring, avoids duplicate work across roles. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | PLAN-* task subject/description | Yes | -| Session folder | Task description `Session:` field | Yes | -| Spec context | `/spec/` (if exists) | No | -| Plan directory | `/plan/` | Yes (create if missing) | -| Project tech | `.workflow/project-tech.json` | No | -| Cache index | `/explorations/cache-index.json` | No (create if missing) | - -## Phase 3: Exploration - -### Complexity Assessment - -Score the task description against keyword indicators: - -| Indicator | Keywords | Score | -|-----------|----------|-------| -| Structural change | refactor, architect, restructure, modular | +2 | -| Multi-scope | multiple, across, cross-cutting | +2 | -| Integration | integrate, api, database | +1 | -| Non-functional | security, performance, auth | +1 | - -**Complexity routing**: - -| Score | Level | Strategy | Angle Count | -|-------|-------|----------|-------------| -| 0-1 | Low | ACE semantic search only | 1 | -| 2-3 | Medium | Explore subagent per angle | 2-3 | -| 4+ | High | Explore subagent per angle | 3-5 | - -### Angle Presets - -Select preset by dominant keyword match, then take first N angles per complexity: - -| Preset | Trigger Keywords | Angles (priority order) | -|--------|-----------------|------------------------| -| architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points | -| security | security, auth, permission, access | security, auth-patterns, dataflow, validation | -| performance | performance, slow, optimize, cache | performance, bottlenecks, caching, data-access | -| bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases | -| feature | (default) | patterns, integration-points, testing, dependencies | - -### Cache-First Strategy (v4 new) - -Before launching any exploration, check the shared cache: - -``` -1. Read /explorations/cache-index.json -2. For each selected angle: - a. If angle exists in cache -> SKIP (reuse cached result) - b. If angle not in cache -> explore via subagent -3. Only explore uncached angles -``` - -This avoids duplicating work done by analyst's `general` exploration or any prior role. - -### Low Complexity: Direct Search - -```bash -mcp__ace-tool__search_context(project_root_path="", query="") -``` - -Transform results into exploration JSON and write to `/explorations/explore-general.json`. -Update cache-index.json. - -**ACE failure fallback**: - -```bash -Bash(command="rg -l '' --type ts", timeout=30000) -``` - -### Medium/High Complexity: Explore Subagent per Angle - -For each uncached angle, call the shared explore subagent: - -``` -Task({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore: ", - prompt: "Explore codebase for: -Focus angle: -Keywords: -Session folder: - -## Cache Check -1. Read /explorations/cache-index.json (if exists) -2. Look for entry with matching angle -3. If found AND file exists -> read cached result, return summary -4. If not found -> proceed to exploration - -## Exploration Focus - - -## Output -Write JSON to: /explorations/explore-.json -Update cache-index.json with new entry -Each file in relevant_files MUST have: rationale (>10 chars), role, discovery_source, key_symbols" -}) -``` - -### Angle Focus Guide - -| Angle | Focus Points | -|-------|-------------| -| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | -| dependencies | Import chains, external libraries, circular dependencies, shared utilities | -| modularity | Module interfaces, separation of concerns, extraction opportunities | -| integration-points | API endpoints, data flow between modules, event systems, service integrations | -| security | Auth/authz logic, input validation, sensitive data handling, middleware | -| auth-patterns | Auth flows (login/refresh), session management, token validation, permissions | -| dataflow | Data transformations, state propagation, validation points, mutation paths | -| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | -| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | -| patterns | Code conventions, design patterns, naming conventions, best practices | -| testing | Test files, coverage gaps, test patterns (unit/integration/e2e), mocking | - -### Explorations Manifest - -After all explorations complete (both cached and new), write manifest to `/plan/explorations-manifest.json`: - -```json -{ - "task_description": "", - "complexity": "", - "exploration_count": "", - "cached_count": "", - "explorations": [ - { "angle": "", "file": "../explorations/explore-.json", "source": "cached|new" } - ] -} -``` - -## Phase 4: Validation - -### Output Files - -``` -/explorations/ (shared cache) - +- cache-index.json (updated) - +- explore-.json (per angle) - -/plan/ - +- explorations-manifest.json (summary referencing shared cache) -``` - -### Success Criteria - -| Check | Criteria | Required | -|-------|----------|----------| -| At least 1 exploration | Non-empty exploration file exists | Yes | -| Manifest written | explorations-manifest.json exists | Yes | -| File roles assigned | Every relevant_file has role + rationale | Yes | -| Cache updated | cache-index.json reflects all explorations | Yes | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Single exploration agent fails | Skip angle, remove from manifest, continue | -| All explorations fail | Proceed to plan generation with task description only | -| ACE search fails (Low) | Fallback to ripgrep keyword search | -| Schema file not found | Use inline schema from Output section | -| Cache index corrupt | Reset cache-index.json to empty, re-explore all | diff --git a/.claude/skills/team-lifecycle-v4/roles/planner/role.md b/.claude/skills/team-lifecycle-v4/roles/planner/role.md deleted file mode 100644 index a8815bc8..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/planner/role.md +++ /dev/null @@ -1,139 +0,0 @@ -# Role: planner - -Multi-angle code exploration and structured implementation planning. -Uses **Inner Loop** pattern for consistency (currently single PLAN-* task, extensible). - -## Identity - -- **Name**: `planner` | **Prefix**: `PLAN-*` | **Tag**: `[planner]` -- **Mode**: Inner Loop -- **Responsibility**: Complexity assessment -> Code exploration (shared cache) -> Plan generation -> Approval - -## Boundaries - -### MUST -- Only process PLAN-* tasks -- Assess complexity before planning -- Use shared explore subagent for codebase exploration (cache-aware) -- Generate plan.json + .task/TASK-*.json -- Load spec context in full-lifecycle mode -- Submit plan for coordinator approval - -### MUST NOT -- Create tasks for other roles -- Implement code -- Modify spec documents -- Skip complexity assessment - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| plan_ready | -> coordinator | Plan complete | -| plan_revision | -> coordinator | Plan revised per feedback | -| error | -> coordinator | Exploration or planning failure | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/explore.md | Complexity-driven exploration via shared explore subagent | -| Explore subagent | Per-angle exploration (shared cache) | -| cli-lite-planning-agent | Plan generation | - ---- - -## Phase 1.5: Load Spec Context (Full-Lifecycle) - -If `/spec/` exists -> load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise -> impl-only mode. - -**Check shared explorations**: Read `/explorations/cache-index.json` to see if analyst already cached useful explorations. Reuse rather than re-explore. - ---- - -## Phase 2: Multi-Angle Exploration - -**Objective**: Explore codebase to inform planning. - -**Complexity routing**: - -| Complexity | Criteria | Strategy | -|------------|----------|----------| -| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only | -| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent | -| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent | - -Delegate to `commands/explore.md` for angle selection and execution. - -**Key v4 change**: All explorations go through the shared explore subagent with cache. Before launching an exploration for an angle, check cache-index.json -- if analyst or another role already explored that angle, reuse the cached result. - ---- - -## Phase 3: Plan Generation - -**Objective**: Generate structured implementation plan. - -| Complexity | Strategy | -|------------|----------| -| Low | Direct planning -> single TASK-001 with plan.json | -| Medium/High | cli-lite-planning-agent with exploration results | - -**Agent call** (Medium/High): - -``` -Task({ - subagent_type: "cli-lite-planning-agent", - run_in_background: false, - description: "Generate implementation plan", - prompt: "Generate plan. -Output: /plan.json + /.task/TASK-*.json -Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json -Task: -Explorations: -Complexity: -Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on" -}) -``` - -**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition. - ---- - -## Phase 4: Submit for Approval - -1. Read plan.json and TASK-*.json -2. Report to coordinator: complexity, task count, task list, approach, plan location -3. Wait for response: approved -> complete; revision -> update and resubmit - -**Session files**: -``` -/explorations/ (shared cache, written by explore subagent) -+-- cache-index.json -+-- explore-.json - -/plan/ -+-- explorations-manifest.json (summary, references ../explorations/) -+-- plan.json -+-- .task/TASK-*.json -``` - ---- - -## Phase 5: Report (Inner Loop) - -Currently planner only has PLAN-001, so it directly executes Phase 5-F (Final Report). -If future extensions add multiple PLAN-* tasks, Phase 5-L loop activates automatically: -- Phase 5-L: Mark task completed, accumulate summary, loop back to Phase 1 -- Phase 5-F: All PLAN-* done, send final report to coordinator with full summary - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Exploration agent failure | Plan from description only | -| Planning agent failure | Fallback to direct planning | -| Plan rejected 3+ times | Notify coordinator, suggest alternative | -| Schema not found | Use basic structure | -| Cache index corrupt | Clear cache, re-explore all angles | diff --git a/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/code-review.md b/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/code-review.md deleted file mode 100644 index 874c4f98..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/code-review.md +++ /dev/null @@ -1,163 +0,0 @@ -# Command: code-review - -## Purpose - -4-dimension code review analyzing quality, security, architecture, and requirements compliance. Produces a verdict (BLOCK/CONDITIONAL/APPROVE) with categorized findings. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Plan file | `/plan/plan.json` | Yes | -| Git diff | `git diff HEAD~1` or `git diff --cached` | Yes | -| Modified files | From git diff --name-only | Yes | -| Test results | Tester output (if available) | No | -| Wisdom | `/wisdom/` | No | - -## Phase 3: 4-Dimension Review - -### Dimension Overview - -| Dimension | Focus | Weight | -|-----------|-------|--------| -| Quality | Code correctness, type safety, clean code | Equal | -| Security | Vulnerability patterns, secret exposure | Equal | -| Architecture | Module structure, coupling, file size | Equal | -| Requirements | Acceptance criteria coverage, completeness | Equal | - ---- - -### Dimension 1: Quality - -Scan each modified file for quality anti-patterns. - -| Severity | Pattern | What to Detect | -|----------|---------|----------------| -| Critical | Empty catch blocks | `catch(e) {}` with no handling | -| High | @ts-ignore without justification | Suppression comment < 10 chars explanation | -| High | `any` type in public APIs | `any` outside comments and generic definitions | -| High | console.log in production | `console.(log\|debug\|info)` outside test files | -| Medium | Magic numbers | Numeric literals > 1 digit, not in const/comment | -| Medium | Duplicate code | Identical lines (>30 chars) appearing 3+ times | - -**Detection example** (Grep for console statements): - -```bash -Grep(pattern="console\\.(log|debug|info)", path="", output_mode="content", "-n"=true) -``` - ---- - -### Dimension 2: Security - -Scan for vulnerability patterns across all modified files. - -| Severity | Pattern | What to Detect | -|----------|---------|----------------| -| Critical | Hardcoded secrets | `api_key=`, `password=`, `secret=`, `token=` with string values (20+ chars) | -| Critical | SQL injection | String concatenation in `query()`/`execute()` calls | -| High | eval/exec usage | `eval()`, `new Function()`, `setTimeout(string)` | -| High | XSS vectors | `innerHTML`, `dangerouslySetInnerHTML` | -| Medium | Insecure random | `Math.random()` in security context (token/key/password/session) | -| Low | Missing input validation | Functions with parameters but no validation in first 5 lines | - ---- - -### Dimension 3: Architecture - -Assess structural health of modified files. - -| Severity | Pattern | What to Detect | -|----------|---------|----------------| -| Critical | Circular dependencies | File A imports B, B imports A | -| High | Excessive parent imports | Import traverses >2 parent directories (`../../../`) | -| Medium | Large files | Files exceeding 500 lines | -| Medium | Tight coupling | >5 imports from same base module | -| Medium | Long functions | Functions exceeding 50 lines | -| Medium | Module boundary changes | Modifications to index.ts/index.js files | - -**Detection example** (check for deep parent imports): - -```bash -Grep(pattern="from\\s+['\"](\\.\\./){3,}", path="", output_mode="content", "-n"=true) -``` - ---- - -### Dimension 4: Requirements - -Verify implementation against plan acceptance criteria. - -| Severity | Check | Method | -|----------|-------|--------| -| High | Unmet acceptance criteria | Extract criteria from plan, check keyword overlap (threshold: 70%) | -| High | Missing error handling | Plan mentions "error handling" but no try/catch in code | -| Medium | Partially met criteria | Keyword overlap 40-69% | -| Medium | Missing tests | Plan mentions "test" but no test files in modified set | - -**Verification flow**: -1. Read plan file → extract acceptance criteria section -2. For each criterion → extract keywords (4+ char meaningful words) -3. Search modified files for keyword matches -4. Score: >= 70% match = met, 40-69% = partial, < 40% = unmet - ---- - -### Verdict Routing - -| Verdict | Criteria | Action | -|---------|----------|--------| -| BLOCK | Any critical-severity issues found | Must fix before merge | -| CONDITIONAL | High or medium issues, no critical | Should address, can merge with tracking | -| APPROVE | Only low issues or none | Ready to merge | - -## Phase 4: Validation - -### Report Format - -The review report follows this structure: - -``` -# Code Review Report - -**Verdict**: - -## Blocking Issues (if BLOCK) -- **** (:): - -## Review Dimensions - -### Quality Issues -**CRITICAL** () -- (:) - -### Security Issues -(same format per severity) - -### Architecture Issues -(same format per severity) - -### Requirements Issues -(same format per severity) - -## Recommendations -1. -``` - -### Summary Counts - -| Field | Description | -|-------|-------------| -| Total issues | Sum across all dimensions and severities | -| Critical count | Must be 0 for APPROVE | -| Blocking issues | Listed explicitly in report header | -| Dimensions covered | Must be 4/4 | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Plan file not found | Skip requirements dimension, note in report | -| Git diff empty | Report no changes to review | -| File read fails | Skip file, note in report | -| No modified files | Report empty review | diff --git a/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/spec-quality.md b/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/spec-quality.md deleted file mode 100644 index 3dfddc6f..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/spec-quality.md +++ /dev/null @@ -1,202 +0,0 @@ -# Command: spec-quality - -## Purpose - -5-dimension spec quality check with weighted scoring, quality gate determination, and readiness report generation. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Spec documents | `/spec/` (all .md files) | Yes | -| Original requirements | Product brief objectives section | Yes | -| Quality gate config | specs/quality-gates.md | No | -| Session folder | Task description `Session:` field | Yes | - -**Spec document phases** (matched by filename/directory): - -| Phase | Expected Path | Required | -|-------|--------------|---------| -| product-brief | spec/product-brief.md | Yes | -| prd | spec/requirements/*.md | Yes | -| architecture | spec/architecture/_index.md + ADR-*.md | Yes | -| user-stories | spec/epics/*.md | Yes | -| implementation-plan | plan/plan.json | No (impl-only/full-lifecycle) | -| test-strategy | spec/test-strategy.md | No (optional, not generated by pipeline) | - -## Phase 3: 5-Dimension Scoring - -### Dimension Weights - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Completeness | 25% | All required sections present with substance | -| Consistency | 20% | Terminology, format, references, naming | -| Traceability | 25% | Goals -> Reqs -> Components -> Stories chain | -| Depth | 20% | AC testable, ADRs justified, stories estimable | -| Coverage | 10% | Original requirements mapped to spec | - ---- - -### Dimension 1: Completeness (25%) - -Check each spec document for required sections. - -**Required sections by phase**: - -| Phase | Required Sections | -|-------|------------------| -| product-brief | Vision Statement, Problem Statement, Target Audience, Success Metrics, Constraints | -| prd | Goals, Requirements, User Stories, Acceptance Criteria, Non-Functional Requirements | -| architecture | System Overview, Component Design, Data Models, API Specifications, Technology Stack | -| user-stories | Story List, Acceptance Criteria, Priority, Estimation | -| implementation-plan | Task Breakdown, Dependencies, Timeline, Resource Allocation | - -> **Note**: `test-strategy` is optional — skip scoring if `spec/test-strategy.md` is absent. Do not penalize completeness score for missing optional phases. - -**Scoring formula**: -- Section present: 50% credit -- Section has substantial content (>100 chars beyond header): additional 50% credit -- Per-document score = (present_ratio * 50) + (substantial_ratio * 50) -- Overall = average across all documents - ---- - -### Dimension 2: Consistency (20%) - -Check cross-document consistency across four areas. - -| Area | What to Check | Severity | -|------|--------------|----------| -| Terminology | Same concept with different casing/spelling across docs | Medium | -| Format | Mixed header styles at same level across docs | Low | -| References | Broken links (`./` or `../` paths that don't resolve) | High | -| Naming | Mixed naming conventions (camelCase vs snake_case vs kebab-case) | Low | - -**Scoring**: -- Penalty weights: High = 10, Medium = 5, Low = 2 -- Score = max(0, 100 - (total_penalty / 100) * 100) - ---- - -### Dimension 3: Traceability (25%) - -Build and validate traceability chains: Goals -> Requirements -> Components -> Stories. - -**Chain building flow**: -1. Extract goals from product-brief (pattern: `- Goal: `) -2. Extract requirements from PRD (pattern: `- REQ-NNN: `) -3. Extract components from architecture (pattern: `- Component: `) -4. Extract stories from user-stories (pattern: `- US-NNN: `) -5. Link by keyword overlap (threshold: 30% keyword match) - -**Chain completeness**: A chain is complete when a goal links to at least one requirement, one component, and one story. - -**Scoring**: (complete chains / total chains) * 100 - -**Weak link identification**: For each incomplete chain, report which link is missing (no requirements, no components, or no stories). - ---- - -### Dimension 4: Depth (20%) - -Assess the analytical depth of spec content across four sub-dimensions. - -| Sub-dimension | Source | Testable Criteria | -|---------------|--------|-------------------| -| AC Testability | PRD / User Stories | Contains measurable verbs (display, return, validate) or Given/When/Then or numbers | -| ADR Justification | Architecture | Contains rationale, alternatives, consequences, or trade-offs | -| Story Estimability | User Stories | Has "As a/I want/So that" + AC, or explicit estimate | -| Technical Detail | Architecture + Plan | Contains code blocks, API terms, HTTP methods, DB terms | - -**Scoring**: Average of sub-dimension scores (each 0-100%) - ---- - -### Dimension 5: Coverage (10%) - -Map original requirements to spec requirements. - -**Flow**: -1. Extract original requirements from product-brief objectives section -2. Extract spec requirements from all documents (pattern: `- REQ-NNN:` or `- Requirement:` or `- Feature:`) -3. For each original requirement, check keyword overlap with any spec requirement (threshold: 40%) -4. Score = (covered_count / total_original) * 100 - ---- - -### Quality Gate Decision Table - -| Gate | Criteria | Message | -|------|----------|---------| -| PASS | Overall score >= 80% AND coverage >= 70% | Ready for implementation | -| FAIL | Overall score < 60% OR coverage < 50% | Major revisions required | -| REVIEW | All other cases | Improvements needed, may proceed with caution | - -## Phase 4: Validation - -### Readiness Report Format - -Write to `/spec/readiness-report.md`: - -``` -# Specification Readiness Report - -**Generated**: -**Overall Score**: % -**Quality Gate**: - -**Recommended Action**: - -## Dimension Scores - -| Dimension | Score | Weight | Weighted Score | -|-----------|-------|--------|----------------| -| Completeness | % | 25% | % | -| Consistency | % | 20% | % | -| Traceability | % | 25% | % | -| Depth | % | 20% | % | -| Coverage | % | 10% | % | - -## Completeness Analysis -(per-phase breakdown: sections present/expected, missing sections) - -## Consistency Analysis -(issues by area: terminology, format, references, naming) - -## Traceability Analysis -(complete chains / total, weak links) - -## Depth Analysis -(per sub-dimension scores) - -## Requirement Coverage -(covered / total, uncovered requirements list) -``` - -### Spec Summary Format - -Write to `/spec/spec-summary.md`: - -``` -# Specification Summary - -**Overall Quality Score**: % -**Quality Gate**: - -## Documents Reviewed -(per document: phase, path, size, section list) - -## Key Findings -### Strengths (dimensions scoring >= 80%) -### Areas for Improvement (dimensions scoring < 70%) -### Recommendations -``` - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Spec folder empty | FAIL gate, report no documents found | -| Missing phase document | Score 0 for that phase in completeness, note in report | -| No original requirements found | Score coverage at 100% (nothing to cover) | -| Broken references | Flag in consistency, do not fail entire review | diff --git a/.claude/skills/team-lifecycle-v4/roles/reviewer/role.md b/.claude/skills/team-lifecycle-v4/roles/reviewer/role.md deleted file mode 100644 index 6e46e801..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/reviewer/role.md +++ /dev/null @@ -1,150 +0,0 @@ -# Role: reviewer - -Dual-mode review: code review (REVIEW-*) and spec quality validation (QUALITY-*). QUALITY tasks include inline discuss (DISCUSS-006) for final sign-off. - -## Identity - -- **Name**: `reviewer` | **Prefix**: `REVIEW-*` + `QUALITY-*` | **Tag**: `[reviewer]` -- **Responsibility**: Branch by Prefix -> Review/Score -> **Inline Discuss (QUALITY only)** -> Report - -## Boundaries - -### MUST -- Process REVIEW-* and QUALITY-* tasks -- Generate readiness-report.md for QUALITY tasks -- Cover all required dimensions per mode -- Call discuss subagent for DISCUSS-006 after QUALITY-001 - -### MUST NOT -- Create tasks -- Modify source code -- Skip quality dimensions -- Approve without verification - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| review_result | -> coordinator | Code review complete | -| quality_result | -> coordinator | Spec quality + discuss complete | -| fix_required | -> coordinator | Critical issues found | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/code-review.md | 4-dimension code review | -| commands/spec-quality.md | 5-dimension spec quality | -| discuss subagent | Inline DISCUSS-006 (QUALITY tasks only) | - ---- - -## Mode Detection - -| Task Prefix | Mode | Dimensions | Inline Discuss | -|-------------|------|-----------|---------------| -| REVIEW-* | Code Review | quality, security, architecture, requirements | None | -| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage | DISCUSS-006 | - ---- - -## Code Review (REVIEW-*) - -**Inputs**: Plan file, git diff, modified files, test results (if available) - -**4 dimensions** (delegate to commands/code-review.md): - -| Dimension | Critical Issues | -|-----------|----------------| -| Quality | Empty catch, any in public APIs, @ts-ignore, console.log | -| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML | -| Architecture | Circular deps, parent imports >2 levels, files >500 lines | -| Requirements | Missing core functionality, incomplete acceptance criteria | - -**Verdict**: - -| Verdict | Criteria | -|---------|----------| -| BLOCK | Critical issues present | -| CONDITIONAL | High/medium only | -| APPROVE | Low or none | - ---- - -## Spec Quality (QUALITY-*) - -**Inputs**: All spec docs in session folder, quality gate config - -**5 dimensions** (delegate to commands/spec-quality.md): - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Completeness | 25% | All sections present with substance | -| Consistency | 20% | Terminology, format, references | -| Traceability | 25% | Goals -> Reqs -> Arch -> Stories chain | -| Depth | 20% | AC testable, ADRs justified, stories estimable | -| Coverage | 10% | Original requirements mapped | - -**Quality gate**: - -| Gate | Criteria | -|------|----------| -| PASS | Score >= 80% AND coverage >= 70% | -| REVIEW | Score 60-79% OR coverage 50-69% | -| FAIL | Score < 60% OR coverage < 50% | - -**Artifacts**: readiness-report.md + spec-summary.md - -### Inline Discuss (DISCUSS-006) -- QUALITY tasks only - -After generating readiness-report.md, call discuss subagent for final sign-off: - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss DISCUSS-006", - prompt: `## Multi-Perspective Critique: DISCUSS-006 - -### Input -- Artifact: /spec/readiness-report.md -- Round: DISCUSS-006 -- Perspectives: product, technical, quality, risk, coverage -- Session: -- Discovery Context: /spec/discovery-context.json - -` -}) -``` - -**Discuss result handling**: - -| Verdict | Severity | Action | -|---------|----------|--------| -| consensus_reached | - | Include as final endorsement in quality report, proceed to Phase 5 | -| consensus_blocked | HIGH | **DISCUSS-006 is final sign-off gate**. Phase 5 SendMessage includes structured format. Coordinator always pauses for user decision. | -| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed to Phase 5. Coordinator logs to wisdom. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. | - -**consensus_blocked SendMessage format**: -``` -[reviewer] QUALITY-001 complete. Discuss DISCUSS-006: consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -Artifact: /spec/readiness-report.md -Discussion: /discussions/DISCUSS-006-discussion.md -``` - -> **Note**: DISCUSS-006 HIGH always triggers user pause regardless of revision count, since this is the spec->impl gate. - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Missing context | Request from coordinator | -| Invalid mode | Abort with error | -| Analysis failure | Retry, then fallback template | -| Discuss subagent fails | Proceed without final discuss, log warning | diff --git a/.claude/skills/team-lifecycle-v4/roles/tester/commands/validate.md b/.claude/skills/team-lifecycle-v4/roles/tester/commands/validate.md deleted file mode 100644 index 8016d78a..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/tester/commands/validate.md +++ /dev/null @@ -1,152 +0,0 @@ -# Command: validate - -## Purpose - -Test-fix cycle with strategy engine: detect framework, run tests, classify failures, select fix strategy, iterate until pass rate target is met or max iterations exhausted. - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| MAX_ITERATIONS | 10 | Maximum test-fix cycle attempts | -| PASS_RATE_TARGET | 95% | Minimum pass rate to succeed | -| AFFECTED_TESTS_FIRST | true | Run affected tests before full suite | - -## Phase 2: Context Loading - -Load from task description and executor output: - -| Input | Source | Required | -|-------|--------|----------| -| Framework | Auto-detected (see below) | Yes | -| Modified files | Executor task output / git diff | Yes | -| Affected tests | Derived from modified files | No | -| Session folder | Task description `Session:` field | Yes | -| Wisdom | `/wisdom/` | No | - -**Framework detection** (priority order): - -| Priority | Method | Check | -|----------|--------|-------| -| 1 | package.json devDependencies | vitest, jest, mocha, pytest | -| 2 | package.json scripts.test | Command contains framework name | -| 3 | Config file existence | vitest.config.*, jest.config.*, pytest.ini | - -**Affected test discovery** from modified files: -- For each modified file `.`, search: - `.test.ts`, `.spec.ts`, `tests/.test.ts`, `__tests__/.test.ts` - -## Phase 3: Test-Fix Cycle - -### Test Command Table - -| Framework | Affected Tests | Full Suite | -|-----------|---------------|------------| -| vitest | `vitest run --reporter=verbose` | `vitest run --reporter=verbose` | -| jest | `jest --no-coverage --verbose` | `jest --no-coverage --verbose` | -| mocha | `mocha --reporter spec` | `mocha --reporter spec` | -| pytest | `pytest -v --tb=short` | `pytest -v --tb=short` | - -### Iteration Flow - -``` -Iteration 1 - ├─ Run affected tests (or full suite if none) - ├─ Parse results → pass rate - ├─ Pass rate >= 95%? - │ ├─ YES + affected-only → run full suite to confirm - │ │ ├─ Full suite passes → SUCCESS - │ │ └─ Full suite fails → continue with full results - │ └─ YES + full suite → SUCCESS - └─ NO → classify failures → select strategy → apply fixes - -Iteration 2..10 - ├─ Re-run tests - ├─ Track best pass rate across iterations - ├─ Pass rate >= 95% → SUCCESS - ├─ No failures to fix → STOP (anomaly) - └─ Failures remain → classify → select strategy → apply fixes - -After iteration 10 - └─ FAIL: max iterations reached, report best pass rate -``` - -**Progress update**: When iteration > 5, send progress to coordinator with current pass rate and iteration count. - -### Strategy Selection Matrix - -| Condition | Strategy | Behavior | -|-----------|----------|----------| -| Iteration <= 3 OR pass rate >= 80% | Conservative | Fix one failure at a time, highest severity first | -| Critical failures exist AND count < 5 | Surgical | Identify common error pattern, fix all matching occurrences | -| Pass rate < 50% OR iteration > 7 | Aggressive | Fix all critical + high failures in batch | -| Default (no other match) | Conservative | Safe fallback | - -### Failure Classification Table - -| Severity | Error Patterns | -|----------|---------------| -| Critical | SyntaxError, cannot find module, is not defined | -| High | Assertion mismatch (expected/received), toBe/toEqual failures | -| Medium | Timeout, async errors | -| Low | Warnings, deprecation notices | - -### Fix Approach by Error Type - -| Error Type | Pattern | Fix Approach | -|------------|---------|-------------| -| missing_import | "Cannot find module ''" | Add import statement, resolve relative path from modified files | -| undefined_variable | " is not defined" | Check source for renamed/moved exports, update reference | -| assertion_mismatch | "Expected: X, Received: Y" | Read test file at failure line, update expected value if behavior change is intentional | -| timeout | "Timeout" | Increase timeout or add async/await | -| syntax_error | "SyntaxError" | Read source at error line, fix syntax | - -### Tool Call Example - -Run tests with framework-appropriate command: - -```bash -Bash(command="vitest run src/utils/__tests__/parser.test.ts --reporter=verbose", timeout=120000) -``` - -Read test file to analyze failure: - -```bash -Read(file_path="") -``` - -Apply fix via Edit: - -```bash -Edit(file_path="", old_string="", new_string="") -``` - -## Phase 4: Validation - -### Success Criteria - -| Check | Criteria | Required | -|-------|----------|----------| -| Pass rate | >= 95% | Yes | -| Full suite run | At least one full suite pass | Yes | -| No critical failures | Zero critical-severity failures remaining | Yes | -| Best pass rate tracked | Reported in final result | Yes | - -### Result Routing - -| Outcome | Message Type | Content | -|---------|-------------|---------| -| Pass rate >= target | test_result | Success, iterations count, full suite confirmed | -| Max iterations, pass rate < target | fix_required | Best pass rate, remaining failures, iteration count | -| No tests found | error | Framework detected but no test files | -| Framework not detected | error | Detection methods exhausted | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Framework not detected | Report error to coordinator, list detection attempts | -| No test files found | Report to coordinator, suggest manual test path | -| Test command fails (exit code != 0/1) | Check stderr for environment issues, retry once | -| Fix application fails | Skip fix, try next iteration with different strategy | -| Infinite loop (same failures repeat) | Abort after 3 identical result sets | diff --git a/.claude/skills/team-lifecycle-v4/roles/tester/role.md b/.claude/skills/team-lifecycle-v4/roles/tester/role.md deleted file mode 100644 index afdfd887..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/tester/role.md +++ /dev/null @@ -1,108 +0,0 @@ -# Role: tester - -Adaptive test execution with fix cycles and quality gates. - -## Identity - -- **Name**: `tester` | **Prefix**: `TEST-*` | **Tag**: `[tester]` -- **Responsibility**: Detect Framework → Run Tests → Fix Cycle → Report - -## Boundaries - -### MUST -- Only process TEST-* tasks -- Detect test framework before running -- Run affected tests before full suite -- Use strategy engine for fix cycles - -### MUST NOT -- Create tasks -- Contact other workers directly -- Modify production code beyond test fixes -- Skip framework detection - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| test_result | → coordinator | Tests pass or final result | -| fix_required | → coordinator | Failures after max iterations | -| error | → coordinator | Framework not detected | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| commands/validate.md | Test-fix cycle with strategy engine | - ---- - -## Phase 2: Framework Detection & Test Discovery - -**Framework detection** (priority order): - -| Priority | Method | Frameworks | -|----------|--------|-----------| -| 1 | package.json devDependencies | vitest, jest, mocha, pytest | -| 2 | package.json scripts.test | vitest, jest, mocha, pytest | -| 3 | Config files | vitest.config.*, jest.config.*, pytest.ini | - -**Affected test discovery** from executor's modified files: -- Search variants: `.test.ts`, `.spec.ts`, `tests/.test.ts`, `__tests__/.test.ts` - ---- - -## Phase 3: Test Execution & Fix Cycle - -**Config**: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true - -Delegate to `commands/validate.md`: -1. Run affected tests → parse results -2. Pass rate met → run full suite -3. Failures → select strategy → fix → re-run → repeat - -**Strategy selection**: - -| Condition | Strategy | Behavior | -|-----------|----------|----------| -| Iteration ≤ 3 or pass ≥ 80% | Conservative | Fix one critical failure at a time | -| Critical failures < 5 | Surgical | Fix specific pattern everywhere | -| Pass < 50% or iteration > 7 | Aggressive | Fix all failures in batch | - -**Test commands**: - -| Framework | Affected | Full Suite | -|-----------|---------|------------| -| vitest | `vitest run ` | `vitest run` | -| jest | `jest --no-coverage` | `jest --no-coverage` | -| pytest | `pytest -v` | `pytest -v` | - ---- - -## Phase 4: Result Analysis - -**Failure classification**: - -| Severity | Patterns | -|----------|----------| -| Critical | SyntaxError, cannot find module, undefined | -| High | Assertion failures, toBe/toEqual | -| Medium | Timeout, async errors | -| Low | Warnings, deprecations | - -**Report routing**: - -| Condition | Type | -|-----------|------| -| Pass rate ≥ target | test_result (success) | -| Pass rate < target after max iterations | fix_required | - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Framework not detected | Prompt user | -| No tests found | Report to coordinator | -| Infinite fix loop | Abort after MAX_ITERATIONS | diff --git a/.claude/skills/team-lifecycle-v4/roles/writer/commands/generate-doc.md b/.claude/skills/team-lifecycle-v4/roles/writer/commands/generate-doc.md deleted file mode 100644 index d17964b2..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/writer/commands/generate-doc.md +++ /dev/null @@ -1,192 +0,0 @@ -# Command: generate-doc - -## Purpose - -Document generation strategy reference. Used by doc-generation-subagent.md as prompt source. -Writer 主 agent 不再直接执行此文件中的 CLI 调用，而是将对应段落传入 subagent prompt。 - -## Usage - -Writer Phase 3 加载此文件中对应 doc-type 的策略段落，嵌入 subagent prompt 的 "Execution Strategy" 字段。 - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Document standards | `../../specs/document-standards.md` | Yes | -| Template | From routing table below | Yes | -| Spec config | `/spec/spec-config.json` | Yes | -| Discovery context | `/spec/discovery-context.json` | Yes | -| Discussion feedback | `/discussions/` | If exists | -| Session folder | Task description `Session:` field | Yes | - -### Document Type Routing - -| Doc Type | Task | Template | Discussion Input | Output | -|----------|------|----------|-----------------|--------| -| product-brief | DRAFT-001 | templates/product-brief.md | DISCUSS-001-discussion.md | spec/product-brief.md | -| requirements | DRAFT-002 | templates/requirements-prd.md | DISCUSS-002-discussion.md | spec/requirements/_index.md | -| architecture | DRAFT-003 | templates/architecture-doc.md | DISCUSS-003-discussion.md | spec/architecture/_index.md | -| epics | DRAFT-004 | templates/epics-template.md | DISCUSS-004-discussion.md | spec/epics/_index.md | - -### Progressive Dependencies - -Each doc type requires all prior docs: discovery-context → product-brief → requirements/_index → architecture/_index. - -## Phase 3: Document Generation - -### Shared Context Block - -Built from spec-config and discovery-context for all CLI prompts: - -``` -SEED: -PROBLEM: -TARGET USERS: -DOMAIN: -CONSTRAINTS: -FOCUS AREAS: -CODEBASE CONTEXT: (if discovery-context exists) -``` - ---- - -### DRAFT-001: Product Brief - -**Strategy**: 3-way parallel CLI analysis, then synthesize. - -| Perspective | CLI Tool | Focus | -|-------------|----------|-------| -| Product | gemini | Vision, market fit, success metrics, scope | -| Technical | codex | Feasibility, constraints, integration complexity | -| User | claude | Personas, journey maps, pain points, UX | - -**CLI call template** (one per perspective, all `run_in_background: true`): - -```bash -Bash(command="ccw cli -p \"PURPOSE: analysis for specification.\n\nTASK: \nMODE: analysis\nEXPECTED: \nCONSTRAINTS: \" --tool --mode analysis", run_in_background=true) -``` - -**Synthesis flow** (after all 3 return): - -``` -3 CLI outputs received - ├─ Identify convergent themes (2+ perspectives agree) - ├─ Identify conflicts (e.g., product wants X, technical says infeasible) - ├─ Extract unique insights per perspective - ├─ Integrate discussion feedback (if exists) - └─ Fill template → Write to spec/product-brief.md -``` - -**Template sections**: Vision, Problem Statement, Target Users, Goals, Scope, Success Criteria, Assumptions. - ---- - -### DRAFT-002: Requirements/PRD - -**Strategy**: Single CLI expansion, then structure into individual requirement files. - -| Step | Tool | Action | -|------|------|--------| -| 1 | gemini | Generate functional (REQ-NNN) and non-functional (NFR-type-NNN) requirements | -| 2 | (local) | Integrate discussion feedback | -| 3 | (local) | Write individual files + _index.md | - -**CLI prompt focus**: For each product-brief goal, generate 3-7 functional requirements with user stories, acceptance criteria, and MoSCoW priority. Generate NFR categories: performance, security, scalability, usability. - -**Output structure**: - -``` -spec/requirements/ - ├─ _index.md (summary table + MoSCoW breakdown) - ├─ REQ-001-.md (individual functional requirement) - ├─ REQ-002-.md - ├─ NFR-perf-001-.md (non-functional) - └─ NFR-sec-001-.md -``` - -Each requirement file has: YAML frontmatter (id, title, priority, status, traces), description, user story, acceptance criteria. - ---- - -### DRAFT-003: Architecture - -**Strategy**: 2-stage CLI (design + critical review). - -| Stage | Tool | Purpose | -|-------|------|---------| -| 1 | gemini | Architecture design: style, components, tech stack, ADRs, data model, security | -| 2 | codex | Critical review: challenge ADRs, identify bottlenecks, rate quality 1-5 | - -Stage 2 runs after stage 1 completes (sequential dependency). - -**After both complete**: -1. Integrate discussion feedback -2. Map codebase integration points (from discovery-context.relevant_files) -3. Write individual ADR files + _index.md - -**Output structure**: - -``` -spec/architecture/ - ├─ _index.md (overview, component diagram, tech stack, data model, API, security) - ├─ ADR-001-.md (individual decision record) - └─ ADR-002-.md -``` - -Each ADR file has: YAML frontmatter (id, title, status, traces), context, decision, alternatives with pros/cons, consequences, review feedback. - ---- - -### DRAFT-004: Epics & Stories - -**Strategy**: Single CLI decomposition, then structure into individual epic files. - -| Step | Tool | Action | -|------|------|--------| -| 1 | gemini | Decompose requirements into 3-7 Epics with Stories, dependency map, MVP subset | -| 2 | (local) | Integrate discussion feedback | -| 3 | (local) | Write individual EPIC files + _index.md | - -**CLI prompt focus**: Group requirements by domain, generate EPIC-NNN with STORY-EPIC-NNN children, define MVP subset, create Mermaid dependency diagram, recommend execution order. - -**Output structure**: - -``` -spec/epics/ - ├─ _index.md (overview table, dependency map, execution order, MVP scope) - ├─ EPIC-001-.md (individual epic with stories) - └─ EPIC-002-.md -``` - -Each epic file has: YAML frontmatter (id, title, priority, mvp, size, requirements, architecture, dependencies), stories with user stories and acceptance criteria. - -All generated documents include YAML frontmatter: session_id, phase, document_type, status=draft, generated_at, version, dependencies. - -## Phase 4: Validation - -| Check | What to Verify | -|-------|---------------| -| has_frontmatter | Document starts with valid YAML frontmatter | -| sections_complete | All template sections present in output | -| cross_references | session_id matches spec-config | -| discussion_integrated | Feedback reflected (if feedback exists) | -| files_written | All expected files exist (individual + _index.md) | - -### Result Routing - -| Outcome | Message Type | Content | -|---------|-------------|---------| -| All checks pass | draft_ready | Doc type, output path, summary | -| Validation issues | draft_ready (with warnings) | Doc type, output path, issues list | -| Critical failure | error | Missing template, CLI failure | - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Prior doc not found | Notify coordinator, request prerequisite task completion | -| Template not found | Error, report missing template path | -| CLI tool fails | Retry with fallback tool (gemini → codex → claude) | -| Discussion contradicts prior docs | Note conflict in document, flag for next discussion round | -| Partial CLI output | Use available data, note gaps in document | diff --git a/.claude/skills/team-lifecycle-v4/roles/writer/role.md b/.claude/skills/team-lifecycle-v4/roles/writer/role.md deleted file mode 100644 index 109e719e..00000000 --- a/.claude/skills/team-lifecycle-v4/roles/writer/role.md +++ /dev/null @@ -1,246 +0,0 @@ -# Role: writer - -Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation. -Uses **Inner Loop** pattern: one agent handles all DRAFT-* tasks sequentially, -delegating document generation to subagent, retaining summaries across tasks. - -## Identity - -- **Name**: `writer` | **Prefix**: `DRAFT-*` | **Tag**: `[writer]` -- **Mode**: Inner Loop (处理全部 DRAFT-* 任务) -- **Responsibility**: [Loop: Load Context -> Subagent Generate -> Validate + Discuss -> Accumulate] -> Final Report - -## Boundaries - -### MUST -- Only process DRAFT-* tasks -- Use subagent for document generation (不在主 agent 内执行 CLI) -- Maintain context_accumulator across tasks -- Call discuss subagent after each document output -- Loop through all DRAFT-* tasks before reporting to coordinator - -### MUST NOT -- Create tasks for other roles -- Skip template loading -- Execute CLI document generation in main agent (delegate to subagent) -- SendMessage to coordinator mid-loop (除非 consensus_blocked HIGH) - -## Message Types - -| Type | Direction | Trigger | -|------|-----------|---------| -| draft_ready | -> coordinator | Document + discuss complete | -| draft_revision | -> coordinator | Document revised per feedback | -| error | -> coordinator | Template missing, insufficient context | - -## Toolbox - -| Tool | Purpose | -|------|---------| -| subagents/doc-generation-subagent.md | Document generation (per task) | -| discuss subagent | Inline discuss critique | - ---- - -## Phase 1: Task Discovery (Inner Loop) - -**首次进入**：标准 Phase 1 流程，找到第一个 DRAFT-* pending 任务。 - -**循环重入**：Phase 5-L 完成后回到此处，TaskList 查找下一个 DRAFT-* pending 且 blockedBy 已全部 completed 的任务。 - -**终止条件**：无更多 DRAFT-* 可处理 → Phase 5-F。 - ---- - -## Phase 2: Context Loading - -**Objective**: Load all required inputs for document generation. - -**Document type routing**: - -| Task Subject Contains | Doc Type | Template | Prior Discussion Input | -|----------------------|----------|----------|----------------------| -| Product Brief | product-brief | templates/product-brief.md | discussions/DISCUSS-001-discussion.md | -| Requirements / PRD | requirements | templates/requirements-prd.md | discussions/DISCUSS-002-discussion.md | -| Architecture | architecture | templates/architecture-doc.md | discussions/DISCUSS-003-discussion.md | -| Epics | epics | templates/epics-template.md | discussions/DISCUSS-004-discussion.md | - -**Inline discuss mapping**: - -| Doc Type | Inline Discuss Round | Perspectives | -|----------|---------------------|-------------| -| product-brief | DISCUSS-002 | product, technical, quality, coverage | -| requirements | DISCUSS-003 | quality, product, coverage | -| architecture | DISCUSS-004 | technical, risk | -| epics | DISCUSS-005 | product, technical, quality, coverage | - -**Progressive dependency loading**: - -| Doc Type | Requires | -|----------|----------| -| product-brief | discovery-context.json | -| requirements | + product-brief.md | -| architecture | + requirements/_index.md | -| epics | + architecture/_index.md | - -**Prior decisions from accumulator**: 将 context_accumulator 中的前序摘要作为 "Prior Decisions" 传入。 - -| Input | Source | Required | -|-------|--------|----------| -| Document standards | `../../specs/document-standards.md` | Yes | -| Template | From routing table | Yes | -| Spec config | `/spec/spec-config.json` | Yes | -| Discovery context | `/spec/discovery-context.json` | Yes | -| Discussion feedback | `/discussions/` | If exists | -| Prior decisions | context_accumulator (内存) | 如果有前序任务 | - -**Success**: Template loaded, prior discussion feedback loaded (if exists), prior docs loaded, accumulator context prepared. - ---- - -## Phase 3: Subagent Document Generation - -**Objective**: Delegate document generation to doc-generation subagent. - -**变化**：不再在主 agent 内执行 CLI 调用，而是委托给 doc-generation subagent。 - -``` -Task({ - subagent_type: "universal-executor", - run_in_background: false, - description: "Generate document", - prompt: `<从 subagents/doc-generation-subagent.md 加载 prompt> - -## Task -- Document type: -- Session folder: -- Template: - -## Context -- Spec config: -- Discovery context: -- Prior discussion feedback: -- Prior decisions (from writer accumulator): - - -## Instructions -<从 commands/generate-doc.md 加载该 doc-type 的具体策略> - -## Expected Output -Return JSON: -{ - "artifact_path": "", - "summary": "<100-200字摘要>", - "key_decisions": ["", "", ...], - "sections_generated": ["", ...], - "warnings": [""] -}` -}) -``` - -**主 agent 拿到的只是上述 JSON 摘要**，不是整篇文档。文档已由 subagent 写入磁盘。 - ---- - -## Phase 4: Self-Validation + Inline Discuss - -### 4a: Self-Validation - -| Check | What to Verify | -|-------|---------------| -| has_frontmatter | Starts with YAML frontmatter | -| sections_complete | All template sections present | -| cross_references | session_id included | -| discussion_integrated | Reflects prior round feedback (if exists) | - -### 4b: Inline Discuss - -After validation, call discuss subagent for this task's discuss round: - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss ", - prompt: `## Multi-Perspective Critique: - -### Input -- Artifact: -- Round: -- Perspectives: -- Session: -- Discovery Context: /spec/discovery-context.json - -` -}) -``` - -**Discuss result handling**: - -| Verdict | Severity | Action | -|---------|----------|--------| -| consensus_reached | - | Include action items in report, proceed to Phase 5 | -| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format (see below). Do NOT self-revise -- coordinator creates revision task. | -| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed to Phase 5 normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. | - -**consensus_blocked SendMessage format**: -``` -[writer] complete. Discuss : consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -Artifact: -Discussion: /discussions/-discussion.md -``` - -**Report**: doc type, validation status, discuss verdict + severity, average rating, summary, output path. - ---- - -## Phase 5-L: 循环完成 (Loop Completion) - -在还有后续 DRAFT-* 任务时执行： - -1. **TaskUpdate**: 标记当前任务 completed -2. **team_msg**: 记录任务完成 -3. **累积摘要**: - ``` - context_accumulator.append({ - task: "", - artifact: "", - key_decisions: , - discuss_verdict: , - discuss_rating: , - summary: - }) - ``` -4. **中断检查**: - - consensus_blocked HIGH → SendMessage → STOP - - 累计错误 >= 3 → SendMessage → STOP -5. **Loop**: 回到 Phase 1 - -**不做**：不 SendMessage、不 Fast-Advance spawn。 - -## Phase 5-F: 最终报告 (Final Report) - -当所有 DRAFT-* 任务完成后： - -1. **TaskUpdate**: 标记最后一个任务 completed -2. **team_msg**: 记录完成 -3. **汇总报告**: 所有任务摘要 + discuss 结果 + 产出路径 -4. **Fast-Advance 检查**: 检查跨前缀后续 (如 QUALITY-001 是否 ready) -5. **SendMessage** 或 **spawn successor** - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Subagent 失败 | 重试 1 次，换 subagent_type；仍失败则记录错误，继续下一任务 | -| Discuss subagent 失败 | 跳过 discuss，记录 warning | -| 累计 3 个任务失败 | SendMessage 报告 coordinator，STOP | -| Agent crash mid-loop | Coordinator resume 检测 orphan → 重新 spawn → 从断点恢复 | -| Prior doc not found | Notify coordinator, request prerequisite | -| Discussion contradicts prior docs | Note conflict, flag for coordinator | diff --git a/.claude/skills/team-lifecycle-v4/specs/document-standards.md b/.claude/skills/team-lifecycle-v4/specs/document-standards.md deleted file mode 100644 index 2820cd98..00000000 --- a/.claude/skills/team-lifecycle-v4/specs/document-standards.md +++ /dev/null @@ -1,192 +0,0 @@ -# Document Standards - -Defines format conventions, YAML frontmatter schema, naming rules, and content structure for all spec-generator outputs. - -## When to Use - -| Phase | Usage | Section | -|-------|-------|---------| -| All Phases | Frontmatter format | YAML Frontmatter Schema | -| All Phases | File naming | Naming Conventions | -| Phase 2-5 | Document structure | Content Structure | -| Phase 6 | Validation reference | All sections | - ---- - -## YAML Frontmatter Schema - -Every generated document MUST begin with YAML frontmatter: - -```yaml ---- -session_id: SPEC-{slug}-{YYYY-MM-DD} -phase: {1-6} -document_type: {product-brief|requirements|architecture|epics|readiness-report|spec-summary} -status: draft|review|complete -generated_at: {ISO8601 timestamp} -stepsCompleted: [] -version: 1 -dependencies: - - {list of input documents used} ---- -``` - -### Field Definitions - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `session_id` | string | Yes | Session identifier matching spec-config.json | -| `phase` | number | Yes | Phase number that generated this document (1-6) | -| `document_type` | string | Yes | One of: product-brief, requirements, architecture, epics, readiness-report, spec-summary | -| `status` | enum | Yes | draft (initial), review (user reviewed), complete (finalized) | -| `generated_at` | string | Yes | ISO8601 timestamp of generation | -| `stepsCompleted` | array | Yes | List of step IDs completed during generation | -| `version` | number | Yes | Document version, incremented on re-generation | -| `dependencies` | array | No | List of input files this document depends on | - -### Status Transitions - -``` -draft -> review -> complete - | ^ - +-------------------+ (direct promotion in auto mode) -``` - -- **draft**: Initial generation, not yet user-reviewed -- **review**: User has reviewed and provided feedback -- **complete**: Finalized, ready for downstream consumption - -In auto mode (`-y`), documents are promoted directly from `draft` to `complete`. - ---- - -## Naming Conventions - -### Session ID Format - -``` -SPEC-{slug}-{YYYY-MM-DD} -``` - -- **slug**: Lowercase, alphanumeric + Chinese characters, hyphens as separators, max 40 chars -- **date**: UTC+8 date in YYYY-MM-DD format - -Examples: -- `SPEC-task-management-system-2026-02-11` -- `SPEC-user-auth-oauth-2026-02-11` - -### Output Files - -| File | Phase | Description | -|------|-------|-------------| -| `spec-config.json` | 1 | Session configuration and state | -| `discovery-context.json` | 1 | Codebase exploration results (optional) | -| `product-brief.md` | 2 | Product brief document | -| `requirements.md` | 3 | PRD document | -| `architecture.md` | 4 | Architecture decisions document | -| `epics.md` | 5 | Epic/Story breakdown document | -| `readiness-report.md` | 6 | Quality validation report | -| `spec-summary.md` | 6 | One-page executive summary | - -### Output Directory - -``` -.workflow/.spec/{session-id}/ -``` - ---- - -## Content Structure - -### Heading Hierarchy - -- `#` (H1): Document title only (one per document) -- `##` (H2): Major sections -- `###` (H3): Subsections -- `####` (H4): Detail items (use sparingly) - -Maximum depth: 4 levels. Prefer flat structures. - -### Section Ordering - -Every document follows this general pattern: - -1. **YAML Frontmatter** (mandatory) -2. **Title** (H1) -3. **Executive Summary** (2-3 sentences) -4. **Core Content Sections** (H2, document-specific) -5. **Open Questions / Risks** (if applicable) -6. **References / Traceability** (links to upstream/downstream docs) - -### Formatting Rules - -| Element | Format | Example | -|---------|--------|---------| -| Requirements | `REQ-{NNN}` prefix | REQ-001: User login | -| Acceptance criteria | Checkbox list | `- [ ] User can log in with email` | -| Architecture decisions | `ADR-{NNN}` prefix | ADR-001: Use PostgreSQL | -| Epics | `EPIC-{NNN}` prefix | EPIC-001: Authentication | -| Stories | `STORY-{EPIC}-{NNN}` prefix | STORY-001-001: Login form | -| Priority tags | MoSCoW labels | `[Must]`, `[Should]`, `[Could]`, `[Won't]` | -| Mermaid diagrams | Fenced code blocks | ````mermaid ... ``` `` | -| Code examples | Language-tagged blocks | ````typescript ... ``` `` | - -### Cross-Reference Format - -Use relative references between documents: - -```markdown -See [Product Brief](product-brief.md#section-name) for details. -Derived from [REQ-001](requirements.md#req-001). -``` - -### Language - -- Document body: Follow user's input language (Chinese or English) -- Technical identifiers: Always English (REQ-001, ADR-001, EPIC-001) -- YAML frontmatter keys: Always English - ---- - -## spec-config.json Schema - -```json -{ - "session_id": "string (required)", - "seed_input": "string (required) - original user input", - "input_type": "text|file (required)", - "timestamp": "ISO8601 (required)", - "mode": "interactive|auto (required)", - "complexity": "simple|moderate|complex (required)", - "depth": "light|standard|comprehensive (required)", - "focus_areas": ["string array"], - "seed_analysis": { - "problem_statement": "string", - "target_users": ["string array"], - "domain": "string", - "constraints": ["string array"], - "dimensions": ["string array - 3-5 exploration dimensions"] - }, - "has_codebase": "boolean", - "phasesCompleted": [ - { - "phase": "number (1-6)", - "name": "string (phase name)", - "output_file": "string (primary output file)", - "completed_at": "ISO8601" - } - ] -} -``` - ---- - -## Validation Checklist - -- [ ] Every document starts with valid YAML frontmatter -- [ ] `session_id` matches across all documents in a session -- [ ] `status` field reflects current document state -- [ ] All cross-references resolve to valid targets -- [ ] Heading hierarchy is correct (no skipped levels) -- [ ] Technical identifiers use correct prefixes -- [ ] Output files are in the correct directory diff --git a/.claude/skills/team-lifecycle-v4/specs/quality-gates.md b/.claude/skills/team-lifecycle-v4/specs/quality-gates.md deleted file mode 100644 index ae968436..00000000 --- a/.claude/skills/team-lifecycle-v4/specs/quality-gates.md +++ /dev/null @@ -1,207 +0,0 @@ -# Quality Gates - -Per-phase quality gate criteria and scoring dimensions for spec-generator outputs. - -## When to Use - -| Phase | Usage | Section | -|-------|-------|---------| -| Phase 2-5 | Post-generation self-check | Per-Phase Gates | -| Phase 6 | Cross-document validation | Cross-Document Validation | -| Phase 6 | Final scoring | Scoring Dimensions | - ---- - -## Quality Thresholds - -| Gate | Score | Action | -|------|-------|--------| -| **Pass** | >= 80% | Continue to next phase | -| **Review** | 60-79% | Log warnings, continue with caveats | -| **Fail** | < 60% | Must address issues before continuing | - -In auto mode (`-y`), Review-level issues are logged but do not block progress. - ---- - -## Scoring Dimensions - -### 1. Completeness (25%) - -All required sections present with substantive content. - -| Score | Criteria | -|-------|----------| -| 100% | All template sections filled with detailed content | -| 75% | All sections present, some lack detail | -| 50% | Major sections present but minor sections missing | -| 25% | Multiple major sections missing or empty | -| 0% | Document is a skeleton only | - -### 2. Consistency (25%) - -Terminology, formatting, and references are uniform across documents. - -| Score | Criteria | -|-------|----------| -| 100% | All terms consistent, all references valid, formatting uniform | -| 75% | Minor terminology variations, all references valid | -| 50% | Some inconsistent terms, 1-2 broken references | -| 25% | Frequent inconsistencies, multiple broken references | -| 0% | Documents contradict each other | - -### 3. Traceability (25%) - -Requirements, architecture decisions, and stories trace back to goals. - -| Score | Criteria | -|-------|----------| -| 100% | Every story traces to a requirement, every requirement traces to a goal | -| 75% | Most items traceable, few orphans | -| 50% | Partial traceability, some disconnected items | -| 25% | Weak traceability, many orphan items | -| 0% | No traceability between documents | - -### 4. Depth (25%) - -Content provides sufficient detail for execution teams. - -| Score | Criteria | -|-------|----------| -| 100% | Acceptance criteria specific and testable, architecture decisions justified, stories estimable | -| 75% | Most items detailed enough, few vague areas | -| 50% | Mix of detailed and vague content | -| 25% | Mostly high-level, lacking actionable detail | -| 0% | Too abstract for execution | - ---- - -## Per-Phase Quality Gates - -### Phase 1: Discovery - -| Check | Criteria | Severity | -|-------|----------|----------| -| Session ID valid | Matches `SPEC-{slug}-{date}` format | Error | -| Problem statement exists | Non-empty, >= 20 characters | Error | -| Target users identified | >= 1 user group | Error | -| Dimensions generated | 3-5 exploration dimensions | Warning | -| Constraints listed | >= 0 (can be empty with justification) | Info | - -### Phase 2: Product Brief - -| Check | Criteria | Severity | -|-------|----------|----------| -| Vision statement | Clear, 1-3 sentences | Error | -| Problem statement | Specific and measurable | Error | -| Target users | >= 1 persona with needs described | Error | -| Goals defined | >= 2 measurable goals | Error | -| Success metrics | >= 2 quantifiable metrics | Warning | -| Scope boundaries | In-scope and out-of-scope listed | Warning | -| Multi-perspective | >= 2 CLI perspectives synthesized | Info | - -### Phase 3: Requirements (PRD) - -| Check | Criteria | Severity | -|-------|----------|----------| -| Functional requirements | >= 3 with REQ-NNN IDs | Error | -| Acceptance criteria | Every requirement has >= 1 criterion | Error | -| MoSCoW priority | Every requirement tagged | Error | -| Non-functional requirements | >= 1 (performance, security, etc.) | Warning | -| User stories | >= 1 per Must-have requirement | Warning | -| Traceability | Requirements trace to product brief goals | Warning | - -### Phase 4: Architecture - -| Check | Criteria | Severity | -|-------|----------|----------| -| Component diagram | Present (Mermaid or ASCII) | Error | -| Tech stack specified | Languages, frameworks, key libraries | Error | -| ADR present | >= 1 Architecture Decision Record | Error | -| ADR has alternatives | Each ADR lists >= 2 options considered | Warning | -| Integration points | External systems/APIs identified | Warning | -| Data model | Key entities and relationships described | Warning | -| Codebase mapping | Mapped to existing code (if has_codebase) | Info | - -### Phase 5: Epics & Stories - -| Check | Criteria | Severity | -|-------|----------|----------| -| Epics defined | 3-7 epics with EPIC-NNN IDs | Error | -| MVP subset | >= 1 epic tagged as MVP | Error | -| Stories per epic | 2-5 stories per epic | Error | -| Story format | "As a...I want...So that..." pattern | Warning | -| Dependency map | Cross-epic dependencies documented | Warning | -| Estimation hints | Relative sizing (S/M/L/XL) per story | Info | -| Traceability | Stories trace to requirements | Warning | - -### Phase 6: Readiness Check - -| Check | Criteria | Severity | -|-------|----------|----------| -| All documents exist | product-brief, requirements, architecture, epics | Error | -| Frontmatter valid | All YAML frontmatter parseable and correct | Error | -| Cross-references valid | All document links resolve | Error | -| Overall score >= 60% | Weighted average across 4 dimensions | Error | -| No unresolved Errors | All Error-severity issues addressed | Error | -| Summary generated | spec-summary.md created | Warning | - ---- - -## Cross-Document Validation - -Checks performed during Phase 6 across all documents: - -### Completeness Matrix - -``` -Product Brief goals -> Requirements (each goal has >= 1 requirement) -Requirements -> Architecture (each Must requirement has design coverage) -Requirements -> Epics (each Must requirement appears in >= 1 story) -Architecture ADRs -> Epics (tech choices reflected in implementation stories) -``` - -### Consistency Checks - -| Check | Documents | Rule | -|-------|-----------|------| -| Terminology | All | Same term used consistently (no synonyms for same concept) | -| User personas | Brief + PRD + Epics | Same user names/roles throughout | -| Scope | Brief + PRD | PRD scope does not exceed brief scope | -| Tech stack | Architecture + Epics | Stories reference correct technologies | - -### Traceability Matrix Format - -```markdown -| Goal | Requirements | Architecture | Epics | -|------|-------------|--------------|-------| -| G-001: ... | REQ-001, REQ-002 | ADR-001 | EPIC-001 | -| G-002: ... | REQ-003 | ADR-002 | EPIC-002, EPIC-003 | -``` - ---- - -## Issue Classification - -### Error (Must Fix) - -- Missing required document or section -- Broken cross-references -- Contradictory information between documents -- Empty acceptance criteria on Must-have requirements -- No MVP subset defined in epics - -### Warning (Should Fix) - -- Vague acceptance criteria -- Missing non-functional requirements -- No success metrics defined -- Incomplete traceability -- Missing architecture review notes - -### Info (Nice to Have) - -- Could add more detailed personas -- Consider additional ADR alternatives -- Story estimation hints missing -- Mermaid diagrams could be more detailed diff --git a/.claude/skills/team-lifecycle-v4/specs/team-config.json b/.claude/skills/team-lifecycle-v4/specs/team-config.json deleted file mode 100644 index 2a8c480a..00000000 --- a/.claude/skills/team-lifecycle-v4/specs/team-config.json +++ /dev/null @@ -1,200 +0,0 @@ -{ - "team_name": "team-lifecycle", - "team_display_name": "Team Lifecycle v4", - "description": "Optimized team skill: inline discuss subagent + shared explore cache, spec beats halved", - "version": "4.0.0", - "architecture": "folder-based + subagents", - "role_structure": "roles/{name}/role.md + roles/{name}/commands/*.md", - "subagent_structure": "subagents/{name}-subagent.md", - - "roles": { - "coordinator": { - "task_prefix": null, - "responsibility": "Pipeline orchestration, requirement clarification, task chain creation, message dispatch", - "message_types": ["plan_approved", "plan_revision", "task_unblocked", "fix_required", "error", "shutdown"] - }, - "analyst": { - "task_prefix": "RESEARCH", - "responsibility": "Seed analysis, codebase exploration, multi-dimensional context gathering + inline discuss", - "inline_discuss": "DISCUSS-001", - "message_types": ["research_ready", "research_progress", "error"] - }, - "writer": { - "task_prefix": "DRAFT", - "responsibility": "Product Brief / PRD / Architecture / Epics document generation + inline discuss", - "execution_mode": "inner_loop", - "subagent_type": "universal-executor", - "inline_discuss": ["DISCUSS-002", "DISCUSS-003", "DISCUSS-004", "DISCUSS-005"], - "message_types": ["draft_ready", "draft_revision", "error"] - }, - "planner": { - "task_prefix": "PLAN", - "responsibility": "Multi-angle code exploration (via shared explore), structured implementation planning", - "execution_mode": "inner_loop", - "message_types": ["plan_ready", "plan_revision", "error"] - }, - "executor": { - "task_prefix": "IMPL", - "responsibility": "Code implementation following approved plans", - "execution_mode": "inner_loop", - "message_types": ["impl_complete", "impl_progress", "error"] - }, - "tester": { - "task_prefix": "TEST", - "responsibility": "Adaptive test-fix cycles, progressive testing, quality gates", - "message_types": ["test_result", "fix_required", "error"] - }, - "reviewer": { - "task_prefix": "REVIEW", - "additional_prefixes": ["QUALITY", "IMPROVE"], - "responsibility": "Code review (REVIEW-*) + Spec quality validation (QUALITY-*) + Quality improvement recheck (IMPROVE-*) + inline discuss for sign-off", - "inline_discuss": "DISCUSS-006", - "message_types": ["review_result", "quality_result", "quality_recheck", "fix_required", "error"] - }, - "architect": { - "task_prefix": "ARCH", - "responsibility": "Architecture assessment, tech feasibility, design pattern review. Consulting role -- on-demand by coordinator", - "role_type": "consulting", - "consultation_modes": ["spec-review", "plan-review", "code-review", "consult", "feasibility"], - "message_types": ["arch_ready", "arch_concern", "arch_progress", "error"] - }, - "fe-developer": { - "task_prefix": "DEV-FE", - "responsibility": "Frontend component/page implementation, design token consumption, responsive UI", - "role_type": "frontend-pipeline", - "message_types": ["dev_fe_complete", "dev_fe_progress", "error"] - }, - "fe-qa": { - "task_prefix": "QA-FE", - "responsibility": "5-dimension frontend review (quality, a11y, design compliance, UX, pre-delivery), GC loop", - "role_type": "frontend-pipeline", - "message_types": ["qa_fe_passed", "qa_fe_result", "fix_required", "error"] - } - }, - - "subagents": { - "discuss": { - "spec": "subagents/discuss-subagent.md", - "type": "cli-discuss-agent", - "callable_by": ["analyst", "writer", "reviewer"], - "purpose": "Multi-perspective critique with CLI tools, consensus synthesis" - }, - "explore": { - "spec": "subagents/explore-subagent.md", - "type": "cli-explore-agent", - "callable_by": ["analyst", "planner", "any"], - "purpose": "Codebase exploration with centralized cache" - } - }, - - "checkpoint_commands": { - "revise": { - "handler": "handleRevise", - "pattern": "revise [feedback]", - "cascade": true, - "creates": "revision_task" - }, - "feedback": { - "handler": "handleFeedback", - "pattern": "feedback ", - "cascade": true, - "creates": "revision_chain" - }, - "recheck": { - "handler": "handleRecheck", - "pattern": "recheck", - "cascade": false, - "creates": "quality_recheck" - }, - "improve": { - "handler": "handleImprove", - "pattern": "improve [dimension]", - "cascade": false, - "creates": "improvement_task + quality_recheck" - } - }, - - "pipelines": { - "spec-only": { - "description": "Specification pipeline: research+discuss -> draft+discuss x4 -> quality+discuss", - "task_chain": [ - "RESEARCH-001", - "DRAFT-001", "DRAFT-002", "DRAFT-003", "DRAFT-004", - "QUALITY-001" - ], - "beats": 6, - "v3_beats": 12, - "optimization": "Discuss rounds inlined into produce roles" - }, - "impl-only": { - "description": "Implementation pipeline: plan -> implement -> test + review", - "task_chain": ["PLAN-001", "IMPL-001", "TEST-001", "REVIEW-001"], - "beats": 3 - }, - "full-lifecycle": { - "description": "Full lifecycle: spec pipeline -> implementation pipeline", - "task_chain": "spec-only + impl-only (PLAN-001 blockedBy QUALITY-001)", - "beats": 9, - "v3_beats": 15, - "optimization": "6 fewer spec beats + QUALITY-001 is last spec task" - }, - "fe-only": { - "description": "Frontend-only pipeline: plan -> frontend dev -> frontend QA", - "task_chain": ["PLAN-001", "DEV-FE-001", "QA-FE-001"], - "gc_loop": { "max_rounds": 2, "convergence": "score >= 8 && critical === 0" } - }, - "fullstack": { - "description": "Fullstack pipeline: plan -> backend + frontend parallel -> test + QA", - "task_chain": ["PLAN-001", "IMPL-001||DEV-FE-001", "TEST-001||QA-FE-001", "REVIEW-001"], - "sync_points": ["REVIEW-001"] - }, - "full-lifecycle-fe": { - "description": "Full lifecycle with frontend: spec -> plan -> backend + frontend -> test + QA", - "task_chain": "spec-only + fullstack (PLAN-001 blockedBy QUALITY-001)" - } - }, - - "frontend_detection": { - "keywords": ["component", "page", "UI", "frontend", "CSS", "HTML", "React", "Vue", "Tailwind", "Svelte", "Next.js", "Nuxt", "shadcn", "design system"], - "file_patterns": ["*.tsx", "*.jsx", "*.vue", "*.svelte", "*.css", "*.scss", "*.html"], - "routing_rules": { - "frontend_only": "All tasks match frontend keywords, no backend/API mentions", - "fullstack": "Mix of frontend and backend tasks", - "backend_only": "No frontend keywords detected (default impl-only)" - } - }, - - "ui_ux_pro_max": { - "skill_name": "ui-ux-pro-max", - "invocation": "Skill(skill=\"ui-ux-pro-max\", args=\"...\")", - "domains": ["product", "style", "typography", "color", "landing", "chart", "ux", "web"], - "stacks": ["html-tailwind", "react", "nextjs", "vue", "svelte", "shadcn", "swiftui", "react-native", "flutter"], - "design_intelligence_chain": ["analyst -> design-intelligence.json", "architect -> design-tokens.json", "fe-developer -> tokens.css", "fe-qa -> anti-pattern audit"] - }, - - "shared_memory": { - "file": "shared-memory.json", - "schema": { - "design_intelligence": "From analyst via ui-ux-pro-max", - "design_token_registry": "From architect, consumed by fe-developer/fe-qa", - "component_inventory": "From fe-developer, list of implemented components", - "style_decisions": "Accumulated design decisions", - "qa_history": "From fe-qa, audit trail", - "industry_context": "Industry + strictness config", - "exploration_cache": "From explore subagent, shared by all roles" - } - }, - - "session_dirs": { - "base": ".workflow/.team/TLS-{slug}-{YYYY-MM-DD}/", - "spec": "spec/", - "discussions": "discussions/", - "plan": "plan/", - "explorations": "explorations/", - "architecture": "architecture/", - "analysis": "analysis/", - "qa": "qa/", - "wisdom": "wisdom/", - "messages": ".msg/" - } -} diff --git a/.claude/skills/team-lifecycle-v4/subagents/discuss-subagent.md b/.claude/skills/team-lifecycle-v4/subagents/discuss-subagent.md deleted file mode 100644 index d15c3395..00000000 --- a/.claude/skills/team-lifecycle-v4/subagents/discuss-subagent.md +++ /dev/null @@ -1,169 +0,0 @@ -# Discuss Subagent - -Lightweight multi-perspective critique engine. Called inline by produce roles (analyst, writer, reviewer) instead of as a separate team member. Eliminates spawn overhead while preserving multi-CLI analysis quality. - -## Design Rationale - -In v3, `discussant` was a full team role requiring: agent spawn -> Skill load -> Phase 1 task discovery -> Phase 2-4 work -> Phase 5 report + callback. For what is essentially "run CLI analyses + synthesize", the framework overhead exceeded actual work time. - -In v4, discuss is a **subagent call** from within the producing role, reducing each discuss round from ~60-90s overhead to ~5s overhead. - -## Invocation - -Called by produce roles after artifact creation: - -``` -Task({ - subagent_type: "cli-discuss-agent", - run_in_background: false, - description: "Discuss ", - prompt: `## Multi-Perspective Critique: - -### Input -- Artifact: -- Round: -- Perspectives: -- Session: -- Discovery Context: /spec/discovery-context.json (for coverage perspective) - -### Perspective Routing - -| Perspective | CLI Tool | Role | Focus Areas | -|-------------|----------|------|-------------| -| Product | gemini | Product Manager | Market fit, user value, business viability | -| Technical | codex | Tech Lead | Feasibility, tech debt, performance, security | -| Quality | claude | QA Lead | Completeness, testability, consistency | -| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes | -| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context | - -### Execution Steps -1. Read artifact from -2. For each perspective, launch CLI analysis in background: - Bash(command="ccw cli -p 'PURPOSE: Analyze from perspective for - TASK: - MODE: analysis - CONTEXT: Artifact content below - EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5) - CONSTRAINTS: Output valid JSON only - - Artifact: - ' --tool --mode analysis", run_in_background=true) -3. Wait for all CLI results -4. Divergence detection: - - Coverage gap: missing_requirements non-empty -> High severity - - High risk: risk_level is high or critical -> High severity - - Low rating: any perspective rating <= 2 -> Medium severity - - Rating spread: max - min >= 3 -> Medium severity -5. Consensus determination: - - No high-severity divergences AND average rating >= 3.0 -> consensus_reached - - Otherwise -> consensus_blocked -6. Synthesize: - - Convergent themes (agreed by 2+ perspectives) - - Divergent views (conflicting assessments) - - Coverage gaps - - Action items from suggestions -7. Write discussion record to: /discussions/-discussion.md - -### Discussion Record Format -# Discussion Record: - -**Artifact**: -**Perspectives**: -**Consensus**: reached / blocked -**Average Rating**: /5 - -## Convergent Themes -- - -## Divergent Views -- **** (): - -## Action Items -1. - -## Ratings -| Perspective | Rating | -|-------------|--------| -| | /5 | - -### Return Value - -**When consensus_reached**: -Return a summary string with: -- Verdict: consensus_reached -- Average rating -- Key action items (top 3) -- Discussion record path - -**When consensus_blocked**: -Return a structured summary with: -- Verdict: consensus_blocked -- Severity: HIGH | MEDIUM | LOW - - HIGH: any rating <= 2, critical risk identified, or missing_requirements non-empty - - MEDIUM: rating spread >= 3, or single perspective rated <= 2 with others >= 3 - - LOW: minor suggestions only, all ratings >= 3 but divergent views exist -- Average rating -- Divergence summary: top 3 divergent points with perspective attribution -- Action items: prioritized list of required changes -- Recommendation: revise | proceed-with-caution | escalate -- Discussion record path - -### Error Handling -- Single CLI fails -> fallback to direct Claude analysis for that perspective -- All CLI fail -> generate basic discussion from direct artifact reading -- Artifact not found -> return error immediately` -}) -``` - -## Round Configuration - -| Round | Artifact | Perspectives | Calling Role | -|-------|----------|-------------|-------------| -| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | analyst | -| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | writer | -| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | writer | -| DISCUSS-004 | spec/architecture/_index.md | technical, risk | writer | -| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | writer | -| DISCUSS-006 | spec/readiness-report.md | all 5 | reviewer | - -## Integration with Calling Role - -The calling role is responsible for: - -1. **Before calling**: Complete primary artifact output -2. **Calling**: Invoke discuss subagent with correct round config -3. **After calling**: - -| Verdict | Severity | Role Action | -|---------|----------|-------------| -| consensus_reached | - | Include action items in Phase 5 report, proceed normally | -| consensus_blocked | HIGH | Include divergence details in Phase 5 SendMessage with structured format (see below). **Do NOT self-revise** -- coordinator decides. | -| consensus_blocked | MEDIUM | Include warning in Phase 5 SendMessage. Proceed to Phase 5 normally. | -| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. | - -**SendMessage format for consensus_blocked (HIGH or MEDIUM)**: - -``` -[] complete. Discuss : consensus_blocked (severity=) -Divergences: -Action items: -Recommendation: -Artifact: -Discussion: -``` - -The coordinator receives this and routes per severity (see monitor.md Consensus-Blocked Handling): -- HIGH -> creates revision task (max 1) or pauses for user -- MEDIUM -> proceeds with warning logged to wisdom/issues.md -- DISCUSS-006 HIGH -> always pauses for user decision (final sign-off gate) - -## Comparison with v3 - -| Aspect | v3 (discussant role) | v4 (discuss subagent) | -|--------|---------------------|----------------------| -| Spawn | Full general-purpose agent | Inline subagent call | -| Skill load | Reads SKILL.md + role.md | None (prompt contains all logic) | -| Task discovery | TaskList + TaskGet + TaskUpdate | None (called with context) | -| Report overhead | team_msg + SendMessage + TaskUpdate | Return value to caller | -| Total overhead | ~25-45s framework | ~5s call overhead | -| Pipeline beat | 1 beat per discuss round | 0 additional beats | diff --git a/.claude/skills/team-lifecycle-v4/subagents/doc-generation-subagent.md b/.claude/skills/team-lifecycle-v4/subagents/doc-generation-subagent.md deleted file mode 100644 index 3de40a8e..00000000 --- a/.claude/skills/team-lifecycle-v4/subagents/doc-generation-subagent.md +++ /dev/null @@ -1,62 +0,0 @@ -# Doc Generation Subagent - -文档生成执行引擎。由 writer 主 agent 通过 Inner Loop 调用。 -负责 CLI 多视角分析 + 模板填充 + 文件写入。 - -## Design Rationale - -从 v4.0 的 writer 内联 CLI 执行，改为 subagent 隔离调用。 -好处：CLI 调用的大量 token 消耗不污染 writer 主 agent 上下文， -writer 只拿到压缩摘要，可在多任务间保持上下文连续。 - -## Invocation - -``` -Task({ - subagent_type: "universal-executor", - run_in_background: false, - description: "Generate ", - prompt: `## Document Generation: - -### Session -- Folder: -- Spec config: - -### Document Config -- Type: -- Template: -- Output: -- Prior discussion: - -### Writer Accumulator (prior decisions) - - -### Execution Strategy -<从 generate-doc.md 对应 doc-type 段落加载> - -### Output Requirements -1. Write document to (follow template + document-standards.md) -2. Return JSON summary: -{ - "artifact_path": "", - "summary": "<100-200字>", - "key_decisions": [], - "sections_generated": [], - "cross_references": [], - "warnings": [] -}` -}) -``` - -## Doc Type Strategies - -(直接引用 generate-doc.md 的 DRAFT-001/002/003/004 策略，不重复) -See: roles/writer/commands/generate-doc.md - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| CLI 工具失败 | fallback chain: gemini → codex → claude | -| Template 不存在 | 返回错误 JSON | -| Prior doc 不存在 | 返回错误 JSON，writer 决定是否继续 | diff --git a/.claude/skills/team-lifecycle-v4/subagents/explore-subagent.md b/.claude/skills/team-lifecycle-v4/subagents/explore-subagent.md deleted file mode 100644 index 2abbcab4..00000000 --- a/.claude/skills/team-lifecycle-v4/subagents/explore-subagent.md +++ /dev/null @@ -1,172 +0,0 @@ -# Explore Subagent - -Shared codebase exploration utility with centralized caching. Callable by any role needing code context. Replaces v3's standalone explorer role. - -## Design Rationale - -In v3, exploration happened in 3 separate places: -- `analyst` Phase 3: ACE semantic search for architecture patterns -- `planner` Phase 2: multi-angle cli-explore-agent -- `explorer` role: standalone service with full spawn cycle - -Results were scattered across different directories and never shared. In v4, all exploration routes through this subagent with a **unified cache** in `explorations/`. - -## Invocation - -``` -Task({ - subagent_type: "cli-explore-agent", - run_in_background: false, - description: "Explore ", - prompt: `Explore codebase for: - -Focus angle: -Keywords: -Session folder: - -## Cache Check -1. Read /explorations/cache-index.json (if exists) -2. Look for entry with matching angle -3. If found AND file exists -> read cached result, return summary -4. If not found -> proceed to exploration - -## Exploration - - -## Output -Write JSON to: /explorations/explore-.json -Update cache-index.json with new entry - -## Output Schema -{ - "angle": "", - "query": "", - "relevant_files": [ - { "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] } - ], - "patterns": [], - "dependencies": [], - "external_refs": [], - "_metadata": { "created_by": "", "timestamp": "...", "cache_key": "..." } -} - -Return summary: file count, pattern count, top 5 files, output path` -}) -``` - -## Cache Mechanism - -### Cache Index Schema - -`/explorations/cache-index.json`: - -```json -{ - "entries": [ - { - "angle": "architecture", - "keywords": ["auth", "middleware"], - "file": "explore-architecture.json", - "created_by": "analyst", - "created_at": "2026-02-27T10:00:00Z", - "file_count": 15 - } - ] -} -``` - -### Cache Lookup Rules - -| Condition | Action | -|-----------|--------| -| Exact angle match exists | Return cached result | -| No match | Execute exploration, cache result | -| Cache file missing but index has entry | Remove stale entry, re-explore | - -### Cache Invalidation - -Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache. - -## Angle Focus Guide - -| Angle | Focus Points | Typical Caller | -|-------|-------------|----------------| -| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | analyst, planner | -| dependencies | Import chains, external libraries, circular dependencies, shared utilities | planner | -| modularity | Module interfaces, separation of concerns, extraction opportunities | planner | -| integration-points | API endpoints, data flow between modules, event systems | analyst, planner | -| security | Auth/authz logic, input validation, sensitive data handling, middleware | planner | -| auth-patterns | Auth flows, session management, token validation, permissions | planner | -| dataflow | Data transformations, state propagation, validation points | planner | -| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | planner | -| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | planner | -| patterns | Code conventions, design patterns, naming conventions, best practices | analyst, planner | -| testing | Test files, coverage gaps, test patterns, mocking strategies | planner | -| general | Broad semantic search for topic-related code | analyst | - -## Exploration Strategies - -### Low Complexity (direct search) - -For simple queries, use ACE semantic search: - -``` -mcp__ace-tool__search_context(project_root_path="", query="") -``` - -ACE failure fallback: `rg -l '' --type ts` - -### Medium/High Complexity (multi-angle) - -For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles (see planner's `commands/explore.md`). - -## Search Tool Priority - -| Tool | Priority | Use Case | -|------|----------|----------| -| mcp__ace-tool__search_context | P0 | Semantic search | -| Grep / Glob | P1 | Pattern matching | -| cli-explore-agent | Deep | Multi-angle exploration | -| WebSearch | P3 | External docs | - -## Integration with Roles - -### analyst (RESEARCH-001) - -``` -# After seed analysis, explore codebase context -Task({ - subagent_type: "cli-explore-agent", - description: "Explore general context", - prompt: "Explore codebase for: \nFocus angle: general\n..." -}) -# Result feeds into discovery-context.json -``` - -### planner (PLAN-001) - -``` -# Multi-angle exploration before plan generation -for angle in selected_angles: - Task({ - subagent_type: "cli-explore-agent", - description: "Explore ", - prompt: "Explore codebase for: \nFocus angle: \n..." - }) -# Explorations manifest built from cache-index.json -``` - -### Any role needing context - -Any role can call explore subagent when needing codebase context for better decisions. - -## Comparison with v3 - -| Aspect | v3 (explorer role) | v4 (explore subagent) | -|--------|-------------------|----------------------| -| Identity | Full team member | Utility subagent | -| Task creation | Coordinator creates EXPLORE-* tasks | No tasks, direct call | -| Spawn overhead | Full agent lifecycle | Subagent call (~5s) | -| Result sharing | Isolated in explorations/ | Shared cache with index | -| Caller | Only via coordinator dispatch | Any role directly | -| Duplication | analyst + planner + explorer all explore | Single cached path | diff --git a/.claude/skills/team-lifecycle-v4/templates/architecture-doc.md b/.claude/skills/team-lifecycle-v4/templates/architecture-doc.md deleted file mode 100644 index 5106de03..00000000 --- a/.claude/skills/team-lifecycle-v4/templates/architecture-doc.md +++ /dev/null @@ -1,254 +0,0 @@ -# Architecture Document Template (Directory Structure) - -Template for generating architecture decision documents as a directory of individual ADR files in Phase 4. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 4 (Architecture) | Generate `architecture/` directory from requirements analysis | -| Output Location | `{workDir}/architecture/` | - -## Output Structure - -``` -{workDir}/architecture/ -├── _index.md # Overview, components, tech stack, data model, security -├── ADR-001-{slug}.md # Individual Architecture Decision Record -├── ADR-002-{slug}.md -└── ... -``` - ---- - -## Template: _index.md - -```markdown ---- -session_id: {session_id} -phase: 4 -document_type: architecture-index -status: draft -generated_at: {timestamp} -version: 1 -dependencies: - - ../spec-config.json - - ../product-brief.md - - ../requirements/_index.md ---- - -# Architecture: {product_name} - -{executive_summary - high-level architecture approach and key decisions} - -## System Overview - -### Architecture Style -{description of chosen architecture style: microservices, monolith, serverless, etc.} - -### System Context Diagram - -```mermaid -C4Context - title System Context Diagram - Person(user, "User", "Primary user") - System(system, "{product_name}", "Core system") - System_Ext(ext1, "{external_system}", "{description}") - Rel(user, system, "Uses") - Rel(system, ext1, "Integrates with") -``` - -## Component Architecture - -### Component Diagram - -```mermaid -graph TD - subgraph "{product_name}" - A[Component A] --> B[Component B] - B --> C[Component C] - A --> D[Component D] - end - B --> E[External Service] -``` - -### Component Descriptions - -| Component | Responsibility | Technology | Dependencies | -|-----------|---------------|------------|--------------| -| {component_name} | {what it does} | {tech stack} | {depends on} | - -## Technology Stack - -### Core Technologies - -| Layer | Technology | Version | Rationale | -|-------|-----------|---------|-----------| -| Frontend | {technology} | {version} | {why chosen} | -| Backend | {technology} | {version} | {why chosen} | -| Database | {technology} | {version} | {why chosen} | -| Infrastructure | {technology} | {version} | {why chosen} | - -### Key Libraries & Frameworks - -| Library | Purpose | License | -|---------|---------|---------| -| {library_name} | {purpose} | {license} | - -## Architecture Decision Records - -| ADR | Title | Status | Key Choice | -|-----|-------|--------|------------| -| [ADR-001](ADR-001-{slug}.md) | {title} | Accepted | {one-line summary} | -| [ADR-002](ADR-002-{slug}.md) | {title} | Accepted | {one-line summary} | -| [ADR-003](ADR-003-{slug}.md) | {title} | Proposed | {one-line summary} | - -## Data Architecture - -### Data Model - -```mermaid -erDiagram - ENTITY_A ||--o{ ENTITY_B : "has many" - ENTITY_A { - string id PK - string name - datetime created_at - } - ENTITY_B { - string id PK - string entity_a_id FK - string value - } -``` - -### Data Storage Strategy - -| Data Type | Storage | Retention | Backup | -|-----------|---------|-----------|--------| -| {type} | {storage solution} | {retention policy} | {backup strategy} | - -## API Design - -### API Overview - -| Endpoint | Method | Purpose | Auth | -|----------|--------|---------|------| -| {/api/resource} | {GET/POST/etc} | {purpose} | {auth type} | - -## Security Architecture - -### Security Controls - -| Control | Implementation | Requirement | -|---------|---------------|-------------| -| Authentication | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | -| Authorization | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | -| Data Protection | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) | - -## Infrastructure & Deployment - -### Deployment Architecture - -{description of deployment model: containers, serverless, VMs, etc.} - -### Environment Strategy - -| Environment | Purpose | Configuration | -|-------------|---------|---------------| -| Development | Local development | {config} | -| Staging | Pre-production testing | {config} | -| Production | Live system | {config} | - -## Codebase Integration - -{if has_codebase is true:} - -### Existing Code Mapping - -| New Component | Existing Module | Integration Type | Notes | -|--------------|----------------|------------------|-------| -| {component} | {existing module path} | Extend/Replace/New | {notes} | - -### Migration Notes -{any migration considerations for existing code} - -## Quality Attributes - -| Attribute | Target | Measurement | ADR Reference | -|-----------|--------|-------------|---------------| -| Performance | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | -| Scalability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | -| Reliability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) | - -## Risks & Mitigations - -| Risk | Impact | Probability | Mitigation | -|------|--------|-------------|------------| -| {risk} | High/Medium/Low | High/Medium/Low | {mitigation approach} | - -## Open Questions - -- [ ] {architectural question 1} -- [ ] {architectural question 2} - -## References - -- Derived from: [Requirements](../requirements/_index.md), [Product Brief](../product-brief.md) -- Next: [Epics & Stories](../epics/_index.md) -``` - ---- - -## Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record) - -```markdown ---- -id: ADR-{NNN} -status: Accepted -traces_to: [{REQ-NNN}, {NFR-X-NNN}] -date: {timestamp} ---- - -# ADR-{NNN}: {decision_title} - -## Context - -{what is the situation that motivates this decision} - -## Decision - -{what is the chosen approach} - -## Alternatives Considered - -| Option | Pros | Cons | -|--------|------|------| -| {option_1 - chosen} | {pros} | {cons} | -| {option_2} | {pros} | {cons} | -| {option_3} | {pros} | {cons} | - -## Consequences - -- **Positive**: {positive outcomes} -- **Negative**: {tradeoffs accepted} -- **Risks**: {risks to monitor} - -## Traces - -- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md) -- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5) -``` - ---- - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | product-brief.md | Product/feature name | -| `{NNN}` | Auto-increment | ADR/requirement number | -| `{slug}` | Auto-generated | Kebab-case from decision title | -| `{has_codebase}` | spec-config.json | Whether existing codebase exists | diff --git a/.claude/skills/team-lifecycle-v4/templates/epics-template.md b/.claude/skills/team-lifecycle-v4/templates/epics-template.md deleted file mode 100644 index 939d933c..00000000 --- a/.claude/skills/team-lifecycle-v4/templates/epics-template.md +++ /dev/null @@ -1,196 +0,0 @@ -# Epics & Stories Template (Directory Structure) - -Template for generating epic/story breakdown as a directory of individual Epic files in Phase 5. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 5 (Epics & Stories) | Generate `epics/` directory from requirements decomposition | -| Output Location | `{workDir}/epics/` | - -## Output Structure - -``` -{workDir}/epics/ -├── _index.md # Overview table + dependency map + MVP scope + execution order -├── EPIC-001-{slug}.md # Individual Epic with its Stories -├── EPIC-002-{slug}.md -└── ... -``` - ---- - -## Template: _index.md - -```markdown ---- -session_id: {session_id} -phase: 5 -document_type: epics-index -status: draft -generated_at: {timestamp} -version: 1 -dependencies: - - ../spec-config.json - - ../product-brief.md - - ../requirements/_index.md - - ../architecture/_index.md ---- - -# Epics & Stories: {product_name} - -{executive_summary - overview of epic structure and MVP scope} - -## Epic Overview - -| Epic ID | Title | Priority | MVP | Stories | Est. Size | -|---------|-------|----------|-----|---------|-----------| -| [EPIC-001](EPIC-001-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} | -| [EPIC-002](EPIC-002-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} | -| [EPIC-003](EPIC-003-{slug}.md) | {title} | Should | No | {n} | {S/M/L/XL} | - -## Dependency Map - -```mermaid -graph LR - EPIC-001 --> EPIC-002 - EPIC-001 --> EPIC-003 - EPIC-002 --> EPIC-004 - EPIC-003 --> EPIC-005 -``` - -### Dependency Notes -{explanation of why these dependencies exist and suggested execution order} - -### Recommended Execution Order -1. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - foundational} -2. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - depends on #1} -3. ... - -## MVP Scope - -### MVP Epics -{list of epics included in MVP with justification, linking to each} - -### MVP Definition of Done -- [ ] {MVP completion criterion 1} -- [ ] {MVP completion criterion 2} -- [ ] {MVP completion criterion 3} - -## Traceability Matrix - -| Requirement | Epic | Stories | Architecture | -|-------------|------|---------|--------------| -| [REQ-001](../requirements/REQ-001-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-001, STORY-001-002 | [ADR-001](../architecture/ADR-001-{slug}.md) | -| [REQ-002](../requirements/REQ-002-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-003 | Component B | -| [REQ-003](../requirements/REQ-003-{slug}.md) | [EPIC-002](EPIC-002-{slug}.md) | STORY-002-001 | [ADR-002](../architecture/ADR-002-{slug}.md) | - -## Estimation Summary - -| Size | Meaning | Count | -|------|---------|-------| -| S | Small - well-understood, minimal risk | {n} | -| M | Medium - some complexity, moderate risk | {n} | -| L | Large - significant complexity, should consider splitting | {n} | -| XL | Extra Large - high complexity, must split before implementation | {n} | - -## Risks & Considerations - -| Risk | Affected Epics | Mitigation | -|------|---------------|------------| -| {risk description} | [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) | {mitigation} | - -## Open Questions - -- [ ] {question about scope or implementation 1} -- [ ] {question about scope or implementation 2} - -## References - -- Derived from: [Requirements](../requirements/_index.md), [Architecture](../architecture/_index.md) -- Handoff to: execution workflows (lite-plan, plan, req-plan) -``` - ---- - -## Template: EPIC-NNN-{slug}.md (Individual Epic) - -```markdown ---- -id: EPIC-{NNN} -priority: {Must|Should|Could} -mvp: {true|false} -size: {S|M|L|XL} -requirements: [REQ-{NNN}] -architecture: [ADR-{NNN}] -dependencies: [EPIC-{NNN}] -status: draft ---- - -# EPIC-{NNN}: {epic_title} - -**Priority**: {Must|Should|Could} -**MVP**: {Yes|No} -**Estimated Size**: {S|M|L|XL} - -## Description - -{detailed epic description} - -## Requirements - -- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title} -- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title} - -## Architecture - -- [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md): {title} -- Component: {component_name} - -## Dependencies - -- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (blocking): {reason} -- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (soft): {reason} - -## Stories - -### STORY-{EPIC}-001: {story_title} - -**User Story**: As a {persona}, I want to {action} so that {benefit}. - -**Acceptance Criteria**: -- [ ] {criterion 1} -- [ ] {criterion 2} -- [ ] {criterion 3} - -**Size**: {S|M|L|XL} -**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md) - ---- - -### STORY-{EPIC}-002: {story_title} - -**User Story**: As a {persona}, I want to {action} so that {benefit}. - -**Acceptance Criteria**: -- [ ] {criterion 1} -- [ ] {criterion 2} - -**Size**: {S|M|L|XL} -**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md) -``` - ---- - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | product-brief.md | Product/feature name | -| `{EPIC}` | Auto-increment | Epic number (3 digits) | -| `{NNN}` | Auto-increment | Story/requirement number | -| `{slug}` | Auto-generated | Kebab-case from epic/story title | -| `{S\|M\|L\|XL}` | CLI analysis | Relative size estimate | diff --git a/.claude/skills/team-lifecycle-v4/templates/product-brief.md b/.claude/skills/team-lifecycle-v4/templates/product-brief.md deleted file mode 100644 index ffbdf437..00000000 --- a/.claude/skills/team-lifecycle-v4/templates/product-brief.md +++ /dev/null @@ -1,133 +0,0 @@ -# Product Brief Template - -Template for generating product brief documents in Phase 2. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 2 (Product Brief) | Generate product-brief.md from multi-CLI analysis | -| Output Location | `{workDir}/product-brief.md` | - ---- - -## Template - -```markdown ---- -session_id: {session_id} -phase: 2 -document_type: product-brief -status: draft -generated_at: {timestamp} -stepsCompleted: [] -version: 1 -dependencies: - - spec-config.json ---- - -# Product Brief: {product_name} - -{executive_summary - 2-3 sentences capturing the essence of the product/feature} - -## Vision - -{vision_statement - clear, aspirational 1-3 sentence statement of what success looks like} - -## Problem Statement - -### Current Situation -{description of the current state and pain points} - -### Impact -{quantified impact of the problem - who is affected, how much, how often} - -## Target Users - -{for each user persona:} - -### {Persona Name} -- **Role**: {user's role/context} -- **Needs**: {primary needs related to this product} -- **Pain Points**: {current frustrations} -- **Success Criteria**: {what success looks like for this user} - -## Goals & Success Metrics - -| Goal ID | Goal | Success Metric | Target | -|---------|------|----------------|--------| -| G-001 | {goal description} | {measurable metric} | {specific target} | -| G-002 | {goal description} | {measurable metric} | {specific target} | - -## Scope - -### In Scope -- {feature/capability 1} -- {feature/capability 2} -- {feature/capability 3} - -### Out of Scope -- {explicitly excluded item 1} -- {explicitly excluded item 2} - -### Assumptions -- {key assumption 1} -- {key assumption 2} - -## Competitive Landscape - -| Aspect | Current State | Proposed Solution | Advantage | -|--------|--------------|-------------------|-----------| -| {aspect} | {how it's done now} | {our approach} | {differentiator} | - -## Constraints & Dependencies - -### Technical Constraints -- {constraint 1} -- {constraint 2} - -### Business Constraints -- {constraint 1} - -### Dependencies -- {external dependency 1} -- {external dependency 2} - -## Multi-Perspective Synthesis - -### Product Perspective -{summary of product/market analysis findings} - -### Technical Perspective -{summary of technical feasibility and constraints} - -### User Perspective -{summary of user journey and UX considerations} - -### Convergent Themes -{themes where all perspectives agree} - -### Conflicting Views -{areas where perspectives differ, with notes on resolution approach} - -## Open Questions - -- [ ] {unresolved question 1} -- [ ] {unresolved question 2} - -## References - -- Derived from: [spec-config.json](spec-config.json) -- Next: [Requirements PRD](requirements.md) -``` - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | Seed analysis | Product/feature name | -| `{executive_summary}` | CLI synthesis | 2-3 sentence summary | -| `{vision_statement}` | CLI product perspective | Aspirational vision | -| All `{...}` fields | CLI analysis outputs | Filled from multi-perspective analysis | diff --git a/.claude/skills/team-lifecycle-v4/templates/requirements-prd.md b/.claude/skills/team-lifecycle-v4/templates/requirements-prd.md deleted file mode 100644 index 0b1dbf28..00000000 --- a/.claude/skills/team-lifecycle-v4/templates/requirements-prd.md +++ /dev/null @@ -1,224 +0,0 @@ -# Requirements PRD Template (Directory Structure) - -Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3. - -## Usage Context - -| Phase | Usage | -|-------|-------| -| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion | -| Output Location | `{workDir}/requirements/` | - -## Output Structure - -``` -{workDir}/requirements/ -├── _index.md # Summary + MoSCoW table + traceability matrix + links -├── REQ-001-{slug}.md # Individual functional requirement -├── REQ-002-{slug}.md -├── NFR-P-001-{slug}.md # Non-functional: Performance -├── NFR-S-001-{slug}.md # Non-functional: Security -├── NFR-SC-001-{slug}.md # Non-functional: Scalability -├── NFR-U-001-{slug}.md # Non-functional: Usability -└── ... -``` - ---- - -## Template: _index.md - -```markdown ---- -session_id: {session_id} -phase: 3 -document_type: requirements-index -status: draft -generated_at: {timestamp} -version: 1 -dependencies: - - ../spec-config.json - - ../product-brief.md ---- - -# Requirements: {product_name} - -{executive_summary - brief overview of what this PRD covers and key decisions} - -## Requirement Summary - -| Priority | Count | Coverage | -|----------|-------|----------| -| Must Have | {n} | {description of must-have scope} | -| Should Have | {n} | {description of should-have scope} | -| Could Have | {n} | {description of could-have scope} | -| Won't Have | {n} | {description of explicitly excluded} | - -## Functional Requirements - -| ID | Title | Priority | Traces To | -|----|-------|----------|-----------| -| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) | -| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) | -| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) | - -## Non-Functional Requirements - -### Performance - -| ID | Title | Target | -|----|-------|--------| -| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} | - -### Security - -| ID | Title | Standard | -|----|-------|----------| -| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} | - -### Scalability - -| ID | Title | Target | -|----|-------|--------| -| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} | - -### Usability - -| ID | Title | Target | -|----|-------|--------| -| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} | - -## Data Requirements - -### Data Entities - -| Entity | Description | Key Attributes | -|--------|-------------|----------------| -| {entity_name} | {description} | {attr1, attr2, attr3} | - -### Data Flows - -{description of key data flows, optionally with Mermaid diagram} - -## Integration Requirements - -| System | Direction | Protocol | Data Format | Notes | -|--------|-----------|----------|-------------|-------| -| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} | - -## Constraints & Assumptions - -### Constraints -- {technical or business constraint 1} -- {technical or business constraint 2} - -### Assumptions -- {assumption 1 - must be validated} -- {assumption 2 - must be validated} - -## Priority Rationale - -{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries} - -## Traceability Matrix - -| Goal | Requirements | -|------|-------------| -| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) | -| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) | - -## Open Questions - -- [ ] {unresolved question 1} -- [ ] {unresolved question 2} - -## References - -- Derived from: [Product Brief](../product-brief.md) -- Next: [Architecture](../architecture/_index.md) -``` - ---- - -## Template: REQ-NNN-{slug}.md (Individual Functional Requirement) - -```markdown ---- -id: REQ-{NNN} -type: functional -priority: {Must|Should|Could|Won't} -traces_to: [G-{NNN}] -status: draft ---- - -# REQ-{NNN}: {requirement_title} - -**Priority**: {Must|Should|Could|Won't} - -## Description - -{detailed requirement description} - -## User Story - -As a {persona}, I want to {action} so that {benefit}. - -## Acceptance Criteria - -- [ ] {specific, testable criterion 1} -- [ ] {specific, testable criterion 2} -- [ ] {specific, testable criterion 3} - -## Traces - -- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics) -- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable) -- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5) -``` - ---- - -## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement) - -```markdown ---- -id: NFR-{type}-{NNN} -type: non-functional -category: {Performance|Security|Scalability|Usability} -priority: {Must|Should|Could} -status: draft ---- - -# NFR-{type}-{NNN}: {requirement_title} - -**Category**: {Performance|Security|Scalability|Usability} -**Priority**: {Must|Should|Could} - -## Requirement - -{detailed requirement description} - -## Metric & Target - -| Metric | Target | Measurement Method | -|--------|--------|--------------------| -| {metric} | {target value} | {how measured} | - -## Traces - -- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics) -- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable) -``` - ---- - -## Variable Descriptions - -| Variable | Source | Description | -|----------|--------|-------------| -| `{session_id}` | spec-config.json | Session identifier | -| `{timestamp}` | Runtime | ISO8601 generation timestamp | -| `{product_name}` | product-brief.md | Product/feature name | -| `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) | -| `{slug}` | Auto-generated | Kebab-case from requirement title | -| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) | -| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag | diff --git a/ccw/frontend/src/lib/i18n.ts b/ccw/frontend/src/lib/i18n.ts index c22ed58a..4fdd4160 100644 --- a/ccw/frontend/src/lib/i18n.ts +++ b/ccw/frontend/src/lib/i18n.ts @@ -68,9 +68,21 @@ const messages: Record> = { zh: {}, }; +/** + * Load messages for a specific locale only (lazy loading) + * This is the optimized init method that loads only the active locale + */ +export async function loadMessagesForLocale(locale: Locale): Promise> { + const localeMessages = await loadMessages(locale); + messages[locale] = localeMessages; + updateIntl(locale); + return localeMessages; +} + /** * Initialize translation messages for all locales * Call this during app initialization + * NOTE: Use loadMessagesForLocale() for faster single-locale init */ export async function initMessages(): Promise { // Load messages for both locales in parallel diff --git a/ccw/frontend/src/main.tsx b/ccw/frontend/src/main.tsx index ee765f32..72e3e672 100644 --- a/ccw/frontend/src/main.tsx +++ b/ccw/frontend/src/main.tsx @@ -5,7 +5,7 @@ import './index.css' import 'react-grid-layout/css/styles.css' import 'react-resizable/css/styles.css' import 'xterm/css/xterm.css' -import { initMessages, getInitialLocale, getMessages, type Locale } from './lib/i18n' +import { loadMessagesForLocale, getInitialLocale } from './lib/i18n' import { logWebVitals } from './lib/webVitals' /** @@ -29,17 +29,14 @@ async function bootstrapApplication() { const rootElement = document.getElementById('root') if (!rootElement) throw new Error('Failed to find the root element') - // Initialize CSRF token before any API calls - await initCsrfToken() + // Parallelize CSRF token fetch and locale detection (independent operations) + const [, locale] = await Promise.all([ + initCsrfToken(), + getInitialLocale() + ]) - // Initialize translation messages - await initMessages() - - // Determine initial locale from browser/storage - const locale: Locale = getInitialLocale() - - // Get messages for the initial locale - const messages = getMessages(locale) + // Load only the active locale's messages (lazy load secondary on demand) + const messages = await loadMessagesForLocale(locale) const root = createRoot(rootElement) root.render( diff --git a/ccw/frontend/src/router.tsx b/ccw/frontend/src/router.tsx index d79a3830..4e35d2cf 100644 --- a/ccw/frontend/src/router.tsx +++ b/ccw/frontend/src/router.tsx @@ -1,53 +1,68 @@ // ======================================== // Router Configuration // ======================================== -// React Router v6 configuration with all dashboard routes +// React Router v6 configuration with code splitting for optimal bundle size import { createBrowserRouter, RouteObject, Navigate } from 'react-router-dom'; +import { lazy, Suspense } from 'react'; import { AppShell } from '@/components/layout'; -import { - HomePage, - SessionsPage, - FixSessionPage, - ProjectOverviewPage, - SessionDetailPage, - HistoryPage, - OrchestratorPage, - IssueHubPage, - SkillsManagerPage, - CommandsManagerPage, - MemoryPage, - SettingsPage, - NotFoundPage, - LiteTasksPage, - // LiteTaskDetailPage removed - now using TaskDrawer instead - ReviewSessionPage, - McpManagerPage, - EndpointsPage, - InstallationsPage, - HookManagerPage, - RulesManagerPage, - PromptHistoryPage, - ExplorerPage, - GraphExplorerPage, - CodexLensManagerPage, - ApiSettingsPage, - CliViewerPage, - CliSessionSharePage, - TeamPage, - TerminalDashboardPage, - AnalysisPage, - SpecsSettingsPage, -} from '@/pages'; + +// Import HomePage directly (no lazy - needed immediately) +import { HomePage } from '@/pages/HomePage'; + +// Lazy load all other route components for code splitting +const SessionsPage = lazy(() => import('@/pages/SessionsPage').then(m => ({ default: m.SessionsPage }))); +const FixSessionPage = lazy(() => import('@/pages/FixSessionPage').then(m => ({ default: m.FixSessionPage }))); +const ProjectOverviewPage = lazy(() => import('@/pages/ProjectOverviewPage').then(m => ({ default: m.ProjectOverviewPage }))); +const SessionDetailPage = lazy(() => import('@/pages/SessionDetailPage').then(m => ({ default: m.SessionDetailPage }))); +const HistoryPage = lazy(() => import('@/pages/HistoryPage').then(m => ({ default: m.HistoryPage }))); +const OrchestratorPage = lazy(() => import('@/pages/orchestrator/OrchestratorPage').then(m => ({ default: m.OrchestratorPage }))); +const IssueHubPage = lazy(() => import('@/pages/IssueHubPage').then(m => ({ default: m.IssueHubPage }))); +const SkillsManagerPage = lazy(() => import('@/pages/SkillsManagerPage').then(m => ({ default: m.SkillsManagerPage }))); +const CommandsManagerPage = lazy(() => import('@/pages/CommandsManagerPage').then(m => ({ default: m.CommandsManagerPage }))); +const MemoryPage = lazy(() => import('@/pages/MemoryPage').then(m => ({ default: m.MemoryPage }))); +const SettingsPage = lazy(() => import('@/pages/SettingsPage').then(m => ({ default: m.SettingsPage }))); +const NotFoundPage = lazy(() => import('@/pages/NotFoundPage').then(m => ({ default: m.NotFoundPage }))); +const LiteTasksPage = lazy(() => import('@/pages/LiteTasksPage').then(m => ({ default: m.LiteTasksPage }))); +const ReviewSessionPage = lazy(() => import('@/pages/ReviewSessionPage').then(m => ({ default: m.ReviewSessionPage }))); +const McpManagerPage = lazy(() => import('@/pages/McpManagerPage').then(m => ({ default: m.McpManagerPage }))); +const EndpointsPage = lazy(() => import('@/pages/EndpointsPage').then(m => ({ default: m.EndpointsPage }))); +const InstallationsPage = lazy(() => import('@/pages/InstallationsPage').then(m => ({ default: m.InstallationsPage }))); +const HookManagerPage = lazy(() => import('@/pages/HookManagerPage').then(m => ({ default: m.HookManagerPage }))); +const RulesManagerPage = lazy(() => import('@/pages/RulesManagerPage').then(m => ({ default: m.RulesManagerPage }))); +const PromptHistoryPage = lazy(() => import('@/pages/PromptHistoryPage').then(m => ({ default: m.PromptHistoryPage }))); +const ExplorerPage = lazy(() => import('@/pages/ExplorerPage').then(m => ({ default: m.ExplorerPage }))); +const GraphExplorerPage = lazy(() => import('@/pages/GraphExplorerPage').then(m => ({ default: m.GraphExplorerPage }))); +const CodexLensManagerPage = lazy(() => import('@/pages/CodexLensManagerPage').then(m => ({ default: m.CodexLensManagerPage }))); +const ApiSettingsPage = lazy(() => import('@/pages/ApiSettingsPage').then(m => ({ default: m.ApiSettingsPage }))); +const CliViewerPage = lazy(() => import('@/pages/CliViewerPage').then(m => ({ default: m.CliViewerPage }))); +const CliSessionSharePage = lazy(() => import('@/pages/CliSessionSharePage').then(m => ({ default: m.CliSessionSharePage }))); +const TeamPage = lazy(() => import('@/pages/TeamPage').then(m => ({ default: m.TeamPage }))); +const TerminalDashboardPage = lazy(() => import('@/pages/TerminalDashboardPage').then(m => ({ default: m.TerminalDashboardPage }))); +const AnalysisPage = lazy(() => import('@/pages/AnalysisPage').then(m => ({ default: m.AnalysisPage }))); +const SpecsSettingsPage = lazy(() => import('@/pages/SpecsSettingsPage').then(m => ({ default: m.SpecsSettingsPage }))); + +// Loading fallback component for lazy-loaded routes +function PageSkeleton() { + return ( +
+
Loading...
+
+ ); +} /** * Route configuration for the dashboard - * All routes are wrapped in AppShell layout + * All routes are wrapped in AppShell layout with Suspense for code splitting */ const routes: RouteObject[] = [ { path: 'cli-sessions/share', - element: , + element: ( + }> + + + ), }, { path: '/', @@ -59,36 +74,68 @@ const routes: RouteObject[] = [ }, { path: 'sessions', - element: , + element: ( + }> + + + ), }, { path: 'sessions/:sessionId', - element: , + element: ( + }> + + + ), }, { path: 'sessions/:sessionId/fix', - element: , + element: ( + }> + + + ), }, { path: 'sessions/:sessionId/review', - element: , + element: ( + }> + + + ), }, { path: 'lite-tasks', - element: , + element: ( + }> + + + ), }, // /lite-tasks/:sessionId route removed - now using TaskDrawer { path: 'project', - element: , + element: ( + }> + + + ), }, { path: 'history', - element: , + element: ( + }> + + + ), }, { path: 'orchestrator', - element: , + element: ( + }> + + + ), }, { path: 'loops', @@ -96,11 +143,19 @@ const routes: RouteObject[] = [ }, { path: 'cli-viewer', - element: , + element: ( + }> + + + ), }, { path: 'issues', - element: , + element: ( + }> + + + ), }, // Legacy routes - redirect to hub with tab parameter { @@ -113,75 +168,147 @@ const routes: RouteObject[] = [ }, { path: 'skills', - element: , + element: ( + }> + + + ), }, { path: 'commands', - element: , + element: ( + }> + + + ), }, { path: 'memory', - element: , + element: ( + }> + + + ), }, { path: 'prompts', - element: , + element: ( + }> + + + ), }, { path: 'settings', - element: , + element: ( + }> + + + ), }, { path: 'settings/mcp', - element: , + element: ( + }> + + + ), }, { path: 'settings/endpoints', - element: , + element: ( + }> + + + ), }, { path: 'settings/installations', - element: , + element: ( + }> + + + ), }, { path: 'settings/rules', - element: , + element: ( + }> + + + ), }, { path: 'settings/specs', - element: , + element: ( + }> + + + ), }, { path: 'settings/codexlens', - element: , + element: ( + }> + + + ), }, { path: 'api-settings', - element: , + element: ( + }> + + + ), }, { path: 'hooks', - element: , + element: ( + }> + + + ), }, { path: 'explorer', - element: , + element: ( + }> + + + ), }, { path: 'graph', - element: , + element: ( + }> + + + ), }, { path: 'teams', - element: , + element: ( + }> + + + ), }, { path: 'analysis', - element: , + element: ( + }> + + + ), }, { path: 'terminal-dashboard', - element: , + element: ( + }> + + + ), }, { path: 'skill-hub', @@ -190,7 +317,11 @@ const routes: RouteObject[] = [ // Catch-all route for 404 { path: '*', - element: , + element: ( + }> + + + ), }, ], }, diff --git a/ccw/src/core/routes/notification-routes.ts b/ccw/src/core/routes/notification-routes.ts index 8aa1cdcb..6f1d4d8d 100644 --- a/ccw/src/core/routes/notification-routes.ts +++ b/ccw/src/core/routes/notification-routes.ts @@ -30,6 +30,15 @@ import { deepMerge } from '../../types/util.js'; // ========== Input Validation ========== +// Compiled regex patterns for performance (compiled once at module load) +const TELEGRAM_BOT_TOKEN_REGEX = /^\d{8,15}:[A-Za-z0-9_-]{30,50}$/; +const TELEGRAM_CHAT_ID_REGEX = /^-?\d{1,20}$/; +const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; +const DISCORD_HOSTNAMES = ['discord.com', 'discordapp.com']; +const FEISHU_HOSTNAMES = ['feishu.cn', 'larksuite.com', 'lark.com']; +const DINGTALK_HOSTNAMES = ['dingtalk.com', 'oapi.dingtalk.com']; +const WECOM_HOSTNAMES = ['qyapi.weixin.qq.com', 'work.weixin.qq.com']; + /** * Validate URL format (must be http or https) */ @@ -51,7 +60,7 @@ function isValidDiscordWebhookUrl(url: string): boolean { const parsed = new URL(url); // Discord webhooks are typically: discord.com/api/webhooks/{id}/{token} return ( - (parsed.hostname === 'discord.com' || parsed.hostname === 'discordapp.com') && + DISCORD_HOSTNAMES.includes(parsed.hostname) && parsed.pathname.startsWith('/api/webhooks/') ); } catch { @@ -65,7 +74,7 @@ function isValidDiscordWebhookUrl(url: string): boolean { function isValidTelegramBotToken(token: string): boolean { // Telegram bot tokens are in format: {bot_id}:{token} // Bot ID is a number, token is alphanumeric with underscores and hyphens - return /^\d{8,15}:[A-Za-z0-9_-]{30,50}$/.test(token); + return TELEGRAM_BOT_TOKEN_REGEX.test(token); } /** @@ -73,7 +82,7 @@ function isValidTelegramBotToken(token: string): boolean { */ function isValidTelegramChatId(chatId: string): boolean { // Chat IDs are numeric, optionally negative (for groups) - return /^-?\d{1,20}$/.test(chatId); + return TELEGRAM_CHAT_ID_REGEX.test(chatId); } /** @@ -138,7 +147,7 @@ function isValidDingTalkWebhookUrl(url: string): boolean { try { const parsed = new URL(url); // DingTalk webhooks are typically: oapi.dingtalk.com/robot/send?access_token=xxx - return parsed.hostname.includes('dingtalk.com') && parsed.pathname.includes('robot'); + return DINGTALK_HOSTNAMES.some(h => parsed.hostname.includes(h)) && parsed.pathname.includes('robot'); } catch { return false; } @@ -152,7 +161,7 @@ function isValidWeComWebhookUrl(url: string): boolean { try { const parsed = new URL(url); // WeCom webhooks are typically: qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx - return parsed.hostname.includes('qyapi.weixin.qq.com') && parsed.pathname.includes('webhook'); + return WECOM_HOSTNAMES.includes(parsed.hostname) && parsed.pathname.includes('webhook'); } catch { return false; } @@ -162,8 +171,8 @@ function isValidWeComWebhookUrl(url: string): boolean { * Validate email address format */ function isValidEmail(email: string): boolean { - // Basic email validation regex - return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); + // Basic email validation regex (using compiled constant) + return EMAIL_REGEX.test(email); } /** diff --git a/ccw/src/core/websocket.ts b/ccw/src/core/websocket.ts index f695f7e4..c4dfd7d1 100644 --- a/ccw/src/core/websocket.ts +++ b/ccw/src/core/websocket.ts @@ -13,9 +13,55 @@ import type { QueueSchedulerConfigUpdatedMessage, } from '../types/queue-types.js'; +// WebSocket configuration for connection limits and rate limiting +const WS_MAX_CONNECTIONS = 100; +const WS_MESSAGE_RATE_LIMIT = 10; // messages per second per client +const WS_RATE_LIMIT_WINDOW = 1000; // 1 second window + // WebSocket clients for real-time notifications export const wsClients = new Set(); +// Track message counts per client for rate limiting +export const wsClientMessageCounts = new Map(); + +/** + * Check if a new WebSocket connection should be accepted + * Returns true if connection allowed, false if limit reached + */ +export function canAcceptWebSocketConnection(): boolean { + return wsClients.size < WS_MAX_CONNECTIONS; +} + +/** + * Check if a client has exceeded their message rate limit + * Returns true if rate limit OK, false if exceeded + */ +export function checkClientRateLimit(client: Duplex): boolean { + const now = Date.now(); + const tracking = wsClientMessageCounts.get(client); + + if (!tracking || now > tracking.resetTime) { + // First message or window expired - reset tracking + wsClientMessageCounts.set(client, { count: 1, resetTime: now + WS_RATE_LIMIT_WINDOW }); + return true; + } + + if (tracking.count >= WS_MESSAGE_RATE_LIMIT) { + return false; // Rate limit exceeded + } + + tracking.count++; + return true; +} + +/** + * Clean up client tracking when they disconnect + */ +export function removeClientTracking(client: Duplex): void { + wsClients.delete(client); + wsClientMessageCounts.delete(client); +} + /** * WebSocket message types for Loop monitoring */ @@ -154,6 +200,24 @@ export function handleWebSocketUpgrade(req: IncomingMessage, socket: Duplex, _he socket.end(); return; } + + // Check connection limit + if (!canAcceptWebSocketConnection()) { + const responseHeaders = [ + 'HTTP/1.1 429 Too Many Requests', + 'Content-Type: text/plain', + 'Connection: close', + '', + 'WebSocket connection limit reached. Please try again later.', + '', + '' + ].join('\r\n'); + socket.write(responseHeaders); + socket.end(); + console.warn(`[WS] Connection rejected: limit reached (${wsClients.size}/${WS_MAX_CONNECTIONS})`); + return; + } + const acceptKey = createHash('sha1') .update(key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11') .digest('base64'); @@ -171,6 +235,8 @@ export function handleWebSocketUpgrade(req: IncomingMessage, socket: Duplex, _he // Add to clients set wsClients.add(socket); + // Initialize rate limit tracking + wsClientMessageCounts.set(socket, { count: 0, resetTime: Date.now() + WS_RATE_LIMIT_WINDOW }); console.log(`[WS] Client connected (${wsClients.size} total)`); // Replay any buffered A2UI surfaces to the new client @@ -194,6 +260,11 @@ export function handleWebSocketUpgrade(req: IncomingMessage, socket: Duplex, _he switch (opcode) { case 0x1: // Text frame if (payload) { + // Check rate limit before processing + if (!checkClientRateLimit(socket)) { + console.warn('[WS] Rate limit exceeded for client'); + break; + } console.log('[WS] Received:', payload); // Try to handle as A2UI message const handledAsA2UI = handleA2UIMessage(payload, a2uiWebSocketHandler, handleAnswer); @@ -227,12 +298,12 @@ export function handleWebSocketUpgrade(req: IncomingMessage, socket: Duplex, _he // Handle disconnect socket.on('close', () => { - wsClients.delete(socket); + removeClientTracking(socket); console.log(`[WS] Client disconnected (${wsClients.size} remaining)`); }); socket.on('error', () => { - wsClients.delete(socket); + removeClientTracking(socket); }); }