blueprint-os 1.2.0 → 1.3.1

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

@@ -21,7 +21,7 @@ description: Explores a problem through Socratic questioning before any spec or
 - [ ] 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`
+- [ ] Save the design document to `specs/brainstorming/<name>/design.md`
 - [ ] Hand off to `shaping-specs` with the design document as input
 
 ## Instructions
@@ -34,7 +34,7 @@ Pick the mode based on what the user is starting from:
 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.
+A codebase exists. Load `standards/` files (root and backend/, frontend/, design/) 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.
@@ -96,7 +96,7 @@ Ask the user which direction resonates before writing the design document.
 
 ### Design document format
 
-Save to `specs/brainstorm-<name>.md`:
+Save to `specs/brainstorming/<name>/design.md`:
 
 ```markdown
 # Brainstorm: [Topic]
@@ -128,7 +128,7 @@ Save to `specs/brainstorm-<name>.md`:
 - [Anything still unresolved that shaping-specs needs to address]
 
 ## Context loaded
-- `standards/[file].md` — [what was relevant]
+- `standards/[layer/][file].md` — [what was relevant]
 - `path/to/file` — [why it was included]
 ```
 
@@ -137,7 +137,7 @@ Save to `specs/brainstorm-<name>.md`:
 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.
+Brainstorm complete. Load specs/brainstorming/<name>/design.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.
@@ -151,7 +151,7 @@ The `shaping-specs` skill will use the design document as its starting context,
 
 ## Resources
 
-- Design document output: `specs/`
+- Design document output: `specs/brainstorming/<name>/design.md`
 - Next step: `.agent/skills/shaping-specs/SKILL.md`
 - Existing standards (Mode 2): `standards/README.md`
 - Superpowers brainstorming reference: `npx skills add obra/superpowers -a antigravity -y --copy`

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

@@ -13,13 +13,13 @@ description: Validates changes against the spec and standards before merge. Use
 
 ## Workflow
 
-- [ ] Load the spec from `specs/<feature-name>.md`
+- [ ] Load the spec from `specs/shaped-specs/<name>/spec.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
+- [ ] Save review to `specs/shaped-specs/<name>/code-review.md`
 
 ## Instructions
 
@@ -56,6 +56,8 @@ If the change touches authentication, API endpoints, or sensitive data:
 
 ### Output format
 
+Save to `specs/shaped-specs/<name>/code-review.md`:
+
 ```markdown
 ## Code review — [feature]
 
@@ -75,6 +77,7 @@ If the change touches authentication, API endpoints, or sensitive data:
 
 ## Resources
 
-- Spec directory: `specs/`
+- Spec: `specs/shaped-specs/<name>/spec.md`
+- Output: `specs/shaped-specs/<name>/code-review.md`
 - Standards: `standards/`
 - Security audit: `.agent/skills/security-audit/SKILL.md` (run before review when applicable)

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

@@ -14,7 +14,7 @@ description: Injects relevant project standards into the agent's current context
 
 ## Workflow
 
-- [ ] Check if a spec exists for the current task in `specs/`
+- [ ] Check if a spec exists for the current task in `specs/shaped-specs/<name>/spec.md`
 - [ ] 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)
@@ -26,19 +26,19 @@ description: Injects relevant project standards into the agent's current context
 
 ### Relevance mapping
 
-Match the task type to the standards files most likely to apply:
+Match the task type to the standards files most likely to apply. Load from the correct layer:
 
 | 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` |
+| Building a UI component | `frontend/component-patterns`, `naming-conventions`, `tech-stack` |
+| Creating an API endpoint | `backend/api-design`, `backend/error-handling`, `naming-conventions` |
+| Writing database queries | `backend/data-models`, `naming-conventions` |
+| Adding authentication | `backend/authentication`, `backend/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.
+When in doubt, always load `tech-stack` and `naming-conventions` at minimum. Shared standards are at root; layer-specific are in `backend/`, `frontend/`, `design/`.
 
 ### Auto-suggest mode
 
@@ -46,13 +46,13 @@ 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`"
+3. Load those files and confirm: "Loaded: `standards/backend/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/`
+1. Locate the matching file in `standards/` (check root and `backend/`, `frontend/`, `design/` subfolders)
 2. Read it and confirm it is loaded
 
 ### References
@@ -79,7 +79,7 @@ No standards files found. To create standards for this project, use the discover
 
 ## Resources
 
