claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-executor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-executor
 description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "Team Executor".
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+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(*)
 ---
 
 # Team Executor
@@ -109,6 +109,8 @@ When executor spawns workers, use `team-worker` agent with role-spec path:
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -132,10 +134,35 @@ 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: <name> })` each worker.
 
 ---
 
+
+### Model Selection Guide
+
+team-executor loads roles dynamically from session role-specs. Use reasoning_effort based on the role type defined in the session:
+- Implementation/fix roles: `reasoning_effort: "high"`
+- Verification/test roles: `reasoning_effort: "medium"`
+- Default when role type is unclear: `reasoning_effort: "high"`
+
+## v4 Agent Coordination
+
+### State Reconciliation
+
+On resume, executor reconciles session state with actual running agents:
+```
+const running = list_agents({})
+// Compare with session's task-analysis.json active tasks
+// Reset orphaned tasks (in_progress but agent gone) to pending
+```
+
+### Worker Communication
+
+- `send_message({ target: "<task-id>", items: [...] })` -- queue supplementary context
+- `assign_task({ target: "<task-id>", items: [...] })` -- assign new work to inner_loop worker
+- `close_agent({ target: "<task-id>" })` -- cleanup completed worker
+
 ## Completion Action
 
 When pipeline completes (all tasks done), executor presents an interactive choice:

package/.codex/skills/team-executor/roles/executor/commands/monitor.md

@@ -167,22 +167,30 @@ After spawning all ready tasks:
 const agentIds = Object.values(state.active_agents)
   .filter(a => !a.resident)
   .map(a => a.agentId)
-wait_agent({ ids: agentIds, timeout_ms: 900000 })
-
-// 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].error = disc.error || null
-  } catch {
-    state.tasks[taskId].status = 'failed'
-    state.tasks[taskId].error = 'No discovery file produced'
+const waitResult = wait_agent({ targets: agentIds, timeout_ms: 900000 })
+if (waitResult.timed_out) {
+  for (const [taskId, agent] of Object.entries(state.active_agents)) {
+    if (agent.resident) continue
+    state.tasks[taskId].status = 'timed_out'
+    close_agent({ target: agent.agentId })
+    delete state.active_agents[taskId]
+  }
+} else {
+  // 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].error = disc.error || null
+    } catch {
+      state.tasks[taskId].status = 'failed'
+      state.tasks[taskId].error = 'No discovery file produced'
+    }
+    close_agent({ target: agent.agentId })
+    delete state.active_agents[taskId]
   }
-  close_agent({ id: agent.agentId })
-  delete state.active_agents[taskId]
 }
 ```
 

package/.codex/skills/team-frontend/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-frontend
 description: Unified team skill for frontend development. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend".
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), WebFetch(*), WebSearch(*), 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(*), WebFetch(*), WebSearch(*), mcp__ace-tool__search_context(*)
 ---
 
 # Team Frontend Development
@@ -54,7 +54,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 |
@@ -84,6 +85,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>
@@ -107,7 +110,29 @@ 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.
+
+
+### Model Selection Guide
+
+| Role | model | reasoning_effort | Rationale |
+|------|-------|-------------------|-----------|
+| Analyst (ANALYZE-*) | (default) | high | Design intelligence requires deep UI/UX reasoning |
+| Architect (ARCH-*) | (default) | high | Component spec and design token generation needs precision |
+| Developer (DEV-*) | (default) | high | Frontend code generation needs full reasoning |
+| QA (QA-*) | (default) | high | 5-dimension audit requires thorough analysis |
+
+Override model/reasoning_effort in spawn_agent when cost optimization is needed:
+```
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
+  model: "<model-override>",
+  reasoning_effort: "<effort-level>",
+  items: [...]
+})
+```
 
 ## User Commands
 
@@ -141,6 +166,55 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 
 - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Send architecture specs to running developer | `send_message` | Queue design tokens and component specs to DEV-* |
+| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot |
+| Check running agents | `list_agents` | Verify agent health during resume |
+
+### Pipeline Pattern
+
+Sequential pipeline with GC loops: analyst -> architect -> developer -> QA. In **system mode**, architect revision (ARCH-002) and developer (DEV-001) may run in parallel after QA-001 arch review.
+
+### fork_context Consideration
+
+Developer workers (DEV-*) benefit from `fork_context: true` when the coordinator has accumulated significant design context (analysis results, architecture specs, design tokens). This avoids the developer needing to re-read all upstream artifacts:
+
+```
+// Consider fork_context: true for developer in feature/system modes
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "DEV-001",
+  fork_context: true,  // Developer gets full coordinator context including design decisions
+  items: [...]
+})
+```
+
+### GC Loop (QA Fix Cycle)
+
+QA may flag FIX_REQUIRED, creating DEV-fix + QA-recheck tasks (max 2 rounds). If QA score remains < 6 after 2 rounds, escalate to user.
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with tasks.json active_agents
+// 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: "DEV-001", items: [...] })` -- queue architecture specs to running developer
+- `close_agent({ target: "ARCH-001" })` -- cleanup by name after completion
+
 ## Error Handling
 
 | Scenario | Resolution |

