diff --git a/.ccw/workflows/cli-templates/schemas/explore-json-schema.json b/.ccw/workflows/cli-templates/schemas/explore-json-schema.json index ecbbd739..9f71282b 100644 --- a/.ccw/workflows/cli-templates/schemas/explore-json-schema.json +++ b/.ccw/workflows/cli-templates/schemas/explore-json-schema.json @@ -63,6 +63,35 @@ "type": "array", "items": {"type": "string"}, "description": "Key symbols (functions, classes, types) in this file relevant to the task. Example: ['AuthService', 'login', 'TokenPayload']" + }, + "key_code": { + "type": "array", + "items": { + "type": "object", + "required": ["symbol", "description"], + "properties": { + "symbol": { + "type": "string", + "description": "Symbol identifier (function, class, method, type). Example: 'AuthService.login()'" + }, + "location": { + "type": "string", + "description": "Line range in file. Example: 'L45-L78'" + }, + "description": { + "type": "string", + "minLength": 10, + "description": "What this code does and why it matters. Example: 'JWT token generation with bcrypt verification, returns {token, refreshToken} pair'" + } + }, + "additionalProperties": false + }, + "description": "Key code constructs with descriptions. Richer complement to key_symbols. Populate for files with relevance >= 0.7." + }, + "topic_relation": { + "type": "string", + "minLength": 15, + "description": "How this file relates to the exploration ANGLE/TOPIC. Must reference the angle explicitly. Example: 'Security exploration targets this file because JWT generation lacks token rotation'. Distinct from rationale (WHY selected) - topic_relation explains the CONNECTION to the exploration perspective." } }, "additionalProperties": false diff --git a/.claude/agents/cli-explore-agent.md b/.claude/agents/cli-explore-agent.md index b72493de..775affd8 100644 --- a/.claude/agents/cli-explore-agent.md +++ b/.claude/agents/cli-explore-agent.md @@ -123,7 +123,10 @@ RULES: {from prompt, if template specified} | analysis=READ-ONLY 2. Gemini results: Semantic understanding, design intent → `discovery_source: "cli-analysis"` 3. ACE search: Semantic code search → `discovery_source: "ace-search"` 4. Dependency tracing: Import/export graph → `discovery_source: "dependency-trace"` -5. Merge with source attribution and generate rationale for each file +5. Merge with source attribution and generate for each file: + - `rationale`: WHY the file was selected (selection basis) + - `topic_relation`: HOW the file connects to the exploration angle/topic + - `key_code`: Detailed descriptions of key symbols with locations (for relevance >= 0.7) --- @@ -155,6 +158,12 @@ Every file entry MUST have: - BAD: "Related to auth" or "Relevant file" - `role` (required, enum): Structural classification of why it was selected - `discovery_source` (optional but recommended): How the file was found +- `key_code` (strongly recommended for relevance >= 0.7): Array of {symbol, location?, description} + - GOOD: [{"symbol": "AuthService.login()", "location": "L45-L78", "description": "JWT token generation with bcrypt verification, returns token pair"}] + - BAD: [{"symbol": "login", "description": "login function"}] +- `topic_relation` (strongly recommended for relevance >= 0.7): Connection from exploration angle perspective + - GOOD: "Security exploration targets this file because JWT generation lacks token rotation" + - BAD: "Related to security" **Step 4: Pre-Output Validation Checklist** @@ -168,6 +177,8 @@ Before writing ANY JSON output, verify: - [ ] Data types correct (string, integer, array, object) - [ ] Every file in relevant_files has: path + relevance + rationale + role - [ ] Every rationale is specific (>10 chars, not generic) +- [ ] Files with relevance >= 0.7 have key_code with symbol + description (minLength 10) +- [ ] Files with relevance >= 0.7 have topic_relation explaining connection to angle (minLength 15) --- @@ -216,6 +227,8 @@ Brief summary: 9. **Every file MUST have rationale**: Specific selection basis tied to the topic (not generic) 10. **Every file MUST have role**: Classify as modify_target/dependency/pattern_reference/test_target/type_definition/integration_point/config/context_only 11. **Track discovery source**: Record how each file was found (bash-scan/cli-analysis/ace-search/dependency-trace/manual) +12. **Populate key_code for high-relevance files**: relevance >= 0.7 → key_code array with symbol, location, description +13. **Populate topic_relation for high-relevance files**: relevance >= 0.7 → topic_relation explaining file-to-angle connection **Bash Tool**: - Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution diff --git a/.claude/agents/cli-lite-planning-agent.md b/.claude/agents/cli-lite-planning-agent.md index 893a8f8f..fe699cda 100644 --- a/.claude/agents/cli-lite-planning-agent.md +++ b/.claude/agents/cli-lite-planning-agent.md @@ -504,7 +504,7 @@ function parseCLIOutput(cliOutput) { ```javascript // NOTE: relevant_files items are structured objects: -// {path, relevance, rationale, role, discovery_source?, key_symbols?} +// {path, relevance, rationale, role, discovery_source?, key_symbols?, key_code?, topic_relation?} function buildEnrichedContext(explorationsContext, explorationAngles) { const enriched = { relevant_files: [], patterns: [], dependencies: [], integration_points: [], constraints: [] } @@ -566,6 +566,7 @@ function inferAction(title) { } // NOTE: relevant_files items are structured objects with .path property +// New fields: key_code? (array of {symbol, location?, description}), topic_relation? (string) function inferFile(task, ctx) { const files = ctx?.relevant_files || [] const getPath = f => typeof f === 'string' ? f : f.path diff --git a/.claude/skills/team-lifecycle-v4/SKILL.md b/.claude/skills/team-lifecycle-v4/SKILL.md new file mode 100644 index 00000000..7a1e4446 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/SKILL.md @@ -0,0 +1,465 @@ +--- +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. + +## Key Changes from v3 + +| Change | Before (v3) | After (v4) | Impact | +|--------|------------|------------|--------| +| Discuss | Standalone role, 6 separate beats | Inline subagent called by produce roles | Spec beats: 12 -> 6 | +| Explorer | Standalone service role | Shared Explore subagent with cache | Eliminates spawn overhead | +| Explore cache | Per-role, no sharing | Centralized `explorations/` with cache-index | Avoids duplicate exploration | +| Worker advance | Always callback coordinator | Fast-advance for simple successors | Fewer coordinator wakes | + +## 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 | + +### 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 | + +--- + +## 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= + - **CLI fallback**: When MCP unavailable -> `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 | +|-----------|--------| +| 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) | + +### 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. + +### Shared Explore Utility + +Any role needing codebase context calls the explore subagent: + +``` +Task({ + subagent_type: "Explore", + 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 | Pause, wait for user `resume` | +| 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 | + +**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 + +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 +- 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 + SendMessage results to coordinator +4. TaskUpdate completed -> check next task or fast-advance` +}) +``` + +## 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 new file mode 100644 index 00000000..a09bb194 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/analyst/role.md @@ -0,0 +1,159 @@ +# 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: "Explore", + 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**: +- `consensus_reached` -> include in report, proceed normally +- `consensus_blocked` -> flag in SendMessage, coordinator decides next step + +**Report**: complexity, codebase presence, problem statement, exploration dimensions, discuss verdict, 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 new file mode 100644 index 00000000..8c6bc967 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/architect/commands/assess.md @@ -0,0 +1,193 @@ +# 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 new file mode 100644 index 00000000..a2cc6c5e --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/architect/role.md @@ -0,0 +1,103 @@ +# 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 new file mode 100644 index 00000000..1cc922fb --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md @@ -0,0 +1,139 @@ +# 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: ", + 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: ` | +| Inline discuss | Spec tasks have InlineDiscuss field matching round config | + +## 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 new file mode 100644 index 00000000..6e76bbb3 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md @@ -0,0 +1,191 @@ +# 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 | + +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 + +- 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 + +[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 | +|---------------|----------------|--------| +| QUALITY-001 | 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 | +| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers | + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Session file not found | Error, suggest re-initialization | +| Worker callback from unknown role | Log info, scan for other completions | +| All workers still running on resume | Report status, suggest check later | +| Pipeline stall (no ready, no running) | Check for missing tasks, report to user | +| Fast-advance conflict | Coordinator reconciles, no duplicate spawns | diff --git a/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md b/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md new file mode 100644 index 00000000..d4ec74c5 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md @@ -0,0 +1,176 @@ +# 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 + +--- + +## 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 | +| New session | None of the above | -> Phase 0 (Session Resume Check) | + +For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP. + +--- + +## 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) + +--- + +## 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 new file mode 100644 index 00000000..26501c5e --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md @@ -0,0 +1,166 @@ +# 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 new file mode 100644 index 00000000..0cd3296f --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/executor/role.md @@ -0,0 +1,103 @@ +# 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 new file mode 100644 index 00000000..b23f4f1d --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/fe-developer/role.md @@ -0,0 +1,111 @@ +# 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 new file mode 100644 index 00000000..c742380d --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/fe-qa/commands/pre-delivery-checklist.md @@ -0,0 +1,152 @@ +# 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 new file mode 100644 index 00000000..8e91131c --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/fe-qa/role.md @@ -0,0 +1,113 @@ +# 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 new file mode 100644 index 00000000..25b7271e --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/planner/commands/explore.md @@ -0,0 +1,172 @@ +# 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: "Explore", + 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 new file mode 100644 index 00000000..b5e96abd --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/planner/role.md @@ -0,0 +1,127 @@ +# Role: planner + +Multi-angle code exploration (via shared explore subagent with cache) and structured implementation planning. + +## Identity + +- **Name**: `planner` | **Prefix**: `PLAN-*` | **Tag**: `[planner]` +- **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**: +``` +/plan/ ++-- exploration-.json (per angle, from shared cache) ++-- explorations-manifest.json (summary) ++-- plan.json ++-- .task/TASK-*.json +``` + +Note: exploration files may be symlinked or referenced from `/explorations/` (shared cache location). + +--- + +## 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 new file mode 100644 index 00000000..874c4f98 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/code-review.md @@ -0,0 +1,163 @@ +# 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 new file mode 100644 index 00000000..3dfddc6f --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/spec-quality.md @@ -0,0 +1,202 @@ +# 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 new file mode 100644 index 00000000..c3d4692e --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/reviewer/role.md @@ -0,0 +1,133 @@ +# 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**: +- `consensus_reached` -> include in quality report as final endorsement +- `consensus_blocked` -> flag in SendMessage, report specific divergences + +--- + +## 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 new file mode 100644 index 00000000..8016d78a --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/tester/commands/validate.md @@ -0,0 +1,152 @@ +# 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 new file mode 100644 index 00000000..afdfd887 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/tester/role.md @@ -0,0 +1,108 @@ +# 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 new file mode 100644 index 00000000..9f7341a0 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/writer/commands/generate-doc.md @@ -0,0 +1,187 @@ +# 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-v4/roles/writer/role.md b/.claude/skills/team-lifecycle-v4/roles/writer/role.md new file mode 100644 index 00000000..212faada --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/writer/role.md @@ -0,0 +1,135 @@ +# Role: writer + +Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation. Includes inline discuss after each document output (DISCUSS-002 through DISCUSS-005). + +## Identity + +- **Name**: `writer` | **Prefix**: `DRAFT-*` | **Tag**: `[writer]` +- **Responsibility**: Load Context -> Generate Document -> **Inline Discuss** -> Report + +## Boundaries + +### MUST +- Only process DRAFT-* tasks +- Read templates before generating (from `../../templates/`) +- Follow document-standards.md (from `../../specs/`) +- Integrate prior discussion feedback when available +- Generate proper YAML frontmatter +- Call discuss subagent after document output (round from InlineDiscuss field) + +### MUST NOT +- Create tasks for other roles +- Skip template loading +- Modify discussion records from prior rounds +- Skip inline discuss + +## 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 | +|------|---------| +| commands/generate-doc.md | Multi-CLI document generation | +| gemini, codex, claude CLI | Multi-perspective content generation | +| discuss subagent | Inline discuss critique | + +--- + +## Phase 2: Context & Discussion 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 | + +**Success**: Template loaded, prior 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, prior discussion feedback, prior docs. + +--- + +## 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**: +- `consensus_reached` -> include action items in report +- `consensus_blocked` -> flag in SendMessage, include divergence details + +**Report**: doc type, validation status, discuss verdict, average rating, 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 coordinator | +| Discuss subagent fails | Proceed without discuss, log warning in report | diff --git a/.claude/skills/team-lifecycle-v4/specs/document-standards.md b/.claude/skills/team-lifecycle-v4/specs/document-standards.md new file mode 100644 index 00000000..2820cd98 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/specs/document-standards.md @@ -0,0 +1,192 @@ +# 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 new file mode 100644 index 00000000..ae968436 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/specs/quality-gates.md @@ -0,0 +1,207 @@ +# 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 new file mode 100644 index 00000000..c4b7fa48 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/specs/team-config.json @@ -0,0 +1,169 @@ +{ + "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", + "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", + "message_types": ["plan_ready", "plan_revision", "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", "fix_required", "error"] + }, + "reviewer": { + "task_prefix": "REVIEW", + "additional_prefixes": ["QUALITY"], + "responsibility": "Code review (REVIEW-*) + Spec quality validation (QUALITY-*) + inline discuss for sign-off", + "inline_discuss": "DISCUSS-006", + "message_types": ["review_result", "quality_result", "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": "Explore", + "callable_by": ["analyst", "planner", "any"], + "purpose": "Codebase exploration with centralized cache" + } + }, + + "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 new file mode 100644 index 00000000..67451075 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/subagents/discuss-subagent.md @@ -0,0 +1,134 @@ +# 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 +Return a summary string with: +- Verdict: consensus_reached or consensus_blocked +- Average rating +- Key action items (top 3) +- 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**: + - Include discuss verdict in Phase 5 report + - If `consensus_blocked` with high-severity divergences -> flag in SendMessage to coordinator + - Discussion record is written by the subagent, no further action needed + +## 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/explore-subagent.md b/.claude/skills/team-lifecycle-v4/subagents/explore-subagent.md new file mode 100644 index 00000000..6d34a3cd --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/subagents/explore-subagent.md @@ -0,0 +1,172 @@ +# 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: "Explore", + 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: "Explore", + 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: "Explore", + 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 new file mode 100644 index 00000000..5106de03 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/templates/architecture-doc.md @@ -0,0 +1,254 @@ +# 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 new file mode 100644 index 00000000..939d933c --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/templates/epics-template.md @@ -0,0 +1,196 @@ +# 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 new file mode 100644 index 00000000..ffbdf437 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/templates/product-brief.md @@ -0,0 +1,133 @@ +# 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 new file mode 100644 index 00000000..0b1dbf28 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/templates/requirements-prd.md @@ -0,0 +1,224 @@ +# 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/workflow-lite-plan/phases/01-lite-plan.md b/.claude/skills/workflow-lite-plan/phases/01-lite-plan.md index 0efc642f..de1181aa 100644 --- a/.claude/skills/workflow-lite-plan/phases/01-lite-plan.md +++ b/.claude/skills/workflow-lite-plan/phases/01-lite-plan.md @@ -255,6 +255,8 @@ cli-explore-agent autonomously handles: project structure discovery, schema load - [ ] Constraints are project-specific to ${angle} - [ ] JSON output follows schema exactly - [ ] clarification_needs includes options + recommended +- [ ] Files with relevance >= 0.7 have key_code array describing key symbols +- [ ] Files with relevance >= 0.7 have topic_relation explaining connection to ${angle} ## Execution **Write**: \`${sessionFolder}/exploration-${angle}.json\` diff --git a/.temp-memory-content.txt b/.temp-memory-content.txt new file mode 100644 index 00000000..9085900f --- /dev/null +++ b/.temp-memory-content.txt @@ -0,0 +1,105 @@ +## Session ID +(none) + +## Project Root +D:\Claude_dms3 + +## Objective +为 CCW spec 系统添加独立的 category 分类字段，实现 workflow stage 标记与 keywords 的分离，支持按阶段过滤加载 spec 文档。 + +## Execution Plan + +### Source: inferred + +
+Full Execution Plan (Click to expand) + +1. 分析当前 spec 系统实现 +2. 设计 category 分类方案 (general | exploration | planning | execution) +3. 后端实现： + - spec-index-builder.ts: 添加 category 字段到 SpecIndexEntry + - spec-init.ts: 更新 seed documents 使用 category + - spec-loader.ts: 支持 category 过滤 + - commands/spec.ts: 添加 --category 选项 + - cli.ts: 注册 --category 选项 +4. 前端实现： + - api.ts: 添加 category 类型 + - SpecCard.tsx: 显示 category badge + - SpecsSettingsPage.tsx: 添加 category 过滤 UI +5. 测试所有 ccw spec 命令 + +
+ +## Working Files (Modified) +- D:\Claude_dms3\ccw\src\tools\spec-index-builder.ts (role: core types + parsing) +- D:\Claude_dms3\ccw\src\tools\spec-init.ts (role: seed documents) +- D:\Claude_dms3\ccw\src\tools\spec-loader.ts (role: loading + filtering) +- D:\Claude_dms3\ccw\src\commands\spec.ts (role: CLI command handler) +- D:\Claude_dms3\ccw\src\cli.ts (role: CLI registration) +- D:\Claude_dms3\ccw\frontend\src\lib\api.ts (role: frontend types) +- D:\Claude_dms3\ccw\frontend\src\components\specs\SpecCard.tsx (role: UI display) +- D:\Claude_dms3\ccw\frontend\src\components\specs\index.ts (role: exports) +- D:\Claude_dms3\ccw\frontend\src\pages\SpecsSettingsPage.tsx (role: filtering UI) + +## Reference Files (Read-Only) +- D:\Claude_dms3\ccw\src\core\routes\spec-routes.ts (role: API routes) +- D:\Claude_dms3\ccw\frontend\src\hooks\useSystemSettings.ts (role: hooks) + +## Last Action +成功测试所有 ccw spec 命令： +- ccw spec help ✅ +- ccw spec init ✅ +- ccw spec rebuild ✅ +- ccw spec list ✅ +- ccw spec status ✅ +- ccw spec load --category general ✅ (仅加载 general 分类) +- ccw spec load --category planning ✅ (仅加载 planning 分类) + +发现并修复 CLI 启动问题：cli.ts 中 run() 函数未被调用，已添加 run(process.argv) 调用。 + +## Decisions +- 添加 category 为独立字段而非混入 keywords: 清晰的职责分离，keywords 用于主题匹配，category 用于 workflow stage 过滤 +- 使用 general 作为默认值: 适用于所有阶段的通用规范 +- 前端显示 category badge: 提供可视化分类指示 +- SpecIndexEntry 增加 contentLength 字段: 由用户系统优化添加，避免重复读取文件 + +## Constraints +- 保持向后兼容：category 为可选字段，默认 general +- 不修改现有 spec 文档的 keywords 语义 + +## Dependencies +(none) + +## Known Issues +- 前端构建存在预存 TypeScript 错误（IssuePanel.tsx, IssueManagerPage.tsx），与本功能无关 +- esbuild 打包需要正确配置 --packages=external 以避免动态 require 问题 + +## Changes Made +- spec-index-builder.ts: 添加 SpecCategory 类型、VALID_CATEGORIES、isValidCategory()、buildEntry() 解析 category +- spec-init.ts: SpecFrontmatter 添加 category，SEED_DOCS 使用独立 category 字段 +- spec-loader.ts: SpecLoadOptions 添加 category，filterSpecs() 支持 category 过滤 +- spec.ts: SpecOptions 添加 category，loadAction() 传递 category 到 loadSpecs +- cli.ts: 添加 --category 选项，修复 run() 未调用问题 +- api.ts: SpecEntry 添加 category 类型 +- SpecCard.tsx: 添加 SpecCategory 类型、categoryConfig 配置、显示 category badge +- SpecsSettingsPage.tsx: 添加 CategoryFilter 状态、categoryCounts 计算、category 过滤按钮 + +## Pending +(none - 功能实现完成并测试通过) + +## Notes +**Category 设计思路**： +- general: 适用于所有阶段（如编码规范） +- exploration: 代码探索、分析、调试 +- planning: 任务规划、需求分析 +- execution: 实现、测试、部署 + +系统级加载示例：ccw spec load --category exploration + +**索引验证**： +{ + "title": "Architecture Constraints", + "category": "planning", + "keywords": ["architecture", "module", "layer", "pattern"] +} +keywords 不再包含 exploration/planning/execution 标记。 diff --git a/assets/wechat-group-qr.jpg b/assets/wechat-group-qr.jpg new file mode 100644 index 00000000..d218cf11 Binary files /dev/null and b/assets/wechat-group-qr.jpg differ diff --git a/assets/wechat-group-qr.png b/assets/wechat-group-qr.png deleted file mode 100644 index 73382dc5..00000000 Binary files a/assets/wechat-group-qr.png and /dev/null differ diff --git a/ccw/frontend/src/components/mcp/CcwToolsMcpCard.tsx b/ccw/frontend/src/components/mcp/CcwToolsMcpCard.tsx index d5a78125..467cb83e 100644 --- a/ccw/frontend/src/components/mcp/CcwToolsMcpCard.tsx +++ b/ccw/frontend/src/components/mcp/CcwToolsMcpCard.tsx @@ -324,9 +324,16 @@ export function CcwToolsMcpCard({ {/* Tool Checkboxes */}
-

