claude-code-workflow 6.3.54 → 7.0.0

package/.claude/skills/team-coordinate/specs/role-template.md

@@ -0,0 +1,434 @@
+# Dynamic Role Template
+
+Template used by coordinator to generate worker role.md files at runtime. Each generated role is written to `<session>/roles/<role-name>.md`.
+
+## Template
+
+```markdown
+# Role: <role_name>
+
+<role_description>
+
+## Identity
+
+- **Name**: `<role_name>` | **Tag**: `[<role_name>]`
+- **Task Prefix**: `<prefix>-*`
+- **Responsibility**: <responsibility_type>
+<if inner_loop>
+- **Mode**: Inner Loop (handle all `<prefix>-*` tasks in single agent)
+</if>
+
+## Boundaries
+
+### MUST
+- Only process `<prefix>-*` prefixed tasks
+- All output (SendMessage, team_msg, logs) must carry `[<role_name>]` identifier
+- Only communicate with coordinator via SendMessage
+- Work strictly within <responsibility_type> responsibility scope
+- Use fast-advance for simple linear successors (see SKILL.md Phase 5)
+- Produce MD artifacts in `<session>/artifacts/`
+<if inner_loop>
+- Use subagent for heavy work (do not execute CLI/generation in main agent context)
+- Maintain context_accumulator across tasks within the inner loop
+- Loop through all `<prefix>-*` tasks before reporting to coordinator
+</if>
+
+### MUST NOT
+- Execute work outside this role's responsibility scope
+- Communicate directly with other worker roles (must go through coordinator)
+- Create tasks for other roles (TaskCreate is coordinator-exclusive)
+- Modify files or resources outside this role's scope
+- Omit `[<role_name>]` identifier in any output
+- Fast-advance when multiple tasks are ready or at checkpoint boundaries
+<if inner_loop>
+- Execute heavy work (CLI calls, large document generation) in main agent (delegate to subagent)
+- SendMessage to coordinator mid-loop (unless consensus_blocked HIGH or error count >= 3)
+</if>
+
+## Toolbox
+
+| Tool | Purpose |
+|------|---------|
+<tools based on responsibility_type -- see reference sections below>
+
+## Message Types
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| `<prefix>_complete` | -> coordinator | Task completed with artifact path |
+| `<prefix>_error` | -> coordinator | Error encountered |
+| `capability_gap` | -> coordinator | Work outside role scope discovered |
+
+## Message Bus
+
+Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
+
+```
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  team: <session-id>,
+  from: "<role_name>",
+  to: "coordinator",
+  type: <message-type>,
+  summary: "[<role_name>] <prefix> complete: <task-subject>",
+  ref: <artifact-path>
+})
+```
+
+**`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name.
+
+**CLI fallback** (when MCP unavailable):
+
+```
+Bash("ccw team log --team <session-id> --from <role_name> --to coordinator --type <message-type> --summary \"[<role_name>] <prefix> complete\" --ref <artifact-path> --json")
+```
+
+---
+
+## Execution (5-Phase)
+
+### Phase 1: Task Discovery
+
+> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
+
+Standard task discovery flow: TaskList -> filter by prefix `<prefix>-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
+
+### Phase 2: <phase2_name>
+
+<phase2_content -- generated by coordinator based on responsibility type>
+
+### Phase 3: <phase3_name>
+
+<phase3_content -- generated by coordinator based on task specifics>
+
+### Phase 4: <phase4_name>
+
+<phase4_content -- generated by coordinator based on responsibility type>
+
+<if inline_discuss>
+### Phase 4b: Inline Discuss (optional)
+
+After primary work, optionally call discuss subagent:
+
+```
+Task({
+  subagent_type: "cli-discuss-agent",
+  run_in_background: false,
+  description: "Discuss <round-id>",
+  prompt: "## Multi-Perspective Critique: <round-id>
+  See subagents/discuss-subagent.md for prompt template.
+  Perspectives: <specified by coordinator when generating this role>"
+})
+```
+
+| Verdict | Severity | Action |
+|---------|----------|--------|
+| consensus_reached | - | Include action items in report, proceed to Phase 5 |
+| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format. Do NOT self-revise. |
+| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed normally. |
+| consensus_blocked | LOW | Treat as consensus_reached with notes. |
+</if>
+
+<if inner_loop>
+### Phase 5-L: Loop Completion (Inner Loop)
+
+When more same-prefix tasks remain:
+
+1. **TaskUpdate**: Mark current task completed
+2. **team_msg**: Log task completion
+3. **Accumulate summary**:
+   ```
+   context_accumulator.append({
+     task: "<task-id>",
+     artifact: "<output-path>",
+     key_decisions: <from subagent return>,
+     discuss_verdict: <from Phase 4>,
+     summary: <from subagent return>
+   })
+   ```
+4. **Interrupt check**:
+   - consensus_blocked HIGH -> SendMessage -> STOP
+   - Error count >= 3 -> SendMessage -> STOP
+5. **Loop**: Back to Phase 1
+
+**Does NOT**: SendMessage to coordinator, Fast-Advance spawn.
+
+### Phase 5-F: Final Report (Inner Loop)
+
+When all same-prefix tasks are done:
+
+1. **TaskUpdate**: Mark last task completed
+2. **team_msg**: Log completion
+3. **Summary report**: All tasks summary + discuss results + artifact paths
+4. **Fast-Advance check**: Check cross-prefix successors
+5. **SendMessage** or **spawn successor**
+
+> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report + Fast-Advance
+
+<else>
+### Phase 5: Report + Fast-Advance
+
+> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report + Fast-Advance
+
+Standard report flow: team_msg log -> SendMessage with `[<role_name>]` prefix -> TaskUpdate completed -> Fast-Advance Check -> Loop to Phase 1 for next task.
+</if>
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No <prefix>-* tasks available | Idle, wait for coordinator assignment |
+| Context file not found | Notify coordinator, request location |
+| Subagent fails | Retry once with fallback; still fails -> log error, continue next task |
+| Fast-advance spawn fails | Fall back to SendMessage to coordinator |
+<if inner_loop>
+| Cumulative 3 task failures | SendMessage to coordinator, STOP inner loop |
+| Agent crash mid-loop | Coordinator detects orphan on resume -> re-spawn -> resume from interrupted task |
+</if>
+| Work outside scope discovered | SendMessage capability_gap to coordinator |
+| Critical issue beyond scope | SendMessage fix_required to coordinator |
+```
+
+---
+
+## Phase 2-4 Content by Responsibility Type
+
+Reference sections for coordinator to fill when generating roles. Select the matching section based on `responsibility_type`.
+
+### orchestration
+
+**Phase 2: Context Assessment**
+
+```
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From TaskGet | Yes |
+| Shared memory | <session>/shared-memory.json | No |
+| Prior artifacts | <session>/artifacts/ | No |
+| Wisdom | <session>/wisdom/ | No |
+
+Loading steps:
+1. Extract session path from task description
+2. Read shared-memory.json for cross-role context
+3. Read prior artifacts (if any exist from upstream tasks)
+4. Load wisdom files for accumulated knowledge
+5. Optionally call explore subagent for codebase context
+```
+
+**Phase 3: Subagent Execution**
+
+```
+Delegate to appropriate subagent based on task:
+
+Task({
+  subagent_type: "general-purpose",
+  run_in_background: false,
+  description: "<task-type> for <task-id>",
+  prompt: "## Task
+  - <task description>
+  - Session: <session-folder>
+  ## Context
+  <prior artifacts + shared memory + explore results>
+  ## Expected Output
+  Write artifact to: <session>/artifacts/<artifact-name>.md
+  Return JSON summary: { artifact_path, summary, key_decisions[], warnings[] }"
+})
+```
+
+**Phase 4: Result Aggregation**
+
+```
+1. Verify subagent output artifact exists
+2. Read artifact, validate structure/completeness
+3. Update shared-memory.json with key findings
+4. Write insights to wisdom/ files
+```
+
+### code-gen (docs)
+
+**Phase 2: Load Prior Context**
+
+```
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From TaskGet | Yes |
+| Prior artifacts | <session>/artifacts/ from upstream tasks | Conditional |
+| Shared memory | <session>/shared-memory.json | No |
+| Wisdom | <session>/wisdom/ | No |
+
+Loading steps:
+1. Extract session path from task description
+2. Read upstream artifacts (e.g., research findings for a writer)
+3. Read shared-memory.json for cross-role context
+4. Load wisdom for accumulated decisions
+```
+
+**Phase 3: Document Generation**
+
+```
+Task({
+  subagent_type: "universal-executor",
+  run_in_background: false,
+  description: "Generate <doc-type> for <task-id>",
+  prompt: "## Task
+  - Generate: <document type>
+  - Session: <session-folder>
+  ## Prior Context
+  <upstream artifacts + shared memory>
+  ## Instructions
+  <task-specific writing instructions from coordinator>
+  ## Expected Output
+  Write document to: <session>/artifacts/<doc-name>.md
+  Return JSON: { artifact_path, summary, key_decisions[], sections_generated[], warnings[] }"
+})
+```
+
+**Phase 4: Structure Validation**
+
+```
+1. Verify document artifact exists
+2. Check document has expected sections
+3. Validate no placeholder text remains
+4. Update shared-memory.json with document metadata
+```
+
+### code-gen (code)
+
+**Phase 2: Load Plan/Specs**
+
+```
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From TaskGet | Yes |
+| Plan/design artifacts | <session>/artifacts/ | Conditional |
+| Shared memory | <session>/shared-memory.json | No |
+| Wisdom | <session>/wisdom/ | No |
+
+Loading steps:
+1. Extract session path from task description
+2. Read plan/design artifacts from upstream
+3. Load shared-memory.json for implementation context
+4. Load wisdom for conventions and patterns
+```
+
+**Phase 3: Code Implementation**
+
+```
+Task({
+  subagent_type: "code-developer",
+  run_in_background: false,
+  description: "Implement <task-id>",
+  prompt: "## Task
+  - <implementation description>
+  - Session: <session-folder>
+  ## Plan/Design Context
+  <upstream artifacts>
+  ## Instructions
+  <task-specific implementation instructions>
+  ## Expected Output
+  Implement code changes.
+  Write summary to: <session>/artifacts/implementation-summary.md
+  Return JSON: { artifact_path, summary, files_changed[], key_decisions[], warnings[] }"
+})
+```
+
+**Phase 4: Syntax Validation**
+
+```
+1. Run syntax check (tsc --noEmit or equivalent)
+2. Verify all planned files exist
+3. Check no broken imports
+4. If validation fails -> attempt auto-fix (max 2 attempts)
+5. Write implementation summary to artifacts/
+```
+
+### read-only
+
+**Phase 2: Target Loading**
+
+```
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From TaskGet | Yes |
+| Target artifacts/files | From task description or upstream | Yes |
+| Shared memory | <session>/shared-memory.json | No |
+
+Loading steps:
+1. Extract session path and target files from task description
+2. Read target artifacts or source files for analysis
+3. Load shared-memory.json for context
+```
+
+**Phase 3: Multi-Dimension Analysis**
+
+```
+Task({
+  subagent_type: "general-purpose",
+  run_in_background: false,
+  description: "Analyze <target> for <task-id>",
+  prompt: "## Task
+  - Analyze: <target description>
+  - Dimensions: <analysis dimensions from coordinator>
+  - Session: <session-folder>
+  ## Target Content
+  <artifact content or file content>
+  ## Expected Output
+  Write report to: <session>/artifacts/analysis-report.md
+  Return JSON: { artifact_path, summary, findings[], severity_counts: {critical, high, medium, low} }"
+})
+```
+
+**Phase 4: Severity Classification**
+
+```
+1. Verify analysis report exists
+2. Classify findings by severity (Critical/High/Medium/Low)
+3. Update shared-memory.json with key findings
+4. Write issues to wisdom/issues.md
+```
+
+### validation
+
+**Phase 2: Environment Detection**
+
+```
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From TaskGet | Yes |
+| Implementation artifacts | Upstream code changes | Yes |
+
+Loading steps:
+1. Detect test framework from project files
+2. Get changed files from implementation
+3. Identify test command and coverage tool
+```
+
+**Phase 3: Test-Fix Cycle**
+
+```
+Task({
+  subagent_type: "test-fix-agent",
+  run_in_background: false,
+  description: "Test-fix for <task-id>",
+  prompt: "## Task
+  - Run tests and fix failures
+  - Session: <session-folder>
+  - Max iterations: 5
+  ## Changed Files
+  <from upstream implementation>
+  ## Expected Output
+  Write report to: <session>/artifacts/test-report.md
+  Return JSON: { artifact_path, pass_rate, coverage, iterations_used, remaining_failures[] }"
+})
+```
+
+**Phase 4: Result Analysis**
+
+```
+1. Check pass rate >= 95%
+2. Check coverage meets threshold
+3. Generate test report with pass/fail counts
+4. Update shared-memory.json with test results
+```

