blueprint · git:20260716.78e7355 · 2026-07-16 · sha256 5911d743ad801284
blueprint git:20260716.78e7355A
Immutable. This exact content never changes and is served at /api/v1/blob/5911d743ad801284.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_odbfspyzt2ufvfip/5911d743ad801284ccc7972e466092e30de4562f0c1ce3e26eee426e46933813.json
Then /plugin install blueprint@markdownregistry-odbfspyzt2ufvfip in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: blueprint
description: "Use when a single objective is too large for one pull request and must span multiple sessions or PRs. Turns the objective into a sequenced construction plan of 3-12 one-PR steps, each with a cold-start context brief, dependency edges, and exit criteria, then reviews it adversarially and registers it as Markdown."
license: MIT
metadata:
author: "Petr Král (pekral.cz)"
---
# Blueprint
## Constraints
- Apply `@rules/git/general.mdc` — branch, commit, and PR conventions below come from it.
- Apply `@rules/compound-engineering/general.mdc` — the plan is durable memory the next agent reuses, not throwaway prose.
- Apply `@rules/compound-engineering/general.mdc` *Assign the most relevant existing label when creating a tracker issue* for any tracker issue this plan creates or hands off to `@skills/create-issues-from-text/SKILL.md` to create.
- Apply `@rules/laravel/architecture.mdc` when the project uses `pekral/arch-app-services`, so each step lands in the correct layer.
- Plan only. Do not implement, commit, or push any step.
- Output Markdown only. English only.
- Every step must be one pull request: independently reviewable and mergeable on its own.
- Break the objective into 3-12 steps. Fewer means it likely fits one PR; more means the objective is too broad and should be split first.
- Each step must be executable cold by `@skills/resolve-issue/SKILL.md` or a fresh agent with no prior context.
- Do not invent dependencies on tooling that may be absent. Degrade gracefully when GitHub CLI (`gh`) is missing.
## Use when
- An objective clearly exceeds one pull request (a migration, a multi-layer feature, a cross-cutting refactor).
- Work will span multiple sessions or multiple agents and needs a sequenced, resumable plan.
- You need to know which parts can run in parallel and which must be sequential before starting.
Do not use for single-PR tasks (use `@skills/analyze-problem/SKILL.md` or `@skills/resolve-issue/SKILL.md`), for splitting an objective into tracker issues without a dependency graph (use `@skills/create-issues-from-text/SKILL.md`), or when the user wants one high-leverage suggestion (`@skills/smartest-project-addition/SKILL.md` / `@skills/product-capability/SKILL.md`).
## Execution
Run the five phases in order. Do not register a plan that has not passed Review.
1. **Research** — Establish ground truth before planning.
- Read the actual code, layers, and conventions the objective will touch. Per `@rules/compound-engineering/general.mdc`, find the existing part of the system the work extends before inventing a new abstraction.
- Walk `git log` / `git blame` over the affected area to learn how it evolved and what was already tried or reverted.
- Detect the git baseline: confirm the repo, the default branch (`master`), and whether `gh` is available (`gh auth status`). Record the result; it drives the PR template in Output.
- For an unfamiliar pattern, library, or security-sensitive surface, consult current authoritative references and cite them.
2. **Design** — Decompose the objective into 3-12 one-PR steps.
- Each step is the smallest change that delivers reviewable value and can merge alone.
- Sequence steps so each builds on a merged predecessor; never assume an unmerged step's code.
- Map dependency edges: for every step, list which steps must merge before it. Steps with no shared files and no dependency edge between them may run in parallel.
- Name the layer each step lands in (Action, Service, Repository, etc.) when `@rules/laravel/architecture.mdc` applies.
3. **Draft** — Write the per-step plan (structure in Output).
- Give every step a self-contained context brief: enough background, file paths, and conventions for a fresh agent to execute it without reading the other steps.
- Write concrete, observable exit criteria per step (tests, behavior, verification commands).
- Add the parallelism summary: the dependency graph and which steps may run concurrently.
4. **Review** — Adversarially check the draft against the anti-patterns below before registering. Fix every hit; re-run until clean.
- A "step" that spans multiple PRs, or is too small to justify its own PR.
- A step whose context brief is not self-contained (assumes prior conversation or another step's unmerged work).
- Missing, unobservable, or untestable exit criteria.
- Hidden ordering: two steps marked parallel that touch the same files or share an unstated dependency.
- A new abstraction where an existing part of the system already fit (`@rules/compound-engineering/general.mdc`).
- Branch / commit / PR wording that violates `@rules/git/general.mdc` (wrong type, base branch, period, attribution).
- A plan that assumes `gh` exists when Research found it absent.
5. **Register** — Persist the approved plan as Markdown in the repo (e.g. `docs/plans/<objective-slug>/`): one `README.md` index plus one file per step, or a single plan file when small. State the path so the next agent picks it up.
## Output
Register a plan index plus one entry per step.
**Plan index** (`README.md`): objective in one or two sentences; ordered step list; the parallelism summary; git baseline (default branch `master`, `gh` present yes/no).
**Per step:**
- **Title** — `type(scope): short description`, lowercase type/scope, no trailing period (`@rules/git/general.mdc`).
- **Branch** — feature branch off `master` (e.g. `feat/<short-slug>`).
- **Context brief** — self-contained background, file paths, and conventions; readable cold, with no reference to other steps' unmerged work.
- **Tasks** — concrete, ordered actions implementing this one PR.
- **Dependencies** — the step IDs that must merge first; `none` if it can start immediately.
- **Exit criteria** — observable, verifiable conditions that prove the step is done: tests to pass, behavior to confirm, and the exact verification commands to run.
- **PR** — title in English; body as Markdown linking the issue (`Closes #N`) when one exists. Open with `gh` when available; otherwise output the title and body for the human to open manually and say so.
**Parallelism summary** — the dependency graph (e.g. `1 -> 2 -> 4`, `3` parallel to `2`) and an explicit list of step sets that may run concurrently because they share no files and no dependency edge.
## Done when
- The plan has 3-12 steps, each one mergeable pull request.
- Every step has a self-contained cold-start context brief, explicit dependencies, and observable exit criteria.
- The parallelism summary states what can run concurrently and what must be sequential, with no hidden shared-file conflicts.
- The Review pass found no remaining anti-patterns.
- Branch, commit, and PR templates follow `@rules/git/general.mdc` and degrade gracefully when `gh` is absent.
- The plan is registered as Markdown in the repo and its path is reported.