claude-code-workflow 7.2.29 → 7.2.30

package/.claude/skills/chain-loader/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: chain-loader
+description: Meta-skill for generating chain-based skills with progressive step loading and LLM-driven decision routing. Converts linear phase skills into chain graph skills. Triggers on "create chain", "chain skill", "add chain", "generate chain".
+allowed-tools: Agent, AskUserQuestion, Read, Bash, Glob, Grep, Write
+---
+
+# Chain Skill Generator
+
+Generate chain graph JSON for skills, enabling progressive content delivery and LLM-driven decision routing via the `chain_loader` tool.
+
+## Architecture
+
+```
+User Request (target skill + chain purpose)
+       |
+Phase 1: Analyze target skill (existing phases/ or new requirements)
+       |
+Phase 2: Design node graph (step/decision/delegate nodes + routing)
+       |
+Phase 3: Generate chain JSON + validate with chain_loader
+       |
+Output: .claude/skills/{skill}/chains/{chain}.json
+```
+
+## Key Rules
+
+1. **Spec-first** — Read `specs/chain-schema.md` and `specs/design-patterns.md` before any generation
+2. **content_ref over inline** — Use `@phases/` file references; `content_inline` only for <200 char
+3. **Validate before commit** — Never write chain JSON without graph connectivity check
+4. **Preserve existing content** — When adding chains to existing skills, never modify existing phase files
+5. **12-node limit** — If a chain exceeds 12 nodes, split into main + sub-chains
+
+## Exemplar
+
+`ccw-chain` is the canonical example of this meta-skill's output:
+- 8 chains, 79 total nodes, cross-chain routing via `->chain-name`
+- phases/ contains actual command/skill documents (not orchestration code)
+- Location: `.claude/skills/ccw-chain/`
+
+Study its structure before generating new chains: `Read(".claude/skills/ccw-chain/SKILL.md")`
+
+## Execution Flow
+
+```
+Pre-Phase: Read specs/chain-schema.md + specs/design-patterns.md
+
+Phase 1: Analyze Target Skill
+   Ref: phases/01-analyze-skill.md
+   Input: user request, target skill name
+   Output: skill analysis (workflow steps, decision points, content files)
+
+Phase 2: Design Node Graph
+   Ref: phases/02-design-graph.md
+   Input: skill analysis
+   Output: validated node graph (in-memory)
+
+Phase 3: Generate & Validate
+   Ref: phases/03-generate-validate.md
+   Input: validated node graph
+   Output: chain JSON files, validation report
+```
+
+| Phase | Document | Purpose |
+|-------|----------|---------|
+| 1 | phases/01-analyze-skill.md | Understand target skill workflow and content |
+| 2 | phases/02-design-graph.md | Design nodes, routing, validate connectivity |
+| 3 | phases/03-generate-validate.md | Write JSON, test with chain_loader |
+
+## Output Structure
+
+```
+.claude/skills/{skill}/
+├── chains/
+│   ├── {chain-name}.json       # Main chain
+│   └── {sub-chain}.json        # Optional sub-chains
+├── phases/                     # Content files (existing or generated)
+└── SKILL.md                    # Existing or updated entry
+```

package/.claude/skills/chain-loader/phases/01-analyze-skill.md

