Documentation/Tools/Blueprints
šŸ”§

Blueprints

v1.2.0Apache 2.0

Skills and hooks for managing technical blueprint documentation. Provides guidelines for writing, maintaining, and organizing blueprints using native tools (Glob, Grep, Read, Write).

toolsskillhookblueprintsdocumentationtechnical-docsimplementation-docsarchitecture

Installation

Install han binary (required for hooks to work):

curl -fsSL https://han.guru/install.sh | bash

Then install this plugin:

han plugin install blueprints

Overview

Skills and hooks for managing technical blueprint documentation.

Overview

This plugin provides comprehensive blueprint management through:

  • Skills - Guidelines for writing, maintaining, and organizing technical blueprints
  • Hooks - Enforcement and reminders for documentation requirements

Blueprint files are managed using native Claude Code tools (Glob, Grep, Read, Write) - no external server required.

Installation

bash
han plugin install blueprints

This installs the skills and hooks.

Slash Commands (via Skills)

/blueprint <system-name>

Research a specific system and create or update its documentation:

/blueprint mcp-server
/blueprint authentication
/blueprint lib/commands/hook

/blueprints

Deeply research all systems and create comprehensive documentation:

/blueprints

This skill:

  1. Discovers all systems in the codebase
  2. Audits existing blueprints for accuracy
  3. Creates missing documentation
  4. Updates outdated blueprints

Skills

  • blueprints-writing - How to write effective technical blueprints
  • blueprints-maintenance - Keeping blueprints in sync with implementation
  • blueprints-organization - Directory structure and avoiding duplication

Tool Usage

Blueprints are managed with native Claude Code tools:

  • Glob("blueprints/*.md") - List all blueprint files
  • Grep("keyword", path: "blueprints/") - Search blueprints by keyword
  • Read("blueprints/{name}.md") - Read a blueprint
  • Write("blueprints/{name}.md", content) - Create or update a blueprint (include frontmatter)

Hooks

SessionStart

Syncs the blueprint index to .claude/rules/blueprints/blueprints-index.md for automatic context injection.

Blueprint Format

All blueprints must include YAML frontmatter:

markdown
---
name: system-name
summary: Brief description of what this system does
---

# System Name

[Blueprint content...]

Blueprint File Template

markdown
---
name: system-name
summary: One-line description
---

# System Name

Brief description.

## Overview

Purpose and role in the larger system.

## Architecture

Components, data flow, dependencies.

## 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.

blueprints/ Directory Structure

blueprints/
ā”œā”€ā”€ system-name.md      # One file per system
ā””ā”€ā”€ feature-name.md     # One file per feature

Note: The index at .claude/rules/blueprints/blueprints-index.md is auto-generated by the SessionStart hook.

De-duplication

The plugin enforces de-duplication through:

  1. Search before creating - Use Glob and Grep to find existing blueprints
  2. Cross-references - Link between blueprints instead of copying
  3. Merge guidance - Combine related systems when appropriate
  4. Frontmatter metadata - Enables discovery via the auto-generated index

Related Plugins

  • bushido: Core quality principles and standards

Skills

šŸ“–

blueprints-maintenance

Use after modifying existing systems to update blueprint documentation. Read blueprints before changes, update after. Prevents documentation drift.

šŸ“–

blueprints-organization

Use when managing blueprints directory structure and avoiding duplication. Always search existing blueprints before creating to prevent duplicate documentation. Handles naming conventions and cross-references.

šŸ“–

blueprints-writing

Use when creating or updating technical blueprint documentation for new features, API changes, or architectural modifications. Always search existing blueprints first to avoid duplication, then write with proper structure.

šŸ“–

create-blueprint

Research a specific system and create or update its blueprints/ documentation

šŸ“–

generate-blueprints

Deeply research all systems and create or update blueprints/ documentation for the entire codebase

Hooks

ā–¶ļø

SessionStart

Runs when Claude Code starts a new session or resumes an existing session. Can inject project context, set up environment, or provide important reminders at the start of work.

han blueprints sync-index
ā±ļø 10s