blueprint-os 1.0.0

package/.agent/skills/security-audit/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: security-audit
+description: Audits code changes for security vulnerabilities and data exposure. Use when the user asks for a security audit, SEC review, or before merge of auth, API, or sensitive data changes. Required for authentication, API endpoints, and sensitive data handling. Applies to frontend and backend.
+---
+
+# Security Audit
+
+## When to use this skill
+
+- User asks to "security audit", "SEC", or "audit for vulnerabilities"
+- Before merge when changes touch authentication, API endpoints, or sensitive data
+- Implementation involves user input, file uploads, or third-party integrations
+- After quality-assurance when tests revealed security-sensitive code paths
+
+## Workflow
+
+- [ ] Load the spec from `specs/<feature-name>.md`
+- [ ] Load changed files and identify security-relevant code
+- [ ] Run through the security checklist (frontend and backend as applicable)
+- [ ] Assign severity to each finding (Critical, High, Medium, Low)
+- [ ] Produce audit report inline or in `specs/<feature-name>-security-audit.md`
+- [ ] Block merge for Critical and High; document Medium and Low for resolution
+
+## Instructions
+
+### When this skill is required
+
+Run security-audit before merge when the change involves:
+
+- Authentication or authorization flows
+- API endpoints (new or modified)
+- Sensitive data (passwords, tokens, PII, API keys)
+- User input processing or file uploads
+- Third-party integrations or external service calls
+
+### Security checklist
+
+**Data protection (frontend and backend)**
+
+- No sensitive data in client-side code, logs, or error messages
+- No passwords, tokens, or API keys in localStorage/sessionStorage without encryption
+- Secrets use environment variables only; .env never committed
+- Validate all user inputs before processing or sending to backend
+- Sanitize outputs to prevent XSS
+
+**Frontend-specific**
+
+- No eval(), Function(), or innerHTML with user-controlled data
+- Token handling uses httpOnly cookies when possible
+- API calls use centralized client; no arbitrary external requests
+- Third-party scripts and dynamic imports reference trusted sources
+
+**Backend-specific**
+
+- Auth checks occur server-side; never trust client for authorization
+- SQL/NoSQL injection prevented via parameterized queries or ORM
+- File uploads validated (type, size) before processing
+- Rate limiting and CORS configured appropriately
+
+**Network**
+
+- HTTPS only for production
+- No credentials in URLs or query params
+- CORS explicitly defined on backend
+
+**Dependencies**
+
+- New dependencies checked for known vulnerabilities (npm audit, etc.)
+- Avoid packages with excessive permissions or unclear provenance
+
+**Configuration**
+
+- .cursorignore blocks agent access to sensitive config
+- Workspace trust enabled for unknown repositories
+
+### Severity levels
+
+| Level | Examples | Action |
+|-------|----------|--------|
+| Critical | Data exposure, auth bypass, arbitrary code execution | Block merge |
+| High | XSS, insecure storage, missing input validation | Block merge |
+| Medium | Verbose errors, dependency vulns, missing error handling | Document for resolution |
+| Low | Style issues that could cause security confusion | Document |
+
+### Audit report format
+
+Save to `specs/<feature-name>-security-audit.md` or append to the spec:
+
+```markdown
+## Security audit — [date]
+
+### Summary
+[Pass / Block — list Critical/High if blocking]
+
+### Findings
+| Severity | Location | Issue | Recommendation |
+|----------|----------|-------|----------------|
+| High | path/to/file.ts:42 | [description] | [fix] |
+
+### Checklist coverage
+- [x] Data protection
+- [x] Input validation
+- [ ] [any unchecked items]
+```
+
+## Handoff
+
+- Recommend running `code-review` after audit
+- If Critical or High: list required fixes; do not recommend merge until resolved
+
+## Resources
+
+- Spec directory: `specs/`
+- Standards: `standards/authentication.md`, `standards/api-design.md` if present
+- Next step: `.agent/skills/code-review/SKILL.md`

