claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-lifecycle-v4/templates/requirements.md

@@ -1,224 +1,224 @@
-# Requirements PRD Template (Directory Structure)
-
-Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3.
-
-## Usage Context
-
-| Phase | Usage |
-|-------|-------|
-| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion |
-| Output Location | `{workDir}/requirements/` |
-
-## Output Structure
-
-```
-{workDir}/requirements/
-├── _index.md                      # Summary + MoSCoW table + traceability matrix + links
-├── REQ-001-{slug}.md              # Individual functional requirement
-├── REQ-002-{slug}.md
-├── NFR-P-001-{slug}.md            # Non-functional: Performance
-├── NFR-S-001-{slug}.md            # Non-functional: Security
-├── NFR-SC-001-{slug}.md           # Non-functional: Scalability
-├── NFR-U-001-{slug}.md            # Non-functional: Usability
-└── ...
-```
-
----
-
-## Template: _index.md
-
-```markdown
----
-session_id: {session_id}
-phase: 3
-document_type: requirements-index
-status: draft
-generated_at: {timestamp}
-version: 1
-dependencies:
-  - ../spec-config.json
-  - ../product-brief.md
----
-
-# Requirements: {product_name}
-
-{executive_summary - brief overview of what this PRD covers and key decisions}
-
-## Requirement Summary
-
-| Priority | Count | Coverage |
-|----------|-------|----------|
-| Must Have | {n} | {description of must-have scope} |
-| Should Have | {n} | {description of should-have scope} |
-| Could Have | {n} | {description of could-have scope} |
-| Won't Have | {n} | {description of explicitly excluded} |
-
-## Functional Requirements
-
-| ID | Title | Priority | Traces To |
-|----|-------|----------|-----------|
-| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
-| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
-| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) |
-
-## Non-Functional Requirements
-
-### Performance
-
-| ID | Title | Target |
-|----|-------|--------|
-| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} |
-
-### Security
-
-| ID | Title | Standard |
-|----|-------|----------|
-| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} |
-
-### Scalability
-
-| ID | Title | Target |
-|----|-------|--------|
-| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} |
-
-### Usability
-
-| ID | Title | Target |
-|----|-------|--------|
-| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} |
-
-## Data Requirements
-
-### Data Entities
-
-| Entity | Description | Key Attributes |
-|--------|-------------|----------------|
-| {entity_name} | {description} | {attr1, attr2, attr3} |
-
-### Data Flows
-
-{description of key data flows, optionally with Mermaid diagram}
-
-## Integration Requirements
-
-| System | Direction | Protocol | Data Format | Notes |
-|--------|-----------|----------|-------------|-------|
-| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} |
-
-## Constraints & Assumptions
-
-### Constraints
-- {technical or business constraint 1}
-- {technical or business constraint 2}
-
-### Assumptions
-- {assumption 1 - must be validated}
-- {assumption 2 - must be validated}
-
-## Priority Rationale
-
-{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries}
-
-## Traceability Matrix
-
-| Goal | Requirements |
-|------|-------------|
-| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) |
-| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) |
-
-## Open Questions
-
-- [ ] {unresolved question 1}
-- [ ] {unresolved question 2}
-
-## References
-
-- Derived from: [Product Brief](../product-brief.md)
-- Next: [Architecture](../architecture/_index.md)
-```
-
----
-
-## Template: REQ-NNN-{slug}.md (Individual Functional Requirement)
-
-```markdown
----
-id: REQ-{NNN}
-type: functional
-priority: {Must|Should|Could|Won't}
-traces_to: [G-{NNN}]
-status: draft
----
-
-# REQ-{NNN}: {requirement_title}
-
-**Priority**: {Must|Should|Could|Won't}
-
-## Description
-
-{detailed requirement description}
-
-## User Story
-
-As a {persona}, I want to {action} so that {benefit}.
-
-## Acceptance Criteria
-
-- [ ] {specific, testable criterion 1}
-- [ ] {specific, testable criterion 2}
-- [ ] {specific, testable criterion 3}
-
-## Traces
-
-- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
-- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
-- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
-```
-
----
-
-## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement)
-
-```markdown
----
-id: NFR-{type}-{NNN}
-type: non-functional
-category: {Performance|Security|Scalability|Usability}
-priority: {Must|Should|Could}
-status: draft
----
-
-# NFR-{type}-{NNN}: {requirement_title}
-
-**Category**: {Performance|Security|Scalability|Usability}
-**Priority**: {Must|Should|Could}
-
-## Requirement
-
-{detailed requirement description}
-
-## Metric & Target
-
-| Metric | Target | Measurement Method |
-|--------|--------|--------------------|
-| {metric} | {target value} | {how measured} |
-
-## Traces
-
-- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
-- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
-```
-
----
-
-## Variable Descriptions
-
-| Variable | Source | Description |
-|----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
-| `{timestamp}` | Runtime | ISO8601 generation timestamp |
-| `{product_name}` | product-brief.md | Product/feature name |
-| `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |
-| `{slug}` | Auto-generated | Kebab-case from requirement title |
-| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) |
-| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag |
+# Requirements PRD Template (Directory Structure)
+
+Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion |
+| Output Location | `{workDir}/requirements/` |
+
+## Output Structure
+
+```
+{workDir}/requirements/
+├── _index.md                      # Summary + MoSCoW table + traceability matrix + links
+├── REQ-001-{slug}.md              # Individual functional requirement
+├── REQ-002-{slug}.md
+├── NFR-P-001-{slug}.md            # Non-functional: Performance
+├── NFR-S-001-{slug}.md            # Non-functional: Security
+├── NFR-SC-001-{slug}.md           # Non-functional: Scalability
+├── NFR-U-001-{slug}.md            # Non-functional: Usability
+└── ...
+```
+
+---
+
+## Template: _index.md
+
+```markdown
+---
+session_id: {session_id}
+phase: 3
+document_type: requirements-index
+status: draft
+generated_at: {timestamp}
+version: 1
+dependencies:
+  - ../spec-config.json
+  - ../product-brief.md
+---
+
+# Requirements: {product_name}
+
+{executive_summary - brief overview of what this PRD covers and key decisions}
+
+## Requirement Summary
+
+| Priority | Count | Coverage |
+|----------|-------|----------|
+| Must Have | {n} | {description of must-have scope} |
+| Should Have | {n} | {description of should-have scope} |
+| Could Have | {n} | {description of could-have scope} |
+| Won't Have | {n} | {description of explicitly excluded} |
+
+## Functional Requirements
+
+| ID | Title | Priority | Traces To |
+|----|-------|----------|-----------|
+| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
+| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
+| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) |
+
+## Non-Functional Requirements
+
+### Performance
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} |
+
+### Security
+
+| ID | Title | Standard |
+|----|-------|----------|
+| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} |
+
+### Scalability
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} |
+
+### Usability
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} |
+
+## Data Requirements
+
+### Data Entities
+
+| Entity | Description | Key Attributes |
+|--------|-------------|----------------|
+| {entity_name} | {description} | {attr1, attr2, attr3} |
+
+### Data Flows
+
+{description of key data flows, optionally with Mermaid diagram}
+
+## Integration Requirements
+
+| System | Direction | Protocol | Data Format | Notes |
+|--------|-----------|----------|-------------|-------|
+| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} |
+
+## Constraints & Assumptions
+
+### Constraints
+- {technical or business constraint 1}
+- {technical or business constraint 2}
+
+### Assumptions
+- {assumption 1 - must be validated}
+- {assumption 2 - must be validated}
+
+## Priority Rationale
+
+{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries}
+
+## Traceability Matrix
+
+| Goal | Requirements |
+|------|-------------|
+| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) |
+| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) |
+
+## Open Questions
+
+- [ ] {unresolved question 1}
+- [ ] {unresolved question 2}
+
+## References
+
+- Derived from: [Product Brief](../product-brief.md)
+- Next: [Architecture](../architecture/_index.md)
+```
+
+---
+
+## Template: REQ-NNN-{slug}.md (Individual Functional Requirement)
+
+```markdown
+---
+id: REQ-{NNN}
+type: functional
+priority: {Must|Should|Could|Won't}
+traces_to: [G-{NNN}]
+status: draft
+---
+
+# REQ-{NNN}: {requirement_title}
+
+**Priority**: {Must|Should|Could|Won't}
+
+## Description
+
+{detailed requirement description}
+
+## User Story
+
+As a {persona}, I want to {action} so that {benefit}.
+
+## Acceptance Criteria
+
+- [ ] {specific, testable criterion 1}
+- [ ] {specific, testable criterion 2}
+- [ ] {specific, testable criterion 3}
+
+## Traces
+
+- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
+- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
+- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
+```
+
+---
+
+## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement)
+
+```markdown
+---
+id: NFR-{type}-{NNN}
+type: non-functional
+category: {Performance|Security|Scalability|Usability}
+priority: {Must|Should|Could}
+status: draft
+---
+
+# NFR-{type}-{NNN}: {requirement_title}
+
+**Category**: {Performance|Security|Scalability|Usability}
+**Priority**: {Must|Should|Could}
+
+## Requirement
+
+{detailed requirement description}
+
+## Metric & Target
+
+| Metric | Target | Measurement Method |
+|--------|--------|--------------------|
+| {metric} | {target value} | {how measured} |
+
+## Traces
+
+- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
+- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
+```
+
+---
+
+## Variable Descriptions
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{session_id}` | spec-config.json | Session identifier |
+| `{timestamp}` | Runtime | ISO8601 generation timestamp |
+| `{product_name}` | product-brief.md | Product/feature name |
+| `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |
+| `{slug}` | Auto-generated | Kebab-case from requirement title |
+| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) |
+| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag |

package/.codex/skills/team-perf-opt/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-perf-opt
 description: Unified team skill for performance optimization. Coordinator orchestrates pipeline, workers are team-worker agents. Supports single/fan-out/independent parallel modes. Triggers on "team perf-opt".
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
 ---
 
 # Team Performance Optimization
@@ -65,7 +65,8 @@ Before calling ANY tool, apply this check:
 
 | Tool Call | Verdict | Reason |
 |-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_input` | ALLOWED | Orchestration |
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `list_agents` | ALLOWED | Agent health check |
 | `request_user_input` | ALLOWED | User interaction |
 | `mcp__ccw-tools__team_msg` | ALLOWED | Message bus |
 | `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
@@ -96,6 +97,8 @@ Coordinator spawns workers using this template:
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -119,11 +122,37 @@ pipeline_phase: <pipeline-phase>` },
 })
 ```
 
-After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
+After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
 
 **Inner Loop roles** (optimizer): Set `inner_loop: true`.
 **Single-task roles** (profiler, strategist, benchmarker, reviewer): Set `inner_loop: false`.
 
+
+### Model Selection Guide
+
+Performance optimization is measurement-driven. Profiler and benchmarker need consistent context for before/after comparison.
+
+| Role | reasoning_effort | Rationale |
+|------|-------------------|-----------|
+| profiler | high | Must identify subtle bottlenecks from profiling data |
+| strategist | high | Optimization strategy requires understanding tradeoffs |
+| optimizer | high | Performance-critical code changes need precision |
+| benchmarker | medium | Benchmark execution follows defined measurement plan |
+| reviewer | high | Must verify optimizations don't introduce regressions |
+
+### Benchmark Context Sharing with fork_context
+
+For before/after comparison, benchmarker should share context with profiler's baseline:
+```
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "BENCH-001",
+  fork_context: true,   // Share context so benchmarker sees profiler's baseline metrics
+  reasoning_effort: "medium",
+  items: [...]
+})
+```
+
 ## User Commands
 
 | Command | Action |
@@ -155,6 +184,42 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 +-- .msg/meta.json                  # Session metadata
 ```
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Queue supplementary info (don't interrupt) | `send_message` | Send baseline metrics to running optimizer |
+| Assign fix after benchmark regression | `assign_task` | Assign FIX task when benchmark shows regression |
+| Check running agents | `list_agents` | Verify agent health during resume |
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with session.json active tasks
+// Reset orphaned tasks (in_progress but agent gone) to pending
+```
+
+### Named Agent Targeting
+
+Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
+- `send_message({ target: "IMPL-001", items: [...] })` -- send strategy details to optimizer
+- `assign_task({ target: "IMPL-001", items: [...] })` -- assign fix after benchmark regression
+- `close_agent({ target: "BENCH-001" })` -- cleanup after benchmarking completes
+
+### Baseline-to-Result Pipeline
+
+Profiler baseline metrics flow through the pipeline and must reach benchmarker for comparison:
+1. PROFILE-001 produces `baseline-metrics.json` in artifacts/
+2. Coordinator includes baseline reference in upstream context for all downstream workers
+3. BENCH-001 reads baseline and compares against post-optimization measurements
+4. If regression detected, coordinator auto-creates FIX task with regression details
+
 ## Completion Action
 
 When the pipeline completes: