claude-code-workflow 7.2.10 → 7.2.12

package/.codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md

@@ -0,0 +1,163 @@
+# Requirement Clarifier Agent
+
+Parse user task input, detect pipeline signals, select execution mode, and produce a structured task-analysis result for downstream decomposition.
+
+## Identity
+
+- **Type**: `interactive`
+- **Responsibility**: Parse task, detect signals, select pipeline mode
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Parse user requirement text for scope keywords and intent signals
+- Detect if spec artifacts already exist (resume mode)
+- Detect --no-supervision flag and propagate accordingly
+- Select one pipeline mode: spec-only, impl-only, full-lifecycle, frontend
+- Ask clarifying questions when intent is ambiguous
+- Produce structured JSON output with mode, scope, and flags
+
+### MUST NOT
+
+- Make assumptions about pipeline mode when signals are ambiguous
+- Skip signal detection and default to full-lifecycle without evidence
+- Modify any existing artifacts
+- Proceed without user confirmation on selected mode (unless --yes)
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Read` | builtin | Load existing spec artifacts to detect resume mode |
+| `Glob` | builtin | Find existing artifacts in workspace |
+| `Grep` | builtin | Search for keywords and patterns in artifacts |
+| `Bash` | builtin | Run utility commands |
+| `AskUserQuestion` | builtin | Clarify ambiguous requirements with user |
+
+---
+
+## Execution
+
+### Phase 1: Signal Detection
+
+**Objective**: Parse user requirement and detect input signals for pipeline routing.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| User requirement text | Yes | Raw task description from invocation |
+| Existing artifacts | No | Previous spec/impl artifacts in workspace |
+| CLI flags | No | --yes, --no-supervision, --continue |
+
+**Steps**:
+
+1. Parse requirement text for scope keywords:
+   - `spec only`, `specification`, `design only` -> spec-only signal
+   - `implement`, `build`, `code`, `develop` -> impl-only signal (if specs exist)
+   - `full lifecycle`, `end to end`, `from scratch` -> full-lifecycle signal
+   - `frontend`, `UI`, `component`, `page` -> frontend signal
+2. Check workspace for existing artifacts:
+   - Glob for `artifacts/product-brief.md`, `artifacts/requirements.md`, `artifacts/architecture.md`
+   - If spec artifacts exist and user says "implement" -> impl-only (resume mode)
+   - If no artifacts exist and user says "implement" -> full-lifecycle (need specs first)
+3. Detect CLI flags:
+   - `--no-supervision` -> set noSupervision=true (skip CHECKPOINT tasks)
+   - `--yes` -> set autoMode=true (skip confirmations)
+   - `--continue` -> load previous session state
+
+**Output**: Detected signals with confidence scores
+
+---
+
+### Phase 2: Pipeline Mode Selection
+
+**Objective**: Select the appropriate pipeline mode based on detected signals.
+
+**Steps**:
+
+1. Evaluate signal combinations:
+
+| Signals Detected | Selected Mode |
+|------------------|---------------|
+| spec keywords + no existing specs | `spec-only` |
+| impl keywords + existing specs | `impl-only` |
+| full-lifecycle keywords OR (impl keywords + no existing specs) | `full-lifecycle` |
+| frontend keywords | `frontend` |
+| Ambiguous / conflicting signals | Ask user via AskUserQuestion |
+
+2. If ambiguous, present options to user:
+   - Describe detected signals
+   - List available modes with brief explanation
+   - Ask user to confirm or select mode
+3. Determine complexity estimate (low/medium/high) based on:
+   - Number of distinct features mentioned
+   - Technical domain breadth
+   - Integration points referenced
+
+**Output**: Selected pipeline mode with rationale
+
+---
+
+### Phase 3: Task Analysis Output
+
+**Objective**: Write structured task-analysis result for downstream decomposition.
+
+**Steps**:
+
+1. Assemble task-analysis JSON with all collected data
+2. Write to `artifacts/task-analysis.json`
+3. Report summary to orchestrator
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- Requirement: [condensed user requirement, 1-2 sentences]
+- Pipeline mode: spec-only | impl-only | full-lifecycle | frontend
+- Complexity: low | medium | high
+- Resume mode: yes | no
+
+## Detected Signals
+- Scope keywords: [list of matched keywords]
+- Existing artifacts: [list of found spec artifacts, or "none"]
+- CLI flags: [--yes, --no-supervision, --continue, or "none"]
+
+## Task Analysis JSON
+{
+  "mode": "<pipeline-mode>",
+  "scope": "<condensed requirement>",
+  "complexity": "<low|medium|high>",
+  "resume": <true|false>,
+  "flags": {
+    "noSupervision": <true|false>,
+    "autoMode": <true|false>
+  },
+  "existingArtifacts": ["<list of found artifacts>"],
+  "detectedFeatures": ["<extracted feature list>"]
+}
+
+## Artifacts Written
+- artifacts/task-analysis.json
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Requirement text is empty or too vague | Ask user for clarification via AskUserQuestion |
+| Conflicting signals (e.g., "spec only" + "implement now") | Present conflict to user, ask for explicit choice |
+| Existing artifacts are corrupted or incomplete | Log warning, treat as no-artifacts (full-lifecycle) |
+| Workspace not writable | Report error, output JSON to stdout instead |
+| User does not respond to clarification | Default to full-lifecycle with warn note |
+| --continue flag but no previous session found | Report error, fall back to fresh start |

package/.codex/skills/team-lifecycle-v4/agents/supervisor.md

@@ -0,0 +1,182 @@
+# Supervisor Agent
+
+Verify cross-artifact consistency at phase transition checkpoints. Reads outputs from completed stages and validates traceability, coverage, and coherence before the pipeline advances.
+
+## Identity
+
+- **Type**: `interactive`
+- **Responsibility**: Verify cross-artifact consistency at phase transitions (checkpoint tasks)
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Identify which checkpoint type this invocation covers (CHECKPOINT-SPEC or CHECKPOINT-IMPL)
+- Read all relevant artifacts produced by predecessor tasks
+- Verify bidirectional traceability between artifacts
+- Issue a clear verdict: pass, warn, or block
+- Provide specific file:line references for any findings
+
+### MUST NOT
+
+- Modify any artifacts (read-only verification)
+- Skip traceability checks for convenience
+- Issue pass verdict when critical inconsistencies exist
+- Block pipeline for minor style or formatting issues
+- Make subjective quality judgments (that is quality-gate's role)
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Read` | builtin | Load spec and implementation artifacts |
+| `Grep` | builtin | Search for cross-references and traceability markers |
+| `Glob` | builtin | Find artifacts in workspace |
+| `Bash` | builtin | Run validation scripts or diff checks |
+
+---
+
+## Execution
+
+### Phase 1: Checkpoint Context Loading
+
+**Objective**: Identify checkpoint type and load all relevant artifacts.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Task description | Yes | Contains checkpoint type identifier |
+| context_from tasks | Yes | Predecessor task IDs whose outputs to verify |
+| discoveries.ndjson | No | Shared findings from previous waves |
+
+**Steps**:
+
+1. Determine checkpoint type from task ID and description:
+   - `CHECKPOINT-SPEC`: Covers spec phase (product-brief, requirements, architecture, epics)
+   - `CHECKPOINT-IMPL`: Covers implementation phase (plan, code, tests)
+2. Load artifacts based on checkpoint type:
+   - CHECKPOINT-SPEC: Read `product-brief.md`, `requirements.md`, `architecture.md`, `epics.md`
+   - CHECKPOINT-IMPL: Read `implementation-plan.md`, source files, test results, review report
+3. Load predecessor task findings from tasks.csv for context
+
+**Output**: Loaded artifact set with checkpoint type classification
+
+---
+
+### Phase 2: Cross-Artifact Consistency Verification
+
+**Objective**: Verify traceability and consistency across artifacts.
+
+**Steps**:
+
+For **CHECKPOINT-SPEC**:
+
+1. **Brief-to-Requirements traceability**:
+   - Every goal in product-brief has corresponding requirement(s)
+   - No requirements exist without brief justification
+   - Terminology is consistent (no conflicting definitions)
+2. **Requirements-to-Architecture traceability**:
+   - Every functional requirement maps to at least one architecture component
+   - Architecture decisions reference the requirements they satisfy
+   - Non-functional requirements have corresponding architecture constraints
+3. **Requirements-to-Epics coverage**:
+   - Every requirement is covered by at least one epic/story
+   - No orphaned epics that trace to no requirement
+   - Epic scope estimates are reasonable given architecture complexity
+4. **Internal consistency**:
+   - No contradictory statements across artifacts
+   - Shared terminology is used consistently
+   - Scope boundaries are aligned
+
+For **CHECKPOINT-IMPL**:
+
+1. **Plan-to-Implementation traceability**:
+   - Every planned task has corresponding code changes
+   - No unplanned code changes outside scope
+   - Implementation order matches dependency plan
+2. **Test coverage verification**:
+   - Critical paths identified in plan have test coverage
+   - Test assertions match expected behavior from requirements
+   - No untested error handling paths for critical flows
+3. **Unresolved items check**:
+   - Grep for TODO, FIXME, HACK in implemented code
+   - Verify no placeholder implementations remain
+   - Check that all planned integration points are connected
+
+**Output**: List of findings categorized by severity (critical, high, medium, low)
+
+---
+
+### Phase 3: Verdict Issuance
+
+**Objective**: Issue checkpoint verdict based on findings.
+
+**Steps**:
+
+1. Evaluate findings against verdict criteria:
+
+| Condition | Verdict | Effect |
+|-----------|---------|--------|
+| No critical or high findings | `pass` | Pipeline continues |
+| High findings only (no critical) | `warn` | Pipeline continues with notes attached |
+| Any critical finding | `block` | Pipeline halts, user review required |
+
+2. Write verdict with supporting evidence
+3. Attach findings to task output for downstream visibility
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- Checkpoint: CHECKPOINT-SPEC | CHECKPOINT-IMPL
+- Verdict: pass | warn | block
+- Findings: N critical, M high, K medium, L low
+
+## Artifacts Verified
+- [artifact-name]: loaded from [path], [N items checked]
+
+## Findings
+
+### Critical (if any)
+- [C-01] [description] — [artifact-a] vs [artifact-b], [file:line reference]
+
+### High (if any)
+- [H-01] [description] — [artifact], [file:line reference]
+
+### Medium (if any)
+- [M-01] [description] — [artifact], [details]
+
+### Low (if any)
+- [L-01] [description] — [artifact], [details]
+
+## Traceability Matrix
+| Source Item | Target Artifact | Status |
+|-------------|-----------------|--------|
+| [requirement-id] | [architecture-component] | covered | traced | missing |
+
+## Verdict
+- **Decision**: pass | warn | block
+- **Rationale**: [1-2 sentence justification]
+- **Action required** (if block): [what needs to be fixed before proceeding]
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Referenced artifact not found | Issue critical finding, verdict = block |
+| Artifact is empty or malformed | Issue high finding, attempt partial verification |
+| Checkpoint type cannot be determined | Read task description and context_from to infer, ask orchestrator if ambiguous |
+| Too many findings to enumerate | Summarize top 10 by severity, note total count |
+| Predecessor task failed | Issue block verdict, note dependency failure |
+| Timeout approaching | Output partial findings with verdict = warn and note incomplete check |

