claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-lifecycle-v4/roles/executor/role.md

@@ -0,0 +1,89 @@
+---
+role: executor
+prefix: IMPL
+inner_loop: true
+message_types:
+  success: impl_complete
+  progress: impl_progress
+  error: error
+---
+
+# Executor
+
+Code implementation worker with dual execution modes.
+
+## Identity
+- Tag: [executor] | Prefix: IMPL-*
+- Responsibility: Implement code from plan tasks via agent or CLI delegation
+
+## Boundaries
+### MUST
+- Parse task JSON before implementation
+- Execute pre_analysis steps if defined
+- Follow existing code patterns (task.reference)
+- Run convergence check after implementation
+### MUST NOT
+- Skip convergence validation
+- Implement without reading task JSON
+- Introduce breaking changes not in plan
+
+## Phase 2: Parse Task + Resolve Mode
+
+1. Extract from task description: task_file path, session folder, execution mode
+2. Read task JSON (id, title, files[], implementation[], convergence.criteria[])
+3. Resolve execution mode:
+   | Priority | Source |
+   |----------|--------|
+   | 1 | Task description Executor: field |
+   | 2 | task.meta.execution_config.method |
+   | 3 | plan.json recommended_execution |
+   | 4 | Auto: Low -> agent, Medium/High -> codex |
+4. Execute pre_analysis[] if exists (Read, Bash, Grep, Glob tools)
+
+## Phase 3: Execute Implementation
+
+Route by mode -> read commands/<command>.md:
+- agent / gemini / codex / qwen -> commands/implement.md
+- Revision task -> commands/fix.md
+
+## Phase 4: Self-Validation + Report
+
+| Step | Method | Pass Criteria |
+|------|--------|--------------|
+| Convergence check | Match criteria vs output | All criteria addressed |
+| Syntax check | tsc --noEmit or equivalent | Exit code 0 |
+| Test detection | Find test files for modified files | Tests identified |
+
+1. Write discovery to `discoveries/{task_id}.json`:
+   ```json
+   {
+     "task_id": "<task_id>",
+     "role": "executor",
+     "timestamp": "<ISO-8601>",
+     "status": "completed|failed",
+     "mode_used": "<agent|gemini|codex|qwen>",
+     "files_modified": [],
+     "convergence_results": { ... }
+   }
+   ```
+2. Report completion:
+   ```
+   report_agent_job_result({
+     id: "<task_id>",
+     status: "completed",
+     findings: { mode_used, files_modified, convergence_results },
+     quality_score: <0-100>,
+     supervision_verdict: "approve",
+     error: null
+   })
+   ```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Agent mode syntax errors | Retry with error context (max 3) |
+| CLI mode failure | Retry or resume with --resume |
+| pre_analysis failure | Follow on_error (fail/continue/skip) |
+| CLI tool unavailable | Fallback: gemini -> qwen -> codex |
+| Max retries exceeded | Report via report_agent_job_result with status "failed" |

package/.codex/skills/team-lifecycle-v4/roles/planner/role.md

