Create Blueprint

Name

blueprints:create-blueprint - Generate or update blueprint documentation for a specific system

Synopsis

/blueprint <system-name>

Description

Research a specific system in the codebase and create or update its technical blueprint documentation in the blueprints/ directory at the repository root.

Important: Blueprint Location

CRITICAL: Blueprints MUST be created at the repository root, never in subdirectories or packages.

• {repo-root}/blueprints/{system-name}.md
• {repo-root}/packages/foo/blueprints/{system-name}.md
• {repo-root}/src/blueprints/{system-name}.md

Blueprints are repository-wide system design documents. A single system may span multiple packages or directories, but there should be ONE blueprint at the repo root describing the entire system.

Implementation

You are tasked with creating or updating technical blueprint documentation for a specific system.

Process

1. Identify the Target System

The user will specify which system to document. This could be:

• A feature name (e.g., "authentication", "caching")
• A directory path (e.g., "lib/commands/mcp")
• A component name (e.g., "MCP server", "hook dispatcher")

2. Deep Research Phase

Thoroughly investigate the system:

1. Find all relevant files using Glob and Grep
2. Read the implementation to understand:
   • Entry points and public APIs
   • Internal architecture and data flow
   • Dependencies and integrations
   • Configuration options
   • Error handling and edge cases
3. Check for existing documentation:
   • README files in the directory
   • Inline code comments
   • Existing blueprints/ files
   • Test files (they document expected behavior)

3. Check for Duplicates

Before creating a new blueprint, check what already exists:

1. List all blueprints: Use Glob("blueprints/*.md") to see all existing blueprint files
2. Search by keyword: Use Grep to search frontmatter in blueprints/ for related topics
3. Read related blueprints: Use Read("blueprints/{related-name}.md") to check for overlap
4. Identify overlapping systems that should be documented together

4. Write the Blueprint

Use the Write tool to create or update the blueprint file at blueprints/{system-name}.md.

The file MUST include YAML frontmatter:

---
name: system-name
summary: Brief one-line description
---

# {System Name}
...

The blueprint content should follow this structure:

---
name: system-name
summary: Brief one-line description
---

# {System Name}

{Brief one-line description}

## Overview

{2-3 paragraphs explaining the system's purpose, why it exists, and its role in the larger system}

## Architecture

{Describe the system structure}

### Components

- **{Component A}** - {description}
- **{Component B}** - {description}

### Data Flow

{How data moves through the system}

### Dependencies

- {Dependency 1} - {why it's needed}
- {Dependency 2} - {why it's needed}

## API / Interface

### Public Functions/Methods

#### `functionName(params)`

{Description}

**Parameters:**
- `param1` (type) - {description}

**Returns:** {description}

### Commands

{If applicable, document CLI commands}

### Configuration

{Document configuration options}

## Behavior

### Normal Operation

{How the system behaves under normal conditions}

### Error Handling

{How errors are handled}

### Edge Cases

{Notable edge cases and how they're handled}

## Files

Key implementation files:

- `path/to/main.ts` - {brief description}
- `path/to/helper.ts` - {brief description}

## Related Systems

- [{Related System}](./related-system.md) - {relationship description}

Output

After completing the research and documentation:

1. Create/update the blueprint using Write("blueprints/{system-name}.md", content)
2. Report what was documented and any related systems that may need documentation

Note: The blueprint index at .claude/rules/blueprints/blueprints-index.md is automatically regenerated by the SessionStart hook - you don't need to manually update it.