Name

blueprints:generate-blueprints - Generate comprehensive blueprint documentation for the entire codebase

Synopsis

/blueprints

Description

Comprehensively document all systems in the codebase by creating or updating the blueprints/ directory at the repository root with technical documentation for each major system.

Important: Blueprint Location

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

• {repo-root}/blueprints/

• {repo-root}/packages/foo/blueprints/

• {repo-root}/src/blueprints/

Blueprints are repository-wide system design documents. Systems may span multiple packages or directories, but all blueprints belong in a single blueprints/ directory at the repo root.

Implementation

You are tasked with comprehensively documenting all systems in this codebase.

Process

Phase 1: Discovery

Analyze project structure to identify all major systems:

• Top-level directories and their purposes

• Package/module boundaries

• Entry points (main files, CLI commands, API endpoints)

• Configuration systems

Read existing documentation:

• README.md files at all levels

• Any existing blueprints/ directory

• Inline documentation patterns

• Test files for behavioral documentation

Create a system inventory:

• List all distinct systems/features

• Note dependencies between systems

• Identify documentation gaps

Phase 2: Audit Existing Blueprints

Audit existing documentation using native tools:

• List all blueprints: Use Glob("blueprints/*.md") to find all existing blueprint files

• Read each blueprint: Use Read("blueprints/{name}.md") to check each documented system:

• Does the blueprint match current implementation?

• Are there new features not documented?

• Is any documented functionality removed?

• Identify orphaned blueprints (documentation for removed systems)

Phase 3: Prioritize Documentation

Order systems by importance:

• Core systems - Central functionality everything depends on

• Public APIs - User-facing features and interfaces

• Integration points - How systems connect

• Supporting systems - Utilities and helpers

Phase 4: Generate Documentation

For each system, use the Write tool to create or update the blueprint file:

Write("blueprints/{system-name}.md", content)

Each file MUST include YAML frontmatter:

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

{System Name}

{Brief description}

Overview

{Purpose and role in the larger system}

Architecture

{Structure, components, data flow}

API / Interface

{Public methods, commands, configuration}

Behavior

{Normal operation, error handling, edge cases}

Files

{Key implementation files with descriptions}

Related Systems

{Links to related blueprints}

Phase 5: Index Management

The blueprint index is automatically managed by the SessionStart hook. When you run han blueprints sync-index , the index is updated at .claude/rules/blueprints/blueprints-index.md .

You don't need to manually create or update any index files - just focus on creating quality blueprint content using the Write tool.

De-duplication Strategy

When documenting, actively prevent duplicates:

• Check before creating - Use Glob("blueprints/*.md") and Grep to search for existing coverage

• Read existing blueprints - Use Read("blueprints/{name}.md") to check content

• Merge related systems - Document tightly coupled systems together

• Use cross-references - Link between blueprints rather than duplicating

• One source of truth - Each concept documented in exactly one place

Output

After completing:

• List all systems discovered

• List blueprints created/updated

• Note any systems that couldn't be documented (why)

• Identify areas needing future documentation

Remember: Use native tools (Glob, Grep, Read, Write) to manage blueprint files. The frontmatter format (name and summary fields) enables discovery via the auto-generated index.