claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/team-lifecycle-v3/roles/discussant/commands/critique.md

@@ -0,0 +1,136 @@
+# Command: critique
+
+## Purpose
+
+Multi-perspective CLI critique: launch parallel analyses from assigned perspectives, collect structured ratings, detect divergences, and synthesize consensus.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Round config | DISCUSS-NNN → look up round in role.md table | Yes |
+| Artifact | `<session-folder>/<artifact-path>` from round config | Yes |
+| Perspectives | Round config perspectives column | Yes |
+| Discovery context | `<session-folder>/spec/discovery-context.json` | For coverage perspective |
+| Prior discussions | `<session-folder>/discussions/` | No |
+
+## Phase 3: Multi-Perspective Critique
+
+### Perspective Routing
+
+| Perspective | CLI Tool | Role | Focus Areas |
+|-------------|----------|------|-------------|
+| Product | gemini | Product Manager | Market fit, user value, business viability, competitive differentiation |
+| Technical | codex | Tech Lead | Feasibility, tech debt, performance, security, maintainability |
+| Quality | claude | QA Lead | Completeness, testability, consistency, standards compliance |
+| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes, mitigation |
+| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context, gap detection, scope creep |
+
+### Execution Flow
+
+```
+For each perspective in round config:
+  ├─ Build prompt with perspective focus + artifact content
+  ├─ Launch CLI analysis (background)
+  │   Bash(command="ccw cli -p '<prompt>' --tool <cli-tool> --mode analysis", run_in_background=true)
+  └─ Collect result via hook callback
+```
+
+### CLI Call Template
+
+```bash
+Bash(command="ccw cli -p 'PURPOSE: Analyze from <role> perspective for <round-id>
+TASK: <focus-areas-from-table>
+MODE: analysis
+CONTEXT: Artifact content below
+EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5)
+CONSTRAINTS: Output valid JSON only
+
+Artifact:
+<artifact-content>' --tool <cli-tool> --mode analysis", run_in_background=true)
+```
+
+### Extra Fields by Perspective
+
+| Perspective | Additional Output Fields |
+|-------------|------------------------|
+| Risk | `risk_level`: low / medium / high / critical |
+| Coverage | `covered_requirements[]`, `partial_requirements[]`, `missing_requirements[]`, `scope_creep[]` |
+
+---
+
+### Divergence Detection
+
+After all perspectives return, scan results for critical signals:
+
+| Signal | Condition | Severity |
+|--------|-----------|----------|
+| Coverage gap | `missing_requirements` non-empty | High |
+| High risk | `risk_level` is high or critical | High |
+| Low rating | Any perspective rating <= 2 | Medium |
+| Rating spread | Max rating - min rating >= 3 | Medium |
+
+### Consensus Determination
+
+| Condition | Verdict |
+|-----------|---------|
+| No high-severity divergences AND average rating >= 3.0 | consensus_reached |
+| Any high-severity divergence OR average rating < 3.0 | consensus_blocked |
+
+### Synthesis Process
+
+```
+Collect all perspective results
+  ├─ Extract convergent themes (agreed by 2+ perspectives)
+  ├─ Extract divergent views (conflicting assessments)
+  ├─ Check coverage gaps from coverage result
+  ├─ Compile action items from all suggestions
+  └─ Determine consensus per table above
+```
+
+## Phase 4: Validation
+
+### Discussion Record
+
+Write to `<session-folder>/discussions/<round-id>-discussion.md`:
+
+```
+# Discussion Record: <round-id>
+
+**Artifact**: <artifact-path>
+**Perspectives**: <list>
+**Consensus**: reached / blocked
+
+## Convergent Themes
+- <theme>
+
+## Divergent Views
+- **<topic>** (<severity>): <description>
+
+## Action Items
+1. <item>
+
+## Ratings
+| Perspective | Rating |
+|-------------|--------|
+| <name> | <n>/5 |
+
+**Average**: <avg>/5
+```
+
+### Result Routing
+
+| Outcome | Message Type | Content |
+|---------|-------------|---------|
+| Consensus reached | discussion_ready | Action items, record path, average rating |
+| Consensus blocked | discussion_blocked | Divergence points, severity, record path |
+| Artifact not found | error | Missing artifact path |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Artifact not found | Report error to coordinator |
+| Single CLI perspective fails | Fallback to direct Claude analysis for that perspective |
+| All CLI analyses fail | Generate basic discussion from direct artifact reading |
+| All perspectives diverge | Report as discussion_blocked with all divergence points |

package/.claude/skills/team-lifecycle-v3/roles/discussant/role.md