-- Standards directory: `standards/`
+- Standards directory: `standards/` (shared at root; `backend/`, `frontend/`, `design/` for layer-specific)
 - 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

@@ -19,25 +19,29 @@ description: Extracts coding patterns, conventions, and architectural decisions
 - [ ] 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`
+- [ ] Save to `standards/<layer>/<category>.md` or `standards/<category>.md` for shared
 - [ ] 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
+Approach one area at a time. Save to the appropriate layer:
+
+| Area | Layer | Path |
+|------|-------|------|
+| Tech stack | shared | `standards/tech-stack.md` |
+| Folder structure | shared | `standards/folder-structure.md` |
+| Naming conventions | shared | `standards/naming-conventions.md` |
+| Testing approach | shared | `standards/testing-approach.md` |
+| API design | backend | `standards/backend/api-design.md` |
+| Data models | backend | `standards/backend/data-models.md` |
+| Error handling | backend | `standards/backend/error-handling.md` |
+| Authentication | backend | `standards/backend/authentication.md` |
+| Component patterns | frontend | `standards/frontend/component-patterns.md` |
+| State management | frontend | `standards/frontend/state-management.md` |
+| Design system | design | `standards/design/design-system.md` |
+| Accessibility | design | `standards/design/accessibility.md` |
 
 ### Extraction process
 
@@ -50,7 +54,7 @@ For each area:
 
 ### Standards file format
 
-Save to `standards/<category>.md`:
+Save to `standards/<layer>/<category>.md` (or `standards/<category>.md` for shared):
 
 ```markdown
 # [Category] Standards
@@ -90,18 +94,19 @@ Save to `standards/<category>.md`:
 
 ### File naming
 
-Use lowercase, hyphen-separated names that match the category:
+Use lowercase, hyphen-separated names. Place in the correct layer folder:
 
 ```
 standards/tech-stack.md
 standards/naming-conventions.md
-standards/api-design.md
-standards/component-patterns.md
+standards/backend/api-design.md
+standards/frontend/component-patterns.md
+standards/design/design-system.md
 ```
 
 ## Resources
 
-- Standards directory: `standards/`
+- Standards directory: `standards/` (shared at root, layer-specific in `backend/`, `frontend/`, `design/`)
 - 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

@@ -14,11 +14,11 @@ description: Adds or updates tests to validate behavior against acceptance crite
 
 ## Workflow
 
-- [ ] Load the spec for the current task from `specs/<feature-name>.md`
+- [ ] Load the spec for the current task from `specs/shaped-specs/<name>/spec.md`
 - [ ] Identify acceptance criteria and success criteria from the spec
-- [ ] Load `standards/testing-approach.md` if it exists
+- [ ] Load `standards/testing-approach.md` if it exists (shared at root)
 - [ ] Add or update tests to cover the acceptance criteria
-- [ ] Record test coverage or evidence in the spec or a brief report
+- [ ] Save test evidence to `specs/shaped-specs/<name>/quality-assurance.md`
 - [ ] Flag auth, API, or sensitive data changes for security-audit if applicable
 
 ## Instructions
@@ -31,7 +31,7 @@ description: Adds or updates tests to validate behavior against acceptance crite
 | 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).
+Follow project conventions in `standards/testing-approach.md` when present (shared at root). If no testing standard exists, use common patterns for the stack (e.g., Vitest/Jest for unit, Playwright/Cypress for E2E).
 
 ### Acceptance criteria mapping
 
@@ -44,10 +44,14 @@ For each unchecked success criterion in the spec:
 
 ### Evidence recording
 
-Add a section to the spec or append a note:
+Save to `specs/shaped-specs/<name>/quality-assurance.md`:
 
 ```markdown
-## Test evidence
+## Quality assurance — [feature]
+
+**Date:** [YYYY-MM-DD]
+
+### Test evidence
 - [Criterion X]: Covered by `path/to/test.ts` — passes
 - [Criterion Y]: Covered by integration test in `path/to/integration.test.ts`
 ```
@@ -63,6 +67,7 @@ If the implementation touches authentication, API security, or sensitive data ha
 
 ## Resources
 
-- Spec directory: `specs/`
-- Testing standards: `standards/testing-approach.md`
+- Spec: `specs/shaped-specs/<name>/spec.md`
+- Output: `specs/shaped-specs/<name>/quality-assurance.md`
+- Testing standards: `standards/testing-approach.md` (shared)
 - Next step: `.agent/skills/security-audit/SKILL.md` (for auth/API/sensitive) or `.agent/skills/code-review/SKILL.md`

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

