Blueprint

Blueprint

Unified CLI for the Blueprint orchestration framework.

CRITICAL: Data Location

Blueprint project data (plans, session state, configurations) is NOT stored in local project directories.

You MUST:

• Load this skill FIRST when user asks about Blueprint projects, plans, or status
• Use blueprint commands to access project data

You MUST NOT:

• Search local directories (./blueprint/, ./.claude/) for Blueprint data
• Assume "no local files" means "not initialized"

Without loading this skill, you cannot determine Blueprint project status.

Quick Reference

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:

1. This skill is loaded via /blueprint (provides this instruction)
2. 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

Load this skill IMMEDIATELY when user mentions:

• Blueprint project, plan, or phase
• Plan status or progress
• Project initialization or registration

Then use appropriate commands:

• Checking status: project current - determines if project is registered
• Viewing plans: plan list - shows available plans
• Reading FrontMatter: frontis show - do NOT use head or direct file reading
• Creating documents: forma for templates, frontis for schemas
• Validating work: aegis for gate criteria and aspects
• Agent communication: hermes for handoff formats
• Understanding roles: lexis for constitutions, polis for agent info

Template Usage Guidelines

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:

1. Project alias - Suggest current directory name as default
2. Notes (optional) - Brief description for identification

Workflows

New Project:

1. Ask user for alias and notes via AskUserQuestion
2. Execute in Bash: ~/.claude/skills/blueprint/blueprint.sh project init <alias> --notes "<notes>"

Existing Project on New Machine:

1. Check if project exists: ~/.claude/skills/blueprint/blueprint.sh project list
2. If project exists, link current path: ~/.claude/skills/blueprint/blueprint.sh project link <alias>
3. If not, create new project: ~/.claude/skills/blueprint/blueprint.sh project init <alias>

Data Locations

NOTE: For querying (status checks, listing), use submodule commands. Direct file access is permitted when following skill instructions (e.g., /bplan, /save, /load).

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:

1. Run blueprint project manage to scan
2. Use AskUserQuestion to gather alias preferences
3. Execute appropriate commands (rename, init, or cleanup)

Before blueprint project remove: Use AskUserQuestion to confirm with user:

1. Confirm removal of the project
2. 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