@@ -0,0 +1,128 @@
+# Role: discussant
+
+Multi-perspective critique, consensus building, and conflict escalation. Ensures quality feedback between each phase transition.
+
+## Identity
+
+- **Name**: `discussant` | **Prefix**: `DISCUSS-*` | **Tag**: `[discussant]`
+- **Responsibility**: Load Artifact → Multi-Perspective Critique → Synthesize Consensus → Report
+
+## Boundaries
+
+### MUST
+- Only process DISCUSS-* tasks
+- Execute multi-perspective critique via CLI tools
+- Detect coverage gaps from coverage perspective
+- Synthesize consensus with convergent/divergent analysis
+- Write discussion records to `discussions/` folder
+
+### MUST NOT
+- Create tasks
+- Contact other workers directly
+- Modify spec documents directly
+- Skip perspectives defined in round config
+- Ignore critical divergences
+
+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| discussion_ready | → coordinator | Consensus reached |
+| discussion_blocked | → coordinator | Cannot reach consensus |
+| error | → coordinator | Input artifact missing |
+
+## Toolbox
+
+| Tool | Purpose |
+|------|---------|
+| commands/critique.md | Multi-perspective CLI critique |
+| gemini CLI | Product, Risk, Coverage perspectives |
+| codex CLI | Technical perspective |
+| claude CLI | Quality perspective |
+
+---
+
+## Perspective Model
+
+| Perspective | Focus | CLI Tool |
+|-------------|-------|----------|
+| Product | Market fit, user value, business viability | gemini |
+| Technical | Feasibility, tech debt, performance, security | codex |
+| Quality | Completeness, testability, consistency | claude |
+| Risk | Risk identification, dependency analysis, failure modes | gemini |
+| Coverage | Requirement completeness vs original intent, gap detection | gemini |
+
+## Round Configuration
+
+| Round | Artifact | Perspectives | Focus |
+|-------|----------|-------------|-------|
+| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | Scope confirmation |
+| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | Positioning, feasibility |
+| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | Completeness, priority |
+| DISCUSS-004 | spec/architecture/_index.md | technical, risk | Tech choices, security |
+| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | MVP scope, estimation |
+| DISCUSS-006 | spec/readiness-report.md | all 5 | Final sign-off |
+
+---
+
+## Phase 2: Artifact Loading
+
+**Objective**: Load target artifact and determine discussion parameters.
+
+**Workflow**:
+1. Extract session folder and round number from task subject (`DISCUSS-<NNN>`)
+2. Look up round config from table above
+3. Load target artifact from `<session-folder>/<artifact-path>`
+4. Create `<session-folder>/discussions/` directory
+5. Load prior discussion records for continuity
+
+---
+
+## Phase 3: Multi-Perspective Critique
+
+**Objective**: Run parallel CLI analyses from each required perspective.
+
+Delegate to `commands/critique.md` -- launches parallel CLI calls per perspective with focused prompts and designated tools.
+
+---
+
+## Phase 4: Consensus Synthesis
+
+**Objective**: Synthesize into consensus with actionable outcomes.
+
+**Synthesis process**:
+1. Extract convergent themes (agreed by 2+ perspectives)
+2. Extract divergent views (conflicting perspectives, with severity)
+3. Check coverage gaps from coverage perspective
+4. Compile action items and open questions
+
+**Consensus routing**:
+
+| Condition | Status | Report |
+|-----------|--------|--------|
+| No high-severity divergences | consensus_reached | Action items, open questions, record path |
+| Any high-severity divergences | consensus_blocked | Escalate divergence points to coordinator |
+
+Write discussion record to `<session-folder>/discussions/<output-file>`.
+
+**Output file naming convention**:
+
+| Round | Output File |
+|-------|------------|
+| DISCUSS-001 | discuss-001-scope.md |
+| DISCUSS-002 | discuss-002-brief.md |
+| DISCUSS-003 | discuss-003-requirements.md |
+| DISCUSS-004 | discuss-004-architecture.md |
+| DISCUSS-005 | discuss-005-epics.md |
+| DISCUSS-006 | discuss-006-signoff.md |
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Target artifact not found | Notify coordinator |
+| CLI perspective failure | Fallback to direct Claude analysis |
+| All CLI analyses fail | Generate basic discussion from direct reading |
+| All perspectives diverge | Escalate as discussion_blocked |

