blueprint
Provides unified CLI access for Blueprint framework - gate validation, document templates, FrontMatter schemas, worker handoffs, constitutions, and worker registry.
When & Why to Use This Skill
The Blueprint skill is a comprehensive CLI-based orchestration tool designed to streamline the development and management of AI agents within the Blueprint framework. It provides a unified interface for handling critical agentic workflows, including document templating, gate validation, multi-agent handoffs, and centralized agent registries. By standardizing how agents interact and follow constitutions, this skill enhances the reliability, scalability, and maintainability of complex AI agent systems.
Use Cases
- Standardizing document creation: Use the 'forma' and 'frontis' modules to generate files from templates and validate FrontMatter schemas, ensuring consistency across large-scale projects.
- Managing multi-agent workflows: Facilitate seamless communication and task transitions between specialized AI workers using the 'hermes' handoff forms and 'polis' agent registry.
- Enforcing quality and safety guardrails: Implement 'aegis' gate validation to verify that agent outputs meet specific criteria and adhere to defined project aspects before proceeding.
- Centralized project and agent management: Organize multiple AI development environments using project aliases and view agent instructions or constitutions via 'lexis' and 'project' modules.
| name | blueprint |
|---|---|
| description | Provides unified CLI access for Blueprint framework - gate validation, document templates, FrontMatter schemas, agent handoffs, constitutions, and agent registry. |
| allowed-tools | Bash, Read |
Blueprint
Unified CLI for the Blueprint orchestration framework.
Quick Reference
| Submodule | Purpose | Data Source |
|---|---|---|
aegis |
Gate validation & aspects | blueprint/gates/ |
forma |
Document templates | blueprint/templates/ |
frontis |
FrontMatter search & schemas | blueprint/front-matters/ |
hermes |
Handoff forms | blueprint/forms/ |
lexis |
Constitution viewer | blueprint/constitutions/ |
plan |
Plan directory & listing | blueprint/plans/ |
polis |
Agent registry | .claude/agents/ |
project |
Project alias management | ~/.claude/blueprint/projects/ |
Command Structure
blueprint <submodule> <subcommand> [flags] [arguments]
│ │ │ └─ Positional values (e.g., <file>, <alias>)
│ │ └─ Options (e.g., --list, --base, --data)
│ └─ Submodule action (e.g., current, show, search)
└─ Functional module (e.g., project, forma, lexis, plan)
Terminology:
- Submodule: Independent functional module (
aegis,forma,frontis,hermes,lexis,plan,polis,project) - Subcommand: Action within a submodule (
current,show,search,init,list) - Flag: Boolean switch (
--list,--base,--aspects) - Argument: Positional value (
<file>,<alias>,<gate>)
Commands
How to Execute:
- This skill is loaded via
/blueprint(provides this instruction) - Run commands in Bash using full path:
~/.claude/skills/blueprint/blueprint.sh <submodule> [args]
# Execute via full path in Bash:
# General
blueprint --help
blueprint --list
# Aegis - Gates
blueprint aegis --list # List all gates
blueprint aegis <gate> # Show gate definition
blueprint aegis <gate> --aspects # List aspects for gate
blueprint aegis <gate> <aspect> # Show specific aspect
# Forma - Templates
blueprint forma list # List available templates
blueprint forma show <name> # Show template content
blueprint forma copy <name> <dir> # Copy template to directory (RECOMMENDED)
# Frontis - FrontMatter
blueprint frontis search <field> <value> [path] # Search by FrontMatter
blueprint frontis show <file> [file...] # Show frontmatter
blueprint frontis schema <type> # View schema
blueprint frontis schema --list # List schemas
# Hermes - Handoff Forms
blueprint hermes --list # List all Handoff forms
blueprint hermes <form> # Show Handoff form (after-*, request:*, response:*)
# Lexis - Constitutions
blueprint lexis --list # List all agents
blueprint lexis <agent> # Show agent constitution
blueprint lexis --base # Show base constitution only
# Plan - Plans
blueprint plan dir # Get plans directory path
blueprint plan list # List all plans
blueprint plan list --status <status> # List plans by status (e.g., in-progress)
blueprint plan resolve <identifier> # Resolve plan path from identifier
# Polis - Agents
blueprint polis --list # List all agents with descriptions
blueprint polis <agent> # Show agent instruction
# Project - Project Aliases
blueprint project init <alias> [--notes "text"] # Initialize new project
blueprint project list # List all projects
blueprint project show <alias> # Show project details
blueprint project remove <alias> --registry [--data-dir] # Remove project
blueprint project link <alias> # Link current path to project
blueprint project unlink <alias> [path] # Unlink path from project
blueprint project rename <new-alias> # Rename project alias
blueprint project manage # Scan and manage projects
blueprint project current # Show current project info
blueprint project current --data # Get data directory path
Examples
# All examples below use 'blueprint' as shorthand.
# Actual execution: ~/.claude/skills/blueprint/blueprint.sh <submodule> [args]
# Find all spec documents
blueprint frontis search type spec
# View spec-lib template
blueprint forma show spec-lib
# Check gate aspects
blueprint aegis documentation --aspects
# View Handoff form
blueprint hermes after-load:standard
# Check agent constitution
blueprint lexis reviewer
# List available agents
blueprint polis --list
# Manage project aliases
blueprint project list
blueprint project init myproject --notes "My project"
# Get plans directory
blueprint plan dir
# List active plans
blueprint plan list --status in-progress
# Resolve specific plan
blueprint plan resolve 001
When to Use
Use this skill when working with Blueprint Framework:
- Creating documents: Use
formafor templates,frontisfor schemas - Validating work: Use
aegisfor gate criteria and aspects - Agent communication: Use
hermesfor handoff formats - Understanding roles: Use
lexisfor constitutions,polisfor agent info - Managing projects: Use
projectfor cross-machine project aliases
Template Usage Guidelines
| Action | Command | Context Impact |
|---|---|---|
| Create file from template | forma copy |
None (recommended) |
| View template structure | forma show |
~500 tokens |
| Validate FrontMatter | frontis schema |
Necessary |
IMPORTANT: Use forma copy to create files. Avoid forma show unless you need to understand template structure without creating a file.
Project Usage Guidelines
Before blueprint project init
Use AskUserQuestion tool to ask the user:
- Project alias - Suggest current directory name as default
- Notes (optional) - Brief description for identification
Workflows
New Project:
- Ask user for alias and notes via AskUserQuestion
- Execute in Bash:
~/.claude/skills/blueprint/blueprint.sh project init <alias> --notes "<notes>"
Existing Project on New Machine:
- Check if project exists:
~/.claude/skills/blueprint/blueprint.sh project list - If project exists, link current path:
~/.claude/skills/blueprint/blueprint.sh project link <alias> - If not, create new project:
~/.claude/skills/blueprint/blueprint.sh project init <alias>
Registry Location
- Registry:
~/.claude/blueprint/projects/.projects - Project data:
~/.claude/blueprint/projects/<alias>/ - Base files:
~/.claude/blueprint/base/
Session Guidelines
path-based Project Notifications:
- Once per session per project: Only mention rename suggestion once
- Track mentioned projects: Don't repeat for the same project in same session
- Be concise: Brief suggestion, not a lecture
Example (first mention):
Project 'Users-duyo-Desktop-test' uses path-based identification.
Consider: `blueprint project rename <alias>`
Using blueprint project manage:
- Run
blueprint project manageto scan - Use AskUserQuestion to gather alias preferences
- Execute appropriate commands (
rename,init, or cleanup)
Before blueprint project remove:
Use AskUserQuestion to confirm with user:
- Confirm removal of the project
- Ask whether to also delete data directory
Then execute with appropriate flags in Bash:
- Registry only:
~/.claude/skills/blueprint/blueprint.sh project remove <alias> --registry - Registry + data:
~/.claude/skills/blueprint/blueprint.sh project remove <alias> --registry --data-dir