blueprint:help

What this skill does

# Blueprint Help

Explain Blueprint Mode plugin and available commands.

**Invoked by:** `/blueprint:help` or when user asks "how does blueprint work?", "what commands are available?", "how do I use specs?".

## Principles

1. **Context-aware**: Focus on the topic the user asked about.
2. **Actionable**: Always suggest concrete next steps.
3. **Discoverable**: Help users find related commands.

## Process

### Step 1: Determine Help Topic

If a specific topic is provided, focus on that area. Otherwise, provide a general overview.

**Topics:**
- `commands` - List all available skills with descriptions
- `workflow` - Explain the recommended development workflow
- `specs` - How to work with specifications
- `adrs` - How to work with Architecture Decision Records
- `patterns` - How to work with patterns (any subject)
- `design` - How the design tree works (UX decisions)

### Step 2: Display Help

#### General Overview (default)

```markdown
## Blueprint Mode

Blueprint Mode keeps humans in control of system design during AI-assisted development by documenting:

**Code / architecture tree** (engineering audience):
- **Specs** - What you're building and why (`docs/specs/`)
- **ADRs** - Architecture decisions with rationale (`docs/adrs/`)
- **Patterns** - Examples and anti-patterns to follow or avoid (`patterns/`)
- **Boundaries** - Rules for AI agents (`docs/specs/boundaries.md`)

**Design / UX intent** (design audience):
- **DESIGN.md** - Top-level cross-cutting design rules and prohibitions (community-format file at repo root; Blueprint stays compatible with it)
- **UX decisions** - Per-context choices with alternatives considered (`design/ux-decisions/`)

The Blueprint trees are strictly separate so different reviewers (engineering vs design) can own different paths via CODEOWNERS. `DESIGN.md` sits adjacent to the Blueprint structure as important repo-level design context. Cross-cutting rules go in `DESIGN.md`; per-decision rationale goes in `design/ux-decisions/`. Don't duplicate.

### Getting Started

**New project:**
```
/blueprint:setup-repo
```

**Existing codebase:**
```
/blueprint:onboard
```

### Available Commands

| Command | Purpose |
|---------|---------|
| `/blueprint:setup-repo` | Create new project with spec structure |
| `/blueprint:onboard` | Add spec structure to existing codebase (code/architecture tree only) |
| `/blueprint:onboard-design` | Opt in to design intent capture — design tree, optional `DESIGN.md` stub, optional existing-UI triage |
| `/blueprint:require` | Add functional or non-functional requirements |
| `/blueprint:decide` | Record decisions — triages tech (ADR), UX (UX decision), and cross-cutting `DESIGN.md` rules |
| `/blueprint:good-pattern` | Capture approved patterns (any subject — code, schema, UI) |
| `/blueprint:bad-pattern` | Document anti-patterns (any subject — code, schema, UI) |
| `/blueprint:supersede` | Replace or deprecate a previous decision (ADR or UX) |
| `/blueprint:list-adrs` | List all ADRs with status (architectural only) |
| `/blueprint:status` | Show overview of Blueprint structure plus adjacent DESIGN.md context |
| `/blueprint:validate` | Check code against documented specs and design |
| `/blueprint:help` | Show this help |

### Before Writing Code

**IMPORTANT:** Before implementing any feature, you should:

1. Check if a feature spec exists in `docs/specs/features/`
2. Read relevant ADRs (check `related_adrs` field in specs)
3. Review `docs/specs/boundaries.md` for rules
4. Check `patterns/good/` for relevant examples to follow
5. Check `patterns/bad/anti-patterns.md` for what to avoid
6. For UI work, also read `DESIGN.md` (if present) and `design/ux-decisions/`

Run `/blueprint:validate` to check if your code follows documented specs.
```

#### Commands Topic

