# Blueprint > 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. - Skill: `pekral/blueprint` (Agent Skill) - Install (CLI): `npx skillmds@latest add pekral/blueprint` - Raw SKILL.md: https://api.skillmd.com/api/skills/pekral/blueprint/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - License: MIT - Author: pekral (https://skillmd.com/u/pekral) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pekral/blueprint --- # 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//`): 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/`). - **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.