claude-code-workflow 7.2.15 → 7.2.16

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

@@ -0,0 +1,104 @@
+---
+role: analyst
+prefix: RESEARCH
+inner_loop: false
+discuss_rounds: [DISCUSS-001]
+message_types:
+  success: research_ready
+  error: error
+---
+
+# Analyst
+
+Research and codebase exploration for context gathering.
+
+## Identity
+- Tag: [analyst] | Prefix: RESEARCH-*
+- Responsibility: Gather structured context from topic and codebase
+
+## Boundaries
+### MUST
+- Extract structured seed information from task topic
+- Explore codebase if project detected
+- Package context for downstream roles
+### MUST NOT
+- Implement code or modify files
+- Make architectural decisions
+- Skip codebase exploration when project files exist
+
+## Phase 2: Seed Analysis
+
+1. Read upstream state:
+   - Read `tasks.json` to get current task assignments and upstream status
+   - Read `discoveries/*.json` to load any prior discoveries from upstream roles
+2. Extract session folder from task description
+3. Parse topic from task description
+4. If topic references file (@path or .md/.txt) -> read it
+5. CLI seed analysis:
+   ```
+   Bash({ command: `ccw cli -p "PURPOSE: Analyze topic, extract structured seed info.
+   TASK: * Extract problem statement * Identify target users * Determine domain
+   * List constraints * Identify 3-5 exploration dimensions
+   TOPIC: <topic-content>
+   MODE: analysis
+   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --tool gemini --mode analysis`)
+   ```
+6. Parse result JSON
+
+## Phase 3: Codebase Exploration
+
+| Condition | Action |
+|-----------|--------|
+| package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore |
+| No project files | Skip (codebase_context = null) |
+
+When project detected:
+```
+Bash({ command: `ccw cli -p "PURPOSE: Explore codebase for context
+TASK: * Identify tech stack * Map architecture patterns * Document conventions * List integration points
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis`)
+```
+
+## Phase 4: Context Packaging
+
+1. Write spec-config.json -> <session>/spec/
+2. Write discovery-context.json -> <session>/spec/
+3. Inline Discuss (DISCUSS-001):
+   - Artifact: <session>/spec/discovery-context.json
+   - Perspectives: product, risk, coverage
+4. Handle verdict per consensus protocol
+5. Write discovery to `discoveries/<task_id>.json`:
+   ```json
+   {
+     "task_id": "RESEARCH-001",
+     "status": "task_complete",
+     "ref": "<session>/spec/discovery-context.json",
+     "findings": {
+       "complexity": "<low|medium|high>",
+       "codebase_present": true,
+       "dimensions": ["..."],
+       "discuss_verdict": "<verdict>"
+     },
+     "data": {
+       "output_paths": ["spec-config.json", "discovery-context.json"]
+     }
+   }
+   ```
+6. Report via `report_agent_job_result`:
+   ```
+   report_agent_job_result({
+     id: "RESEARCH-001",
+     status: "completed",
+     findings: { complexity, codebase_present, dimensions, discuss_verdict, output_paths }
+   })
+   ```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| CLI failure | Fallback to direct analysis |
+| No project detected | Continue as new project |
+| Topic too vague | Report with clarification questions |

package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/analyze.md