@@ -14,11 +14,11 @@ description: Audits code changes for security vulnerabilities and data exposure.
 
 ## Workflow
 
-- [ ] Load the spec from `specs/<feature-name>.md`
+- [ ] Load the spec from `specs/shaped-specs/<name>/spec.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`
+- [ ] Save audit report to `specs/shaped-specs/<name>/security-audit.md`
 - [ ] Block merge for Critical and High; document Medium and Low for resolution
 
 ## Instructions
@@ -84,7 +84,7 @@ Run security-audit before merge when the change involves:
 
 ### Audit report format
 
-Save to `specs/<feature-name>-security-audit.md` or append to the spec:
+Save to `specs/shaped-specs/<name>/security-audit.md`:
 
 ```markdown
 ## Security audit — [date]
@@ -110,6 +110,7 @@ Save to `specs/<feature-name>-security-audit.md` or append to the spec:
 
 ## Resources
 
-- Spec directory: `specs/`
-- Standards: `standards/authentication.md`, `standards/api-design.md` if present
+- Spec: `specs/shaped-specs/<name>/spec.md`
+- Output: `specs/shaped-specs/<name>/security-audit.md`
+- Standards: `standards/backend/authentication.md`, `standards/backend/api-design.md` if present
 - Next step: `.agent/skills/code-review/SKILL.md`

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

@@ -9,20 +9,20 @@ description: Shapes a structured spec for a feature or task by asking clarifying
 
 - 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
+- A brainstorm document exists in `specs/brainstorming/<name>/design.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.
+The brainstorm document (`specs/brainstorming/<name>/design.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
+- [ ] Check for a brainstorm document in `specs/brainstorming/<name>/design.md` — load it if it exists
+- [ ] Load relevant standards from `standards/` (root and `backend/`, `frontend/`, `design/`) 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`
+- [ ] Write the spec file to `specs/shaped-specs/<name>/spec.md`
 - [ ] Summarize the spec and confirm it is ready to execute
 
 ## Instructions
@@ -56,14 +56,14 @@ Ask these questions in a conversational flow. Adapt wording to context, but cove
 - Are there edge cases or failure modes to account for?
 
 **7. What standards apply?**
-- Which entries in `standards/` are relevant to this task?
+- Which entries in `standards/` (root, backend/, frontend/, design/) 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`:
+Save the completed spec to `specs/shaped-specs/<name>/spec.md`:
 
 ```markdown
 # Spec: [Feature Name]
@@ -95,7 +95,7 @@ Save the completed spec to `specs/<feature-name>.md`:
 - [Risk or edge case]
 
 ## Applicable standards
-- `standards/[file].md` — [which section]
+- `standards/[layer/][file].md` — [which section]
 
 ## Applicable references
 - `references/[file]` — [design, flowchart, diagram that defines this]
@@ -115,6 +115,6 @@ After execution, consider running `quality-assurance`, `security-audit` (for aut
 - 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/`
+- Spec output: `specs/shaped-specs/<name>/spec.md`
 - 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

@@ -113,7 +113,7 @@ your-project/
 
 ```
 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"
+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]"
 ```
 
@@ -122,7 +122,7 @@ your-project/
 ```
 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"
+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]"
 ```
 
@@ -191,7 +191,7 @@ These two skills are sequential, not interchangeable.
 | 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.
+**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.
 
 ---
 
@@ -223,13 +223,13 @@ You have an idea. No code exists yet.
 ```
 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`.
+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/brainstorm-task-app.md
+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/user-auth.md` with scope, success criteria, and implementation notes.
+The agent formalizes the brainstorm into `specs/shaped-specs/user-auth/spec.md` with scope, success criteria, and implementation notes.
 
 **Step 3: Execute**
 ```
@@ -247,19 +247,19 @@ You've been handed a 3-year-old Express API and need to add a payments feature.
 ```
 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`.
+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/brainstorm-payments.md`.
+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/brainstorm-payments.md
+Read .agent/skills/shaping-specs/SKILL.md and shape a spec using specs/brainstorming/payments/design.md
 ```
-Saves `specs/payments-feature.md` with relevant files mapped out, risks identified, and applicable standards and references.
+Saves `specs/shaped-specs/payments-feature/spec.md` with relevant files mapped out, risks identified, and applicable standards and references.
 
 **Step 4: Build**
 ```