package/.claude/skills/team-coordinate/subagents/discuss-subagent.md

@@ -0,0 +1,133 @@
+# Discuss Subagent
+
+Lightweight multi-perspective critique engine. Called inline by any role needing peer review. Perspectives are dynamic -- specified by the calling role, not pre-defined.
+
+## Design
+
+Unlike team-lifecycle-v4's fixed perspective definitions (product, technical, quality, risk, coverage), team-coordinate uses **dynamic perspectives** passed in the prompt. The calling role decides what viewpoints matter for its artifact.
+
+## Invocation
+
+Called by roles after artifact creation:
+
+```
+Task({
+  subagent_type: "cli-discuss-agent",
+  run_in_background: false,
+  description: "Discuss <round-id>",
+  prompt: `## Multi-Perspective Critique: <round-id>
+
+### Input
+- Artifact: <artifact-path>
+- Round: <round-id>
+- Session: <session-folder>
+
+### Perspectives
+<Dynamic perspective list -- each entry defines: name, cli_tool, role_label, focus_areas>
+
+Example:
+| Perspective | CLI Tool | Role | Focus Areas |
+|-------------|----------|------|-------------|
+| Feasibility | gemini | Engineer | Implementation complexity, technical risks, resource needs |
+| Clarity | codex | Editor | Readability, logical flow, completeness of explanation |
+| Accuracy | gemini | Domain Expert | Factual correctness, source reliability, claim verification |
+
+### Execution Steps
+1. Read artifact from <artifact-path>
+2. For each perspective, launch CLI analysis in background:
+   Bash(command="ccw cli -p 'PURPOSE: Analyze from <role> perspective for <round-id>
+   TASK: <focus-areas>
+   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)
+3. Wait for all CLI results
+4. Divergence detection:
+   - High severity: any rating <= 2, critical issue identified
+   - Medium severity: rating spread (max - min) >= 3, or single perspective rated <= 2 with others >= 3
+   - Low severity: minor suggestions only, all ratings >= 3
+5. Consensus determination:
+   - No high-severity divergences AND average rating >= 3.0 -> consensus_reached
+   - Otherwise -> consensus_blocked
+6. Synthesize:
+   - Convergent themes (agreed by 2+ perspectives)
+   - Divergent views (conflicting assessments)
+   - Action items from suggestions
+7. Write discussion record to: <session-folder>/discussions/<round-id>-discussion.md
+
+### Discussion Record Format
+# Discussion Record: <round-id>
+
+**Artifact**: <artifact-path>
+**Perspectives**: <list>
+**Consensus**: reached / blocked
+**Average Rating**: <avg>/5
+
+## Convergent Themes
+- <theme>
+
+## Divergent Views
+- **<topic>** (<severity>): <description>
+
+## Action Items
+1. <item>
+
+## Ratings
+| Perspective | Rating |
+|-------------|--------|
+| <name> | <n>/5 |
+
+### Return Value
+
+**When consensus_reached**:
+Return a summary string with:
+- Verdict: consensus_reached
+- Average rating
+- Key action items (top 3)
+- Discussion record path
+
+**When consensus_blocked**:
+Return a structured summary with:
+- Verdict: consensus_blocked
+- Severity: HIGH | MEDIUM | LOW
+- Average rating
+- Divergence summary: top 3 divergent points with perspective attribution
+- Action items: prioritized list of required changes
+- Recommendation: revise | proceed-with-caution | escalate
+- Discussion record path
+
+### Error Handling
+- Single CLI fails -> fallback to direct Claude analysis for that perspective
+- All CLI fail -> generate basic discussion from direct artifact reading
+- Artifact not found -> return error immediately`
+})
+```
+
+## Integration with Calling Role
+
+The calling role is responsible for:
+
+1. **Before calling**: Complete primary artifact output
+2. **Calling**: Invoke discuss subagent with appropriate dynamic perspectives
+3. **After calling**:
+
+| Verdict | Severity | Role Action |
+|---------|----------|-------------|
+| consensus_reached | - | Include action items in Phase 5 report, proceed normally |
+| consensus_blocked | HIGH | Include divergence details in Phase 5 SendMessage. Do NOT self-revise -- coordinator decides. |
+| consensus_blocked | MEDIUM | Include warning in Phase 5 SendMessage. Proceed normally. |
+| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. |
+
+**SendMessage format for consensus_blocked (HIGH or MEDIUM)**:
+
+```
+[<role>] <task-id> complete. Discuss <round-id>: consensus_blocked (severity=<severity>)
+Divergences: <top-3-divergent-points>
+Action items: <prioritized-items>
+Recommendation: <revise|proceed-with-caution|escalate>
+Artifact: <artifact-path>
+Discussion: <discussion-record-path>
+```