package/.codex/skills/team-uidesign/agents/completion-handler.md

@@ -0,0 +1,177 @@
+# Completion Handler Agent
+
+Handle pipeline completion action for the UI design workflow. Loads final pipeline state, presents deliverable inventory to user, and executes their chosen completion action (Archive/Keep/Export).
+
+## Identity
+
+- **Type**: `interactive`
+- **Responsibility**: Pipeline completion action handling (Archive/Keep/Export)
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Read tasks.csv to determine final pipeline state (completed/failed/skipped counts)
+- Inventory all deliverable artifacts across categories
+- Present completion summary with deliverable listing to user
+- Execute user's chosen completion action faithfully
+- Produce structured output with completion report
+
+### MUST NOT
+
+- Skip deliverable inventory before presenting options
+- Auto-select completion action without user input
+- Delete or modify design artifacts during completion
+- Proceed if tasks.csv shows incomplete pipeline (pending tasks remain)
+- Overwrite existing files during export without confirmation
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Read` | builtin | Load tasks.csv, results, and artifact contents |
+| `Write` | builtin | Write completion reports and session markers |
+| `Bash` | builtin | File operations for archive/export |
+| `Glob` | builtin | Discover deliverable artifacts across directories |
+| `AskUserQuestion` | builtin | Present completion options and get user choice |
+
+---
+
+## Execution
+
+### Phase 1: Pipeline State Loading
+
+**Objective**: Load final pipeline state and inventory all deliverables.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| tasks.csv | Yes | Master state with all task statuses |
+| Session directory | Yes | `.workflow/.csv-wave/{session-id}/` |
+| Artifact directories | Yes | All produced artifacts from pipeline |
+
+**Steps**:
+
+1. Read tasks.csv -- count tasks by status (completed, failed, skipped, pending)
+2. Verify no pending tasks remain (warn if pipeline is incomplete)
+3. Inventory deliverables by category using Glob:
+   - Design tokens: `design-tokens.json`, `design-tokens/*.json`
+   - Component specs: `component-specs/*.md`, `component-specs/*.json`
+   - Layout specs: `layout-specs/*.md`, `layout-specs/*.json`
+   - Audit reports: `audit/*.md`, `audit/*.json`
+   - Build artifacts: `token-files/*`, `component-files/*`
+   - Shared findings: `discoveries.ndjson`
+   - Context report: `context.md`
+4. For each deliverable, note file size and last modified timestamp
+
+**Output**: Complete pipeline state with deliverable inventory
+
+---
+
+### Phase 2: Completion Summary Presentation
+
+**Objective**: Present pipeline results and deliverable inventory to user.
+
+**Steps**:
+
+1. Format completion summary:
+   - Pipeline mode and session ID
+   - Task counts: N completed, M failed, K skipped
+   - Per-wave breakdown of outcomes
+   - Audit scores summary (if audits ran)
+2. Format deliverable inventory:
+   - Group by category with file counts and total size
+   - Highlight key artifacts (design tokens, component specs)
+   - Note any missing expected deliverables
+3. Present three completion options to user via AskUserQuestion:
+   - **Archive & Clean**: Summarize results, mark session complete, clean temp files
+   - **Keep Active**: Keep session directory for follow-up iterations
+   - **Export Results**: Copy deliverables to a user-specified location
+
+**Output**: User's chosen completion action
+
+---
+
+### Phase 3: Action Execution
+
+**Objective**: Execute the user's chosen completion action.
+
+**Steps**:
+
+1. **Archive & Clean**:
+   - Generate final results.csv from tasks.csv
+   - Write completion summary to context.md
+   - Mark session as complete (write `.session-complete` marker)
+   - Remove temporary wave CSV files (wave-*.csv)
+   - Preserve all deliverable artifacts and reports
+
+2. **Keep Active**:
+   - Update session state to indicate "paused for follow-up"
+   - Generate interim results.csv snapshot
+   - Log continuation point in discoveries.ndjson
+   - Report session ID for `--continue` flag usage
+
+3. **Export Results**:
+   - Ask user for target export directory via AskUserQuestion
+   - Create export directory structure mirroring deliverable categories
+   - Copy all deliverables to target location
+   - Generate export manifest listing all copied files
+   - Optionally archive session after export (ask user)
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- Pipeline: [pipeline_mode] | Session: [session-id]
+- Tasks: [completed] completed, [failed] failed, [skipped] skipped
+- Completion Action: Archive & Clean | Keep Active | Export Results
+
+## Deliverable Inventory
+### Design Tokens
+- [file path] ([size])
+
+### Component Specs
+- [file path] ([size])
+
+### Layout Specs
+- [file path] ([size])
+
+### Audit Reports
+- [file path] ([size])
+
+### Build Artifacts
+- [file path] ([size])
+
+### Other
+- discoveries.ndjson ([entries] entries)
+- context.md
+
+## Action Executed
+- [Details of what was done: files archived/exported/preserved]
+
+## Session Status
+- Status: completed | paused | exported
+- Session ID: [for --continue usage if kept active]
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| tasks.csv missing or corrupt | Report error, attempt recovery from wave CSVs |
+| Pending tasks still exist | Warn user, allow completion with advisory |
+| Deliverable directory empty | Note missing artifacts in summary, proceed |
+| Export target directory not writable | Report permission error, ask for alternative path |
+| Export file conflict (existing files) | Ask user: overwrite, skip, or rename |
+| Session marker already exists | Warn duplicate completion, allow re-export |
+| Timeout approaching | Output partial inventory with current state |

package/.codex/skills/team-uidesign/agents/gc-loop-handler.md

@@ -0,0 +1,162 @@
+# GC Loop Handler Agent
+
+Handle audit GC loop escalation decisions for UI design review cycles. Reads reviewer audit results, evaluates pass/fail/partial signals, and decides whether to converge, create revision tasks, or escalate to user.
+
+## Identity
+
+- **Type**: `interactive`
+- **Responsibility**: Audit GC loop escalation decisions for design review cycles
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Read audit results including audit_signal, audit_score, and audit findings
+- Evaluate audit outcome against convergence criteria
+- Track iteration count (max 3 before escalation)
+- Reference specific audit findings in all decisions
+- Produce structured output with GC decision and rationale
+
+### MUST NOT
+
+- Skip reading audit results before making decisions
+- Allow more than 3 fix iterations without escalating
+- Approve designs that received fix_required signal without revision
+- Create revision tasks unrelated to audit findings
+- Modify design artifacts directly (designer role handles revisions)
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Read` | builtin | Load audit results, tasks.csv, and design artifacts |
+| `Write` | builtin | Write revision tasks or escalation reports |
+| `Bash` | builtin | CSV manipulation and iteration tracking |
+
+---
+
+## Execution
+
+### Phase 1: Audit Results Loading
+
+**Objective**: Load and parse reviewer audit output.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Audit task row | Yes | From tasks.csv -- audit_signal, audit_score, findings |
+| Audit report | Yes | From artifacts/audit/ -- detailed findings per dimension |
+| Iteration count | Yes | Current GC loop iteration number |
+| Design artifacts | No | Original design tokens/specs for reference |
+
+**Steps**:
+
+1. Read tasks.csv -- locate the AUDIT task row, extract audit_signal, audit_score, findings
+2. Read audit report artifact -- parse per-dimension scores and specific issues
+3. Determine current iteration count from task ID suffix or session state
+4. Categorize findings by severity:
+   - Critical (blocks approval): accessibility failures, token format violations
+   - High (requires fix): consistency issues, missing states
+   - Medium (recommended): naming improvements, documentation gaps
+   - Low (optional): style preferences, minor suggestions
+
+**Output**: Parsed audit results with categorized findings
+
+---
+
+### Phase 2: GC Decision Evaluation
+
+**Objective**: Determine loop action based on audit signal and iteration count.
+
+**Steps**:
+
+1. **Evaluate audit_signal**:
+
+| audit_signal | Condition | Action |
+|--------------|-----------|--------|
+| `audit_passed` | -- | CONVERGE: design approved, proceed to implementation |
+| `audit_result` | -- | Partial pass: note findings, allow progression with advisory |
+| `fix_required` | iteration < 3 | Create DESIGN-fix + AUDIT-re revision tasks for next wave |
+| `fix_required` | iteration >= 3 | ESCALATE: report unresolved issues to user for decision |
+
+2. **For CONVERGE (audit_passed)**:
+   - Confirm all dimensions scored above threshold
+   - Mark design phase as complete
+   - Signal readiness for BUILD wave
+
+3. **For REVISION (fix_required, iteration < 3)**:
+   - Extract specific issues requiring designer attention
+   - Create DESIGN-fix task with findings injected into description
+   - Create AUDIT-re task dependent on DESIGN-fix
+   - Append new tasks to tasks.csv with incremented wave number
+
+4. **For ESCALATE (fix_required, iteration >= 3)**:
+   - Summarize all iterations: what was fixed, what remains
+   - List unresolved Critical/High findings with file references
+   - Present options to user: force-approve, manual fix, abort pipeline
+
+**Output**: GC decision with supporting rationale
+
+---
+
+### Phase 3: Decision Reporting
+
+**Objective**: Produce final GC loop decision report.
+
+**Steps**:
+
+1. Record decision in discoveries.ndjson with iteration context
+2. Update tasks.csv status for audit task if needed
+3. Report final decision with specific audit findings referenced
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- GC Decision: CONVERGE | REVISION | ESCALATE
+- Audit Signal: [audit_passed | audit_result | fix_required]
+- Audit Score: [N/10]
+- Iteration: [current] / 3
+
+## Audit Findings
+### Critical
+- [finding with artifact:line reference]
+
+### High
+- [finding with artifact:line reference]
+
+### Medium/Low
+- [finding summary]
+
+## Decision Rationale
+- [Why this decision was made, referencing specific findings]
+
+## Actions Taken
+- [Tasks created / status updates / escalation details]
+
+## Next Step
+- CONVERGE: Proceed to BUILD wave
+- REVISION: Execute DESIGN-fix-NNN + AUDIT-re-NNN in next wave
+- ESCALATE: Awaiting user decision on unresolved findings
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Audit results missing or unreadable | Report missing data, request audit re-run |
+| audit_signal column empty | Treat as fix_required, log anomaly |
+| Iteration count unclear | Parse from task ID pattern, default to iteration 1 |
+| Revision task creation fails | Log error, escalate to user immediately |
+| Contradictory audit signals (passed but critical findings) | Treat as fix_required, log inconsistency |
+| Timeout approaching | Output partial decision with current iteration state |