```markdown
## Blueprint Commands

### Setup & Onboarding
| Command | Use When |
|---------|----------|
| `/blueprint:setup-repo` | Starting a brand new project |
| `/blueprint:onboard` | Adding Blueprint to an existing codebase (code/architecture tree only) |
| `/blueprint:onboard-design` | Opting in to design intent capture (UX decisions + optional `DESIGN.md` stub) |

### Documentation
| Command | Use When |
|---------|----------|
| `/blueprint:require [desc]` | Adding a feature or non-functional requirement (NOT for components) |
| `/blueprint:decide [topic]` | Making a technology or UX/design choice (skill triages) |
| `/blueprint:good-pattern [file]` | Capturing examples to emulate (any subject) |
| `/blueprint:bad-pattern [desc]` | Documenting things to avoid (any subject) |
| `/blueprint:supersede [ADR\|UX]` | Replacing or retiring a previous ADR or UX decision |

### Discovery & Validation
| Command | Use When |
|---------|----------|
| `/blueprint:status` | Checking what's been documented |
| `/blueprint:list-adrs` | Reviewing all architecture decisions |
| `/blueprint:validate` | Verifying code matches specs |
| `/blueprint:help [topic]` | Getting help with Blueprint |
```

#### Workflow Topic

```markdown
## Recommended Workflow

### 1. Set Up (Once)

**New project:**
```
/blueprint:setup-repo
```
This interviews you about your project and creates the full spec structure.

**Existing project:**
```
/blueprint:onboard
```
This analyzes your codebase and creates specs from what exists.

### 2. Document Decisions

When making a tech choice:
```
/blueprint:decide Use PostgreSQL because the team knows it well
```

When adding a feature requirement:
```
/blueprint:require Users can reset password via email
```

### 3. Capture Patterns

When you see good code:
```
/blueprint:good-pattern src/repositories/user.repository.ts
```

When you see code to avoid:
```
/blueprint:bad-pattern Using any type in TypeScript
```

### 4. Before Implementing

Always check specs before coding:
1. Read `docs/specs/features/` for what to build
2. Read `docs/adrs/` for how to build it
3. Read `docs/specs/boundaries.md` for rules to follow
4. Check `patterns/good/` for examples

### 5. Validate

After implementing:
```
/blueprint:validate
```
This checks your code against documented specs and patterns.

### 6. Evolve

When decisions change:
```
/blueprint:supersede ADR-003
```
This preserves history while recording the new decision.
```

#### Specs Topic

```markdown
## Working with Specs

Specs live in `docs/specs/` and define **what** you're building.

### Files

| Path | Purpose |
|------|---------|
| `product.md` | Project vision, users, success metrics |
| `tech-stack.md` | Technology choices |
| `boundaries.md` | Rules for AI agents (Always/Ask/Never) |
| `features/*.md` | Feature specs (discovered via globbing) |
| `non-functional/*.md` | NFRs by category (discovered via globbing) |

### Adding Requirements

**Functional requirement:**
```
/blueprint:require Users can export data as CSV
```
Creates a feature spec in `docs/specs/features/`.

**Non-functional requirement:**
```
/blueprint:require API response under 100ms P95
```
Creates `docs/specs/non-functional/performance.md`.

### Feature Spec Structure

```markdown
---
status: Planned | Active | Deprecated
module: src/[path]/
related_adrs: [001, 003]
---

# Feature Name

## Overview
What this feature does.

## User Stories
- As a [user], I want [capability] so that [benefit]

## Requirements
What must be true for this feature to work.

## Acceptance Criteria (optional)
- Given [context], when [action], then [outcome]
```
```

#### ADRs Topic

```markdown
## Working with ADRs

Architecture Decision Records live in `docs/adrs/` and capture **why** you made choices.

### Creating ADRs

```
/blueprint:decide Use PostgreSQL because the team has experience
```

ADRs can be:
- **Active** - Current decisions in use
- **Draft** - Incomplete, needs more info
- **Superseded** - Replaced by a newer decision
- **Deprecated** - Retired without replacement

### ADR Structure

```markdown
---
status: Active
date: 2025-01-25
---

# ADR-001: PostgreSQL as Database

## Context
What problem we're solving.