package/.agent/skills/shaping-specs/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: shaping-specs
+description: Shapes a structured spec for a feature or task by asking clarifying questions and saving the output to a persistent file. Use when the user wants to plan a feature, create a spec, write a PRD, or define what to build before coding starts.
+---
+
+# Shaping Specs
+
+## When to use this skill
+
+- User wants to plan a feature before implementation
+- User asks to "create a spec", "write a PRD", or "shape this idea"
+- A brainstorm document exists in `specs/brainstorm-<name>.md` and is ready to formalize
+- User is starting work on a new feature, epic, or significant change where the approach is already decided
+
+**If the approach is still undecided or the problem is not fully understood, run `brainstorming` first.**
+Load `.agent/skills/brainstorming/SKILL.md` and complete that workflow before returning here.
+The brainstorm document (`specs/brainstorm-<name>.md`) becomes the starting context for spec shaping.
+
+## Workflow
+
+- [ ] Check for a brainstorm document in `specs/brainstorm-<name>.md` — load it if it exists
+- [ ] Load relevant standards from `standards/` and references from `references/` if they exist
+- [ ] Ask the shaping questions (see below) — skip any already answered in the brainstorm doc
+- [ ] Confirm answers with the user before proceeding
+- [ ] Write the spec file to `specs/<feature-name>.md`
+- [ ] Summarize the spec and confirm it is ready to execute
+
+## Instructions
+
+### Shaping questions
+
+Ask these questions in a conversational flow. Adapt wording to context, but cover every area:
+
+**1. What are we building?**
+- What is the feature or task in one sentence?
+- What problem does it solve for the user?
+
+**2. Who is it for?**
+- Who is the primary user or system consuming this?
+- Are there secondary users or systems affected?
+
+**3. What does success look like?**
+- What is the expected behavior when it works correctly?
+- Are there measurable outcomes or acceptance criteria?
+
+**4. What are the boundaries?**
+- What is explicitly out of scope?
+- Are there constraints (performance, security, compatibility)?
+
+**5. What already exists?**
+- Which files, modules, or components are relevant?
+- Is there existing code to extend, or is this net new?
+
+**6. What are the risks?**
+- What could go wrong?
+- Are there edge cases or failure modes to account for?
+
+**7. What standards apply?**
+- Which entries in `standards/` are relevant to this task?
+
+**8. What references apply?**
+- Are there design docs, flowcharts, or diagrams in `references/` that define this feature?
+
+### Spec file format
+
+Save the completed spec to `specs/<feature-name>.md`:
+
+```markdown
+# Spec: [Feature Name]
+
+**Date:** [YYYY-MM-DD]
+**Status:** Draft | Ready | In Progress | Done
+
+## What we're building
+[One paragraph summary]
+
+## Users and context
+[Who this is for and why]
+
+## Success criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+## Scope
+**In scope:**
+- [Item]
+
+**Out of scope:**
+- [Item]
+
+## Relevant files and modules
+- `path/to/file.ts` — [why it's relevant]
+
+## Risks and edge cases
+- [Risk or edge case]
+
+## Applicable standards
+- `standards/[file].md` — [which section]
+
+## Applicable references
+- `references/[file]` — [design, flowchart, diagram that defines this]
+
+## Implementation notes
+[Any technical direction, decisions, or constraints to carry into execution]
+```
+
+### Execution hand-off
+
+After saving the spec, tell the agent (or user) to run the `deploying-standards` skill before executing, so relevant standards are loaded alongside the spec.
+
+After execution, consider running `quality-assurance`, `security-audit` (for auth, API, or sensitive data changes), and `code-review` before merge.
+
+## Resources
+
+- Run first if approach is undecided: `.agent/skills/brainstorming/SKILL.md`
+- Standards reference: `standards/README.md`
+- References index: `references/README.md`
+- Spec output directory: `specs/`
+- Deploy before executing: `.agent/skills/deploying-standards/SKILL.md`
+- Quality gates after execution: `.agent/skills/quality-assurance/SKILL.md`, `.agent/skills/security-audit/SKILL.md`, `.agent/skills/code-review/SKILL.md`

package/README.md

@@ -0,0 +1,406 @@
+# 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
+
+```mermaid
+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:
+
+```bash
+npx blueprint-os init
+```
+
+This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your project. No dependency is added to `package.json`.
+
+**Or copy manually:** Place the `.agent/` folder, `standards/` folder, and `references/` folder at the root of your project:
+
+```
+your-project/
+├── .agent/
+│   └── skills/
+├── standards/
+├── references/
+└── ... your code
+```
+
+### 2. Choose your tool
+
+| Tool | Setup | Guide |
+|---|---|---|
+| Cursor | Reference SKILL.md files via `.cursor/rules/` | [adapters/cursor.md](adapters/cursor.md) |
+| Antigravity | Native — `.agent/skills/` is the default path | [adapters/antigravity.md](adapters/antigravity.md) |
+| Claude Code | Use slash commands or `@file` references | [adapters/claude-code.md](adapters/claude-code.md) |
+| skills.sh | Install community skills with `npx skills add` | [adapters/skills-sh.md](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/brainstorm-<name>.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/brainstorm-<name>.md"
+4. Ask your agent: "Read .agent/skills/deploying-standards/SKILL.md and inject relevant standards for [task]"
+```
+
+**Adding a new skill:**
+
+```
+1. Browse https://skills.sh or run: npx skills add find-skills
+2. If found: npx skills add <owner/repo>
+3. If not found: ask your agent "Read .agent/skills/creating-skills/SKILL.md and create a skill for [task]"
+```
+
+---
+
+## Skills Index
+
+Skills live in `.agent/skills/`. Each skill is a `SKILL.md` file the agent reads and follows.
+
+| Skill | Path | Purpose |
+|---|---|---|
+| 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](https://skills.sh) install directly into `.agent/skills/` and work with Blueprint OS out of the box. Run `npx skills add <owner/repo>` to install any skill from the registry.
+
+---
+
+## 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/brainstorm-<name>.md`). Spec shaping picks that up and formalizes it into an implementation spec (`specs/<feature-name>.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/brainstorm-task-app.md`.
+
+**Step 2: Shape the first feature spec**
+```
+Read .agent/skills/shaping-specs/SKILL.md and shape a spec using specs/brainstorm-task-app.md
+```
+The agent formalizes the brainstorm into `specs/user-auth.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/api-design.md` and `standards/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/brainstorm-payments.md`.
+
+**Step 3: Shape the spec**
+```
+Read .agent/skills/shaping-specs/SKILL.md and shape a spec using specs/brainstorm-payments.md
+```
+Saves `specs/payments-feature.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: Check skills.sh first**
+```
+npx skills add find-skills
+```
+Then: `Use the find-skills skill to search for a test-driven development skill`
+
+Found: `obra/superpowers` has `test-driven-development`.
+
+**Step 2: Install it**
+```
+npx skills add obra/superpowers test-driven-development
+```
+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/payments-feature.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/
+│   └── (brainstorm docs and specs saved here)
+├── standards/
+│   └── README.md
+├── 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:
+
+```markdown
+---
+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/](adapters/) folder.
+
+---
+
+## Standards
+
+Standards live in `standards/`. They are plain markdown files documenting the patterns, conventions, and architecture decisions of your specific project. See [standards/README.md](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](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