create-blueprint

## Name blueprints:create-blueprint - Generate or update blueprint documentation for a specific system ## Synopsis ```text /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: ```markdown --- name: system-name summary: Brief one-line description --- # {System Name} ... ``` The blueprint content should follow this structure: ```markdown --- 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.