Blueprint OS

A portable, tool-agnostic AI agent workflow system built on skills and standards. Works in Cursor, Antigravity, Claude Code, or any AI IDE.

What is Blueprint OS?

Every time you start a new session with an AI agent, you re-teach it your context — your conventions, your architecture, your preferences. Blueprint OS eliminates that friction.

It gives your AI agent a persistent operating system:

• Skills — reusable instruction sets the agent follows for specific tasks
• Standards — documented patterns extracted from your codebase
• Specs — structured plans shaped before execution

Since everything is plain markdown, it works with any tool that can read files.

Workflow

flowchart TD
    Start([New Product or Feature]) --> IsNew{New or existing codebase?}
    IsNew -->|New product| Brainstorm[Brainstorm]
    IsNew -->|Existing codebase| DiscoverStandards[Discover Standards]
    DiscoverStandards --> Brainstorm

    subgraph planning [Planning]
        Brainstorm --> ShapeSpec[Shape Spec]
        ShapeSpec --> DeployStandards[Deploy Standards & References]
    end

    subgraph execution [Execution]
        DeployStandards --> Execute[Execute with Agent]
    end

    subgraph qualityGates [Quality Gates - Optional]
        Execute --> QA[Quality Assurance]
        QA --> SEC[Security Audit]
        SEC --> REV[Code Review]
    end

    REV --> Review{Review Output}
    Review -->|Standards need updating| DiscoverStandards
    Review -->|Next feature| Brainstorm
    Review -->|New capability needed| SearchSkillssh[Search skills.sh]
    SearchSkillssh -->|Found| InstallSkill[Install and customize]
    SearchSkillssh -->|Not found| CreateSkill[Create from scratch]
    InstallSkill --> ShapeSpec
    CreateSkill --> ShapeSpec

The Core Loop

| Step | What happens | Skill | |---|---|---| | 1. Plan Product | Document your mission, stack, and roadmap | (manual) | | 2. Discover Standards | Extract patterns from your codebase into standards/ files | discovering-standards | | 3. Brainstorm | Explore the problem, compare approaches, produce a design document | brainstorming | | 4. Shape Spec | Formalize the chosen direction into an implementation spec | shaping-specs | | 5. Deploy Standards | Inject relevant standards and references into the agent's context | deploying-standards | | 6. Execute | Run the agent with full context | (your agent) | | 7a. Quality Assurance (optional) | Add or update tests against acceptance criteria | quality-assurance | | 7b. Security Audit (optional) | Audit auth, API, or sensitive data changes | security-audit | | 7c. Code Review (optional) | Validate against spec and standards before merge | code-review | | 8. Review & Refine | Update standards as patterns evolve | repeat |

Quick Start

1. Install Blueprint OS into your project

From your project directory:

npx blueprint-os init

This copies .agent/, standards/, references/, and adapters/ into your project. No dependency is added to package.json. The find-skills skill is included so you can search the skills.sh registry without installing it separately.

Conditional copy: If standards/ or references/ already contain project content (files beyond the template), they are preserved and not overwritten.

Or copy manually: Place the .agent/ folder, standards/ folder, and references/ folder at the root of your project:

your-project/
├── .agent/
│   └── skills/
│       ├── find-skills/      ← pre-installed
│       ├── brainstorming/
│       └── ...
├── standards/
├── references/
└── ... your code

2. Choose your tool

| Tool | Setup | Guide | |---|---|---| | Cursor | Reference SKILL.md files via .cursor/rules/ | adapters/cursor.md | | Antigravity | Native — .agent/skills/ is the default path | adapters/antigravity.md | | Claude Code | Use slash commands or @file references | adapters/claude-code.md | | skills.sh | Install community skills with npx skills add | adapters/skills-sh.md | | Any other AI | Paste or reference SKILL.md content directly | Read the skill file and include it in your prompt |

3. Run your first workflow

Starting a new product (no codebase yet):

1. Ask your agent: "Read .agent/skills/brainstorming/SKILL.md and brainstorm [product idea]"
2. Ask your agent: "Read .agent/skills/shaping-specs/SKILL.md and shape a spec using specs/brainstorming/<name>/design.md"
3. Ask your agent: "Read .agent/skills/deploying-standards/SKILL.md and inject relevant standards for [task]"

Starting a new feature in an existing codebase:

1. Ask your agent: "Read .agent/skills/discovering-standards/SKILL.md and document my codebase standards"
2. Ask your agent: "Read .agent/skills/brainstorming/SKILL.md and brainstorm [feature] with the existing standards loaded"
3. Ask your agent: "Read .agent/skills/shaping-specs/SKILL.md and shape a spec using specs/brainstorming/<name>/design.md"
4. Ask your agent: "Read .agent/skills/deploying-standards/SKILL.md and inject relevant standards for [task]"

Adding a new skill:

1. Use the pre-installed find-skills: "Read .agent/skills/find-skills/SKILL.md and find a skill for [task]" — or browse https://skills.sh
2. If found: npx skills add <owner/repo> -a antigravity -y --copy
3. If not found: ask your agent "Read .agent/skills/creating-skills/SKILL.md and create a skill for [task]"

Updating Blueprint OS

To refresh core skills and adapters without touching your content:

npx blueprint-os@latest update

What update does:

• Updates core skills in .agent/skills/ (brainstorming, shaping-specs, discovering-standards, etc.)
• Updates adapters/
• Refreshes references/agent-workflow/ and references/README.md
• Refreshes standards/README.md

What update preserves:

• specs/ — never touched
• Your standards files (e.g. api-design.md, error-handling.md)
• Your reference files (anything beyond agent-workflow/)
• Community skills you installed from skills.sh

Conditional copy on init: If you run init again, standards/ and references/ are preserved when they already contain project content (files beyond the shipped template).

Skills Index

Skills live in .agent/skills/. Each skill is a SKILL.md file the agent reads and follows.

| Skill | Path | Purpose | |---|---|---| | Find Skills | .agent/skills/find-skills/ | Search the skills.sh registry for community skills (pre-installed) | | Brainstorming | .agent/skills/brainstorming/ | Explore problems, compare approaches, produce a design document | | Creating Skills | .agent/skills/creating-skills/ | Find on skills.sh first, author from scratch as fallback | | Shaping Specs | .agent/skills/shaping-specs/ | Formalize a chosen direction into an implementation spec | | Discovering Standards | .agent/skills/discovering-standards/ | Extract codebase patterns into standards files | | Deploying Standards | .agent/skills/deploying-standards/ | Inject relevant standards and references into agent context | | Quality Assurance | .agent/skills/quality-assurance/ | Add or update tests, validate against acceptance criteria | | Security Audit | .agent/skills/security-audit/ | Audit auth, API, and sensitive data changes before merge | | Code Review | .agent/skills/code-review/ | Final validation against spec and standards before merge |

Community skills from skills.sh install into .agent/skills/ when you use -a antigravity -y --copy. The --copy flag creates real files so deleting .agents (created when Cursor is detected) won't break the skill.

When to brainstorm vs. shape a spec

These two skills are sequential, not interchangeable.

| Situation | Start with | |---|---| | You know what to build and how | shaping-specs directly | | You know what to build but not how | brainstorming first | | You have a rough idea but it's unclear | brainstorming first | | New product, no codebase yet | brainstorming first | | New feature in a legacy codebase | discovering-standards → brainstorming → shaping-specs | | Bug fix or small task | shaping-specs or skip to deploying-standards |

Brainstorming produces a design document (specs/brainstorming/<name>/design.md). Spec shaping picks that up and formalizes it into an implementation spec (specs/shaped-specs/<name>/spec.md). They're two steps in the same pipeline, not alternatives.

When to use quality gates

Quality gates run after implementation and before merge. They are optional — use them when rigor matters.

| Gate | When to run | |------|-------------| | quality-assurance | After implementation; add or update tests against spec acceptance criteria | | security-audit | Required for auth flows, API endpoints, sensitive data handling | | code-review | Before merge; validates scope alignment and that SEC was run when required |

Typical order: QA → SEC (if auth/API/sensitive) → REV.

Scenarios

Real-world walkthroughs showing exactly how Blueprint OS fits into your work.

Scenario 1 — Brand new SaaS product

You have an idea. No code exists yet.

Step 1: Brainstorm the product

Read .agent/skills/brainstorming/SKILL.md and brainstorm a task management app for remote teams

The agent asks Socratic questions, presents 3 approaches (e.g., kanban vs. list-based vs. AI-prioritized), and saves the chosen direction to specs/brainstorming/task-app/design.md.

Step 2: Shape the first feature spec

Read .agent/skills/shaping-specs/SKILL.md and shape a spec using specs/brainstorming/task-app/design.md

The agent formalizes the brainstorm into specs/shaped-specs/user-auth/spec.md with scope, success criteria, and implementation notes.

Step 3: Execute

Read .agent/skills/deploying-standards/SKILL.md and inject standards and references for building a Next.js auth system

The agent loads any standards and references you have (design docs, flowcharts if present) and proceeds to build with full context.

Scenario 2 — New feature in a legacy codebase

You've been handed a 3-year-old Express API and need to add a payments feature.

Step 1: Discover what conventions already exist

Read .agent/skills/discovering-standards/SKILL.md and document the API design standards

The agent reads your existing routes, middleware, and error handling patterns, then saves standards/backend/api-design.md and standards/backend/error-handling.md.

Step 2: Brainstorm the payments feature within those constraints

Read .agent/skills/brainstorming/SKILL.md and brainstorm a Stripe payments integration with the existing standards loaded

The agent loads your standards as constraints, explores integration approaches (webhook-first vs. sync, where to put the service layer, etc.), and saves specs/brainstorming/payments/design.md.

