hornflow

An AI agent orchestration pipeline that chains three tools so each agent works with a tight, fresh context and every change is test-first and independently reviewed.

gstack  ──▶  GSD                          ──▶  superpowers                ──▶  git / CI
spec         phases + vertical slices          build each slice                one PR ▶ main
             (strict TDD + acceptance)         (fresh agent per slice;
                                                fresh subagent + independent
                                                reviewer per task)

Why: large AI builds rot when one agent carries the whole job in one conversation. hornflow splits the work into phases → vertical slices → tasks, and gives each unit its own process/subagent, handing context over as files. The result: low per-agent token use, strict TDD, and independent review at every grain.

Install

cd /c/dev/hornflow
./setup          # puts `hornflow` on PATH (~/.local/bin) and registers the /hornflow skill

Prerequisites: git, claude (Claude Code CLI), gh, and these installed for Claude: gstack, gsd-core (GSD), and the superpowers plugin. bun is needed by gstack/GSD binaries.

Use (inside a target repo)

hornflow spec                              # interactive: gstack → docs/specs/<slug>.md
hornflow decompose docs/specs/<slug>.md    # GSD → .planning/ phases + vertical slices
hornflow run                               # gated build (checkpoints between phases)
hornflow run --autonomous                  # unattended; auto-merges on green CI
hornflow status                            # phase/slice progress

The model

Level	What it is	Boundary
Spec	the whole job	one spec/<slug> branch; one final PR → main
Phase	a chunk that ships together	reviewed milestone committed on the spec branch
Vertical slice	one fresh agent's unit (UI→API→DB)	isolated worktree, integrated on pass
Task	a step in a slice	atomic TDD commits; fresh subagent per task

Guarantees

• Strict TDD, git-gated: a failing test(...) commit must precede each feat(...) commit on every slice, or the slice is rejected into a bounded fix loop.
• Independent review at task / slice / phase / whole-spec grains, always in a context separate from the writer.
• Anti context-rot: one claude -p process per slice; one subagent per task; file-only hand-offs (.planning/**, git diffs).
• Git/CI: spec/<slug> branch off base, slices integrate as they pass, phases are completion markers, a single gated PR → main, CI gated (baseline scaffolded if absent).

Configuration (env)

Var	Default	Meaning
HORNFLOW_MAX_TURNS	200	max turns per claude -p slice/review run
HORNFLOW_FIX_RETRIES	2	TDD-gate fix-loop retries per slice
HORNFLOW_SUPERPOWERS_DIR	auto (newest)	force a superpowers plugin dir
HORNFLOW_SLUG	from spec filename	override the spec slug / branch name
HORNFLOW_OUTPUT_FORMAT	stream-json	stream-json or text for claude -p logs

Status / limitations

• Slices run sequentially (safe, conflict-free). Parallel waves are planned.
• Targets Git Bash on Windows (and POSIX shells elsewhere).
• The build step uses --dangerously-skip-permissions; blast radius is contained by isolated worktrees + the spec branch + CI/review gates before main.

See docs/WORKFLOW.md for the full SOP and design rationale.