package/.codex/skills/team-frontend/roles/analyst/role.md

@@ -1,92 +1,92 @@
----
-role: analyst
-prefix: ANALYZE
-inner_loop: false
-message_types:
-  success: analyze_ready
-  error: error
----
-
-# Requirements Analyst
-
-Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| Industry context | Extracted from task description | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | No |
-
-1. Extract session path, industry type, and tech stack from task description
-2. Detect existing design system:
-
-| Signal | Detection Method |
-|--------|-----------------|
-| Token files | Glob `**/*token*.*` |
-| CSS files | Glob `**/*.css` |
-| Package.json | Read for framework dependencies |
-
-3. Detect tech stack from package.json:
-
-| Dependency | Stack |
-|------------|-------|
-| `next` | nextjs |
-| `react` | react |
-| `vue` | vue |
-| `svelte` | svelte |
-| `@shadcn/ui` | shadcn |
-| (none) | html-tailwind |
-
-4. Load .msg/meta.json for shared state
-
-## Phase 3: Design Intelligence Retrieval
-
-Retrieve design intelligence via ui-ux-pro-max skill integration.
-
-**Step 1: Invoke ui-ux-pro-max** (primary path):
-
-| Action | Invocation |
-|--------|------------|
-| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
-| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
-| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
-
-**Step 2: Fallback** (if skill unavailable):
-- Generate design recommendations from LLM general knowledge
-- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
-
-**Step 3: Analyze existing codebase** (if token/CSS files found):
-- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
-
-**Step 4: Competitive reference** (optional, if industry is not "Other"):
-- `WebSearch({ query: "<industry> web design trends best practices" })`
-
-**Step 5: Compile design-intelligence.json**:
-
-| Field | Source |
-|-------|--------|
-| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
-| `industry` | Task description |
-| `detected_stack` | Phase 2 detection |
-| `design_system` | Skill output (colors, typography, effects) |
-| `ux_guidelines` | Skill UX domain output |
-| `stack_guidelines` | Skill stack output |
-| `recommendations` | Synthesized: style, anti-patterns, must-have |
-
-**Output files**:
-- `<session>/analysis/design-intelligence.json`
-- `<session>/analysis/requirements.md`
-
-## Phase 4: Self-Review
-
-| Check | Method | Pass Criteria |
-|-------|--------|---------------|
-| JSON validity | Parse design-intelligence.json | No parse errors |
-| Required fields | Check _source, industry, design_system | All present |
-| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
-| Requirements doc exists | File check | requirements.md written |
-
-Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.
+---
+role: analyst
+prefix: ANALYZE
+inner_loop: false
+message_types:
+  success: analyze_ready
+  error: error
+---
+
+# Requirements Analyst
+
+Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Industry context | Extracted from task description | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path, industry type, and tech stack from task description
+2. Detect existing design system:
+
+| Signal | Detection Method |
+|--------|-----------------|
+| Token files | Glob `**/*token*.*` |
+| CSS files | Glob `**/*.css` |
+| Package.json | Read for framework dependencies |
+
+3. Detect tech stack from package.json:
+
+| Dependency | Stack |
+|------------|-------|
+| `next` | nextjs |
+| `react` | react |
+| `vue` | vue |
+| `svelte` | svelte |
+| `@shadcn/ui` | shadcn |
+| (none) | html-tailwind |
+
+4. Load .msg/meta.json for shared state
+
+## Phase 3: Design Intelligence Retrieval
+
+Retrieve design intelligence via ui-ux-pro-max skill integration.
+
+**Step 1: Invoke ui-ux-pro-max** (primary path):
+
+| Action | Invocation |
+|--------|------------|
+| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
+| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
+| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
+
+**Step 2: Fallback** (if skill unavailable):
+- Generate design recommendations from LLM general knowledge
+- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
+
+**Step 3: Analyze existing codebase** (if token/CSS files found):
+- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
+
+**Step 4: Competitive reference** (optional, if industry is not "Other"):
+- `WebSearch({ query: "<industry> web design trends best practices" })`
+
+**Step 5: Compile design-intelligence.json**:
+
+| Field | Source |
+|-------|--------|
+| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
+| `industry` | Task description |
+| `detected_stack` | Phase 2 detection |
+| `design_system` | Skill output (colors, typography, effects) |
+| `ux_guidelines` | Skill UX domain output |
+| `stack_guidelines` | Skill stack output |
+| `recommendations` | Synthesized: style, anti-patterns, must-have |
+
+**Output files**:
+- `<session>/analysis/design-intelligence.json`
+- `<session>/analysis/requirements.md`
+
+## Phase 4: Self-Review
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| JSON validity | Parse design-intelligence.json | No parse errors |
+| Required fields | Check _source, industry, design_system | All present |
+| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
+| Requirements doc exists | File check | requirements.md written |
+
+Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.

