FrancoStino/blueprint

Blueprint — Construction Plan Generator

Turn a one-line objective into a step-by-step plan any coding agent can execute cold.

Overview

Blueprint is for multi-session, multi-agent engineering projects where each step must be independently executable by a fresh agent that has never seen the conversation history. Install it once, invoke it with /blueprint <project> <objective>.

When to Use This Skill

• Use when the task requires multiple PRs or sessions
• Use when multiple agents or team members need to share execution
• Use when you want adversarial review of the plan before execution
• Use when parallel step detection and dependency graphs matter

How It Works

1. Research — Scans the codebase, reads project memory, runs pre-flight checks
2. Design — Breaks the objective into one-PR-sized steps, identifies parallelism, assigns model tiers
3. Draft — Generates the plan from a structured template with branch workflow rules, CI policy, and rollback strategies inline
4. Review — Delegates adversarial review to a strongest-model sub-agent (falls back to default model if unavailable)
5. Register — Saves the plan and updates project memory

Examples

Example 1: Database migration

/blueprint myapp "migrate database to PostgreSQL"

Example 2: Plugin extraction

/blueprint antbot "extract providers into plugins"

Best Practices

• ✅ Use for tasks requiring 3+ PRs or multiple sessions
• ✅ Let Blueprint auto-detect git/gh availability — it degrades gracefully
• ❌ Don't invoke for tasks completable in a single PR
• ❌ Don't invoke when the user says "just do it"

Key Differentiators

• Cold-start execution: Every step has a self-contained context brief
• Adversarial review gate: Strongest-model review before execution
• Markdown-first distribution: The reviewed revision is primarily instructions and templates, but installing or following it can still cause an agent to run commands. Treat the repository as untrusted until inspected.
• Plan mutation protocol: Steps can be split, inserted, skipped with audit trail

Installation

Do not clone a moving branch directly into an active skills directory. First ask the user to approve network access to the named repository. Then inspect the reviewed revision and ask separately before activating it:

review_dir="$(mktemp -d)"
git clone --filter=blob:none https://github.com/antbotlab/blueprint.git "$review_dir/blueprint"
git -C "$review_dir/blueprint" checkout --detach 07c5b305cf2d95d584a0d0398c390e839fec5954
git -C "$review_dir/blueprint" ls-files
git -C "$review_dir/blueprint" status --short

Read SKILL.md and every bundled file at that exact commit. Check for scripts, hooks, symlinks, network calls, credential access, and instructions that request commands or elevated permissions. Only after explicit user approval, copy the reviewed files into the selected host's skills directory. Re-review a newer revision instead of silently updating this pin.

Additional Resources

• GitHub Repository
• Examples: small plan
• Examples: large plan

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
• A pinned revision is reproducible, not automatically trustworthy; its contents still require review.