Blueprint Engine — Hybrid DAG Primitive

Inspired by Stripe Minions: deterministic scaffolding + bounded agentic intelligence. Hard caps are non-advisory — they are enforced by iteration-counter.py.

Node Types

Deterministic Nodes (No LLM — Always Idempotent)

Commands executed directly with no iteration cost:

git-branch — git checkout -b minion/{task-id}
git-commit — git add -A && git commit -m "minion: {message}"
git-push — git push -u origin HEAD
create-pr — gh pr create --title "minion: {task}" --body "{template}" --label "minion-generated"
lint — pnpm turbo run lint
type-check — pnpm turbo run type-check
test — pnpm turbo run test
circular-deps-check — pnpm turbo run lint (includes circular dep detection)
system-supervisor-quick-audit — read .claude/memory/current-state.md + grep for violations (deterministic)
execution-guardian-check — evaluate risk level from task keywords (deterministic mapping)

Agentic Nodes (LLM Reasoning — Hard Caps Apply)

implement — Implement the requested feature. Cap: 1 pass only
reproduce-bug — Write a failing test that reproduces the bug. Cap: 1 pass only
implement-fix — Fix the reproduced bug. Cap: 1 pass only
implement-migration — Execute a database or code migration. Cap: 1 pass only
implement-refactor — Refactor per system supervisor audit findings. Cap: 1 pass only
fix-ci — Fix CI/test failures. Cap: 2 rounds maximum
fix-lint — Fix non-auto-fixable lint errors. Cap: 1 round maximum

Hard Iteration Caps (Non-Advisory)

Node	Cap
`implement`	1 pass
`reproduce-bug`	1 pass
`implement-fix`	1 pass
`implement-migration`	1 pass
`implement-refactor`	1 pass
`fix-ci`	2 rounds
`fix-lint`	1 round
Total agentic per blueprint	3 max

When any cap is reached → output BLUEPRINT_ESCALATION block, halt, write to .claude/memory/current-state.md, stop.

Auto-Fixes (Deterministic — Zero Iteration Cost)

These are applied automatically before any agentic node. They do NOT count against caps:

Error Pattern	Auto-Fix Command
`Cannot find module`	`pnpm install`
`ModuleNotFoundError`	`uv sync`
Auto-fixable ESLint errors	`pnpm turbo run lint -- --fix`
Auto-fixable Python lint	`uv run ruff check src/ --fix`
Missing type stubs	`pnpm add -D @types/{package}`

Escalation Format

When a cap is reached or a blocking error occurs, output this exact block and halt:

BLUEPRINT_ESCALATION
task_id: {id}
node: {failing-node}
iteration: {n}/{max}
reason: {what failed in one line}
evidence: {last 5 lines of error output}
next_action: Human review required — do not retry automatically

Then write to .claude/memory/current-state.md:

## Minion Escalation — {DD/MM/YYYY HH:MM AEST}
task_id: {id}
status: ESCALATED
node: {failing-node}
reason: {reason}

Execution Rules

One-shot mandate: Execute the full blueprint DAG without asking clarifying questions.
Context scoping: Read ONLY files in the pre-hydration manifest. No additional file reads.
Iteration counting: Every agentic node execution increments the counter in .claude/data/minion-state.json.
Human review gate: NEVER auto-merge PRs. The blueprint always ends at create-pr.
en-AU locale: All PR bodies, commit messages, and output use Australian English.
Deterministic first: Always attempt auto-fixes before invoking any agentic node.

Blueprint DAG Notation

node-type → node-type → [optional-node] → node-type

Brackets [...] indicate conditional nodes (only executed if the preceding deterministic check fails).

blueprint-engine