package/.codex/skills/team-frontend/roles/architect/role.md

@@ -1,86 +1,86 @@
----
-role: architect
-prefix: ARCH
-inner_loop: false
-message_types:
-  success: arch_ready
-  error: error
----
-
-# Frontend Architect
-
-Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
-| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | No |
-
-1. Extract session path and scope from task description
-2. Load design intelligence from analyst output
-3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
-4. Detect existing project structure via Glob `src/**/*`
-
-**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
-
-## Phase 3: Architecture Design
-
-**Scope selection**:
-
-| Scope | Output |
-|-------|--------|
-| `tokens` | Design token system only |
-| `components` | Component specs only |
-| `full` | Both tokens and components + project structure |
-
-**Step 1: Design Token System** (scope: tokens or full):
-
-Generate `<session>/architecture/design-tokens.json` with categories:
-
-| Category | Content | Source |
-|----------|---------|--------|
-| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
-| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
-| `spacing` | xs through 2xl | Standard scale |
-| `border-radius` | sm, md, lg, full | Standard scale |
-| `shadow` | sm, md, lg | Standard elevation |
-| `transition` | fast, normal, slow | Standard durations |
-
-Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
-
-**Step 2: Component Architecture** (scope: components or full):
-
-Generate component specs in `<session>/architecture/component-specs/`:
-- Design reference (style, stack)
-- Props table (name, type, default, description)
-- Variants table
-- Accessibility requirements (role, keyboard, ARIA, contrast)
-- Anti-patterns to avoid (from design intelligence)
-
-**Step 3: Project Structure** (scope: full):
-
-Generate `<session>/architecture/project-structure.md` with stack-specific layout:
-
-| Stack | Key Directories |
-|-------|----------------|
-| react | src/components/, src/pages/, src/hooks/, src/styles/ |
-| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
-| vue | src/components/, src/views/, src/composables/, src/styles/ |
-| html-tailwind | src/components/, src/pages/, src/styles/ |
-
-## Phase 4: Self-Review
-
-| Check | Method | Pass Criteria |
-|-------|--------|---------------|
-| JSON validity | Parse design-tokens.json | No errors |
-| Required categories | Check color, typography, spacing | All present |
-| Anti-pattern compliance | Token values vs anti-patterns | No violations |
-| Component specs complete | Each has props + accessibility | All complete |
-| File existence | Verify all planned files | All present |
-
-Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.
+---
+role: architect
+prefix: ARCH
+inner_loop: false
+message_types:
+  success: arch_ready
+  error: error
+---
+
+# Frontend Architect
+
+Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
+| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path and scope from task description
+2. Load design intelligence from analyst output
+3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
+4. Detect existing project structure via Glob `src/**/*`
+
+**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
+
+## Phase 3: Architecture Design
+
+**Scope selection**:
+
+| Scope | Output |
+|-------|--------|
+| `tokens` | Design token system only |
+| `components` | Component specs only |
+| `full` | Both tokens and components + project structure |
+
+**Step 1: Design Token System** (scope: tokens or full):
+
+Generate `<session>/architecture/design-tokens.json` with categories:
+
+| Category | Content | Source |
+|----------|---------|--------|
+| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
+| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
+| `spacing` | xs through 2xl | Standard scale |
+| `border-radius` | sm, md, lg, full | Standard scale |
+| `shadow` | sm, md, lg | Standard elevation |
+| `transition` | fast, normal, slow | Standard durations |
+
+Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
+
+**Step 2: Component Architecture** (scope: components or full):
+
+Generate component specs in `<session>/architecture/component-specs/`:
+- Design reference (style, stack)
+- Props table (name, type, default, description)
+- Variants table
+- Accessibility requirements (role, keyboard, ARIA, contrast)
+- Anti-patterns to avoid (from design intelligence)
+
+**Step 3: Project Structure** (scope: full):
+
+Generate `<session>/architecture/project-structure.md` with stack-specific layout:
+
+| Stack | Key Directories |
+|-------|----------------|
+| react | src/components/, src/pages/, src/hooks/, src/styles/ |
+| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
+| vue | src/components/, src/views/, src/composables/, src/styles/ |
+| html-tailwind | src/components/, src/pages/, src/styles/ |
+
+## Phase 4: Self-Review
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| JSON validity | Parse design-tokens.json | No errors |
+| Required categories | Check color, typography, spacing | All present |
+| Anti-pattern compliance | Token values vs anti-patterns | No violations |
+| Component specs complete | Each has props + accessibility | All complete |
+| File existence | Verify all planned files | All present |
+
+Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.