@@ -0,0 +1,53 @@
+# Phase 1: Analyze Target Skill
+
+Understand the target skill's workflow to identify nodes, decision points, and content files.
+
+## Step 1.1: Identify Target
+
+Determine if adding chains to an existing skill or creating new:
+
+**Existing skill**: Read its SKILL.md and list its phases/ directory
+```bash
+# Find the skill
+ls .claude/skills/{skill-name}/SKILL.md
+ls .claude/skills/{skill-name}/phases/
+```
+
+**New skill**: Collect requirements from user — what workflow steps, what branches, what content.
+
+## Step 1.2: Map Workflow Steps
+
+For existing skills, read each phase file and identify:
+
+1. **Sequential steps** — each phase becomes a StepNode with `content_ref: "@phases/{file}"`
+2. **Decision points** — look for conditional language ("if...", "based on...", "choose...") that implies branching
+3. **Sub-workflows** — sections that reference other skills or could be extracted as separate chains
+
+For new skills, work with the user to define:
+- What are the execution steps?
+- Where does the LLM need to make a routing decision?
+- What content should each step load?
+
+## Step 1.3: Inventory Content Files
+
+List all files that chain nodes will reference:
+
+| Type | Source | content_ref Format |
+|------|--------|--------------------|
+| Phase files | `phases/01-xxx.md` | `@phases/01-xxx.md` |
+| Skill subdirs | `phases/workflow-plan/SKILL.md` | `@phases/workflow-plan/SKILL.md` |
+| Commands | `.claude/commands/workflow/xxx.md` | Copy to phases/ first, then `@phases/xxx.md` |
+| Inline content | Short instructions (<200 chars) | Use `content_inline` instead |
+
+**Key lesson from ccw-chain**: phases/ should contain **actual command/skill documents** that the LLM executes, not orchestration pseudocode.
+
+## Output
+
+- Skill name and directory path
+- List of workflow steps with their content file mappings
+- Identified decision points with branch options
+- List of content files that need to be created or copied
+
+## Next Phase
+
+Proceed to [Phase 2: Design Node Graph](02-design-graph.md).

package/.claude/skills/chain-loader/phases/02-design-graph.md

