blueprint-os 1.0.0

package/.agent/skills/brainstorming/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: brainstorming
+description: Explores a problem through Socratic questioning before any spec or code is written. Surfaces real needs, compares approaches, and produces a design document. Use when the user wants to think through a new product, a new feature, a technical decision, or anything where the right approach is still undecided.
+---
+
+# Brainstorming
+
+## When to use this skill
+
+- User says "I want to build X" but hasn't decided how yet
+- Starting a brand new product with no codebase yet
+- Adding a significant feature to an existing codebase
+- A technical or architectural decision needs exploration before committing
+- The approach is unclear or multiple valid paths exist
+- User asks to "brainstorm", "think through", "explore", or "figure out" something
+
+## Workflow
+
+- [ ] Identify which mode applies (see Instructions > Modes)
+- [ ] Load relevant context for the mode (standards, existing files, or nothing)
+- [ ] Ask the brainstorming questions — one section at a time, conversationally
+- [ ] Present 2–3 alternative approaches with tradeoffs after gathering answers
+- [ ] Validate the preferred direction with the user
+- [ ] Save the design document to `specs/brainstorm-<name>.md`
+- [ ] Hand off to `shaping-specs` with the design document as input
+
+## Instructions
+
+### Modes
+
+Pick the mode based on what the user is starting from:
+
+**Mode 1 — New product**
+No codebase exists yet. Start with open-ended exploration. No standards to load. Focus on the problem, the user, and the product vision before any technical decisions.
+
+**Mode 2 — New feature in a legacy codebase**
+A codebase exists. Load `standards/` files first to understand existing patterns and constraints. Brainstorm within those constraints — what fits the existing architecture, what would require deviation and why.
+
+**Mode 3 — New feature with loaded context**
+The user has specific files or modules in mind. Load those files before brainstorming. Keep exploration scoped to the relevant area.
+
+### Brainstorming questions
+
+Ask these in a natural, conversational flow — one section at a time. Do not ask all at once. Wait for responses before moving on.
+
+**1. What is the real problem?**
+- What are you actually trying to solve? (not the solution — the problem)
+- Who experiences this problem and when?
+- What happens today without this? What's the workaround?
+
+**2. What does success look like?**
+- If this works perfectly, what changes for the user?
+- How would you know it worked? What's measurable?
+- What would make this a failure even if it ships?
+
+**3. What are the constraints?**
+- Are there technical boundaries (existing stack, performance, compatibility)?
+- Are there product constraints (scope, timeline, dependencies)?
+- What can we NOT change, no matter what?
+
+**4. What approaches could work?**
+- What's the most obvious solution? What are its downsides?
+- Is there a simpler version that solves 80% of the problem?
+- Is there an existing tool, library, or pattern that does this?
+
+**5. What are the risks?**
+- What could go wrong during implementation?
+- What edge cases will be hardest to handle?
+- What assumption, if wrong, would invalidate the whole approach?
+
+### Presenting alternatives
+
+After gathering answers, present 2–3 distinct approaches:
+
+```
+## Approach A: [Name]
+[One paragraph description]
+
+Pros:
+- [Pro 1]
+- [Pro 2]
+
+Cons:
+- [Con 1]
+- [Con 2]
+
+Best if: [condition where this wins]
+
+---
+
+## Approach B: [Name]
+...
+```
+
+Ask the user which direction resonates before writing the design document.
+
+### Design document format
+
+Save to `specs/brainstorm-<name>.md`:
+
+```markdown
+# Brainstorm: [Topic]
+
+**Date:** [YYYY-MM-DD]
+**Mode:** New product | Legacy codebase | Feature in context
+**Chosen approach:** [Approach name]
+
+## The problem
+[What we're actually solving and for whom]
+
+## Success criteria
+- [What done looks like]
+
+## Constraints
+- [Technical and product constraints]
+
+## Approaches considered
+### [Approach A]
+[Summary + why it was not chosen, or why it was chosen]
+
+### [Approach B]
+[Summary + tradeoffs]
+
+## Chosen direction
+[Rationale for the selected approach]
+
+## Open questions
+- [Anything still unresolved that shaping-specs needs to address]
+
+## Context loaded
+- `standards/[file].md` — [what was relevant]
+- `path/to/file` — [why it was included]
+```
+
+### Hand-off to shaping-specs
+
+After saving the design document, tell the user:
+
+```
+Brainstorm complete. Load specs/brainstorm-<name>.md and run the shaping-specs skill to formalize this into an implementation spec.
+```
+
+The `shaping-specs` skill will use the design document as its starting context, so the shaping questions can be answered faster and with less ambiguity.
+
+### What to avoid
+
+- Do not propose implementation details during brainstorming — that belongs in the spec
+- Do not skip to a single approach without exploring alternatives
+- Do not skip the problem questions and jump to solutions
+- Do not ask all questions at once — keep the conversation flowing
+
+## Resources
+
+- Design document output: `specs/`
+- Next step: `.agent/skills/shaping-specs/SKILL.md`
+- Existing standards (Mode 2): `standards/README.md`
+- Superpowers brainstorming reference: `npx skills add obra/superpowers`

