Blueprints
v1.1.6MCP server for managing technical blueprint documentation. Use search_blueprints before creating, read_blueprint before modifying, write_blueprint after implementation changes. Includes skills and hooks for quality enforcement.
Installation
Install han binary (required for hooks to work):
curl -fsSL https://han.guru/install.sh | bashThen install this plugin:
han plugin install hashi-blueprintsOverview
MCP server for managing technical blueprint documentation with programmatic tools, skills, and quality enforcement.
Overview
This plugin provides comprehensive blueprint management through:
- MCP Server - Programmatic access to blueprints via JSON-RPC tools
- Skills - Guidelines for writing effective technical blueprints
- Commands - Generate and update documentation
- Hooks - Enforcement and reminders for documentation requirements
Installation
han plugin install hashi-blueprints@han
This installs both the MCP server and the skills/commands/hooks.
MCP Tools
The MCP server exposes three tools for programmatic blueprint access:
search_blueprints
List all available blueprints with their names and summaries.
Parameters:
keyword(optional): Filter blueprints by keyword in name or summary
Returns:
{
blueprints: Array<{
name: string;
summary: string;
}>
}
read_blueprint
Read the full content of a specific blueprint.
Parameters:
name(required): Blueprint name (without .md extension)
Returns:
{
name: string;
summary: string;
content: string; // Markdown content without frontmatter
}
write_blueprint
Create or update a blueprint with frontmatter.
Parameters:
name(required): Blueprint name (without .md extension)summary(required): Short summary of the blueprintcontent(required): Markdown content (frontmatter added automatically)
Returns:
{
success: boolean;
message: string;
}
Commands
/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 command:
- Discovers all systems in the codebase
- Audits existing blueprints for accuracy
- Creates missing documentation
- Updates outdated blueprints
- Uses MCP tools to manage blueprint files
Skills
- blueprints-writing - How to write effective technical blueprints
- blueprints-maintenance - Keeping blueprints in sync with implementation
- blueprints-organization - Directory structure and avoiding duplication
Hooks
UserPromptSubmit
Injects documentation requirements into every prompt, reminding you when to create or update blueprints.
Stop
Prompt-based hook that asks Claude to verify blueprints match the changes just made, offering to update documentation if needed.
Blueprint Format
All blueprints must include YAML frontmatter:
---
name: system-name
summary: Brief description of what this system does
---
# System Name
[Blueprint content...]
Blueprint File Template
---
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 README.md index is no longer required - blueprint discovery is handled by the MCP server using frontmatter metadata.
De-duplication
The plugin enforces de-duplication through:
- Search before creating - Use
search_blueprintsMCP tool - Cross-references - Link between blueprints instead of copying
- Merge guidance - Combine related systems when appropriate
- MCP-based discovery - Frontmatter metadata enables programmatic search
Related Plugins
- bushido: Core quality principles and standards
License
MIT
MCP Servers
blueprints
Commands
Skills
blueprints-maintenance
Use after modifying existing systems to update blueprint documentation. Read blueprints with read_blueprint before changes, update with write_blueprint after. Prevents documentation drift.
blueprints-organization
Use when managing blueprints directory structure and avoiding duplication. Always search_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 use search_blueprints first to avoid duplication, then write_blueprint with proper structure.
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.
echo '# Blueprint System Available
This project uses technical blueprints for system documentation.
**MCP Tools:**
- search_blueprints - Find existing blueprints (use BEFORE creating)
- read_blueprint - Read current documentation (use BEFORE modifying)
- write_blueprint - Update documentation (use AFTER implementation)
**When to use:** New features, API changes, architectural modifications, behavior changes.
See UserPromptSubmit hook for detailed requirements.'UserPromptSubmit
Runs when the user submits a prompt, before Claude processes it. Can inject required context, enforce workflows, or validate user intent before processing begins.
Stop
Runs when the main Claude Code agent has finished responding. Can verify task completion, check quality gates, or ensure documentation requirements are met before the session ends.