Step 3: Shape the spec

Read .agent/skills/shaping-specs/SKILL.md and shape a spec using specs/brainstorming/payments/design.md

Saves specs/shaped-specs/payments-feature/spec.md with relevant files mapped out, risks identified, and applicable standards and references.

Step 4: Build

Read .agent/skills/deploying-standards/SKILL.md and inject standards and references for implementing a payment service

Agent loads api-design.md, error-handling.md, and any references listed in the spec (e.g. payment flow diagram), then executes against the spec.

Scenario 3 — Quick bug fix

A button submits twice on slow connections. Approach is already clear.

Skip brainstorming entirely. Go straight to deployment.

Read .agent/skills/deploying-standards/SKILL.md and inject standards and references — I'm fixing a double-submit bug in the checkout form

Agent loads component-patterns.md, error-handling.md, and any relevant references, then fixes the issue without any planning overhead.

Scenario 4 — Adding a capability your agent doesn't have

You want the agent to follow a strict TDD workflow but Blueprint OS has no skill for it.

Step 1: Use the pre-installed find-skills

Read .agent/skills/find-skills/SKILL.md and find a skill for test-driven development

Found: obra/superpowers has test-driven-development.

Step 2: Install it

npx skills add obra/superpowers --skill test-driven-development -a antigravity -y --copy

Lands in .agent/skills/test-driven-development/SKILL.md — immediately available.

Step 3: Use it in your workflow

Read .agent/skills/test-driven-development/SKILL.md and implement the payments service using TDD

Scenario 5 — Resuming work in a new session

You shaped a spec yesterday. Today you're back in a fresh chat with no context.

Read specs/shaped-specs/payments-feature/spec.md — this is what we're building.
Read .agent/skills/deploying-standards/SKILL.md and inject the relevant standards and references for continuing this work.

The spec, standards, and references persist on disk. The agent picks up exactly where you left off, no re-explaining needed.

Scenario 6 — Before merging a feature

Implementation is done. You want tests, a security check, and a final review before merge.

Step 1: Add tests

Read .agent/skills/quality-assurance/SKILL.md and add tests for [feature]

Agent loads the spec, identifies acceptance criteria, adds or updates tests, records evidence.

Step 2: Security audit (if auth, API, or sensitive data)

Read .agent/skills/security-audit/SKILL.md and audit [feature] for vulnerabilities

Agent runs through the security checklist, produces an audit report, blocks merge if Critical or High findings exist.

Step 3: Code review

Read .agent/skills/code-review/SKILL.md and review [feature] before merge

Agent validates scope alignment, confirms SEC was run when required, and confirms readiness for merge.

Project Structure

blueprint-os/
├── README.md
├── .agent/
│   └── skills/
│       ├── brainstorming/
│       │   └── SKILL.md
│       ├── creating-skills/
│       │   └── SKILL.md
│       ├── shaping-specs/
│       │   └── SKILL.md
│       ├── discovering-standards/
│       │   └── SKILL.md
│       ├── deploying-standards/
│       │   └── SKILL.md
│       ├── quality-assurance/
│       │   └── SKILL.md
│       ├── security-audit/
│       │   └── SKILL.md
│       └── code-review/
│           └── SKILL.md
├── specs/
│   ├── brainstorming/<name>/design.md
│   └── shaped-specs/<name>/spec.md (+ quality-assurance.md, security-audit.md, code-review.md when run)
├── standards/
│   ├── README.md
│   ├── backend/
│   ├── frontend/
│   └── design/
├── references/
│   ├── README.md
│   └── agent-workflow/    # Meta: framework links (agent-os, superpowers, etc.)
└── adapters/
    ├── cursor.md
    ├── antigravity.md
    ├── claude-code.md
    └── skills-sh.md

Skill Format

Every SKILL.md is self-contained and follows this universal structure:

---
name: gerund-skill-name
description: Third-person description with specific triggers. Max 1024 chars.
---

# Skill Title

## When to use this skill
- Trigger condition 1
- Trigger condition 2

## Workflow
- [ ] Step 1
- [ ] Step 2

## Instructions
Specific logic, rules, and code examples.

## Resources
- Links to supporting files

This format is compatible with Antigravity natively. For other tools, see the adapters/ folder.

Standards

Standards live in standards/. Shared standards (tech-stack, naming-conventions, folder-structure, testing-approach) are at root; layer-specific standards go in backend/, frontend/, and design/. See standards/README.md for the format and conventions.

References

References live in references/. Design docs, flowcharts, diagrams, and other reference materials that guide implementation. The shaping-specs and deploying-standards skills load relevant references when planning and executing. See references/README.md for the index and conventions.

Philosophy

• Portable — plain markdown files, no vendor lock-in
• Composable — skills are independent and combinable
• Iterative — standards evolve with your codebase
• AI-first — written for agents to read and follow, not for humans to memorize