splitty-design

splitty-design

Translate a user request into a valid splitty pipeline YAML file.

Inputs you have

• The user's natural-language description of the goal.
• The corpus / input source (file, glob, or @stdin).
• Optional constraints (output format, model preferences, parallelism limits).

Procedure

1 — Read the schema and examples

You must read these before authoring:

• ${CLAUDE_PLUGIN_ROOT}/docs/pipeline-schema.md
• At least one of:
  • ${CLAUDE_PLUGIN_ROOT}/pipelines/examples/map-reduce-summary.yaml
  • ${CLAUDE_PLUGIN_ROOT}/pipelines/examples/classify-and-extract.yaml
  • ${CLAUDE_PLUGIN_ROOT}/pipelines/examples/fan-out-fan-in.yaml

Pick the example closest to the user's goal as your starting template.

2 — Decide the topology

Map the request to one of these patterns. If unsure, ask the user.

Goal shape	Topology
Summarize / extract one thing per chunk → one report	map → terminal(custom)
Filter chunks, then expensive analysis on survivors	map(classify) → gate → map(extract) → terminal
Two independent analyses combined per chunk	map(A) ∥ map(B) → map(merge) → terminal
Aggregate counts / structured records	map(extract-json) → terminal(strategy: concat-json)
Iteratively refine a draft	reduce(draft) → loop(critique→revise) → terminal

3 — Pick chunker settings

Strategy	Use when
paragraphs	Prose, notes, long-form documents (default)
lines	Logs, CSV-ish, line-oriented text
tokens	Need consistent prompt sizing across chunks
fixed	Binary-ish or unstructured streams
none	Pipeline must see entire input as one chunk

Default chunk sizes:

• paragraphs: size: 2000 (chars), overlap: 0
• lines: size: 200 (lines)
• tokens: size: 1000
• fixed: size: 4000 (chars)

4 — Author each stage

For every map, reduce, and custom-strategy terminal stage, write:

• id — kebab-case, descriptive (extract-entities, not s1)
• agent_def.system — the persona in 1-3 sentences. Be specific about role and constraints (e.g., "You never invent facts", "You output strict JSON").
• agent_def.tools — almost always [Read, Write]. Add Grep / Glob only if the stage genuinely needs to look outside its input.
• agent_def.model — haiku for cheap classification, sonnet (default) for most analysis, opus only for hard synthesis at the terminal.
• instructions — the precise task: format, length, what to include, what to exclude. Include negative constraints (no prose, no commentary, no fences).
• output_format — json whenever downstream stages will programmatically consume the output. markdown only at the terminal.

For gate stages: write a condition that operates on JSON keys produced upstream. Keep it simple — see docs/pipeline-schema.md for supported syntax.

For terminal with strategy: concat | concat-json | deep-merge: no agent_def needed; the union is mechanical.

5 — Write the file

Save to .splitty/pipelines/<name>.yaml in the user's workspace. If the directory does not exist, create it. Use the user's stated name or derive a kebab-case one from the goal.

6 — Validate

Run:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/splitty.py validate <path>

If validation fails, fix the issues and re-validate. Do not hand off an invalid pipeline.

7 — Show the user

Print:

1. The path to the saved pipeline.
2. A short ASCII diagram of the topology.
3. The 1-line description of each stage (id + role).

Then ask: "Run it now?" Do not autorun unless the user said so explicitly in their original request.

Anti-patterns to avoid

• One mega-stage doing many things. Split into discrete filters, each with a single responsibility. The whole point of the plugin is composition.
• Vague personas like "you are a helpful assistant". Personas should declare a specific filtering role and its hard constraints.
• Markdown output before the terminal. Intermediate stages should output JSON whenever possible so downstream stages can consume them programmatically.
• Fan-out without fan-in. Every leaf must be a terminal. The validator enforces this; if you hit the error, add a synthesizer.