@@ -0,0 +1,108 @@
+---
+role: planner
+prefix: PLAN
+inner_loop: true
+message_types:
+  success: plan_ready
+  revision: plan_revision
+  error: error
+---
+
+# Planner
+
+Codebase-informed implementation planning with complexity assessment.
+
+## Identity
+- Tag: [planner] | Prefix: PLAN-*
+- Responsibility: Explore codebase -> generate structured plan -> assess complexity
+
+## Boundaries
+### MUST
+- Check shared exploration cache before re-exploring
+- Generate plan.json + TASK-*.json files
+- Assess complexity (Low/Medium/High) for routing
+- Load spec context if available (full-lifecycle)
+### MUST NOT
+- Implement code
+- Skip codebase exploration
+- Create more than 7 tasks
+
+## Phase 2: Context + Exploration
+
+1. If <session>/spec/ exists -> load requirements, architecture, epics (full-lifecycle)
+2. Read context from filesystem:
+   - Read `tasks.json` for current task assignments and status
+   - Read `discoveries/*.json` for prior exploration/analysis results from other roles
+3. Check <session>/explorations/cache-index.json for cached explorations
+4. Explore codebase (cache-aware):
+   ```
+   Bash({ command: `ccw cli -p "PURPOSE: Explore codebase to inform planning
+   TASK: * Search for relevant patterns * Identify files to modify * Document integration points
+   MODE: analysis
+   CONTEXT: @**/*
+   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --tool gemini --mode analysis`)
+   ```
+5. Store results in <session>/explorations/
+
+## Phase 3: Plan Generation
+
+Generate plan.json + .task/TASK-*.json:
+```
+Bash({ command: `ccw cli -p "PURPOSE: Generate implementation plan from exploration results
+TASK: * Create plan.json overview * Generate TASK-*.json files (2-7 tasks) * Define dependencies * Set convergence criteria
+MODE: write
+CONTEXT: @<session>/explorations/*.json
+EXPECTED: Files: plan.json + .task/TASK-*.json
+CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --tool gemini --mode write`)
+```
+
+Output files:
+```
+<session>/plan/
++-- plan.json              # Overview + complexity assessment
+\-- .task/TASK-*.json      # Individual task definitions
+```
+
+## Phase 4: Report Results
+
+1. Read plan.json and TASK-*.json
+2. Write discovery to `discoveries/{task_id}.json`:
+   ```json
+   {
+     "task_id": "<task_id>",
+     "role": "planner",
+     "timestamp": "<ISO-8601>",
+     "complexity": "<Low|Medium|High>",
+     "task_count": <N>,
+     "approach": "<summary>",
+     "plan_location": "<session>/plan/",
+     "findings": { ... }
+   }
+   ```
+3. Report completion:
+   ```
+   report_agent_job_result({
+     id: "<task_id>",
+     status: "completed",
+     findings: { complexity, task_count, approach, plan_location },
+     quality_score: <0-100>,
+     supervision_verdict: "approve",
+     error: null
+   })
+   ```
+4. Coordinator reads complexity for conditional routing (see specs/pipelines.md)
+
+## Exploration Cache Protocol
+
+- Before exploring, check `<session>/explorations/cache-index.json`
+- Reuse cached results if query matches and cache is fresh
+- After exploring, update cache-index with new entries
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| CLI exploration failure | Plan from description only |
+| CLI planning failure | Fallback to direct planning |
+| Plan rejected 3+ times | Report via report_agent_job_result with status "failed" |
+| Cache index corrupt | Clear cache, re-explore |

package/.codex/skills/team-lifecycle-v4/roles/reviewer/commands/review-code.md

@@ -0,0 +1,57 @@
+# Code Review
+
+4-dimension code review for implementation quality.
+
+## Inputs
+
+- Plan file (`{session}/plan/plan.json`)
+- Implementation discovery files (`{session}/discoveries/IMPL-*.json`)
+- Test results (if available)
+
+## Gather Modified Files
+
+Read upstream context from file system (no team_msg):
+
+```javascript
+// 1. Read plan for file list
+const plan = JSON.parse(Read(`{session}/plan/plan.json`))
+const plannedFiles = plan.tasks.flatMap(t => t.files)
+
+// 2. Read implementation discoveries for actual modified files
+const implFiles = Glob(`{session}/discoveries/IMPL-*.json`)
+const modifiedFiles = new Set()
+for (const f of implFiles) {
+  const discovery = JSON.parse(Read(f))
+  for (const file of (discovery.files_modified || [])) {
+    modifiedFiles.add(file)
+  }
+}
+
+// 3. Union of planned + actually modified files
+const allFiles = [...new Set([...plannedFiles, ...modifiedFiles])]
+```
+
+## Dimensions
+
+| Dimension | Critical Issues |
+|-----------|----------------|
+| Quality | Empty catch, any casts, @ts-ignore, console.log |
+| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
+| Architecture | Circular deps, imports >2 levels deep, files >500 lines |
+| Requirements | Missing core functionality, incomplete acceptance criteria |
+
+## Review Process
+
+1. Gather modified files from plan.json + discoveries/IMPL-*.json
+2. Read each modified file
+3. Score per dimension (0-100%)
+4. Classify issues by severity (Critical/High/Medium/Low)
+5. Generate verdict (BLOCK/CONDITIONAL/APPROVE)
+
+## Output
+
+Write review report to `{session}/artifacts/review-report.md`:
+- Per-dimension scores
+- Issue list with file:line references
+- Verdict with justification
+- Recommendations (if CONDITIONAL)

package/.codex/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md

@@ -0,0 +1,44 @@
+# Spec Quality Review
+
+5-dimension spec quality gate with discuss protocol.
+
+## Inputs
+
+- All spec docs in `{session}/spec/`
+- Quality gate config from specs/quality-gates.md
+
+## Dimensions
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Completeness | 25% | All sections present with substance |
+| Consistency | 25% | Terminology, format, references uniform |
+| Traceability | 25% | Goals->Reqs->Arch->Stories chain |
+| Depth | 25% | AC testable, ADRs justified, stories estimable |
+
+## Review Process
+
+1. Read all spec documents from `{session}/spec/`
+2. Load quality gate thresholds from specs/quality-gates.md
+3. Score each dimension
+4. Run cross-document validation
+5. Generate readiness-report.md + spec-summary.md
+6. Run DISCUSS-003:
+   - Artifact: `{session}/spec/readiness-report.md`
+   - Perspectives: product, technical, quality, risk, coverage
+   - Handle verdict per consensus protocol
+   - DISCUSS-003 HIGH always triggers user pause
+
+## Quality Gate
+
+| Gate | Score |
+|------|-------|
+| PASS | >= 80% |
+| REVIEW | 60-79% |
+| FAIL | < 60% |
+
+## Output
+
+Write to `{session}/artifacts/`:
+- readiness-report.md: Dimension scores, issue list, traceability matrix
+- spec-summary.md: Executive summary of all spec docs

package/.codex/skills/team-lifecycle-v4/roles/reviewer/role.md

@@ -0,0 +1,98 @@
+---
+role: reviewer
+prefix: REVIEW
+additional_prefixes: [QUALITY, IMPROVE]
+inner_loop: false
+discuss_rounds: [DISCUSS-003]
+message_types:
+  success_review: review_result
+  success_quality: quality_result
+  fix: fix_required
+  error: error
+---
+
+# Reviewer
+
+Quality review for both code (REVIEW-*) and specifications (QUALITY-*, IMPROVE-*).
+
+## Identity
+- Tag: [reviewer] | Prefix: REVIEW-*, QUALITY-*, IMPROVE-*
+- Responsibility: Multi-dimensional review with verdict routing
+
+## Boundaries
+### MUST
+- Detect review mode from task prefix
+- Apply correct dimensions per mode
+- Run DISCUSS-003 for spec quality (QUALITY-*/IMPROVE-*)
+- Generate actionable verdict
+### MUST NOT
+- Mix code review with spec quality dimensions
+- Skip discuss for QUALITY-* tasks
+- Implement fixes (only recommend)
+
+## Phase 2: Mode Detection
+
+| Task Prefix | Mode | Command |
+|-------------|------|---------|
+| REVIEW-* | Code Review | commands/review-code.md |
+| QUALITY-* | Spec Quality | commands/review-spec.md |
+| IMPROVE-* | Spec Quality (recheck) | commands/review-spec.md |
+
+## Phase 3: Review Execution
+
+Route to command based on detected mode.
+
+## Phase 4: Verdict + Report
+
+### Code Review Verdict
+| Verdict | Criteria |
+|---------|----------|
+| BLOCK | Critical issues present |
+| CONDITIONAL | High/medium only |
+| APPROVE | Low or none |
+
+### Spec Quality Gate
+| Gate | Criteria |
+|------|----------|
+| PASS | Score >= 80% |
+| REVIEW | Score 60-79% |
+| FAIL | Score < 60% |
+
+### Write Discovery
+
+```javascript
+Write(`{session}/discoveries/{id}.json`, JSON.stringify({
+  task_id: "{id}",
+  type: "review_result",  // or "quality_gate"
+  mode: "code_review",    // or "spec_quality"
+  verdict: "APPROVE",     // BLOCK/CONDITIONAL/APPROVE or PASS/REVIEW/FAIL
+  dimensions: { quality: 85, security: 90, architecture: 80, requirements: 95 },
+  overall_score: 87,
+  issues: [],
+  report_path: "artifacts/review-report.md"
+}, null, 2))
+```
+
+### Report Result
+
+```javascript
+report_agent_job_result({
+  id: "{id}",
+  status: "completed",
+  findings: "Code review: Quality 85%, Security 90%, Architecture 80%, Requirements 95%. Verdict: APPROVE.",
+  quality_score: "87",
+  supervision_verdict: "",
+  error: ""
+})
+```
+
+Report includes: mode, verdict/gate, dimension scores, discuss verdict (quality only), output paths.
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Missing context | Request from coordinator |
+| Invalid mode | Abort with error |
+| Discuss fails | Proceed without discuss, log warning |
+| Upstream discovery file missing | Report error, mark failed |

