claude-pipe: Instructions file for Claude Code

CLAUDE.md — Instructions for Claude Code

This repo is claude-pipe: conventions for building multi-step pipelines with Claude Code. Agents are markdown files. State is YAML files. Orchestration is flat (ROOT spawns workers, no nesting).

Read this file before building anything. Then use the examples as reference.

---

Core Rules

1. Flat orchestration — ROOT (Claude Code CLI) orchestrates everything. Subagents cannot spawn subagents.
2. Manager = Skill — The manager is a Skill loaded into ROOT, not a separate agent. ROOT reads the manager's instructions and executes them (including spawning workers via Task tool).
3. Files are state — Workers write results to YAML/markdown files. State lives in artifacts/{session}/. You can always cat state.yaml to see where you are.
4. Data layers — L0 (user config) → L1 (plan, agent-generated) → L2 (working data) → L3 (final output). L1 constraints override L2 decisions. L3 must trace to L2 sources.
5. L1 > L2 — If the plan says "3 aspects", workers don't get to decide there should be 5. The plan is authoritative.

---

How to Build a New Pipeline

Step 1: Define Phases and Data Flow

Before writing any files, answer:

• What are the phases? (e.g., plan → research → synthesize → report)
• What data flows between phases? (e.g., plan.yaml → aspects/*.yaml → synthesis.yaml → REPORT.md)
• Which phases can run in parallel? (independent tasks = fan-out)
• What are the gate conditions? (e.g., "all aspects completed" before synthesis)

Step 2: Create Directory Structure

mkdir -p .claude/agents
mkdir -p .claude/skills
mkdir -p artifacts
echo "artifacts/" >> .gitignore

Step 3: Create the Manager Skill First

This is your orchestration entry point. The user runs it as /manager-yourpipeline.

File: .claude/skills/manager-yourpipeline.md

---
name: manager-yourpipeline
type: manager
version: v1.0
description: Short description of your pipeline
---

# Your Pipeline Name

## Session Setup
- Generate session ID: `{pipeline-name}-{YYYYMMDD}-{HHMMSS}`
- Create directory: `artifacts/{session}/`
- Initialize state.yaml with all phases as `pending`

## Phase 1: [Name]
1. [Instructions for this phase]
2. Write output to `artifacts/{session}/[output].yaml`
3. Update state.yaml: phase_states.[name] = completed

## Gate: [Name] → [Next]
- Condition: [what must be true]
- On fail: [what to do]

## Phase 2: [Name] (parallel)
For each item in [previous output]:
  Spawn worker:
    Task(
      subagent_type: "general-purpose",
      prompt: "You are a [role]. Load skill [skill-name]... Process: {item}. Write to: artifacts/{session}/[path]",
      run_in_background: true
    )

IMPORTANT: All Task calls in ONE message = parallel execution.
Wait for all with TaskOutput(block: true).

## Phase 3: [Name]
...