@@ -0,0 +1,56 @@
+# Analyze Task
+
+Parse user task -> detect capabilities -> build dependency graph -> design roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Prefix |
+|----------|------------|--------|
+| investigate, explore, research | analyst | RESEARCH |
+| write, draft, document | writer | DRAFT |
+| implement, build, code, fix | executor | IMPL |
+| design, architect, plan | planner | PLAN |
+| test, verify, validate | tester | TEST |
+| analyze, review, audit | reviewer | REVIEW |
+
+## Dependency Graph
+
+Natural ordering tiers:
+- Tier 0: analyst, planner (knowledge gathering)
+- Tier 1: writer (creation requires context)
+- Tier 2: executor (implementation requires plan/design)
+- Tier 3: tester, reviewer (validation requires artifacts)
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Per capability | +1 |
+| Cross-domain | +2 |
+| Parallel tracks | +1 per track |
+| Serial depth > 3 | +1 |
+
+Results: 1-3 Low, 4-6 Medium, 7+ High
+
+## Role Minimization
+
+- Cap at 5 roles
+- Merge overlapping capabilities
+- Absorb trivial single-step roles
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<spec-only|impl-only|full-lifecycle|...>",
+  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
+  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "needs_research": true
+}
+```

package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,61 @@
+# Dispatch Tasks
+
+Create task chains from dependency graph, write to tasks.json with proper deps relationships.
+
+## Workflow
+
+1. Read task-analysis.json -> extract dependency_graph
+2. Read specs/pipelines.md -> get task registry for selected pipeline
+3. Topological sort tasks (respect deps)
+4. Validate all owners exist in role registry (SKILL.md)
+5. For each task (in order):
+   - Add task entry to tasks.json `tasks` object (see template below)
+   - Set deps array with upstream task IDs
+   - Assign wave number based on dependency depth
+6. Update tasks.json metadata: total count, wave assignments
+7. Validate chain (no orphans, no cycles, all refs valid)
+
+## Task Entry Template
+
+Each task in tasks.json `tasks` object:
+```json
+{
+  "<TASK-ID>": {
+    "title": "<concise title>",
+    "description": "PURPOSE: <goal> | Success: <criteria>\nTASK:\n  - <step 1>\n  - <step 2>\nCONTEXT:\n  - Session: <session-folder>\n  - Upstream artifacts: <list>\n  - Key files: <list>\nEXPECTED: <artifact path> + <quality criteria>\nCONSTRAINTS: <scope limits>\n---\nInnerLoop: <true|false>\nRoleSpec: <project>/.codex/skills/team-lifecycle-v4/roles/<role>/role.md",
+    "role": "<role-name>",
+    "pipeline_phase": "<phase>",
+    "deps": ["<upstream-task-id>", "..."],
+    "context_from": ["<upstream-task-id>", "..."],
+    "wave": 1,
+    "status": "pending",
+    "findings": null,
+    "quality_score": null,
+    "supervision_verdict": null,
+    "error": null
+  }
+}
+```
+
+## InnerLoop Flag Rules
+
+- true: Role has 2+ serial same-prefix tasks (writer: DRAFT-001->004)
+- false: Role has 1 task, or tasks are parallel
+
+## CHECKPOINT Task Rules
+
+CHECKPOINT tasks are dispatched like regular tasks but handled differently at spawn time:
+
+- Added to tasks.json with proper deps (upstream tasks that must complete first)
+- Owner: supervisor
+- **NOT spawned as tlv4_worker** — coordinator wakes the resident supervisor via send_input
+- If `supervision: false` in tasks.json, skip creating CHECKPOINT tasks entirely
+- RoleSpec in description: `<project>/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md`
+
+## Dependency Validation
+
+- No orphan tasks (all tasks have valid owner)
+- No circular dependencies
+- All deps references exist in tasks object
+- Session reference in every task description
+- RoleSpec reference in every task description

package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md

@@ -0,0 +1,177 @@
+# Monitor Pipeline
+
+Synchronous pipeline coordination using spawn_agent + wait_agent.
+
+## Constants
+
+- WORKER_AGENT: tlv4_worker
+- SUPERVISOR_AGENT: tlv4_supervisor (resident, woken via send_input)
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCheck
+
+Read-only status report from tasks.json, then STOP.
+
+1. Read tasks.json
+2. Count tasks by status (pending, in_progress, completed, failed, skipped)
+
+Output:
+```
+[coordinator] Pipeline Status
+[coordinator] Progress: <done>/<total> (<pct>%)
+[coordinator] Active agents: <list from active_agents>
+[coordinator] Ready: <pending tasks with resolved deps>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+## handleResume
+
+1. Read tasks.json, check active_agents
+2. No active agents -> handleSpawnNext
+3. Has active agents -> check each:
+   - If supervisor with `resident: true` + no CHECKPOINT in_progress + pending CHECKPOINT exists
+     -> supervisor may have crashed. Respawn via spawn_agent({ agent_type: "tlv4_supervisor" }) with recovery: true
+4. Proceed to handleSpawnNext
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, wait for completion, process results.
+
+1. Read tasks.json
+2. Collect: completedTasks, inProgressTasks, readyTasks (pending + all deps completed)
+3. No ready + nothing in progress -> handleComplete
+4. No ready + work in progress -> report waiting, STOP
+5. Has ready -> separate regular tasks and CHECKPOINT tasks
+
+### Spawn Regular Tasks
+
+For each ready non-CHECKPOINT task:
+
+```javascript
+// 1) Update status in tasks.json
+state.tasks[task.id].status = 'in_progress'
+
+// 2) Spawn worker
+const agentId = spawn_agent({
+  agent_type: "tlv4_worker",
+  items: [
+    { type: "text", text: `## Role Assignment
+role: ${task.role}
+role_spec: ${skillRoot}/roles/${task.role}/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+requirement: ${requirement}
+inner_loop: ${hasInnerLoop(task.role)}` },
+
+    { type: "text", text: `Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` },
+
+    { type: "text", text: `## Task Context
+task_id: ${task.id}
+title: ${task.title}
+description: ${task.description}
+pipeline_phase: ${task.pipeline_phase}` },
+
+    { type: "text", text: `## Upstream Context\n${prevContext}` }
+  ]
+})
+
+// 3) Track agent
+state.active_agents[task.id] = { agentId, role: task.role, started_at: now }
+```
+
+After spawning all ready regular tasks:
+
+```javascript
+// 4) Batch wait for all spawned workers
+const agentIds = Object.values(state.active_agents)
+  .filter(a => !a.resident)
+  .map(a => a.agentId)
+wait_agent({ ids: agentIds, timeout_ms: 900000 })
+
+// 5) Collect results from discoveries/{task_id}.json
+for (const [taskId, agent] of Object.entries(state.active_agents)) {
+  if (agent.resident) continue
+  try {
+    const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`))
+    state.tasks[taskId].status = disc.status || 'completed'
+    state.tasks[taskId].findings = disc.findings || ''
+    state.tasks[taskId].quality_score = disc.quality_score || null
+    state.tasks[taskId].error = disc.error || null
+  } catch {
+    state.tasks[taskId].status = 'failed'
+    state.tasks[taskId].error = 'No discovery file produced'
+  }
+  close_agent({ id: agent.agentId })
+  delete state.active_agents[taskId]
+}
+```
+
+### Handle CHECKPOINT Tasks
+
+For each ready CHECKPOINT task:
+
+1. Verify supervisor is in active_agents with `resident: true`
+   - Not found -> spawn supervisor via SKILL.md Supervisor Spawn Template, record supervisorId
+2. Determine scope: list task IDs that this checkpoint depends on (its deps)
+3. Wake supervisor:
+   ```javascript
+   send_input({
+     id: supervisorId,
+     items: [
+       { type: "text", text: `## Checkpoint Request
+   task_id: ${task.id}
+   scope: [${task.deps.join(', ')}]
+   pipeline_progress: ${completedCount}/${totalCount} tasks completed` }
+     ]
+   })
+   wait_agent({ ids: [supervisorId], timeout_ms: 300000 })
+   ```
+4. Read checkpoint report from artifacts/${task.id}-report.md
+5. Parse verdict (pass / warn / block):
+   - **pass** -> mark completed, proceed
+   - **warn** -> log risks to wisdom, mark completed, proceed
+   - **block** -> request_user_input: Override / Revise upstream / Abort
+
+### Persist and Loop
+
+After processing all results:
+1. Write updated tasks.json
+2. Check if more tasks are now ready (deps newly resolved)
+3. If yes -> loop back to step 1 of handleSpawnNext
+4. If no more ready and all done -> handleComplete
+5. If no more ready but some still blocked -> report status, STOP
+
+## handleComplete
+
+Pipeline done. Generate report and completion action.
+
+1. Shutdown resident supervisor (if active):
+   ```javascript
+   close_agent({ id: supervisorId })
+   ```
+   Remove from active_agents in tasks.json
+2. Generate summary (deliverables, stats, discussions)
+3. Read tasks.json completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (rm -rf session folder)
+   - auto_keep -> Keep Active (update status to "paused")
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/
+4. Add new task to tasks.json, spawn worker via spawn_agent + wait_agent
+5. Role count >= 5 -> merge or pause

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

@@ -0,0 +1,152 @@
+# Coordinator Role
+
+Orchestrate team-lifecycle-v4: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Parse task description (text-level only, no codebase reading)
+- Create session folder and spawn tlv4_worker agents via spawn_agent
+- Dispatch tasks with proper dependency chains (tasks.json)
+- Monitor progress via wait_agent and process results
+- Maintain session state (tasks.json)
+- Handle capability_gap reports
+- Execute completion action when pipeline finishes
+
+### MUST NOT
+- Read source code or explore codebase (delegate to workers)
+- Execute task work directly
+- Modify task output artifacts
+- Spawn workers with general-purpose agent (MUST use tlv4_worker)
+- Generate more than 5 worker roles
+
+## Command Execution Protocol
+When coordinator needs to execute a specific phase:
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
+| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
+| Interrupted session | Active session in .workflow/.team/TLV4-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan .workflow/.team/TLV4-*/tasks.json for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile:
+   a. Read tasks.json, reset in_progress -> pending
+   b. Rebuild active_agents map
+   c. If pipeline has CHECKPOINT tasks AND `supervision !== false`:
+      - Respawn supervisor via `spawn_agent({ agent_type: "tlv4_supervisor" })` with `recovery: true`
+      - Supervisor auto-rebuilds context from existing CHECKPOINT-*-report.md files
+   d. Kick first ready task via handleSpawnNext
+4. Multiple -> request_user_input for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse task description
+2. Clarify if ambiguous (request_user_input: scope, deliverables, constraints)
+3. Delegate to @commands/analyze.md
+4. Output: task-analysis.json
+5. CRITICAL: Always proceed to Phase 2, never skip team workflow
+
+## Phase 2: Create Session + Initialize
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.codex/skills/team-lifecycle-v4`
+2. Generate session ID: TLV4-<slug>-<date>
+3. Create session folder structure:
+   ```bash
+   mkdir -p .workflow/.team/${SESSION_ID}/{artifacts,discoveries,wisdom,role-specs}
+   ```
+4. Read specs/pipelines.md -> select pipeline
+5. Register roles in tasks.json metadata
+6. Initialize shared infrastructure (wisdom/*.md, explorations/cache-index.json)
+7. Write initial tasks.json:
+   ```json
+   {
+     "session_id": "<id>",
+     "pipeline": "<mode>",
+     "requirement": "<original requirement>",
+     "created_at": "<ISO timestamp>",
+     "supervision": true,
+     "completed_waves": [],
+     "active_agents": {},
+     "tasks": {}
+   }
+   ```
+8. Spawn resident supervisor (if pipeline has CHECKPOINT tasks AND `supervision !== false`):
+   - Use SKILL.md Supervisor Spawn Template:
+     ```javascript
+     const supervisorId = spawn_agent({
+       agent_type: "tlv4_supervisor",
+       items: [
+         { type: "text", text: `## Role Assignment
+     role: supervisor
+     role_spec: ${skillRoot}/roles/supervisor/role.md
+     session: ${sessionFolder}
+     session_id: ${sessionId}
+     requirement: ${requirement}
+
+     Read role_spec file to load checkpoint definitions.
+     Init: load baseline context, report ready, go idle.` }
+       ]
+     })
+     ```
+   - Record supervisorId in tasks.json active_agents with `resident: true` flag
+   - Proceed to Phase 3
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read dependency graph from task-analysis.json
+2. Read specs/pipelines.md for selected pipeline's task registry
+3. Topological sort tasks
+4. Write tasks to tasks.json with deps arrays
+5. Update tasks.json metadata (total count, wave assignments)
+
+## Phase 4: Spawn-and-Wait
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + deps resolved)
+2. Spawn tlv4_worker agents via spawn_agent
+3. Wait for completion via wait_agent
+4. Process results, advance pipeline
+5. Repeat until all waves complete or pipeline blocked
+
+## Phase 5: Report + Completion Action
+
+1. Generate summary (deliverables, pipeline stats, discussions)
+2. Execute completion action per tasks.json completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (rm -rf session folder)
+   - auto_keep -> Keep Active
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task too vague | request_user_input for clarification |
+| Session corruption | Attempt recovery, fallback to manual |
+| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
+| Supervisor crash | Respawn via spawn_agent({ agent_type: "tlv4_supervisor" }) with recovery: true |
+| Dependency cycle | Detect in analysis, halt |
+| Role limit exceeded | Merge overlapping roles |

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

@@ -0,0 +1,35 @@
+# Fix
+
+Revision workflow for bug fixes and feedback-driven changes.
+
+## Workflow
+
+1. Read original task + feedback/revision notes from task description
+2. Load original implementation context (files modified, approach taken)
+3. Analyze feedback to identify specific changes needed
+4. Apply fixes:
+   - Agent mode: Edit tool for targeted changes
+   - CLI mode: Resume previous session with fix prompt
+5. Re-validate convergence criteria
+6. Report: original task, changes applied, validation result
+
+## Fix Prompt Template (CLI mode)
+
+```
+PURPOSE: Fix issues in <task.title> based on feedback
+TASK:
+  - Review original implementation
+  - Apply feedback: <feedback text>
+  - Verify fixes address all feedback points
+MODE: write
+CONTEXT: @<modified files>
+EXPECTED: All feedback points addressed, convergence criteria met
+CONSTRAINTS: Minimal changes | No scope creep
+```
+
+## Quality Rules
+
+- Fix ONLY what feedback requests
+- No refactoring beyond fix scope
+- Verify original convergence criteria still pass
+- Report partial_completion if some feedback unclear

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

@@ -0,0 +1,63 @@
+# Implement
+
+Execute implementation from task JSON via agent or CLI delegation.
+
+## Agent Mode
+
+Direct implementation using Edit/Write/Bash tools:
+
+1. Read task.files[] as target files
+2. Read task.implementation[] as step-by-step instructions
+3. For each step:
+   - Substitute [variable] placeholders with pre_analysis results
+   - New file -> Write tool; Modify file -> Edit tool
+   - Follow task.reference patterns
+4. Apply task.rationale.chosen_approach
+5. Mitigate task.risks[] during implementation
+
+Quality rules:
+- Verify module existence before referencing
+- Incremental progress -- small working changes
+- Follow existing patterns from task.reference
+- ASCII-only, no premature abstractions
+
+## CLI Delegation Mode
+
+Build prompt from task JSON, delegate to CLI:
+
+Prompt structure:
+```
+PURPOSE: <task.title>
+<task.description>
+
+TARGET FILES:
+<task.files[] with paths and changes>
+
+IMPLEMENTATION STEPS:
+<task.implementation[] numbered>
+
+PRE-ANALYSIS CONTEXT:
+<pre_analysis results>
+
+REFERENCE:
+<task.reference pattern and files>
+
+DONE WHEN:
+<task.convergence.criteria[]>
+
+MODE: write
+CONSTRAINTS: Only modify listed files | Follow existing patterns
+```
+
+CLI call:
+```
+Bash(`ccw cli -p "<prompt>" --tool <tool> --mode write --rule development-implement-feature`)
+```
+
+Resume strategy:
+| Strategy | Command |
+|----------|---------|
+| new | --id <session>-<task_id> |
+| resume | --resume <parent_id> |
+
+RoleSpec: `.codex/skills/team-lifecycle-v4/roles/executor/role.md`