- {formatMessage({ id: 'mcp.ccw.tools.label' })} -

+
+

+ {formatMessage({ id: 'mcp.ccw.tools.label' })} +

+ {!isInstalled && ( +

+ {formatMessage({ id: 'mcp.ccw.tools.hint' })} +

+ )} +
{CCW_MCP_TOOLS.map((tool) => { const isEnabled = enabledTools.includes(tool.name); diff --git a/ccw/frontend/src/components/specs/GlobalSettingsTab.tsx b/ccw/frontend/src/components/specs/GlobalSettingsTab.tsx index fa87f7c2..6b6305b0 100644 --- a/ccw/frontend/src/components/specs/GlobalSettingsTab.tsx +++ b/ccw/frontend/src/components/specs/GlobalSettingsTab.tsx @@ -181,9 +181,10 @@ export function GlobalSettingsTab() { updateMutation.mutate({ personalSpecDefaults: newDefaults }); }; - // Calculate totals + // Calculate totals - Only include specs and personal dimensions const dimensions = stats?.dimensions || {}; - const dimensionEntries = Object.entries(dimensions) as [ + const dimensionEntries = Object.entries(dimensions) + .filter(([dim]) => dim === 'specs' || dim === 'personal') as [ keyof typeof dimensions, SpecDimensionStats ][]; @@ -304,8 +305,10 @@ export function GlobalSettingsTab() {
) : ( <> -
- {dimensionEntries.map(([dim, data]) => ( +
+ {dimensionEntries + .filter(([entry]) => entry[0] === 'specs' || entry[1] === 'personal') + .map(([dim, data]) => (
= { + general: { color: 'text-gray-600', bgColor: 'bg-gray-100 dark:bg-gray-800' }, + exploration: { color: 'text-blue-600', bgColor: 'bg-blue-100 dark:bg-blue-900/30' }, + planning: { color: 'text-purple-600', bgColor: 'bg-purple-100 dark:bg-purple-900/30' }, + execution: { color: 'text-green-600', bgColor: 'bg-green-100 dark:bg-green-900/30' }, +}; + // ========== Recommended Hooks Configuration ========== const RECOMMENDED_HOOKS = [ @@ -184,6 +199,7 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) { // State for injection preview const [previewMode, setPreviewMode] = useState<'required' | 'all'>('required'); + const [categoryFilter, setCategoryFilter] = useState('all'); const [previewData, setPreviewData] = useState(null); const [previewLoading, setPreviewLoading] = useState(false); const [expandedDimensions, setExpandedDimensions] = useState>({ @@ -358,17 +374,36 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) { } }, [installedHookIds, installHooksMutation, formatMessage]); - // Group files by dimension + // Group files by dimension and filter by category const filesByDimension = useMemo(() => { if (!previewData) return {}; const grouped: Record = {}; for (const file of previewData.files) { + // Apply category filter + if (categoryFilter !== 'all' && file.category !== categoryFilter) { + continue; + } if (!grouped[file.dimension]) { grouped[file.dimension] = []; } grouped[file.dimension].push(file); } return grouped; + }, [previewData, categoryFilter]); + + // Calculate category statistics + const categoryStats = useMemo(() => { + if (!previewData) { + return { general: 0, exploration: 0, planning: 0, execution: 0 }; + } + const stats: Record = { general: 0, exploration: 0, planning: 0, execution: 0 }; + for (const file of previewData.files) { + const cat = (file.category as SpecCategory) || 'general'; + if (stats[cat] !== undefined) { + stats[cat]++; + } + } + return stats; }, [previewData]); // Calculate progress and status @@ -641,7 +676,37 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) { )} - + + {/* Category Filter */} +
+ + + {formatMessage({ id: 'specs.filterByCategory', defaultMessage: 'Category:' })} + +
+ + {SPEC_CATEGORIES.map(cat => ( + + ))} +
+
+ + {/* Files List */} {previewLoading ? (
@@ -669,45 +734,53 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) {
- {formatNumber(files.reduce((sum, f) => sum + f.contentLength, 0))} {formatMessage({ id: 'specs.injection.characters', defaultMessage: 'chars' })} + {formatNumber(files.reduce((sum, f) => sum + f.contentLength, 0))} {formatMessage({ id: 'specs.injection.characters', defaultMessage: 'characters' })} {expandedDimensions[dim] && (
- {files.map((file) => ( -
-
- {file.scope === 'global' ? ( - - ) : ( - - )} -
-
{file.title}
-
{file.file}
+ {files.map((file) => { + const fileCategory = (file.category as SpecCategory) || 'general'; + const categoryStyle = CATEGORY_CONFIG[fileCategory] || CATEGORY_CONFIG.general; + return ( +
+
+ {file.scope === 'global' ? ( + + ) : ( + + )} +
+
{file.title}
+
{file.file}
+
+
+
+ + + {formatMessage({ id: `specs.category.${fileCategory}`, defaultMessage: fileCategory })} + + + {formatMessage({ id: `specs.priority.${file.priority}`, defaultMessage: file.priority })} + + + {formatNumber(file.contentLength)} + +
-
- - {formatMessage({ id: `specs.priority.${file.priority}`, defaultMessage: file.priority })} - - - {formatNumber(file.contentLength)} - - -
-
- ))} + ); + })}
)}
diff --git a/ccw/frontend/src/components/terminal-dashboard/IssuePanel.tsx b/ccw/frontend/src/components/terminal-dashboard/IssuePanel.tsx index a2068e2d..fee2e3fb 100644 --- a/ccw/frontend/src/components/terminal-dashboard/IssuePanel.tsx +++ b/ccw/frontend/src/components/terminal-dashboard/IssuePanel.tsx @@ -73,11 +73,14 @@ function PriorityBadge({ priority }: { priority: Issue['priority'] }) { function StatusDot({ status }: { status: Issue['status'] }) { const colorMap: Record = { - open: 'text-info', - in_progress: 'text-warning', - resolved: 'text-success', - closed: 'text-muted-foreground', + registered: 'text-info', + planning: 'text-blue-500', + planned: 'text-blue-600', + queued: 'text-yellow-500', + executing: 'text-warning', completed: 'text-success', + failed: 'text-destructive', + paused: 'text-muted-foreground', }; return ; } diff --git a/ccw/frontend/src/locales/en/mcp-manager.json b/ccw/frontend/src/locales/en/mcp-manager.json index 4fdcb715..212e8a57 100644 --- a/ccw/frontend/src/locales/en/mcp-manager.json +++ b/ccw/frontend/src/locales/en/mcp-manager.json @@ -112,6 +112,7 @@ }, "tools": { "label": "Available Tools", + "hint": "Install CCW MCP first to select tools", "core": "Core", "write_file": { "name": "write_file", diff --git a/ccw/frontend/src/locales/zh/mcp-manager.json b/ccw/frontend/src/locales/zh/mcp-manager.json index a0a168c8..fcb0e32e 100644 --- a/ccw/frontend/src/locales/zh/mcp-manager.json +++ b/ccw/frontend/src/locales/zh/mcp-manager.json @@ -112,6 +112,7 @@ }, "tools": { "label": "可用工具", + "hint": "请先安装 CCW MCP 后再选择工具", "core": "核心", "write_file": { "name": "write_file", diff --git a/ccw/frontend/src/pages/IssueManagerPage.tsx b/ccw/frontend/src/pages/IssueManagerPage.tsx index 0e76ec46..d128e616 100644 --- a/ccw/frontend/src/pages/IssueManagerPage.tsx +++ b/ccw/frontend/src/pages/IssueManagerPage.tsx @@ -138,7 +138,7 @@ function EditIssueDialog({ open, onOpenChange, issue, onSubmit, isUpdating }: Ed const [title, setTitle] = useState(''); const [context, setContext] = useState(''); const [priority, setPriority] = useState('medium'); - const [status, setStatus] = useState('open'); + const [status, setStatus] = useState('registered'); // Reset form when dialog opens or issue changes useEffect(() => { @@ -146,12 +146,12 @@ function EditIssueDialog({ open, onOpenChange, issue, onSubmit, isUpdating }: Ed setTitle(issue.title ?? ''); setContext(issue.context ?? ''); setPriority(issue.priority ?? 'medium'); - setStatus(issue.status ?? 'open'); + setStatus(issue.status ?? 'registered'); } else if (!open) { setTitle(''); setContext(''); setPriority('medium'); - setStatus('open'); + setStatus('registered'); } // eslint-disable-next-line react-hooks/exhaustive-deps }, [open, issue?.id]); @@ -217,10 +217,11 @@ function EditIssueDialog({ open, onOpenChange, issue, onSubmit, isUpdating }: Ed - {formatMessage({ id: 'issues.status.open' })} - {formatMessage({ id: 'issues.status.inProgress' })} - {formatMessage({ id: 'issues.status.resolved' })} - {formatMessage({ id: 'issues.status.closed' })} + {formatMessage({ id: 'issues.status.registered', defaultMessage: 'Registered' })} + {formatMessage({ id: 'issues.status.planning', defaultMessage: 'Planning' })} + {formatMessage({ id: 'issues.status.planned', defaultMessage: 'Planned' })} + {formatMessage({ id: 'issues.status.queued', defaultMessage: 'Queued' })} + {formatMessage({ id: 'issues.status.executing', defaultMessage: 'Executing' })} {formatMessage({ id: 'issues.status.completed' })} @@ -341,11 +342,14 @@ export function IssueManagerPage() { // Filter counts const statusCounts = useMemo(() => ({ all: issues.length, - open: issuesByStatus.open?.length || 0, - in_progress: issuesByStatus.in_progress?.length || 0, - resolved: issuesByStatus.resolved?.length || 0, - closed: issuesByStatus.closed?.length || 0, + registered: issuesByStatus.registered?.length || 0, + planning: issuesByStatus.planning?.length || 0, + planned: issuesByStatus.planned?.length || 0, + queued: issuesByStatus.queued?.length || 0, + executing: issuesByStatus.executing?.length || 0, completed: issuesByStatus.completed?.length || 0, + failed: issuesByStatus.failed?.length || 0, + paused: issuesByStatus.paused?.length || 0, }), [issues, issuesByStatus]); const handleCreateIssue = async (data: { title: string; context?: string; priority?: Issue['priority'] }) => { @@ -440,9 +444,9 @@ export function IssueManagerPage() {
- {issuesByStatus.in_progress?.length || 0} + {issuesByStatus.executing?.length || 0}
-

{formatMessage({ id: 'issues.status.inProgress' })}

+

{formatMessage({ id: 'issues.status.executing', defaultMessage: 'Executing' })}
@@ -454,9 +458,9 @@ export function IssueManagerPage() {
- {issuesByStatus.resolved?.length || 0} + {issuesByStatus.completed?.length || 0}
-

{formatMessage({ id: 'issues.status.resolved' })}

+

{formatMessage({ id: 'issues.status.completed' })}
@@ -478,10 +482,12 @@ export function IssueManagerPage() { {formatMessage({ id: 'issues.filters.all' })} - {formatMessage({ id: 'issues.status.open' })} - {formatMessage({ id: 'issues.status.inProgress' })} - {formatMessage({ id: 'issues.status.resolved' })} - {formatMessage({ id: 'issues.status.closed' })} + {formatMessage({ id: 'issues.status.registered', defaultMessage: 'Registered' })} + {formatMessage({ id: 'issues.status.planning', defaultMessage: 'Planning' })} + {formatMessage({ id: 'issues.status.planned', defaultMessage: 'Planned' })} + {formatMessage({ id: 'issues.status.queued', defaultMessage: 'Queued' })} + {formatMessage({ id: 'issues.status.executing', defaultMessage: 'Executing' })} + {formatMessage({ id: 'issues.status.completed' })}