package/.claude/skills/team-coordinate/subagents/explore-subagent.md

@@ -0,0 +1,120 @@
+# Explore Subagent
+
+Shared codebase exploration utility with centralized caching. Callable by any role needing code context.
+
+## Invocation
+
+```
+Task({
+  subagent_type: "cli-explore-agent",
+  run_in_background: false,
+  description: "Explore <angle>",
+  prompt: `Explore codebase for: <query>
+
+Focus angle: <angle>
+Keywords: <keyword-list>
+Session folder: <session-folder>
+
+## Cache Check
+1. Read <session-folder>/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
+<angle-specific-focus-from-table-below>
+
+## Output
+Write JSON to: <session-folder>/explorations/explore-<angle>.json
+Update cache-index.json with new entry
+
+## Output Schema
+{
+  "angle": "<angle>",
+  "query": "<query>",
+  "relevant_files": [
+    { "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] }
+  ],
+  "patterns": [],
+  "dependencies": [],
+  "external_refs": [],
+  "_metadata": { "created_by": "<calling-role>", "timestamp": "...", "cache_key": "..." }
+}
+
+Return summary: file count, pattern count, top 5 files, output path`
+})
+```
+
+## Cache Mechanism
+
+### Cache Index Schema
+
+`<session-folder>/explorations/cache-index.json`:
+
+```json
+{
+  "entries": [
+    {
+      "angle": "architecture",
+      "keywords": ["auth", "middleware"],
+      "file": "explore-architecture.json",
+      "created_by": "analyst",
+      "created_at": "2026-02-27T10:00:00Z",
+      "file_count": 15
+    }
+  ]
+}
+```
+
+### Cache Lookup Rules
+
+| Condition | Action |
+|-----------|--------|
+| Exact angle match exists | Return cached result |
+| No match | Execute exploration, cache result |
+| Cache file missing but index has entry | Remove stale entry, re-explore |
+
+### Cache Invalidation
+
+Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache.
+
+## Angle Focus Guide
+
+| Angle | Focus Points | Typical Caller |
+|-------|-------------|----------------|
+| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | any |
+| dependencies | Import chains, external libraries, circular dependencies, shared utilities | any |
+| modularity | Module interfaces, separation of concerns, extraction opportunities | any |
+| integration-points | API endpoints, data flow between modules, event systems | any |
+| security | Auth/authz logic, input validation, sensitive data handling, middleware | any |
+| dataflow | Data transformations, state propagation, validation points | any |
+| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | any |
+| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | any |
+| patterns | Code conventions, design patterns, naming conventions, best practices | any |
+| testing | Test files, coverage gaps, test patterns, mocking strategies | any |
+| general | Broad semantic search for topic-related code | any |
+
+## Exploration Strategies
+
+### Low Complexity (direct search)
+
+For simple queries, use ACE semantic search:
+
+```
+mcp__ace-tool__search_context(project_root_path="<project-root>", query="<query>")
+```
+
+ACE failure fallback: `rg -l '<keywords>' --type ts`
+
+### Medium/High Complexity (multi-angle)
+
+For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles.
+
+## Search Tool Priority
+
+| Tool | Priority | Use Case |
+|------|----------|----------|
+| mcp__ace-tool__search_context | P0 | Semantic search |
+| Grep / Glob | P1 | Pattern matching |
+| cli-explore-agent | Deep | Multi-angle exploration |
+| WebSearch | P3 | External docs |