@@ -311,7 +311,7 @@ Read .agent/skills/test-driven-development/SKILL.md and implement the payments s
 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 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.
 ```
 
@@ -367,9 +367,13 @@ blueprint-os/
 │       └── code-review/
 │           └── SKILL.md
 ├── specs/
-│   └── (brainstorm docs and specs saved here)
+│   ├── brainstorming/<name>/design.md
+│   └── shaped-specs/<name>/spec.md (+ quality-assurance.md, security-audit.md, code-review.md when run)
 ├── standards/
-│   └── README.md
+│   ├── README.md
+│   ├── backend/
+│   ├── frontend/
+│   └── design/
 ├── references/
 │   ├── README.md
 │   └── agent-workflow/    # Meta: framework links (agent-os, superpowers, etc.)
@@ -415,7 +419,7 @@ This format is compatible with Antigravity natively. For other tools, see the [a
 
 ## 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.
+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](standards/README.md) for the format and conventions.
 
 ---
 

package/adapters/antigravity.md

@@ -29,7 +29,12 @@ your-project/
 │       └── 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/
+│   ├── backend/
+│   ├── frontend/
+│   └── design/
 ├── references/
 └── ... your code
 ```
@@ -66,7 +71,7 @@ Brainstorm a [product idea] — I want to explore the problem and options before
 Then:
 
 ```
-Shape a spec using the brainstorm document in specs/brainstorm-<name>.md.
+Shape a spec using the brainstorm document in specs/brainstorming/<name>/design.md.
 ```
 
 **New feature in a legacy codebase:**