@@ -0,0 +1,73 @@
+# Phase 2: Design Node Graph
+
+Transform skill analysis into a validated directed graph of chain nodes.
+
+## Step 2.1: Choose Chain Pattern
+
+Based on the workflow analysis from Phase 1, select a pattern from `specs/design-patterns.md`:
+
+| Workflow Shape | Pattern | Example |
+|----------------|---------|---------|
+| Pure sequential | Linear Chain | `S1 → S2 → S3 → null` |
+| Quality gate / retry | Decision Gate | `S1 → D1 --[pass]--> S2 --[fail]--> S1` |
+| Normal vs escalation | Escalation Branch | `D1 --[simple]--> S2 --[complex]--> ->deep` |
+| Reusable sub-workflow | Delegate | `S1 → DEL1 [->verify] → S2` |
+| Multi-flow routing | Decision Router | `D1 --[A]--> S_A1 --[B]--> S_B1` (ccw-chain pattern) |
+
+## Step 2.2: Define Nodes
+
+For each workflow step, create a node definition:
+
+**StepNode** — loads content for LLM execution:
+- `content_ref: "@phases/{file}"` for existing files
+- `content_inline: "..."` for short instructions only (<200 chars)
+- `next: "{node_id}"` or `null` for terminal
+
+**DecisionNode** — LLM chooses a path:
+- `prompt`: describe what the LLM should assess
+- `choices[]`: each with `label`, `description`, `next`
+- `default`: fallback node ID
+
+**DelegateNode** — route to sub-chain:
+- `chain`: sub-chain filename (without .json)
+- `next`: return node after sub-chain completes
+
+**Node ID conventions**:
+- Steps: `S1`, `S2`, `S3` (sequential) or `S_{prefix}{n}` for multi-flow (e.g., `S_R1`, `S_B1`)
+- Decisions: `D1`, `D2`
+- Delegates: `DEL1`, `DEL2`
+
+## Step 2.3: Design Routing
+
+For multi-flow chains (like ccw-chain's category chains), use the Decision Router pattern:
+
+```
+D1 (Select Flow)
+├── choice 1 → S_A1 → S_A2 → null
+├── choice 2 → S_B1 → S_B2 → S_B3 → null
+└── choice 3 → S_C1 → null
+```
+
+For cross-chain routing, use `"next": "->chain-name"` to jump to another chain's entry node.
+
+## Step 2.4: Validate Graph
+
+Before proceeding to generation, verify:
+
+1. **Entry exists** — `entry` points to a node in `nodes`
+2. **All `next` references resolve** — every node ID in `next`, `choices[].next`, `default` either exists in `nodes`, is `null`, or starts with `->` (cross-chain)
+3. **No orphan nodes** — BFS from entry reaches every node in `nodes`
+4. **Content files exist** — every `content_ref` path resolves to a real file
+5. **Decision completeness** — every DecisionNode has non-empty `choices` and a `default`
+
+If validation fails, fix the graph before proceeding. Do NOT generate invalid chains.
+
+## Output
+
+- Validated node graph (nodes map ready for JSON serialization)
+- Sub-chain definitions if any
+- List of content files that need creation
+
+## Next Phase
+
+Proceed to [Phase 3: Generate & Validate](03-generate-validate.md).

package/.claude/skills/chain-loader/phases/03-generate-validate.md

@@ -0,0 +1,75 @@
+# Phase 3: Generate & Validate
+
+Write chain JSON files and validate with the chain_loader tool.
+
+## Step 3.1: Create Directory
+
+```bash
+mkdir -p ".claude/skills/${skillName}/chains"
+```
+
+## Step 3.2: Write Chain JSON
+
+Write the main chain file using the validated graph from Phase 2:
+
+```json
+{
+  "chain_id": "{chain-id}",
+  "name": "{Human-Readable Name}",
+  "description": "{What this chain does}",
+  "version": "1.0",
+  "entry": "{first-node-id}",
+  "nodes": { ... }
+}
+```
+
+Write to: `.claude/skills/{skill}/chains/{chain-id}.json`
+
+If there are sub-chains, write each as a separate JSON file in the same `chains/` directory.
+
+## Step 3.3: Create Missing Content Files
+
+If any step nodes need new content files:
+1. Write the content to `phases/{filename}.md`
+2. Ensure the `content_ref` in the chain JSON matches: `@phases/{filename}.md`
+
+For content files copied from commands or other skills, preserve the full document — do not summarize.
+
+## Step 3.4: Validate Structure
+
+Check the generated JSON:
+
+1. **Required fields**: `chain_id`, `name`, `description`, `version`, `entry`, `nodes`
+2. **Entry exists**: `entry` points to a key in `nodes`
+3. **Node completeness**: every node has `type` and `name`
+4. **Step nodes**: have `content_ref` or `content_inline`
+5. **Decision nodes**: have non-empty `choices[]` and `default`
+6. **Delegate nodes**: have `chain` field
+7. **All `next` references**: resolve to existing nodes, `null`, or `->chain-name`
+8. **No orphans**: BFS from entry reaches every node
+9. **Content refs exist**: every `@phases/...` file is on disk
+
+## Step 3.5: Integration Test
+
+Test with the chain_loader tool from the **project root** (not from the skill directory):
+
+```bash
+# List — should show the new chain(s)
+ccw tool exec chain_loader '{"cmd":"list","skill":"{skill-name}"}'
+
+# Start — should return entry node content
+ccw tool exec chain_loader '{"cmd":"start","skill":"{skill-name}","chain":"{chain-id}"}'
+```
+
+**Known gotcha**: `chain_loader list` auto-detects skill from cwd. Run from project root with explicit `skill` param to avoid empty results.
+
+## Step 3.6: Report Results
+
+Output summary:
+- Chains generated (count and names)
+- Total nodes, by type (step/decision/delegate)
+- Validation status (PASS/FAIL)
+- Any warnings (orphan nodes, missing content)
+
+If FAIL: fix errors before marking complete.
+If PASS: the chain is ready for use.

package/.claude/skills/chain-loader/specs/chain-schema.md

@@ -0,0 +1,99 @@
+# Chain JSON Schema & State Machine
+
+## Chain JSON Structure
+
+Files live at `.claude/skills/{skill}/chains/{chain-name}.json`.
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `chain_id` | string | Unique ID matching filename (without .json) |
+| `name` | string | Human-readable name |
+| `description` | string | What this chain does |
+| `version` | string | Semantic version |
+| `entry` | string | Node ID of entry point (must exist in nodes) |
+| `nodes` | object | Map of node ID to node definition |
+
+### StepNode
+
+```json
+{
+  "type": "step",
+  "name": "Phase Name",
+  "content_ref": "@phases/01-xxx.md",
+  "next": "S2"
+}
+```
+- `content_ref` (`@`-prefixed path) or `content_inline` (direct text) — at least one required
+- `content_ref` resolved relative to skill directory: `resolve(skillPath, refPath.replace('@',''))`
+- `next: null` = chain termination
+
+### DecisionNode
+
+```json
+{
+  "type": "decision",
+  "name": "Select Flow",
+  "prompt": "Based on analysis, choose...",
+  "choices": [
+    { "label": "Option A", "description": "...", "next": "S_A1" },
+    { "label": "Option B", "description": "...", "next": "S_B1" }
+  ],
+  "default": "S_A1"
+}
+```
+- `choices` — non-empty array, selected by **1-based index**
+- `choice.next` can be node ID or `"->chain-name"` for cross-chain routing
+- `default` — fallback if no valid choice provided
+
+### DelegateNode
+
+```json
+{
+  "type": "delegate",
+  "name": "Run Sub-workflow",
+  "chain": "sub-chain-name",
+  "next": "S5"
+}
+```
+- `chain` — filename (without .json) of another chain in same skill's `chains/` dir
+- `next` — return node after sub-chain completes; `null` if no return
+
+### Cross-Chain Routing
+
+- `"->chain-name"` in any `next` field jumps to that chain's entry node
+- DelegateNode pushes current chain onto stack; sub-chain completion pops back to `next`
+
+---
+
+## Node State Machine
+
+### Lifecycle
+
+```
+pending → active → completed
+```
+
+### Rules
+
+1. `start` — creates session, entry node becomes `active`
+2. `next` on `active` node — returns current content (idempotent, no state change)
+3. `next` on `completed` node — auto-advances to next node
+4. `done` — forces `active -> completed`, advances to next node
+5. Decision `done` requires `choice` (1-based index)
+6. Delegate `done` — pushes chain onto `chain_stack`, switches to sub-chain entry
+7. Sub-chain termination (`next: null`) — pops `chain_stack`, returns to parent's `return_node`
+8. All chains exhausted (empty stack + `next: null`) — session `completed`
+
+### chain_loader Commands
+
+| cmd | Params | Description |
+|-----|--------|-------------|
+| `list` | `skill?` | List chains (auto-detects skill from cwd) |
+| `start` | `chain`, `skill?` | Create session, load entry node |
+| `next` | `session_id` | Read current node (idempotent if active) |
+| `done` | `session_id`, `choice?` | Complete current node, advance |
+| `status` | `session_id` | Query session state |
+| `content` | `session_id` | Get all loaded content |
+| `complete` | `session_id` | Mark session completed |

package/.claude/skills/chain-loader/specs/design-patterns.md

@@ -0,0 +1,99 @@
+# Chain Design Patterns
+
+Common patterns and anti-patterns for chain graph design.
+
+## Patterns
+
+### 1. Linear Chain (Simplest)
+
+```
+S1 → S2 → S3 → null
+```
+
+Use when: Pure sequential workflow, no branching needed. Equivalent to numbered phases but with session tracking.
+
+### 2. Decision Gate
+
+```
+S1 → S2 → D1 --[pass]--> S3 → null
+                --[fail]--> S2 (loop back)
+```
+
+Use when: Quality gate after analysis, confidence check, retry loop.
+
+### 3. Escalation Branch
+
+```
+S1 → S2 → D1 --[simple]--> S3 → null
+                --[complex]--> →deep-analysis (cross-chain)
+```
+
+Use when: Normal path vs. escalation to separate workflow.
+
+### 4. Delegate Sub-Chain
+
+```
+S1 → S2 → DEL1 [→verification] → S3 → null
+```
+
+Use when: Reusable sub-workflow that multiple chains can call.
+
+### 5. Multi-Path Merge
+
+```
+S1 → D1 --[A]--> S2A → S3
+         --[B]--> S2B → S3
+```
+
+Use when: Different approaches converge to same final step.
+
+### 6. Decision Router (Multi-Flow)
+
+```
+D1 --[flow A]--> S_A1 → S_A2 → null
+   --[flow B]--> S_B1 → S_B2 → S_B3 → null
+   --[flow C]--> S_C1 → null
+```
+
+Use when: Single entry point dispatches to multiple independent pipelines. Each flow has its own step sequence. This is the primary pattern used in ccw-chain's category chains (ccw-lightweight, ccw-standard, ccw-exploration, etc.).
+
+## Anti-Patterns
+
+### 1. Too Many Decisions
+
+Bad: `D1 → D2 → D3 → D4` (decision after decision)
+
+Fix: Combine into one decision with more choices, or add a step between decisions.
+
+### 2. Orphan Nodes
+
+Bad: Node exists in `nodes` but unreachable from `entry`.
+
+Fix: Remove it or connect it to the graph.
+
+### 3. Missing Default
+
+Bad: Decision node without `default` field.
+
+Fix: Always set `default` to a safe fallback node.
+
+### 4. Deep Delegation
+
+Bad: Chain A delegates to B which delegates to C which delegates to D.
+
+Fix: Keep delegation to max 2 levels. Flatten if possible.
+
+### 5. Inline Novel Content
+
+Bad: `content_inline` with 500+ words of unique instruction.
+
+Fix: Extract to a `phases/*.md` file and use `content_ref`.
+
+## Chain Sizing Guide
+
+| Complexity | Nodes | Decisions | Sub-chains |
+|-----------|-------|-----------|------------|
+| Simple | 3-5 | 0-1 | 0 |
+| Standard | 5-8 | 1-2 | 0-1 |
+| Complex | 8-12 | 2-3 | 1-2 |
+| Large | 12+ | Consider splitting into multiple chains |

package/.claude/skills/chain-loader/templates/chain-json.md

@@ -0,0 +1,63 @@
+# Chain JSON Template
+
+## Minimal Linear Chain
+
+```json
+{
+  "chain_id": "my-workflow",
+  "name": "My Workflow",
+  "description": "Sequential 3-step workflow",
+  "version": "1.0",
+  "entry": "S1",
+  "nodes": {
+    "S1": { "type": "step", "name": "Step 1", "content_ref": "@phases/01-step.md", "next": "S2" },
+    "S2": { "type": "step", "name": "Step 2", "content_ref": "@phases/02-step.md", "next": "S3" },
+    "S3": { "type": "step", "name": "Step 3", "content_ref": "@phases/03-step.md", "next": null }
+  }
+}
+```
+
+## Decision Router (from ccw-chain/ccw-lightweight)
+
+```json
+{
+  "chain_id": "ccw-lightweight",
+  "name": "CCW Lightweight Workflows",
+  "description": "Level 2: rapid, bugfix, hotfix, docs-only",
+  "version": "2.0",
+  "entry": "D1",
+  "nodes": {
+    "D1": {
+      "type": "decision",
+      "name": "Select Lightweight Flow",
+      "prompt": "Based on the detected task_type, select the flow:\n1. Rapid\n2. Bugfix\n3. Hotfix\n4. Docs",
+      "choices": [
+        { "label": "Rapid", "description": "lite-plan + test-fix", "next": "S_R1" },
+        { "label": "Bugfix", "description": "lite-plan(--bugfix) + test-fix", "next": "S_B1" },
+        { "label": "Hotfix", "description": "lite-plan(--hotfix)", "next": "S_H1" },
+        { "label": "Docs", "description": "lite-plan(--docs)", "next": "S_D1" }
+      ],
+      "default": "S_R1"
+    },
+    "S_R1": { "type": "step", "name": "Rapid: workflow-lite-plan", "content_ref": "@phases/workflow-lite-plan.md", "next": "S_R2" },
+    "S_R2": { "type": "step", "name": "Rapid: workflow-test-fix", "content_ref": "@phases/workflow-test-fix/SKILL.md", "next": null },
+    "S_B1": { "type": "step", "name": "Bugfix: workflow-lite-plan", "content_ref": "@phases/workflow-lite-plan.md", "next": "S_B2" },
+    "S_B2": { "type": "step", "name": "Bugfix: workflow-test-fix", "content_ref": "@phases/workflow-test-fix/SKILL.md", "next": null },
+    "S_H1": { "type": "step", "name": "Hotfix: workflow-lite-plan", "content_ref": "@phases/workflow-lite-plan.md", "next": null },
+    "S_D1": { "type": "step", "name": "Docs: workflow-lite-plan", "content_ref": "@phases/workflow-lite-plan.md", "next": null }
+  }
+}
+```
+
+## Cross-Chain Routing (from ccw-chain/ccw-main)
+
+Decision choice with `"next": "->ccw-lightweight"` jumps to another chain's entry node.
+
+## Node ID Conventions
+
+| Prefix | Type | Example |
+|--------|------|---------|
+| `S{n}` | Sequential step | S1, S2, S3 |
+| `S_{prefix}{n}` | Flow-scoped step | S_R1, S_B1, S_CP2 |
+| `D{n}` | Decision | D1, D2 |
+| `DEL{n}` | Delegate | DEL1 |