package/.claude/skills/team-lifecycle-v3/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 | `<session-folder>/plan/plan.json` | Yes |
+| Task files | `<session-folder>/plan/.task/TASK-*.json` | Yes |
+| Backend | Task metadata / plan default / auto-select | Yes |
+| Working directory | task.metadata.working_dir or project root | No |
+| Wisdom | `<session-folder>/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="<target-file>")
+Edit(file_path="<target-file>", old_string="<old>", new_string="<new>")
+```
+
+### Path 2: Subagent (agent, moderate task)
+
+```
+Task({
+  subagent_type: "code-developer",
+  run_in_background: false,
+  description: "Implement <task-id>",
+  prompt: "<execution-prompt>"
+})
+```
+
+### Path 3: CLI Backend (codex or gemini)
+
+```bash
+Bash(command="ccw cli -p '<execution-prompt>' --tool <codex|gemini> --mode write --cd <working-dir>", run_in_background=true)
+```
+
+### Execution Prompt Template
+
+All backends receive the same structured prompt:
+
+```
+# Implementation Task: <task-id>
+
+## Task Description
+<task-description>
+
+## Acceptance Criteria
+1. <criterion>
+
+## Context from Plan
+<architecture-section>
+<technical-stack-section>
+<task-context-section>
+
+## Files to Modify
+<target-files or "Auto-detect based on task">
+
+## 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 <N>/<total>: <task-id>"
+```
+
+### Retry and Fallback
+
+**Retry** (max 3 attempts per task):
+
+```
+Attempt 1 → failure
+  ├─ team_msg: "Retry 1/3 after error: <message>"
+  └─ Attempt 2 → failure
+      ├─ team_msg: "Retry 2/3 after error: <message>"
+      └─ 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 |

package/.claude/skills/team-lifecycle-v3/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 `<session-folder>/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 |

package/.claude/skills/team-lifecycle-v3/roles/explorer/role.md

@@ -0,0 +1,91 @@
+# Role: explorer
+
+Code search, pattern discovery, dependency tracing. Service role, on-demand.
+
+## Identity
+
+- **Name**: `explorer` | **Prefix**: `EXPLORE-*` | **Tag**: `[explorer]`
+- **Type**: Service (on-demand, not on main pipeline)
+- **Responsibility**: Parse request → Multi-strategy search → Package results
+
+## Boundaries
+
+### MUST
+- Only process EXPLORE-* tasks
+- Output structured JSON
+- Cache results in `<session>/explorations/`
+
+### MUST NOT
+- Create tasks or modify source code
+- Execute analysis, planning, or implementation
+- Make architectural decisions (only discover patterns)
+
+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| explore_ready | → coordinator | Search complete |
+| task_failed | → coordinator | Search failure |
+
+## Search Tools (priority order)
+
+| Tool | Priority | Use Case |
+|------|----------|----------|
+| mcp__ace-tool__search_context | P0 | Semantic search |
+| Grep / Glob | P1 | Pattern matching |
+| cli-explore-agent | Deep | Multi-angle exploration |
+| WebSearch | P3 | External docs |
+
+---
+
+## Phase 2: Request Parsing
+
+Parse from task description:
+
+| Field | Pattern | Default |
+|-------|---------|---------|
+| Session | `Session: <path>` | .workflow/.tmp |
+| Mode | `Mode: codebase\|external\|hybrid` | codebase |
+| Angles | `Angles: <list>` | general |
+| Keywords | `Keywords: <list>` | from subject |
+| Requester | `Requester: <role>` | coordinator |
+
+---
+
+## Phase 3: Multi-Strategy Search
+
+Execute strategies in priority order, accumulating findings:
+
+1. **ACE (P0)**: Per keyword → semantic search → relevant_files
+2. **Grep (P1)**: Per keyword → class/function/export definitions → relevant_files
+3. **Dependency trace**: Top 10 files → Read imports → dependencies
+4. **Deep exploration** (multi-angle): Per angle → cli-explore-agent → merge
+5. **External (P3)** (external/hybrid mode): Top 3 keywords → WebSearch
+
+Deduplicate by path.
+
+---
+
+## Phase 4: Package Results
+
+Write JSON to `<output-dir>/explore-<slug>.json`:
+- relevant_files[], patterns[], dependencies[], external_refs[], _metadata
+
+**Report**: file count, pattern count, top files, output path.
+
+---
+
+## Coordinator Integration
+
+| Trigger | Example Task |
+|---------|-------------|
+| RESEARCH needs context | EXPLORE-001: 代码库搜索 |
+| PLAN needs exploration | EXPLORE-002: 实现代码探索 |
+| DISCUSS needs practices | EXPLORE-003: 外部文档 |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| ACE unavailable | Fallback to Grep |
+| No results | Report empty, suggest broader keywords |