blueprint-os 1.1.0 → 1.2.0

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

@@ -1,107 +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`
+---
+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/find-skills/SKILL.md

@@ -1,133 +1,133 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Search for Skills
-
-Run the find command with a relevant query:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-The command will return results like:
-
-```
-Install with npx skills add <owner/repo@skill>
-
-vercel-labs/agent-skills@vercel-react-best-practices
-└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 3: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install command they can run
-3. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "vercel-react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-
-To install it:
-npx skills add vercel-labs/agent-skills@vercel-react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 4: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/README.md

@@ -81,6 +81,8 @@ npx blueprint-os init
 
 This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your project. No dependency is added to `package.json`. The `find-skills` skill is included so you can search the skills.sh registry without installing it separately.
 
+**Conditional copy:** If `standards/` or `references/` already contain project content (files beyond the template), they are preserved and not overwritten.
+
 **Or copy manually:** Place the `.agent/` folder, `standards/` folder, and `references/` folder at the root of your project:
 
 ```
@@ -132,6 +134,28 @@ your-project/
 3. If not found: ask your agent "Read .agent/skills/creating-skills/SKILL.md and create a skill for [task]"
 ```
 
+### Updating Blueprint OS
+
+To refresh core skills and adapters without touching your content:
+
+```bash
+npx blueprint-os@latest update
+```
+
+**What `update` does:**
+- Updates core skills in `.agent/skills/` (brainstorming, shaping-specs, discovering-standards, etc.)
+- Updates `adapters/`
+- Refreshes `references/agent-workflow/` and `references/README.md`
+- Refreshes `standards/README.md`
+
+**What `update` preserves:**
+- `specs/` — never touched
+- Your standards files (e.g. `api-design.md`, `error-handling.md`)
+- Your reference files (anything beyond `agent-workflow/`)
+- Community skills you installed from skills.sh
+
+**Conditional copy on `init`:** If you run `init` again, `standards/` and `references/` are preserved when they already contain project content (files beyond the shipped template).
+
 ---
 
 ## Skills Index

package/bin/blueprint-os.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 
-const { init } = require('../lib/init');
+const { init, update } = require('../lib/init');
 
 const [cmd] = process.argv.slice(2);
 
 if (cmd === 'init') {
   init(process.cwd());
+} else if (cmd === 'update') {
+  update(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.');
+  console.log('Usage:');
+  console.log('  npx blueprint-os init    Install or reinstall (preserves standards/references if they have content)');
+  console.log('  npx blueprint-os update   Safe update: refreshes core skills and adapters, preserves your content');
+  console.log('\nUse "npx blueprint-os@latest init" or "npx blueprint-os@latest update" to get the latest version.');
   process.exit(1);
 }

package/lib/init.js

@@ -4,6 +4,40 @@ const path = require('path');
 const PACKAGE_ROOT = path.join(__dirname, '..');
 const FOLDERS = ['.agent', 'standards', 'references', 'adapters'];
 
+const CORE_SKILLS = [
+  'brainstorming',
+  'creating-skills',
+  'shaping-specs',
+  'discovering-standards',
+  'deploying-standards',
+  'quality-assurance',
+  'security-audit',
+  'code-review',
+  'find-skills',
+];
+
+function hasUserContent(dir, packageOnly) {
+  if (!fs.existsSync(dir)) return false;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const name = e.name;
+    if (e.isDirectory()) {
+      if (!packageOnly.dirs.includes(name)) return true;
+    } else {
+      if (!packageOnly.files.includes(name)) return true;
+    }
+  }
+  return false;
+}
+
+function shouldPreserveStandards(dest) {
+  return hasUserContent(dest, { files: ['README.md'], dirs: [] });
+}
+
+function shouldPreserveReferences(dest) {
+  return hasUserContent(dest, { files: ['README.md'], dirs: ['agent-workflow'] });
+}
+
 function init(cwd) {
   const resolvedCwd = path.resolve(cwd);
   const resolvedRoot = path.resolve(PACKAGE_ROOT);
@@ -25,6 +59,16 @@ function init(cwd) {
       continue;
     }
 
+    if (folder === 'standards' && shouldPreserveStandards(dest)) {
+      console.log(`  ⊘ standards/ (preserved - has project content)`);
+      continue;
+    }
+
+    if (folder === 'references' && shouldPreserveReferences(dest)) {
+      console.log(`  ⊘ references/ (preserved - has project content)`);
+      continue;
+    }
+
     fs.cpSync(src, dest, { recursive: true });
     console.log(`  ✓ ${folder}/`);
   }
@@ -40,4 +84,67 @@ function init(cwd) {
   console.log('  npx blueprint-os --help');
 }
 
-module.exports = { init };
+function update(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 update\n');
+    return;
+  }
+
+  const agentDest = path.join(cwd, '.agent', 'skills');
+  if (!fs.existsSync(agentDest)) {
+    console.log('Blueprint OS not found. Run "npx blueprint-os init" first.\n');
+    return;
+  }
+
+  console.log('Updating Blueprint OS...\n');
+
+  const skillsSrc = path.join(PACKAGE_ROOT, '.agent', 'skills');
+  for (const skill of CORE_SKILLS) {
+    const src = path.join(skillsSrc, skill);
+    const dest = path.join(agentDest, skill);
+    if (fs.existsSync(src)) {
+      fs.cpSync(src, dest, { recursive: true });
+      console.log(`  ✓ .agent/skills/${skill}/`);
+    }
+  }
+
+  const adaptersSrc = path.join(PACKAGE_ROOT, 'adapters');
+  const adaptersDest = path.join(cwd, 'adapters');
+  if (fs.existsSync(adaptersSrc)) {
+    fs.cpSync(adaptersSrc, adaptersDest, { recursive: true });
+    console.log('  ✓ adapters/');
+  }
+
+  const refsSrc = path.join(PACKAGE_ROOT, 'references');
+  const refsDest = path.join(cwd, 'references');
+  if (fs.existsSync(refsSrc) && fs.existsSync(refsDest)) {
+    const agentWorkflowSrc = path.join(refsSrc, 'agent-workflow');
+    const agentWorkflowDest = path.join(refsDest, 'agent-workflow');
+    if (fs.existsSync(agentWorkflowSrc)) {
+      fs.cpSync(agentWorkflowSrc, agentWorkflowDest, { recursive: true });
+      console.log('  ✓ references/agent-workflow/');
+    }
+    const refsReadmeSrc = path.join(refsSrc, 'README.md');
+    const refsReadmeDest = path.join(refsDest, 'README.md');
+    if (fs.existsSync(refsReadmeSrc)) {
+      fs.copyFileSync(refsReadmeSrc, refsReadmeDest);
+      console.log('  ✓ references/README.md');
+    }
+  }
+
+  const standardsReadmeSrc = path.join(PACKAGE_ROOT, 'standards', 'README.md');
+  const standardsReadmeDest = path.join(cwd, 'standards', 'README.md');
+  if (fs.existsSync(standardsReadmeSrc) && fs.existsSync(path.dirname(standardsReadmeDest))) {
+    fs.copyFileSync(standardsReadmeSrc, standardsReadmeDest);
+    console.log('  ✓ standards/README.md');
+  }
+
+  console.log('\nDone. Core skills, adapters, and framework references updated.');
+  console.log('Preserved: specs/, your standards files, your references, community skills.');
+}
+
+module.exports = { init, update, CORE_SKILLS };