# Blueprint Engine

> Hybrid DAG execution primitive combining deterministic and agentic nodes with hard iteration caps

- Skill: `cleanexpo/blueprint-engine` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cleanexpo/blueprint-engine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cleanexpo/blueprint-engine/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cleanexpo (https://skillmd.com/u/cleanexpo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cleanexpo/blueprint-engine

---



# 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

1. **One-shot mandate**: Execute the full blueprint DAG without asking clarifying questions.
2. **Context scoping**: Read ONLY files in the pre-hydration manifest. No additional file reads.
3. **Iteration counting**: Every agentic node execution increments the counter in `.claude/data/minion-state.json`.
4. **Human review gate**: NEVER auto-merge PRs. The blueprint always ends at `create-pr`.
5. **en-AU locale**: All PR bodies, commit messages, and output use Australian English.
6. **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).