package/.agent/skills/code-review/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: code-review
+description: Validates changes against the spec and standards before merge. Use when the user asks to review, REV, perform final review, or confirm ready for merge. Ensures scope alignment, completeness, and that security-audit was run when required.
+---
+
+# Code Review
+
+## When to use this skill
+
+- User asks to "review", "REV", "final review", or "ready for merge"
+- After quality-assurance and security-audit (when applicable)
+- Before merging a feature or significant change
+
+## Workflow
+
+- [ ] Load the spec from `specs/<feature-name>.md`
+- [ ] Load relevant standards from `standards/`
+- [ ] Review changed code against the spec
+- [ ] Verify scope alignment — no out-of-scope changes, no missing in-scope items
+- [ ] Confirm security-audit was run if auth/API/sensitive data changed
+- [ ] Check documentation and spec status are updated
+- [ ] Produce review notes: pass for merge or list blocking issues
+
+## Instructions
+
+### Scope validation
+
+- Every success criterion in the spec is addressed (implemented or explicitly deferred)
+- No changes fall outside the spec's in-scope items
+- Out-of-scope items were not introduced without spec update
+
+### Standards compliance
+
+- Code follows patterns in `standards/` (naming, structure, tech stack)
+- Exceptions are documented or justified
+
+### Security gate
+
+If the change touches authentication, API endpoints, or sensitive data:
+
+- Security-audit must have been run
+- No Critical or High findings remain open
+- If audit was skipped, block merge and recommend running `security-audit`
+
+### Documentation
+
+- Spec status reflects current state (e.g., In Progress → Done)
+- New modules or APIs are documented per project conventions
+- Test evidence or coverage noted where applicable
+
+### Review output
+
+**Pass:** Confirm readiness for merge. Summarize what was reviewed and any minor notes.
+
+**Block:** List blocking issues with file/line references and required fixes. Do not recommend merge until resolved.
+
+### Output format
+
+```markdown
+## Code review — [feature]
+
+**Result:** Pass / Block
+
+### Scope
+- [x] All success criteria addressed
+- [x] No out-of-scope changes
+
+### Security
+- [x] Security-audit run (required for auth/API/sensitive)
+- [x] No Critical/High findings
+
+### Notes
+[Any observations or recommendations]
+```
+
+## Resources
+
+- Spec directory: `specs/`
+- Standards: `standards/`
+- Security audit: `.agent/skills/security-audit/SKILL.md` (run before review when applicable)