@@ -140,8 +145,8 @@ The agent will check [skills.sh](https://skills.sh) first (`npx skills add https
 ## 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
+- Brainstorm documents are saved to `specs/brainstorming/<name>/design.md` — reference them when shaping the spec
+- Standards files in `standards/` (root for shared, `backend/`, `frontend/`, `design/` for layer-specific) 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
+- Spec files are saved to `specs/shaped-specs/<name>/spec.md` — reference them in subsequent sessions to maintain continuity
 - For skills.sh integration, see [skills-sh.md](skills-sh.md)

package/adapters/claude-code.md

@@ -72,7 +72,7 @@ Then invoke them with:
 
 ```
 /brainstorm — explore the idea for [product or feature]
-/shape-spec — formalize the spec using specs/brainstorm-<name>.md
+/shape-spec — formalize the spec using specs/brainstorming/<name>/design.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
@@ -89,7 +89,7 @@ Then invoke them with:
 
 ```
 /brainstorm — explore the idea for [product]
-/shape-spec — formalize specs/brainstorm-<name>.md into an implementation spec
+/shape-spec — formalize specs/brainstorming/<name>/design.md into an implementation spec
 /deploy-standards — inject relevant standards for [first task]
 ```
 
@@ -98,7 +98,7 @@ Then invoke them with:
 ```
 /discover-standards — extract patterns from the existing codebase
 /brainstorm — explore [feature] within the existing constraints
-/shape-spec — formalize specs/brainstorm-<name>.md
+/shape-spec — formalize specs/brainstorming/<name>/design.md
 /deploy-standards — inject standards before implementation
 ```
 
@@ -127,8 +127,8 @@ Add a section to your project's `CLAUDE.md` to make Blueprint OS always availabl
 This project uses Blueprint OS for agent workflows.
 
 - Skills: `.agent/skills/`
-- Standards: `standards/`
-- Specs: `specs/` (brainstorm docs + implementation specs)
+- Standards: `standards/` (shared at root; `backend/`, `frontend/`, `design/` for layer-specific)
+- Specs: `specs/brainstorming/<name>/design.md`, `specs/shaped-specs/<name>/spec.md`
 - References: `references/` (design docs, flowcharts, diagrams)
 
 ### Workflow
@@ -153,8 +153,8 @@ Before merge (quality gates):
 
 ## Notes
 
-- Standards files in `standards/` can be referenced with `@standards/api-design.md` to include them directly in context
+- Standards files in `standards/` can be referenced with `@standards/api-design.md` or `@standards/backend/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
+- Brainstorm documents (`specs/brainstorming/<name>/design.md`) and spec files (`specs/shaped-specs/<name>/spec.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

@@ -79,7 +79,7 @@ Cursor will include the file content in context and the agent will follow the sk
 
 ```
 @.agent/skills/brainstorming/SKILL.md — brainstorm [product idea]
-@.agent/skills/shaping-specs/SKILL.md — shape a spec using specs/brainstorm-<name>.md
+@.agent/skills/shaping-specs/SKILL.md — shape a spec using specs/brainstorming/<name>/design.md
 @.agent/skills/deploying-standards/SKILL.md — inject standards for [task]
 ```
 
@@ -88,7 +88,7 @@ Cursor will include the file content in context and the agent will follow the sk
 ```
 @.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/shaping-specs/SKILL.md — shape a spec using specs/brainstorming/<name>/design.md
 @.agent/skills/deploying-standards/SKILL.md — inject standards for [task]
 ```
 
@@ -125,8 +125,8 @@ Run QA after implementation. Run SEC when changes touch auth, API, or sensitive
 
 ## Notes
 
-- Standards files in `standards/` can also be referenced with `@standards/tech-stack.md`
+- Standards files in `standards/` can be referenced with `@standards/tech-stack.md` or `@standards/backend/api-design.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
+- Brainstorm documents (`specs/brainstorming/<name>/design.md`) and spec files (`specs/shaped-specs/<name>/spec.md`) 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). Use `-a antigravity -y --copy` when installing so skills land in `.agent/skills/` as real files. Without `--copy`, the CLI may symlink from `.agents/`, and deleting `.agents` breaks the skill.

package/lib/init.js

@@ -76,6 +76,10 @@ function init(cwd) {
   const specsDir = path.join(cwd, 'specs');
   if (!fs.existsSync(specsDir)) {
     fs.mkdirSync(specsDir, { recursive: true });
+    const specsReadme = path.join(PACKAGE_ROOT, 'specs', 'README.md');
+    if (fs.existsSync(specsReadme)) {
+      fs.copyFileSync(specsReadme, path.join(specsDir, 'README.md'));
+    }
     console.log('  ✓ specs/ (created)');
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint-os",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "A portable, tool-agnostic AI agent workflow system built on skills and standards",
   "bin": {
     "blueprint-os": "./bin/blueprint-os.js"

package/standards/README.md

@@ -16,25 +16,35 @@ Standards files are extracted from your codebase — not invented. They document
 
 ---
 
-## File naming
+## Structure
 
-Use lowercase, hyphen-separated names:
+Standards are organized by layer. Shared standards (cross-cutting) live at root; layer-specific standards go in subfolders:
 
 ```
 standards/
-├── tech-stack.md
-├── naming-conventions.md
-├── folder-structure.md
-├── component-patterns.md
-├── api-design.md
-├── data-models.md
-├── testing-approach.md
-├── error-handling.md
-├── authentication.md
-└── state-management.md
+├── tech-stack.md           # shared
+├── naming-conventions.md   # shared
+├── folder-structure.md     # shared
+├── testing-approach.md    # shared
+├── backend/
+│   ├── api-design.md
+│   ├── data-models.md
+│   ├── error-handling.md
+│   └── authentication.md
+├── frontend/
+│   ├── component-patterns.md
+│   └── state-management.md
+└── design/
+    ├── design-system.md
+    └── accessibility.md
 ```
 
-Name the file after the category it covers. Keep one category per file.
+**Backend** — API, data, auth, server-side patterns.  
+**Frontend** — Components, state, client-side patterns.  
+**Design** — UI system, accessibility, visual conventions.  
+**Root** — Tech stack, naming, folder structure, testing (apply across layers).
+
+Use lowercase, hyphen-separated names. Keep one category per file.
 
 ---
 
@@ -69,7 +79,7 @@ Known deviations from the standard and the reason they exist.
 
 ## Standards index
 
-When you add a new standards file, add it to the table below so agents can discover it:
+When you add a new standards file, add it to the table below so agents can discover it. Group by layer (shared, backend, frontend, design):
 
 | File | Covers |
 |---|---|

package/standards/backend/README.md

@@ -0,0 +1,3 @@
+# Backend Standards
+
+Place backend-specific standards here: `api-design.md`, `data-models.md`, `error-handling.md`, `authentication.md`.

package/standards/design/README.md

@@ -0,0 +1,3 @@
+# Design Standards
+
+Place design/UX standards here: `design-system.md`, `accessibility.md`.

package/standards/frontend/README.md

@@ -0,0 +1,3 @@
+# Frontend Standards
+
+Place frontend-specific standards here: `component-patterns.md`, `state-management.md`.