feat: add MCP server for semantic code search with FastMCP integration

2026-03-18 18:48:48 +08:00 · 2026-03-17 23:03:20 +08:00
parent ef2c5a58e1
commit ad9d3f94e0
80 changed files with 3427 additions and 21329 deletions
--- a/.claude/skills/wf-composer/SKILL.md
+++ b/.claude/skills/wf-composer/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: wf-composer
+description: Semantic workflow composer — parse natural language workflow description into a DAG of skill/CLI/agent nodes, auto-inject checkpoint save nodes, confirm with user, persist as reusable JSON template. Triggers on "wf-composer " or "/wf-composer".
+argument-hint: "[workflow description]"
+allowed-tools: Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+---
+
+# Workflow Design
+
+Parse user's semantic workflow description → decompose into nodes → map to executors → auto-inject checkpoints → confirm pipeline → save as reusable `workflow-template.json`.
+
+## Architecture
+
+```
+User describes workflow in natural language
+  -> Phase 1: Parse — extract intent steps + variables
+  -> Phase 2: Resolve — map each step to executor (skill/cli/agent/command)
+  -> Phase 3: Enrich — inject checkpoint nodes, set DAG edges
+  -> Phase 4: Confirm — visualize pipeline, user approval/edit
+  -> Phase 5: Persist — save .workflow/templates/<name>.json
+```
+
+## Shared Constants
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `WFD` |
+| Template dir | `.workflow/templates/` |
+| Template ID format | `wft-<slug>-<date>` |
+| Node ID format | `N-<seq>` (e.g. N-001), `CP-<seq>` for checkpoints |
+| Max nodes | 20 |
+
+## Entry Router
+
+Parse `$ARGUMENTS`.
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Resume design | `--resume` flag or existing WFD session | -> Phase 0: Resume |
+| Edit template | `--edit <template-id>` flag | -> Phase 0: Load + Edit |
+| New design | Default | -> Phase 1: Parse |
+
+## Phase 0: Resume / Edit (optional)
+
+**Resume design session**:
+1. Scan `.workflow/templates/design-drafts/WFD-*.json` for in-progress designs
+2. Multiple found → AskUserQuestion for selection
+3. Load draft → skip to last incomplete phase
+
+**Edit existing template**:
+1. Load template from `--edit` path
+2. Show current pipeline visualization
+3. AskUserQuestion: which nodes to modify/add/remove
+4. Re-enter at Phase 3 (Enrich) with edits applied
+
+---
+
+## Phase 1: Parse
+
+Read `phases/01-parse.md` and execute.
+
+**Objective**: Extract structured semantic steps + context variables from natural language.
+
+**Success**: `design-session/intent.json` written with: steps[], variables[], task_type, complexity.
+
+---
+
+## Phase 2: Resolve
+
+Read `phases/02-resolve.md` and execute.
+
+**Objective**: Map each intent step to a concrete executor node.
+
+**Executor types**:
+- `skill` — invoke via `Skill(skill=..., args=...)`
+- `cli` — invoke via `ccw cli -p "..." --tool ... --mode ...`
+- `command` — invoke via `Skill(skill="<namespace:command>", args=...)`
+- `agent` — invoke via `Agent(subagent_type=..., prompt=...)`
+- `checkpoint` — state save + optional user pause
+
+**Success**: `design-session/nodes.json` written with resolved executor for each step.
+
+---
+
+## Phase 3: Enrich
+
+Read `phases/03-enrich.md` and execute.
+
+**Objective**: Build DAG edges, auto-inject checkpoints at phase boundaries, validate port compatibility.
+
+**Checkpoint injection rules**:
+- After every `skill` → `skill` transition that crosses a semantic phase boundary
+- Before any long-running `agent` spawn
+- After any node that produces a persistent artifact (plan, spec, analysis)
+- At user-defined breakpoints (if any)
+
+**Success**: `design-session/dag.json` with nodes[], edges[], checkpoints[], context_schema{}.
+
+---
+
+## Phase 4: Confirm
+
+Read `phases/04-confirm.md` and execute.
+
+**Objective**: Visualize the pipeline, present to user, incorporate edits.
+
+**Display format**:
+```
+Pipeline: <template-name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+N-001 [skill]      workflow-lite-plan       "{goal}"
+  |
+CP-01 [checkpoint] After Plan               auto-continue
+  |
+N-002 [skill]      workflow-test-fix        "--session N-001"
+  |
+CP-02 [checkpoint] After Tests              pause-for-user
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Variables: goal (required)
+Checkpoints: 2 (1 auto, 1 pause)
+```
+
+AskUserQuestion:
+- Confirm & Save
+- Edit node (select node ID)
+- Add node after (select position)
+- Remove node (select node ID)
+- Rename template
+
+**Success**: User confirmed pipeline. Final dag.json ready.
+
+---
+
+## Phase 5: Persist
+
+Read `phases/05-persist.md` and execute.
+
+**Objective**: Assemble final template JSON, write to template library, output summary.
+
+**Output**:
+- `.workflow/templates/<slug>.json` — the reusable template
+- Console summary with template path + usage command
+
+**Success**: Template saved. User shown: `Skill(skill="wf-player", args="<template-path>")`
+
+---
+
+## Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/node-catalog.md](specs/node-catalog.md) | Available executors, port definitions, arg templates |
+| [specs/template-schema.md](specs/template-schema.md) | Full JSON template schema |
--- a/.claude/skills/wf-composer/phases/01-parse.md
+++ b/.claude/skills/wf-composer/phases/01-parse.md
@@ -0,0 +1,93 @@
+# Phase 1: Parse — Semantic Intent Extraction
+
+## Objective
+
+Extract structured semantic steps and context variables from the user's natural language workflow description.
+
+## Workflow
+
+### Step 1.1 — Read Input
+
+Parse `$ARGUMENTS` as the workflow description. If empty or ambiguous, AskUserQuestion:
+- "Describe the workflow you want to automate. Include: what steps to run, in what order, and what varies each time (inputs)."
+
+### Step 1.2 — Extract Steps
+
+Scan the description for sequential actions. Each action becomes a candidate node.
+
+**Signal patterns** (not exhaustive — apply NL understanding):
+
+| Signal | Candidate Node Type |
+|--------|---------------------|
+| "analyze", "review", "explore" | analysis step (cli --mode analysis) |
+| "plan", "design", "spec" | planning step (skill: workflow-lite-plan / workflow-plan) |
+| "implement", "build", "code", "fix", "refactor" | execution step (skill: workflow-execute) |
+| "test", "validate", "verify" | testing step (skill: workflow-test-fix) |
+| "brainstorm", "ideate" | brainstorm step (skill: brainstorm / brainstorm-with-file) |
+| "review code", "code review" | review step (skill: review-cycle) |
+| "save", "checkpoint", "pause" | explicit checkpoint node |
+| "spawn agent", "delegate", "subagent" | agent node |
+| "then", "next", "after", "finally" | sequential edge signal |
+| "parallel", "simultaneously", "at the same time" | parallel edge signal |
+
+### Step 1.3 — Extract Variables
+
+Identify inputs that vary per run. These become `context_schema` entries.
+
+**Variable detection**:
+- Direct mentions: "the goal", "the target", "my task", "user-provided X"
+- Parameterized slots: `{goal}`, `[feature]`, `<scope>` patterns in the description
+- Implicit from task type: any "feature/bugfix/topic" is `goal`
+
+For each variable: assign name, type (string|path|boolean), required flag, description.
+
+### Step 1.4 — Detect Task Type
+
+Use ccw-coordinator task detection logic to classify the overall workflow:
+
+```
+bugfix | feature | tdd | review | brainstorm | spec-driven | roadmap |
+refactor | integration-test | greenfield | quick-task | custom
+```
+
+`custom` = user describes a non-standard combination.
+
+### Step 1.5 — Complexity Assessment
+
+Count nodes, detect parallel tracks, identify dependencies:
+- `simple` = 1-3 nodes, linear
+- `medium` = 4-7 nodes, at most 1 parallel track
+- `complex` = 8+ nodes or multiple parallel tracks
+
+### Step 1.6 — Write Output
+
+Create session dir: `.workflow/templates/design-drafts/WFD-<slug>-<date>/`
+
+Write `intent.json`:
+```json
+{
+  "session_id": "WFD-<slug>-<date>",
+  "raw_description": "<original user input>",
+  "task_type": "<detected type>",
+  "complexity": "simple|medium|complex",
+  "steps": [
+    {
+      "seq": 1,
+      "description": "<extracted step description>",
+      "type_hint": "analysis|planning|execution|testing|review|checkpoint|agent|cli",
+      "parallel_with": null,
+      "variables": ["goal"]
+    }
+  ],
+  "variables": {
+    "goal": { "type": "string", "required": true, "description": "<inferred description>" }
+  },
+  "created_at": "<ISO timestamp>"
+}
+```
+
+## Success Criteria
+
+- `intent.json` exists with at least 1 step
+- All referenced variables extracted to `variables` map
+- task_type and complexity assigned
--- a/.claude/skills/wf-composer/phases/02-resolve.md
+++ b/.claude/skills/wf-composer/phases/02-resolve.md
@@ -0,0 +1,89 @@
+# Phase 2: Resolve — Map Steps to Executor Nodes
+
+## Objective
+
+Map each intent step from `intent.json` into a concrete executor node with assigned type, executor, and arg template.
+
+## Workflow
+
+### Step 2.1 — Load Intent
+
+Read `design-session/intent.json`. Load steps[], variables{}.
+
+### Step 2.2 — Map Each Step to Executor
+
+For each step, determine the executor node using the Node Catalog (`specs/node-catalog.md`).
+
+**Resolution algorithm**:
+1. Match `type_hint` to executor candidates in catalog
+2. If multiple candidates, select by semantic fit to step description
+3. If no catalog match, emit `cli` node with inferred `--rule` and `--mode`
+
+**Node type assignment**:
+
+| Step type_hint | Default executor type | Default executor |
+|----------------|----------------------|------------------|
+| `planning` | skill | `workflow-lite-plan` (simple/medium) or `workflow-plan` (complex) |
+| `execution` | skill | `workflow-execute` |
+| `testing` | skill | `workflow-test-fix` |
+| `review` | skill | `review-cycle` |
+| `brainstorm` | skill | `brainstorm` |
+| `analysis` | cli | `ccw cli --tool gemini --mode analysis` |
+| `spec` | skill | `spec-generator` |
+| `tdd` | skill | `workflow-tdd-plan` |
+| `refactor` | command | `workflow:refactor-cycle` |
+| `integration-test` | command | `workflow:integration-test-cycle` |
+| `agent` | agent | (infer subagent_type from description) |
+| `checkpoint` | checkpoint | — |
+
+### Step 2.3 — Build Arg Templates
+
+For each node, build `args_template` by substituting variable references:
+
+```
+skill node:   args_template = `{goal}`  (or `--session {prev_session}`)
+cli node:     args_template = `PURPOSE: {goal}\nTASK: ...\nMODE: analysis\nCONTEXT: @**/*`
+agent node:   args_template = `{goal}\nContext: {prev_output}`
+```
+
+**Context injection rules**:
+- Planning nodes that follow analysis: inject `--context {prev_output_path}`
+- Execution nodes that follow planning: inject `--resume-session {prev_session_id}`
+- Testing nodes that follow execution: inject `--session {prev_session_id}`
+
+Use `{prev_session_id}` and `{prev_output_path}` as runtime-resolved references — the executor will substitute these from node state at run time.
+
+### Step 2.4 — Assign Parallel Groups
+
+For steps with `parallel_with` set:
+- Assign same `parallel_group` string to both nodes
+- Parallel nodes share no data dependency (each gets same input)
+
+### Step 2.5 — Write Output
+
+Write `design-session/nodes.json`:
+```json
+{
+  "session_id": "<WFD-id>",
+  "nodes": [
+    {
+      "id": "N-001",
+      "seq": 1,
+      "name": "<step description shortened>",
+      "type": "skill|cli|command|agent|checkpoint",
+      "executor": "<skill name | cli command | agent subagent_type>",
+      "args_template": "<template string with {variable} placeholders>",
+      "input_ports": ["<port>"],
+      "output_ports": ["<port>"],
+      "parallel_group": null,
+      "on_fail": "abort"
+    }
+  ]
+}
+```
+
+## Success Criteria
+
+- Every intent step has a corresponding node in nodes.json
+- Every node has a non-empty executor and args_template
+- Parallel groups correctly assigned where step.parallel_with is set
--- a/.claude/skills/wf-composer/phases/03-enrich.md
+++ b/.claude/skills/wf-composer/phases/03-enrich.md
@@ -0,0 +1,104 @@
+# Phase 3: Enrich — Inject Checkpoints + Build DAG
+
+## Objective
+
+Build the directed acyclic graph (DAG) with proper edges, auto-inject checkpoint nodes at phase boundaries, and finalize the context_schema.
+
+## Workflow
+
+### Step 3.1 — Load Nodes
+
+Read `design-session/nodes.json`. Get nodes[] list.
+
+### Step 3.2 — Build Sequential Edges
+
+Start with a linear chain: N-001 → N-002 → N-003 → ...
+
+For nodes with the same `parallel_group`:
+- Remove edges between them
+- Add fan-out from the last non-parallel node to all group members
+- Add fan-in from all group members to the next non-parallel node
+
+### Step 3.3 — Auto-Inject Checkpoint Nodes
+
+Scan the edge list and inject a `checkpoint` node between edges that cross a phase boundary.
+
+**Phase boundary detection rules** (inject checkpoint if ANY rule triggers):
+
+| Rule | Condition |
+|------|-----------|
+| **Artifact boundary** | Source node has output_ports containing `plan`, `spec`, `analysis`, `review-findings` |
+| **Execution gate** | Target node type is `skill` with executor containing `execute` |
+| **Agent spawn** | Target node type is `agent` |
+| **Long-running** | Target node executor is `workflow-plan`, `spec-generator`, `collaborative-plan-with-file` |
+| **User-defined** | Intent step had `type_hint: checkpoint` |
+| **Post-testing** | Source node executor contains `test-fix` or `integration-test` |
+
+**Checkpoint node template**:
+```json
+{
+  "id": "CP-<seq>",
+  "name": "Checkpoint: <description>",
+  "type": "checkpoint",
+  "description": "<what was just completed>",
+  "auto_continue": true,
+  "save_fields": ["session_id", "artifacts", "output_path"]
+}
+```
+
+Set `auto_continue: false` for checkpoints that:
+- Precede a user-facing deliverable (spec, plan, review report)
+- Are explicitly requested by the user ("pause and show me")
+
+### Step 3.4 — Insert Checkpoint Edges
+
+For each injected checkpoint CP-X between edge (A → B):
+- Remove edge A → B
+- Add edges: A → CP-X, CP-X → B
+
+### Step 3.5 — Finalize context_schema
+
+Aggregate all `{variable}` references found in nodes' args_template strings.
+
+For each unique variable name found:
+- Look up from `intent.json#variables` if already defined
+- Otherwise infer: type=string, required=true, description="<variable name>"
+
+Produce final `context_schema{}` map.
+
+### Step 3.6 — Validate DAG
+
+Check:
+- No cycles (topological sort must succeed)
+- No orphan nodes (every node reachable from start)
+- Every non-start node has at least one incoming edge
+- Every non-terminal node has at least one outgoing edge
+
+On cycle detection: report error, ask user to resolve.
+
+### Step 3.7 — Write Output
+
+Write `design-session/dag.json`:
+```json
+{
+  "session_id": "<WFD-id>",
+  "nodes": [ /* all nodes including injected checkpoints */ ],
+  "edges": [
+    { "from": "N-001", "to": "CP-01" },
+    { "from": "CP-01", "to": "N-002" }
+  ],
+  "checkpoints": ["CP-01", "CP-02"],
+  "parallel_groups": { "<group-name>": ["N-003", "N-004"] },
+  "context_schema": {
+    "goal": { "type": "string", "required": true, "description": "..." }
+  },
+  "topological_order": ["N-001", "CP-01", "N-002"]
+}
+```
+
+## Success Criteria
+
+- dag.json exists and is valid (no cycles)
+- At least one checkpoint exists (or user explicitly opted out)
+- context_schema contains all variables referenced in args_templates
+- topological_order covers all nodes
--- a/.claude/skills/wf-composer/phases/04-confirm.md
+++ b/.claude/skills/wf-composer/phases/04-confirm.md
@@ -0,0 +1,97 @@
+# Phase 4: Confirm — Visualize + User Approval
+
+## Objective
+
+Render the pipeline as an ASCII diagram, present to user for confirmation and optional edits.
+
+## Workflow
+
+### Step 4.1 — Render Pipeline
+
+Load `design-session/dag.json`. Render in topological order:
+
+```
+Pipeline: <template-name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ N-001  [skill]       workflow-lite-plan         "{goal}"
+   |
+ CP-01  [checkpoint]  After Plan                 auto-continue
+   |
+ N-002  [skill]       workflow-execute            --resume {N-001.session_id}
+   |
+ CP-02  [checkpoint]  Before Review              pause-for-user
+   |
+ N-003  [skill]       review-cycle               --session {N-002.session_id}
+   |
+ N-004  [skill]       workflow-test-fix           --session {N-002.session_id}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Variables (required):  goal
+Checkpoints:           2  (1 auto-continue, 1 pause-for-user)
+Nodes:                 4 work + 2 checkpoints
+```
+
+For parallel groups, show fan-out/fan-in:
+```
+ N-003a [skill]  review-cycle    ─┐
+                                   ├─ N-004 [skill] workflow-test-fix
+ N-003b [cli]    gemini analysis  ─┘
+```
+
+### Step 4.2 — Ask User
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Review the workflow pipeline above.",
+    header: "Confirm Pipeline",
+    options: [
+      { label: "Confirm & Save", description: "Save as reusable template" },
+      { label: "Edit a node", description: "Modify executor or args of a specific node" },
+      { label: "Add a node", description: "Insert a new step at a position" },
+      { label: "Remove a node", description: "Delete a step from the pipeline" },
+      { label: "Rename template", description: "Change the template name" },
+      { label: "Re-run checkpoint injection", description: "Reset and re-inject checkpoints" },
+      { label: "Cancel", description: "Discard and exit" }
+    ]
+  }]
+})
+```
+
+### Step 4.3 — Handle Edit Actions
+
+**Edit a node**:
+- AskUserQuestion: "Which node ID to edit?" → show fields → apply change
+- Re-render pipeline and re-ask
+
+**Add a node**:
+- AskUserQuestion: "Insert after which node ID?" + "Describe the new step"
+- Re-run Phase 2 (resolve) for the new step description
+- Insert new node + update edges
+- Re-run Phase 3 (enrich) for checkpoint injection
+- Re-render and re-ask
+
+**Remove a node**:
+- AskUserQuestion: "Which node ID to remove?"
+- If node is a checkpoint: also remove it, re-wire edges
+- If node is a work node: re-wire edges, re-run checkpoint injection
+- Re-render and re-ask
+
+**Rename template**:
+- AskUserQuestion: "New template name?"
+- Update slug for template_id
+
+### Step 4.4 — Finalize
+
+On "Confirm & Save":
+- Freeze dag.json (mark as confirmed)
+- Proceed to Phase 5
+
+On "Cancel":
+- Save draft to `design-session/dag-draft.json`
+- Output: "Draft saved. Resume with: Skill(skill='wf-composer', args='--resume <session-id>')"
+- Exit
+
+## Success Criteria
+
+- User selected "Confirm & Save"
+- dag.json frozen with all user edits applied
--- a/.claude/skills/wf-composer/phases/05-persist.md
+++ b/.claude/skills/wf-composer/phases/05-persist.md
@@ -0,0 +1,107 @@
+# Phase 5: Persist — Assemble + Save Template
+
+## Objective
+
+Assemble the final workflow template JSON from design session data, write to template library, output usage instructions.
+
+## Workflow
+
+### Step 5.1 — Load Design Session
+
+Read:
+- `design-session/intent.json` → template metadata
+- `design-session/dag.json` → nodes, edges, checkpoints, context_schema
+
+### Step 5.2 — Determine Template Name + Path
+
+**Name**: Use user's confirmed name from Phase 4. If not set, derive from intent.task_type + first 3 meaningful words of raw_description.
+
+**Slug**: kebab-case from name (e.g. "Feature TDD with Review" → "feature-tdd-with-review")
+
+**Path**: `.workflow/templates/<slug>.json`
+
+**template_id**: `wft-<slug>-<YYYYMMDD>`
+
+Check for existing file:
+- If exists and different content: append `-v2`, `-v3`, etc.
+- If exists and identical: skip write, output "Template already exists"
+
+### Step 5.3 — Assemble Template JSON
+
+See `specs/template-schema.md` for full schema. Assemble:
+
+```json
+{
+  "template_id": "wft-<slug>-<date>",
+  "name": "<human name>",
+  "description": "<raw_description truncated to 120 chars>",
+  "version": "1.0",
+  "created_at": "<ISO timestamp>",
+  "source_session": "<WFD-id>",
+  "tags": ["<task_type>", "<complexity>"],
+  "context_schema": { /* from dag.json */ },
+  "nodes": [ /* from dag.json, full node objects */ ],
+  "edges": [ /* from dag.json */ ],
+  "checkpoints": [ /* checkpoint node IDs */ ],
+  "atomic_groups": [ /* from intent.json parallel groups */ ],
+  "execution_mode": "serial",
+  "metadata": {
+    "node_count": <n>,
+    "checkpoint_count": <n>,
+    "estimated_duration": "<rough estimate based on node types>"
+  }
+}
+```
+
+### Step 5.4 — Write Template
+
+Write assembled JSON to `.workflow/templates/<slug>.json`.
+
+Ensure `.workflow/templates/` directory exists (create if not).
+
+### Step 5.5 — Update Template Index
+
+Read/create `.workflow/templates/index.json`:
+```json
+{
+  "templates": [
+    {
+      "template_id": "wft-<slug>-<date>",
+      "name": "<name>",
+      "path": ".workflow/templates/<slug>.json",
+      "tags": ["<task_type>"],
+      "created_at": "<ISO>",
+      "node_count": <n>
+    }
+  ]
+}
+```
+Append or update entry for this template. Write back.
+
+### Step 5.6 — Output Summary
+
+```
+Template saved: .workflow/templates/<slug>.json
+  ID:          wft-<slug>-<date>
+  Nodes:       <n> work nodes + <n> checkpoints
+  Variables:   <comma-separated required vars>
+
+To execute:
+  Skill(skill="wf-player", args="<slug> --context goal='<your goal>'")
+
+To edit later:
+  Skill(skill="wf-composer", args="--edit .workflow/templates/<slug>.json")
+
+To list all templates:
+  Skill(skill="wf-player", args="--list")
+```
+
+### Step 5.7 — Clean Up Draft
+
+Delete `design-session/` directory (or move to `.workflow/templates/design-drafts/archive/`).
+
+## Success Criteria
+
+- `.workflow/templates/<slug>.json` exists and is valid JSON
+- `index.json` updated with new entry
+- Console shows template path + usage command
--- a/.claude/skills/wf-composer/specs/node-catalog.md
+++ b/.claude/skills/wf-composer/specs/node-catalog.md
@@ -0,0 +1,96 @@
+# Node Catalog — Available Executors
+
+All executors available for node resolution in Phase 2.
+
+## Skill Nodes
+
+| Executor | Type | Input Ports | Output Ports | Typical Args Template |
+|----------|------|-------------|--------------|----------------------|
+| `workflow-lite-plan` | skill | requirement | plan | `"{goal}"` |
+| `workflow-plan` | skill | requirement, specification | detailed-plan | `"{goal}"` |
+| `workflow-execute` | skill | detailed-plan, verified-plan | code | `--resume-session {prev_session_id}` |
+| `workflow-test-fix` | skill | failing-tests, code | test-passed | `--session {prev_session_id}` |
+| `workflow-tdd-plan` | skill | requirement | tdd-tasks | `"{goal}"` |
+| `workflow-multi-cli-plan` | skill | requirement | multi-cli-plan | `"{goal}"` |
+| `review-cycle` | skill | code, session | review-findings | `--session {prev_session_id}` |
+| `brainstorm` | skill | exploration-topic | brainstorm-analysis | `"{goal}"` |
+| `spec-generator` | skill | requirement | specification | `"{goal}"` |
+
+## Command Nodes (namespace skills)
+
+| Executor | Type | Input Ports | Output Ports | Typical Args Template |
+|----------|------|-------------|--------------|----------------------|
+| `workflow:refactor-cycle` | command | codebase | refactored-code | `"{goal}"` |
+| `workflow:integration-test-cycle` | command | requirement | test-passed | `"{goal}"` |
+| `workflow:brainstorm-with-file` | command | exploration-topic | brainstorm-document | `"{goal}"` |
+| `workflow:analyze-with-file` | command | analysis-topic | discussion-document | `"{goal}"` |
+| `workflow:debug-with-file` | command | bug-report | understanding-document | `"{goal}"` |
+| `workflow:collaborative-plan-with-file` | command | requirement | plan-note | `"{goal}"` |
+| `workflow:roadmap-with-file` | command | requirement | execution-plan | `"{goal}"` |
+| `workflow:unified-execute-with-file` | command | plan-note, discussion-document | code | (no args — reads from session) |
+| `issue:discover` | command | codebase | pending-issues | (no args) |
+| `issue:plan` | command | pending-issues | issue-plans | `--all-pending` |
+| `issue:queue` | command | issue-plans | execution-queue | (no args) |
+| `issue:execute` | command | execution-queue | completed-issues | `--queue auto` |
+| `issue:convert-to-plan` | command | plan | converted-plan | `--latest-lite-plan` |
+| `team-planex` | skill | requirement, execution-plan | code | `"{goal}"` |
+
+## CLI Nodes
+
+CLI nodes use `ccw cli` with a tool + mode + rule.
+
+| Use Case | cli_tool | cli_mode | cli_rule |
+|----------|----------|----------|----------|
+| Architecture analysis | gemini | analysis | analysis-review-architecture |
+| Code quality review | gemini | analysis | analysis-review-code-quality |
+| Bug root cause | gemini | analysis | analysis-diagnose-bug-root-cause |
+| Security assessment | gemini | analysis | analysis-assess-security-risks |
+| Performance analysis | gemini | analysis | analysis-analyze-performance |
+| Code patterns | gemini | analysis | analysis-analyze-code-patterns |
+| Task breakdown | gemini | analysis | planning-breakdown-task-steps |
+| Architecture design | gemini | analysis | planning-plan-architecture-design |
+| Feature implementation | gemini | write | development-implement-feature |
+| Refactoring | gemini | write | development-refactor-codebase |
+| Test generation | gemini | write | development-generate-tests |
+
+**CLI node args_template format**:
+```
+PURPOSE: {goal}
+TASK: • [derived from step description]
+MODE: analysis
+CONTEXT: @**/* | Memory: {memory_context}
+EXPECTED: [derived from step output_ports]
+CONSTRAINTS: {scope}
+```
+
+## Agent Nodes
+
+| subagent_type | Use Case | run_in_background |
+|---------------|----------|-------------------|
+| `general-purpose` | Freeform analysis or implementation | false |
+| `team-worker` | Worker in team-coordinate pipeline | true |
+| `code-reviewer` | Focused code review | false |
+
+**Agent node args_template format**:
+```
+Task: {goal}
+
+Context from previous step:
+{prev_output}
+
+Deliver: [specify expected output format]
+```
+
+## Checkpoint Nodes
+
+Checkpoints are auto-generated — not selected from catalog.
+
+| auto_continue | When to Use |
+|---------------|-------------|
+| `true` | Background save, execution continues automatically |
+| `false` | Pause for user review before proceeding |
+
+Set `auto_continue: false` when:
+- The next node is user-facing (plan display, spec review)
+- The user requested an explicit pause in their workflow description
+- The next node spawns a background agent (give user chance to cancel)
--- a/.claude/skills/wf-composer/specs/template-schema.md
+++ b/.claude/skills/wf-composer/specs/template-schema.md
@@ -0,0 +1,202 @@
+# Workflow Template Schema
+
+## File Location
+
+`.workflow/templates/<slug>.json`
+
+## Full Schema
+
+```json
+{
+  "template_id": "wft-<slug>-<YYYYMMDD>",
+  "name": "Human readable template name",
+  "description": "Brief description of what this workflow achieves",
+  "version": "1.0",
+  "created_at": "2026-03-17T10:00:00Z",
+  "source_session": "WFD-<slug>-<date>",
+  "tags": ["feature", "medium"],
+
+  "context_schema": {
+    "goal": {
+      "type": "string",
+      "required": true,
+      "description": "Main task goal or feature to implement"
+    },
+    "scope": {
+      "type": "string",
+      "required": false,
+      "description": "Target file or module scope",
+      "default": "src/**/*"
+    }
+  },
+
+  "nodes": [
+    {
+      "id": "N-001",
+      "name": "Plan Feature",
+      "type": "skill",
+      "executor": "workflow-lite-plan",
+      "args_template": "{goal}",
+      "input_ports": ["requirement"],
+      "output_ports": ["plan"],
+      "parallel_group": null,
+      "on_fail": "abort"
+    },
+    {
+      "id": "CP-01",
+      "name": "Checkpoint: After Plan",
+      "type": "checkpoint",
+      "description": "Plan artifact saved before execution proceeds",
+      "auto_continue": true,
+      "save_fields": ["session_id", "artifacts", "output_path"]
+    },
+    {
+      "id": "N-002",
+      "name": "Execute Implementation",
+      "type": "skill",
+      "executor": "workflow-execute",
+      "args_template": "--resume-session {N-001.session_id}",
+      "input_ports": ["plan"],
+      "output_ports": ["code"],
+      "parallel_group": null,
+      "on_fail": "abort"
+    },
+    {
+      "id": "CP-02",
+      "name": "Checkpoint: Before Testing",
+      "type": "checkpoint",
+      "description": "Implementation complete, ready for test validation",
+      "auto_continue": true,
+      "save_fields": ["session_id", "artifacts"]
+    },
+    {
+      "id": "N-003",
+      "name": "Run Tests",
+      "type": "skill",
+      "executor": "workflow-test-fix",
+      "args_template": "--session {N-002.session_id}",
+      "input_ports": ["code"],
+      "output_ports": ["test-passed"],
+      "parallel_group": null,
+      "on_fail": "abort"
+    }
+  ],
+
+  "edges": [
+    { "from": "N-001", "to": "CP-01" },
+    { "from": "CP-01", "to": "N-002" },
+    { "from": "N-002", "to": "CP-02" },
+    { "from": "CP-02", "to": "N-003" }
+  ],
+
+  "checkpoints": ["CP-01", "CP-02"],
+
+  "atomic_groups": [
+    {
+      "name": "planning-execution",
+      "nodes": ["N-001", "CP-01", "N-002"],
+      "description": "Plan must be followed by execution"
+    }
+  ],
+
+  "execution_mode": "serial",
+
+  "metadata": {
+    "node_count": 3,
+    "checkpoint_count": 2,
+    "estimated_duration": "20-40 min"
+  }
+}
+```
+
+## Node Type Definitions
+
+### `skill` node
+```json
+{
+  "id": "N-<seq>",
+  "name": "<descriptive name>",
+  "type": "skill",
+  "executor": "<skill-name>",
+  "args_template": "<string with {variable} and {prev-node-id.field} refs>",
+  "input_ports": ["<port-name>"],
+  "output_ports": ["<port-name>"],
+  "parallel_group": "<group-name> | null",
+  "on_fail": "abort | skip | retry"
+}
+```
+
+### `cli` node
+```json
+{
+  "id": "N-<seq>",
+  "name": "<descriptive name>",
+  "type": "cli",
+  "executor": "ccw cli",
+  "cli_tool": "gemini | qwen | codex",
+  "cli_mode": "analysis | write",
+  "cli_rule": "<rule-template-name>",
+  "args_template": "PURPOSE: {goal}\nTASK: ...\nMODE: analysis\nCONTEXT: @**/*\nEXPECTED: ...\nCONSTRAINTS: ...",
+  "input_ports": ["analysis-topic"],
+  "output_ports": ["analysis"],
+  "parallel_group": null,
+  "on_fail": "abort"
+}
+```
+
+### `command` node
+```json
+{
+  "id": "N-<seq>",
+  "name": "<descriptive name>",
+  "type": "command",
+  "executor": "workflow:refactor-cycle",
+  "args_template": "{goal}",
+  "input_ports": ["codebase"],
+  "output_ports": ["refactored-code"],
+  "parallel_group": null,
+  "on_fail": "abort"
+}
+```
+
+### `agent` node
+```json
+{
+  "id": "N-<seq>",
+  "name": "<descriptive name>",
+  "type": "agent",
+  "executor": "general-purpose",
+  "args_template": "Task: {goal}\n\nContext from previous step:\n{prev_output}",
+  "input_ports": ["requirement"],
+  "output_ports": ["analysis"],
+  "parallel_group": "<group-name> | null",
+  "run_in_background": false,
+  "on_fail": "abort"
+}
+```
+
+### `checkpoint` node
+```json
+{
+  "id": "CP-<seq>",
+  "name": "Checkpoint: <description>",
+  "type": "checkpoint",
+  "description": "<what was just completed, what comes next>",
+  "auto_continue": true,
+  "save_fields": ["session_id", "artifacts", "output_path"]
+}
+```
+
+## Runtime Reference Syntax
+
+In `args_template` strings, these references are resolved at execution time by `wf-player`:
+
+| Reference | Resolves To |
+|-----------|-------------|
+| `{variable}` | Value from context (bound at run start) |
+| `{N-001.session_id}` | `node_states["N-001"].session_id` |
+| `{N-001.output_path}` | `node_states["N-001"].output_path` |
+| `{N-001.artifacts[0]}` | First artifact from N-001 |
+| `{prev_session_id}` | session_id of the immediately preceding work node |
+| `{prev_output}` | Full output text of the immediately preceding node |
+| `{prev_output_path}` | Output file path of the immediately preceding node |