blueprint-os 1.0.0

package/adapters/antigravity.md

@@ -0,0 +1,147 @@
+# Using Blueprint OS in Antigravity
+
+Blueprint OS uses the `.agent/skills/` structure natively — the same format Antigravity expects. No extra setup required.
+
+---
+
+## Setup
+
+Copy the `.agent/` folder into the root of your project:
+
+```
+your-project/
+├── .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/
+├── standards/
+├── references/
+└── ... your code
+```
+
+Antigravity will automatically detect skills in `.agent/skills/` and make them available to the agent.
+
+---
+
+## Triggering skills
+
+Antigravity picks up skills by their `name` field (defined in YAML frontmatter). Trigger them naturally:
+
+| What you say | Skill triggered |
+|---|---|
+| "Brainstorm [idea]" / "Think through [feature]" / "Explore [problem]" | `brainstorming` |
+| "Create a skill for X" / "Find a skill for X" | `creating-skills` |
+| "Shape a spec for X" / "Plan this feature" | `shaping-specs` |
+| "Document my standards" / "Extract patterns" | `discovering-standards` |
+| "Deploy standards" / "Inject context for X" | `deploying-standards` |
+| "Add tests" / "QA" / "Validate acceptance criteria" | `quality-assurance` |
+| "Security audit" / "SEC" / "Audit for vulnerabilities" | `security-audit` |
+| "Review" / "REV" / "Final review" / "Ready for merge" | `code-review` |
+
+---
+
+## Typical workflow in Antigravity
+
+**New product (no codebase yet):**
+
+```
+Brainstorm a [product idea] — I want to explore the problem and options before writing any code.
+```
+
+Then:
+
+```
+Shape a spec using the brainstorm document in specs/brainstorm-<name>.md.
+```
+
+**New feature in a legacy codebase:**
+
+```
+Document the standards for my codebase — start with the tech stack and naming conventions.
+```
+
+Then:
+
+```
+Brainstorm [feature] with the discovered standards loaded as constraints.
+```
+
+Then:
+
+```
+Shape a spec using the brainstorm document.
+```
+
+**Small feature or bug fix (approach already clear):**
+
+```
+Shape a spec for [feature].
+```
+
+**Before coding:**
+
+```
+Deploy standards relevant to building [task].
+```
+
+**After execution (quality gates):**
+
+```
+Add tests for [feature].
+```
+
+Then, if the change touches auth, API, or sensitive data:
+
+```
+Security audit for [feature].
+```
+
+Before merge:
+
+```
+Review [feature] before merge.
+```
+
+**Adding a skill:**
+
+```
+Find or create a skill for [task].
+```
+
+---
+
+## Adding your own skills
+
+Use the `creating-skills` skill — it searches skills.sh first, then creates from scratch if nothing suitable exists:
+
+```
+Find or create a skill for [task]
+```
+
+The agent will check [skills.sh](https://skills.sh) first (`npx skills add find-skills`), install a community skill if available, or create a new one following `.agent/skills/creating-skills/SKILL.md`.
+
+---
+
+## Notes
+
+- The `description` field in each `SKILL.md` controls when Antigravity auto-triggers a skill — keep it specific with clear keywords
+- Brainstorm documents are saved to `specs/brainstorm-<name>.md` — reference them when shaping the spec
+- Standards files in `standards/` are plain markdown — reference them in your prompts or let the `deploying-standards` skill load them automatically
+- Reference designs and diagrams in `references/` — the spec lists applicable references; `deploying-standards` loads them before implementation
+- Spec files are saved to `specs/` — reference them in subsequent sessions to maintain continuity
+- For skills.sh integration, see [skills-sh.md](skills-sh.md)

package/adapters/claude-code.md

@@ -0,0 +1,160 @@
+# Using Blueprint OS in Claude Code
+
+Claude Code works with markdown files natively. Blueprint OS skills are referenced via `@file` syntax or through custom slash commands you define.
+
+---
+
+## Option A — @file reference (simplest)
+
+Reference any skill directly in your prompt using the `@` file reference:
+
+```
+@.agent/skills/brainstorming/SKILL.md — brainstorm a [product or feature idea]
+```
+
+Claude Code will read the file and follow the skill's instructions for the rest of the session.
+
+---
+
+## Option B — Custom slash commands (recommended for daily use)
+
+Claude Code supports custom slash commands defined in `.claude/commands/`. Create one command per skill.
+
+**Create `.claude/commands/brainstorm.md`:**
+
+```markdown
+Read the file `.agent/skills/brainstorming/SKILL.md` and follow all instructions in it for the current task.
+```
+
+**Create `.claude/commands/shape-spec.md`:**
+
+```markdown
+Read the file `.agent/skills/shaping-specs/SKILL.md` and follow all instructions in it for the current task.
+```
+
+**Create `.claude/commands/deploy-standards.md`:**
+
+```markdown
+Read the file `.agent/skills/deploying-standards/SKILL.md` and follow all instructions in it.
+```
+
+**Create `.claude/commands/discover-standards.md`:**
+
+```markdown
+Read the file `.agent/skills/discovering-standards/SKILL.md` and follow all instructions in it.
+```
+
+**Create `.claude/commands/create-skill.md`:**
+
+```markdown
+Read the file `.agent/skills/creating-skills/SKILL.md` and follow all instructions in it.
+```
+
+**Create `.claude/commands/qa.md`:**
+
+```markdown
+Read the file `.agent/skills/quality-assurance/SKILL.md` and follow all instructions in it.
+```
+
+**Create `.claude/commands/security-audit.md`:**
+
+```markdown
+Read the file `.agent/skills/security-audit/SKILL.md` and follow all instructions in it.
+```
+
+**Create `.claude/commands/code-review.md`:**
+
+```markdown
+Read the file `.agent/skills/code-review/SKILL.md` and follow all instructions in it.
+```
+
+Then invoke them with:
+
+```
+/brainstorm — explore the idea for [product or feature]
+/shape-spec — formalize the spec using specs/brainstorm-<name>.md
+/deploy-standards — I'm about to build a REST API
+/discover-standards — extract naming conventions
+/create-skill — find or create a skill for database migrations
+/qa — add tests for [feature]
+/security-audit — audit [feature] for vulnerabilities
+/code-review — review [feature] before merge
+```
+
+---
+
+## Typical workflow in Claude Code
+
+**New product (no codebase yet):**
+
+```
+/brainstorm — explore the idea for [product]
+/shape-spec — formalize specs/brainstorm-<name>.md into an implementation spec
+/deploy-standards — inject relevant standards for [first task]
+```
+
+**New feature in a legacy codebase:**
+
+```
+/discover-standards — extract patterns from the existing codebase
+/brainstorm — explore [feature] within the existing constraints
+/shape-spec — formalize specs/brainstorm-<name>.md
+/deploy-standards — inject standards before implementation
+```
+
+**Small feature or bug fix (approach already clear):**
+
+```
+/shape-spec — plan [feature]
+/deploy-standards — inject relevant standards
+```
+
+**Adding a skill:**
+
+```
+/create-skill — find or create a skill for [task]
+```
+
+---
+
+## CLAUDE.md integration
+
+Add a section to your project's `CLAUDE.md` to make Blueprint OS always available:
+
+```markdown
+## Blueprint OS
+
+This project uses Blueprint OS for agent workflows.
+
+- Skills: `.agent/skills/`
+- Standards: `standards/`
+- Specs: `specs/` (brainstorm docs + implementation specs)
+- References: `references/` (design docs, flowcharts, diagrams)
+
+### Workflow
+
+For new or complex features:
+1. Run `/brainstorm` to explore the problem and options
+2. Run `/shape-spec` using the brainstorm document
+3. Run `/deploy-standards` to load relevant standards
+4. Proceed with implementation
+
+For small tasks where the approach is clear:
+1. Run `/shape-spec` or skip straight to `/deploy-standards`
+2. Proceed with implementation
+
+Before merge (quality gates):
+1. Run `/qa` to add or update tests
+2. Run `/security-audit` when changes touch auth, API, or sensitive data
+3. Run `/code-review` as the final gate
+```
+
+---
+
+## Notes
+
+- Standards files in `standards/` can be referenced with `@standards/api-design.md` to include them directly in context
+- Reference designs and diagrams in `references/` with `@references/checkout-flow.mmd` or `@references/agent-workflow/superpowers-link.md`
+- Brainstorm documents (`specs/brainstorm-<name>.md`) and spec files (`specs/<feature>.md`) persist across sessions — always reference them when resuming work
+- The `@file` approach works in any Claude Code session without any setup
+- For skills.sh integration, see [skills-sh.md](skills-sh.md)

package/adapters/cursor.md

@@ -0,0 +1,131 @@
+# Using Blueprint OS in Cursor
+
+Cursor reads rules from `.cursor/rules/` and skills from a skills directory. Blueprint OS skills live in `.agent/skills/` as portable markdown files. This guide shows how to connect them.
+
+---
+
+## Option A — Reference skills via Cursor Rules (recommended)
+
+Create a rule file that tells Cursor's agent where to find Blueprint OS skills.
+
+**Create `.cursor/rules/blueprint-os.mdc`:**
+
+```markdown
+---
+description: Blueprint OS skill loader. Apply when the user mentions a skill or asks to brainstorm, shape a spec, discover standards, deploy standards, create a skill, add tests, security audit, or code review.
+globs:
+alwaysApply: false
+---
+
+# Blueprint OS
+
+Blueprint OS skills are located in `.agent/skills/`. When the user invokes a skill, read the corresponding `SKILL.md` and follow its instructions.
+
+## Available skills
+
+- **Brainstorming** → `.agent/skills/brainstorming/SKILL.md`
+- **Creating skills** → `.agent/skills/creating-skills/SKILL.md`
+- **Shaping specs** → `.agent/skills/shaping-specs/SKILL.md`
+- **Discovering standards** → `.agent/skills/discovering-standards/SKILL.md`
+- **Deploying standards** → `.agent/skills/deploying-standards/SKILL.md`
+- **Quality assurance** → `.agent/skills/quality-assurance/SKILL.md`
+- **Security audit** → `.agent/skills/security-audit/SKILL.md`
+- **Code review** → `.agent/skills/code-review/SKILL.md`
+
+## How to trigger
+
+Say: "Use the [skill-name] skill" or "Read the [skill-name] SKILL.md and follow it."
+```
+
+---
+
+## Option B — Use Cursor Skills (`.cursor/skills/`)
+
+If you have a Cursor skills directory set up, you can create stub skills that reference the Blueprint OS `SKILL.md` files.
+
+**Create `.cursor/skills/brainstorming/SKILL.md`:**
+
+```markdown
+---
+name: brainstorming
+description: Explores a problem through Socratic questioning before any spec or code is written. Delegates to Blueprint OS. Use when the user wants to think through a new product or feature.
+---
+
+# Brainstorming
+
+Read `.agent/skills/brainstorming/SKILL.md` and follow all instructions there.
+```
+
+Repeat this pattern for each Blueprint OS skill. The stub keeps your Cursor skills directory tidy while the actual logic lives in the portable `.agent/skills/` files.
+
+---
+
+## Option C — Direct file reference
+
+In any Cursor chat, reference a skill directly with `@`:
+
+```
+@.agent/skills/brainstorming/SKILL.md — brainstorm [product or feature idea]
+```
+
+Cursor will include the file content in context and the agent will follow the skill's instructions.
+
+---
+
+## Typical workflow in Cursor
+
+**New product (no codebase yet):**
+
+```
+@.agent/skills/brainstorming/SKILL.md — brainstorm [product idea]
+@.agent/skills/shaping-specs/SKILL.md — shape a spec using specs/brainstorm-<name>.md
+@.agent/skills/deploying-standards/SKILL.md — inject standards for [task]
+```
+
+**New feature in an existing codebase:**
+
+```
+@.agent/skills/discovering-standards/SKILL.md — document [area] standards
+@.agent/skills/brainstorming/SKILL.md — brainstorm [feature] with existing standards loaded
+@.agent/skills/shaping-specs/SKILL.md — shape a spec using specs/brainstorm-<name>.md
+@.agent/skills/deploying-standards/SKILL.md — inject standards for [task]
+```
+
+**Small feature or bug fix (approach already clear):**
+
+```
+@.agent/skills/shaping-specs/SKILL.md — shape a spec for [feature]
+@.agent/skills/deploying-standards/SKILL.md — inject relevant standards for [task]
+```
+
+**Extracting patterns from existing code:**
+
+```
+@.agent/skills/discovering-standards/SKILL.md — document the API design standards
+```
+
+**Adding a new skill:**
+
+```
+@.agent/skills/creating-skills/SKILL.md — find or create a skill for [task]
+```
+
+**Before merge (quality gates):**
+
+```
+@.agent/skills/quality-assurance/SKILL.md — add tests for [feature]
+@.agent/skills/security-audit/SKILL.md — audit [feature] for vulnerabilities
+@.agent/skills/code-review/SKILL.md — review [feature] before merge
+```
+
+Run QA after implementation. Run SEC when changes touch auth, API, or sensitive data. Run REV as the final gate.
+
+---
+
+## Notes
+
+- Standards files in `standards/` can also be referenced with `@standards/tech-stack.md`
+- Reference designs and diagrams in `references/` with `@references/checkout-flow.mmd` or `@references/agent-workflow/superpowers-link.md`
+- Brainstorm documents and spec files saved to `specs/` are readable the same way
+- The `.agent/` folder is invisible to most file trees by default — open it explicitly if needed
+- For skills.sh integration, see [skills-sh.md](skills-sh.md)

package/adapters/skills-sh.md

@@ -0,0 +1,134 @@
+# Using skills.sh with Blueprint OS
+
+[skills.sh](https://skills.sh) is an open registry of reusable agent skills. Skills install directly into `.agent/skills/` — the same directory Blueprint OS uses — so they work together with no extra configuration.
+
+---
+
+## How it works
+
+```
+npx skills add <owner/repo>
+```
+
+This command installs one or more skills from a GitHub repo into your project's `.agent/skills/` folder. Installed skills are immediately available to your agent as Blueprint OS skills.
+
+Skills.sh supports Cursor, Antigravity, Claude Code, Codex, Cline, Windsurf, and more — the same tools Blueprint OS targets.
+
+---
+
+## Discovering skills
+
+**Option 1 — Use the find-skills skill:**
+
+```bash
+npx skills add find-skills
+```
+
+This installs a meta-skill that can search the registry for you. Then ask your agent:
+
+```
+Use the find-skills skill to find a skill for [task]
+```
+
+**Option 2 — Browse the registry directly:**
+
+Visit [skills.sh](https://skills.sh) and search by keyword or browse by category.
+
+**Option 3 — Search by GitHub org:**
+
+Many popular tool maintainers publish official skills:
+
+| Publisher | Install command | What's inside |
+|---|---|---|
+| Vercel | `npx skills add vercel-labs/agent-skills` | React, Next.js, Vercel deployment |
+| Supabase | `npx skills add supabase/agent-skills` | Postgres, auth, storage best practices |
+| Anthropic | `npx skills add anthropics/skills` | PDF, PPTX, DOCX, frontend design, MCP |
+| Expo | `npx skills add expo/skills` | React Native, EAS, native APIs |
+| Obra | `npx skills add obra/superpowers` | Planning, debugging, git worktrees, subagents |
+| wshobson | `npx skills add wshobson/agents` | API design, testing, architecture patterns |
+
+---
+
+## Installing skills
+
+```bash
+# Single repo (may contain multiple skills)
+npx skills add supabase/agent-skills
+
+# Install a specific skill by name
+npx skills add obra/superpowers systematic-debugging
+```
+
+Skills land in `.agent/skills/<skill-name>/SKILL.md`. Open them to inspect what was installed.
+
+---
+
+## Evaluating a skill after install
+
+After installing, read the skill's `SKILL.md` and ask:
+
+1. Does the workflow match your needs exactly? → Use as-is
+2. Does it cover 70–80% of your need? → Customize it
+3. Does it cover a completely different use case? → Delete it and build from scratch
+
+---
+
+## Customizing an installed skill
+
+Open `.agent/skills/<skill-name>/SKILL.md` and:
+
+- **Keep** the core workflow steps and any low-freedom (exact command) sections
+- **Update** paths, naming conventions, and tool references to match your project
+- **Add** a `## Project context` section at the bottom with project-specific notes
+- **Remove** sections that don't apply to your stack
+
+When your changes are substantial, rename the folder to distinguish your fork from upstream:
+
+```
+.agent/skills/supabase-postgres/     ← upstream name
+.agent/skills/postgres-migrations/   ← your customized version
+```
+
+---
+
+## Publishing your own skills
+
+If you've built a Blueprint OS skill that others would benefit from, you can publish it to skills.sh.
+
+**Requirements:**
+- Skill must be in a public GitHub repository
+- Must follow the standard `SKILL.md` format with valid YAML frontmatter
+- `name` must be unique and in gerund form
+- `description` must be written in third person with clear triggers
+
+**Publishing steps:**
+
+1. Push your `.agent/skills/<skill-name>/` folder to a public GitHub repo
+2. Submit your skill at [skills.sh](https://skills.sh) (follow the site's submission process)
+3. Others can then install it with `npx skills add <your-github-username>/<repo>`
+
+**Tip:** Structure your repo so each skill is its own folder at the root — that's the convention the `npx skills add` command expects.
+
+---
+
+## Recommended skills for Blueprint OS workflows
+
+These community skills complement Blueprint OS directly:
+
+| Skill | Install | Pairs with |
+|---|---|---|
+| `systematic-debugging` | `npx skills add obra/superpowers` | Any execution phase |
+| `writing-plans` | `npx skills add obra/superpowers` | `shaping-specs` |
+| `executing-plans` | `npx skills add obra/superpowers` | After `deploying-standards` |
+| `requesting-code-review` | `npx skills add obra/superpowers` | After execution |
+| `api-design-principles` | `npx skills add wshobson/agents` | `discovering-standards` for API projects |
+| `test-driven-development` | `npx skills add obra/superpowers` | Before writing new features |
+
+---
+
+## Notes
+
+- skills.sh skills use the same `SKILL.md` format as Blueprint OS — no conversion needed
+- If `npx skills add` is not available, clone the repo and copy the skill folder manually into `.agent/skills/`
+- Community skills may not follow all Blueprint OS conventions — review before use
+- Pin to a specific commit if you need a stable, reproducible skill version

package/bin/blueprint-os.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+const { init } = require('../lib/init');
+
+const [cmd] = process.argv.slice(2);
+
+if (cmd === 'init') {
+  init(process.cwd());
+} else {
+  console.log('Blueprint OS - AI agent workflow system\n');
+  console.log('Usage: npx blueprint-os init');
+  console.log('\nCopies .agent/, standards/, and references/ into your project.');
+  process.exit(1);
+}

package/lib/init.js

@@ -0,0 +1,43 @@
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const FOLDERS = ['.agent', 'standards', 'references', 'adapters'];
+
+function init(cwd) {
+  const resolvedCwd = path.resolve(cwd);
+  const resolvedRoot = path.resolve(PACKAGE_ROOT);
+  if (resolvedCwd === resolvedRoot || resolvedCwd.startsWith(resolvedRoot + path.sep)) {
+    console.log('You are inside the Blueprint OS package. Run from your project directory instead:\n');
+    console.log('  cd /path/to/your-project');
+    console.log('  npx blueprint-os init\n');
+    return;
+  }
+
+  console.log('Installing Blueprint OS...\n');
+
+  for (const folder of FOLDERS) {
+    const src = path.join(PACKAGE_ROOT, folder);
+    const dest = path.join(cwd, folder);
+
+    if (!fs.existsSync(src)) {
+      console.warn(`  Skipping ${folder}/ (not found in package)`);
+      continue;
+    }
+
+    fs.cpSync(src, dest, { recursive: true });
+    console.log(`  ✓ ${folder}/`);
+  }
+
+  const specsDir = path.join(cwd, 'specs');
+  if (!fs.existsSync(specsDir)) {
+    fs.mkdirSync(specsDir, { recursive: true });
+    console.log('  ✓ specs/ (created)');
+  }
+
+  console.log('\nDone. Blueprint OS is ready.');
+  console.log('\nNext: Read adapters/cursor.md for Cursor setup, or run:');
+  console.log('  npx blueprint-os --help');
+}
+
+module.exports = { init };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "blueprint-os",
+  "version": "1.0.0",
+  "description": "A portable, tool-agnostic AI agent workflow system built on skills and standards",
+  "bin": {
+    "blueprint-os": "./bin/blueprint-os.js"
+  },
+  "files": [
+    ".agent",
+    "standards",
+    "references",
+    "adapters",
+    "bin",
+    "lib"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "workflow",
+    "cursor",
+    "claude",
+    "standards",
+    "specs"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gj1342/blueprint-os"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}