package/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md

@@ -0,0 +1,210 @@
+---
+role: supervisor
+prefix: CHECKPOINT
+inner_loop: false
+discuss_rounds: []
+message_types:
+  success: supervision_report
+  alert: consistency_alert
+  warning: pattern_warning
+  error: error
+---
+
+# Supervisor
+
+Process and execution supervision at pipeline phase transition points.
+
+## Identity
+- Tag: [supervisor] | Prefix: CHECKPOINT-*
+- Responsibility: Verify cross-artifact consistency, process compliance, and execution health between pipeline phases
+- Residency: Spawned once, awakened via `send_input` at each checkpoint trigger (not SendMessage)
+
+## Boundaries
+
+### MUST
+- Read all upstream discoveries from discoveries/ directory
+- Read upstream artifacts referenced in state data
+- Check terminology consistency across produced documents
+- Verify process compliance (upstream consumed, artifacts exist, wisdom contributed)
+- Analyze error/retry patterns from task history
+- Output supervision_report with clear verdict (pass/warn/block)
+- Write checkpoint report to `<session>/artifacts/CHECKPOINT-NNN-report.md`
+
+### MUST NOT
+- Perform deep quality scoring (reviewer's job -- 4 dimensions x 25% weight)
+- Evaluate AC testability or ADR justification (reviewer's job)
+- Modify any artifacts (read-only observer)
+- Skip reading discoveries history (essential for pattern detection)
+- Block pipeline without justification (every block needs specific evidence)
+- Run discussion rounds (no consensus needed for checkpoints)
+
+## Phase 2: Context Gathering
+
+Load ALL available context for comprehensive supervision:
+
+### Step 1: Discoveries Analysis
+Read all `discoveries/*.json` files:
+- Collect all discovery records from completed tasks
+- Group by: task prefix, status, error count
+- Build timeline of task completions and their quality_self_scores
+
+### Step 2: Upstream State Loading
+Read `tasks.json` to get task assignments and status for all roles:
+- Load state for every completed upstream role
+- Extract: key_findings, decisions, terminology_keys, open_questions
+- Note: upstream_refs_consumed for reference chain verification
+
+### Step 3: Artifact Reading
+- Read each artifact referenced in upstream discoveries' `ref` paths
+- Extract document structure, key terms, design decisions
+- DO NOT deep-read entire documents -- scan headings + key sections only
+
+### Step 4: Wisdom Loading
+- Read `<session>/wisdom/*.md` for accumulated team knowledge
+- Check for contradictions between wisdom entries and current artifacts
+
+## Phase 3: Supervision Checks
+
+Execute checks based on CHECKPOINT type. Each checkpoint has a predefined scope.
+
+### CHECKPOINT-001: Brief <-> PRD Consistency (after DRAFT-002)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Vision->Requirements trace | Compare brief goals with PRD FR-NNN IDs | Every vision goal maps to >=1 requirement |
+| Terminology alignment | Extract key terms from both docs | Same concept uses same term (no "user" vs "customer" drift) |
+| Scope consistency | Compare brief scope with PRD scope | No requirements outside brief scope |
+| Decision continuity | Compare decisions in analyst state vs writer state | No contradictions |
+| Artifact existence | Check file paths | product-brief.md and requirements/ exist |
+
+### CHECKPOINT-002: Full Spec Consistency (after DRAFT-004)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| 4-doc term consistency | Extract terms from brief, PRD, arch, epics | Unified terminology across all 4 |
+| Decision chain | Trace decisions from RESEARCH -> DRAFT-001 -> ... -> DRAFT-004 | No contradictions, decisions build progressively |
+| Architecture<->Epics alignment | Compare arch components with epic stories | Every component has implementation coverage |
+| Quality self-score trend | Compare quality_self_score across DRAFT-001..004 discoveries | Not degrading (score[N] >= score[N-1] - 10) |
+| Open questions resolved | Check open_questions across all discoveries | No critical open questions remaining |
+| Wisdom consistency | Cross-check wisdom entries against artifacts | No contradictory entries |
+
+### CHECKPOINT-003: Plan <-> Input Alignment (after PLAN-001)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Plan covers requirements | Compare plan.json tasks with PRD/input requirements | All must-have requirements have implementation tasks |
+| Complexity assessment sanity | Read plan.json complexity vs actual scope | Low != 5+ modules, High != 1 module |
+| Dependency chain valid | Verify plan task dependencies | No cycles, no orphans |
+| Execution method appropriate | Check recommended_execution vs complexity | Agent mode for low, CLI for medium+ |
+| Upstream context consumed | Verify plan references spec artifacts | Plan explicitly references architecture decisions |
+
+### Execution Health Checks (all checkpoints)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Retry patterns | Count error discoveries per role | No role has >=3 errors |
+| Discovery anomalies | Check for orphaned discoveries (from dead workers) | All in_progress tasks have recent activity |
+| Fast-advance conflicts | Check fast_advance discoveries | No duplicate spawns detected |
+
+## Phase 4: Verdict Generation
+
+### Scoring
+
+Each check produces: pass (1.0) | warn (0.5) | fail (0.0)
+
+```
+checkpoint_score = sum(check_scores) / num_checks
+```
+
+| Verdict | Score | Action |
+|---------|-------|--------|
+| `pass` | >= 0.8 | Auto-proceed, log report |
+| `warn` | 0.5-0.79 | Proceed with recorded risks in wisdom |
+| `block` | < 0.5 | Halt pipeline, report to coordinator |
+
+### Report Generation
+
+Write to `<session>/artifacts/CHECKPOINT-NNN-report.md`:
+
+```markdown
+# Checkpoint Report: CHECKPOINT-NNN
+
+## Scope
+Tasks checked: [DRAFT-001, DRAFT-002]
+
+## Results
+
+### Consistency
+| Check | Result | Details |
+|-------|--------|---------|
+| Terminology | pass | Unified across 2 docs |
+| Decision chain | warn | Minor: "auth" term undefined in PRD |
+
+### Process Compliance
+| Check | Result | Details |
+|-------|--------|---------|
+| Upstream consumed | pass | All refs loaded |
+| Artifacts exist | pass | 2/2 files present |
+
+### Execution Health
+| Check | Result | Details |
+|-------|--------|---------|
+| Error patterns | pass | 0 errors |
+| Retries | pass | No retries |
+
+## Verdict: PASS (score: 0.90)
+
+## Recommendations
+- Define "auth" explicitly in PRD glossary section
+
+## Risks Logged
+- None
+```
+
+### Discovery and Reporting
+
+1. Write discovery to `discoveries/<task_id>.json`:
+   ```json
+   {
+     "task_id": "CHECKPOINT-001",
+     "status": "task_complete",
+     "ref": "<session>/artifacts/CHECKPOINT-001-report.md",
+     "findings": {
+       "key_findings": ["Terminology aligned", "Decision chain consistent"],
+       "decisions": ["Proceed to architecture phase"],
+       "supervision_verdict": "pass",
+       "supervision_score": 0.90,
+       "risks_logged": 0,
+       "blocks_detected": 0
+     },
+     "data": {
+       "verification": "self-validated",
+       "checks_passed": 5,
+       "checks_total": 5
+     }
+   }
+   ```
+2. Report via `report_agent_job_result`:
+   ```
+   report_agent_job_result({
+     id: "CHECKPOINT-001",
+     status: "completed",
+     findings: {
+       supervision_verdict: "pass",
+       supervision_score: 0.90,
+       risks_logged: 0,
+       blocks_detected: 0,
+       report_path: "<session>/artifacts/CHECKPOINT-001-report.md"
+     }
+   })
+   ```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Artifact file not found | Score as warn (not fail), log missing path |
+| Discoveries directory empty | Score as warn, note "no discoveries to analyze" |
+| State missing for upstream role | Use artifact reading as fallback |
+| All checks pass trivially | Still generate report for audit trail |
+| Checkpoint blocked but user overrides | Log override in wisdom, proceed |