package/.agent/skills/creating-skills/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: creating-skills
+description: Acquires or creates Blueprint OS skills. Searches skills.sh registry first, installs and customizes if found, creates from scratch as fallback. Use when the user asks to create a skill, add a capability, find a skill, or automate a repeatable agent task.
+---
+
+# Creating Skills
+
+## When to use this skill
+
+- User asks to "create a skill for [task]" or "find a skill for [task]"
+- A repeatable workflow needs to be captured and reused
+- An existing skill needs to be refactored or extended
+- User wants to document a process the agent should follow consistently
+
+## Workflow
+
+- [ ] Clarify the skill's purpose — what task does it solve, and what are its triggers?
+- [ ] Search skills.sh for an existing community skill (see Instructions > Discovering on skills.sh)
+- [ ] If found: install with `npx skills add <owner/repo>` and evaluate fit
+- [ ] If it covers the need as-is: done — update the Skills Index in `README.md`
+- [ ] If it partially fits: customize it (see Instructions > Customizing an installed skill)
+- [ ] If nothing suitable found: create from scratch (see Instructions > Creating from scratch)
+- [ ] Save to `.agent/skills/<skill-name>/SKILL.md`
+- [ ] Update the Skills Index in `README.md`
+
+## Instructions
+
+### Discovering on skills.sh
+
+Before building anything, search the [skills.sh registry](https://skills.sh) — it has 200+ community skills covering frontend, backend, testing, APIs, databases, and more.
+
+**Search via agent:**
+
+```bash
+npx skills add find-skills
+```
+
+Then ask the `find-skills` skill to search for what you need.
+
+**Browse directly:** [skills.sh](https://skills.sh) — filter by category or search by keyword.
+
+**Install a skill:**
+
+```bash
+npx skills add <owner/repo>
+```
+
+Example:
+
+```bash
+npx skills add supabase/agent-skills
+npx skills add vercel-labs/agent-skills
+npx skills add anthropics/skills
+```
+
+Installed skills land in `.agent/skills/` automatically — compatible with Blueprint OS out of the box.
+
+### Customizing an installed skill
+
+After installing, open the skill's `SKILL.md` and evaluate:
+
+- **Keep**: the core workflow steps and any low-freedom (exact command) sections
+- **Adjust**: naming conventions, paths, and tool-specific references to match your project
+- **Add**: project-specific context in a new `## Project context` section at the bottom
+- **Remove**: sections irrelevant to your stack
+
+When customizing, save edits directly to the installed `SKILL.md`. Do not rename the file — only update its content.
+
+If the changes are substantial enough that the skill diverges significantly from upstream, rename the folder to reflect your custom version (e.g., `supabase-postgres/` → `postgres-migrations/`).
+
+### Creating from scratch
+
+Use this path only when skills.sh has nothing suitable.
+
+**Naming**
+
+- `name` field: gerund form, lowercase, hyphens only, max 64 chars
+  - Good: `reviewing-code`, `managing-databases`, `deploying-to-production`
+  - Bad: `code-review`, `database`, `deploy`
+- Folder name must match the `name` field exactly
+
+**Description**
+
+- Written in third person
+- Must state what it does AND when to trigger it (keywords/phrases)
+- Max 1024 chars
+- Example: "Reviews code changes for quality, security, and style. Use when the user asks for a code review, PR review, or feedback on an implementation."
+
+**Body structure**
+
+```markdown
+---
+name: [gerund-name]
+description: [third-person description with triggers]
+---
+
+# [Skill Title]
+
+## When to use this skill
+- [Specific trigger condition]
+- [Another trigger]
+
+## Workflow
+- [ ] [Step 1]
+- [ ] [Step 2]
+
+## Instructions
+[Logic, rules, code examples — tailored to the task]
+
+## Resources
+- [Link to scripts/ or examples/ if applicable]
+```
+
+**Degrees of freedom**
+
+Match the instruction style to how much autonomy the agent should have:
+
+- **High freedom** (exploration, design decisions) → use bullet points with heuristics
+- **Medium freedom** (structured but flexible) → use code block templates the agent fills in
+- **Low freedom** (fragile operations, exact steps required) → use specific bash commands or exact sequences
+
+**File size**
+
+Keep `SKILL.md` under 500 lines. If more detail is needed, create a secondary file and link to it:
+
+```markdown
+[See ADVANCED.md](ADVANCED.md)
+```
+
+Only one level of linking. Do not nest further.
+
+### Path conventions
+
+Always use forward slashes `/` for paths, never backslashes `\`.
+
+## Resources
+
+- Community registry: [skills.sh](https://skills.sh)
+- skills.sh guide: `adapters/skills-sh.md`
+- Blueprint OS skill examples: `.agent/skills/`
+- Standards guide: `standards/README.md`

package/.agent/skills/deploying-standards/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: deploying-standards
+description: Injects relevant project standards into the agent's current context before implementation work begins. Use when the user is about to start coding, asks the agent to build something, or says "inject standards", "load standards", or "deploy standards".
+---
+
+# Deploying Standards
+
+## When to use this skill
+
+- User is about to start implementation on a task or feature
+- User asks to "inject standards", "load context", or "deploy standards"
+- Starting a new conversation with context that needs to carry forward
+- After shaping a spec and before executing it
+
+## Workflow
+
+- [ ] Check if a spec exists for the current task in `specs/`
+- [ ] Read `standards/README.md` to see what standards files are available
+- [ ] Read `references/README.md` to see what reference files exist
+- [ ] Identify which standards and references are relevant to the current task (spec may list applicable references)
+- [ ] Read those standards and reference files and internalize the content
+- [ ] Confirm to the user which standards and references were loaded
+- [ ] Proceed with the task using those standards and references actively applied
+
+## Instructions
+
+### Relevance mapping
+
+Match the task type to the standards files most likely to apply:
+
+| Task type | Standards to load |
+|---|---|
+| Building a UI component | `component-patterns`, `naming-conventions`, `tech-stack` |
+| Creating an API endpoint | `api-design`, `error-handling`, `naming-conventions` |
+| Writing database queries | `data-models`, `naming-conventions` |
+| Adding authentication | `authentication`, `error-handling` |
+| Writing tests | `testing-approach`, `naming-conventions` |
+| Refactoring | `naming-conventions`, `folder-structure`, relevant domain |
+| General feature | `tech-stack`, `naming-conventions`, `folder-structure` |
+
+When in doubt, always load `tech-stack` and `naming-conventions` at minimum.
+
+### Auto-suggest mode
+
+If the user says "deploy standards" without specifying which:
+
+1. Ask what they are about to build (one sentence)
+2. Use the relevance map above to select the appropriate files
+3. Load those files and confirm: "Loaded: `standards/api-design.md`, `standards/naming-conventions.md`"
+
+### Manual mode
+
+If the user specifies standards explicitly (e.g., "inject the API standards"):
+
+1. Locate the matching file in `standards/`
+2. Read it and confirm it is loaded
+
+### References
+
+If the spec lists "Applicable references" or the task involves UI flows, architecture, or design, check `references/` and load relevant files (design docs, flowcharts, diagrams). Reference `references/README.md` for the index.
+
+### After loading
+
+State which standards and references were loaded, then proceed with the task. Keep standards active throughout the session — do not ignore them mid-task.
+
+If a decision during execution conflicts with a loaded standard, surface the conflict explicitly:
+
+```
+This would normally follow [standard X], but [situation]. Do you want me to follow the standard or make an exception here?
+```
+
+### Standards not found
+
+If `standards/` is empty or does not exist:
+
+```
+No standards files found. To create standards for this project, use the discovering-standards skill.
+```
+
+## Resources
+
+- Standards directory: `standards/`
+- References directory: `references/`
+- Discover new standards: `.agent/skills/discovering-standards/SKILL.md`
+- Shape a spec first: `.agent/skills/shaping-specs/SKILL.md`

package/.agent/skills/discovering-standards/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: discovering-standards
+description: Extracts coding patterns, conventions, and architectural decisions from an existing codebase and saves them as standards files. Use when the user asks to document standards, capture patterns, extract conventions, or onboard an AI agent to an existing project.
+---
+
+# Discovering Standards
+
+## When to use this skill
+
+- User asks to "document my standards", "capture my conventions", or "extract patterns from my code"
+- Onboarding Blueprint OS to an existing project for the first time
+- A recurring pattern has emerged that should be formalized
+- Tribal knowledge exists in the code but not in writing
+- Before brainstorming a new feature in an existing codebase — discover constraints first, then brainstorm within them
+
+## Workflow
+
+- [ ] Identify which area to document (ask user if unclear)
+- [ ] Scan relevant files in that area
+- [ ] Identify recurring patterns, naming conventions, and architectural decisions
+- [ ] Draft a standards file and confirm with the user
+- [ ] Save to `standards/<category>.md`
+- [ ] Update `standards/README.md` index if the file is new
+
+## Instructions
+
+### Discovery areas
+
+Approach one area at a time. Common areas to document:
+
+- **Tech stack** — languages, frameworks, libraries, versions
+- **Folder structure** — how the project is organized and why
+- **Naming conventions** — files, variables, components, routes, database columns
+- **Component patterns** — how UI components are structured and composed
+- **API design** — endpoint naming, request/response shapes, error handling
+- **Data models** — schema conventions, relationships, field naming
+- **Testing approach** — test file location, naming, tooling, coverage expectations
+- **Error handling** — how errors surface, are logged, and returned to clients
+- **State management** — how application state is structured and updated
+- **Authentication** — how auth is implemented and enforced
+
+### Extraction process
+
+For each area:
+
+1. Read 3–5 representative files
+2. Identify what is consistent across them (naming, structure, patterns)
+3. Note any exceptions — are they intentional or accidental?
+4. Write only what the agent needs to replicate the pattern, not what is obvious
+
+### Standards file format
+
+Save to `standards/<category>.md`:
+
+```markdown
+# [Category] Standards
+
+**Last updated:** [YYYY-MM-DD]
+
+## Overview
+[One paragraph: what this standard covers and why it exists]
+
+## Conventions
+
+### [Convention name]
+[Description of the pattern]
+
+**Example:**
+[code example or file path showing the pattern]
+
+**Avoid:**
+[counter-example if useful]
+
+## Exceptions
+[Known deviations and why they exist]
+```
+
+### What to capture vs. skip
+
+**Capture:**
+- Decisions that aren't obvious from reading a single file
+- Patterns that repeat across the codebase
+- Choices that differ from common defaults (e.g., "we use tabs, not spaces")
+- Architectural boundaries (e.g., "services never import from controllers")
+
+**Skip:**
+- Things the language or framework enforces automatically
+- One-off implementations with no pattern
+- Preferences with no clear rationale
+
+### File naming
+
+Use lowercase, hyphen-separated names that match the category:
+
+```
+standards/tech-stack.md
+standards/naming-conventions.md
+standards/api-design.md
+standards/component-patterns.md
+```
+
+## Resources
+
+- Standards directory: `standards/`
+- Standards guide: `standards/README.md`
+- Next step for new feature work: `.agent/skills/brainstorming/SKILL.md` (brainstorm within discovered constraints)
+- Next step before implementation: `.agent/skills/deploying-standards/SKILL.md`

package/.agent/skills/quality-assurance/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: quality-assurance
+description: Adds or updates tests to validate behavior against acceptance criteria. Use when the user asks to add tests, run QA, validate acceptance criteria, or ensure test coverage after implementation. Applies to frontend and backend code.
+---
+
+# Quality Assurance
+
+## When to use this skill
+
+- Implementation is complete and tests need to be added or updated
+- User asks to "add tests", "QA", "validate acceptance criteria", or "test coverage"
+- Spec has success criteria that require test evidence
+- Before merge when quality gates are in use
+
+## Workflow
+
+- [ ] Load the spec for the current task from `specs/<feature-name>.md`
+- [ ] Identify acceptance criteria and success criteria from the spec
+- [ ] Load `standards/testing-approach.md` if it exists
+- [ ] Add or update tests to cover the acceptance criteria
+- [ ] Record test coverage or evidence in the spec or a brief report
+- [ ] Flag auth, API, or sensitive data changes for security-audit if applicable
+
+## Instructions
+
+### Test scope by layer
+
+| Layer | Test types | Examples |
+|-------|------------|----------|
+| Frontend | Unit, integration, E2E | Components, hooks, user flows |
+| Backend | Unit, integration, API | Services, handlers, database |
+| Shared | Unit | Utilities, validation, data transforms |
+
+Follow project conventions in `standards/testing-approach.md` when present. If no testing standard exists, use common patterns for the stack (e.g., Vitest/Jest for unit, Playwright/Cypress for E2E).
+
+### Acceptance criteria mapping
+
+For each unchecked success criterion in the spec:
+
+1. Determine the test type needed (unit, integration, E2E)
+2. Write the test
+3. Run the test and confirm it passes
+4. Update the spec to mark the criterion as verified or add a brief evidence note
+
+### Evidence recording
+
+Add a section to the spec or append a note:
+
+```markdown
+## Test evidence
+- [Criterion X]: Covered by `path/to/test.ts` — passes
+- [Criterion Y]: Covered by integration test in `path/to/integration.test.ts`
+```
+
+### Security-sensitive changes
+
+If the implementation touches authentication, API security, or sensitive data handling, note that the `security-audit` skill should be run before merge.
+
+## Handoff
+
+- If auth/API/sensitive data: recommend running `security-audit` next
+- Otherwise: recommend running `code-review` before merge
+
+## Resources
+
+- Spec directory: `specs/`
+- Testing standards: `standards/testing-approach.md`
+- Next step: `.agent/skills/security-audit/SKILL.md` (for auth/API/sensitive) or `.agent/skills/code-review/SKILL.md`