Initialize Blueprint Development in this project. Steps : Check if already initialized : Look for docs/blueprint/manifest.json If exists, read version and ask user: Use AskUserQuestion: question: "Blueprint already initialized (v{version}). What would you like to do?" options: - "Check for upgrades" → run /blueprint:upgrade - "Reinitialize (will reset manifest)" → continue with step 2 - "Cancel" → exit Ask about feature tracking (use AskUserQuestion): question: "Would you like to enable feature tracking?" options: - label: "Yes - Track implementation against requirements" description: "Creates feature-tracker.json to track FR codes from a requirements document" - label: "No - Skip feature tracking" description: "Can be added later with /blueprint:feature-tracker-sync" If "Yes" selected: a. Search for markdown files in the project that contain requirements, features, or user stories b. Auto-detect the most likely source document based on content analysis c. Create docs/blueprint/feature-tracker.json from template using the detected source d. Set has_feature_tracker: true in manifest Ask about document migration (use AskUserQuestion): Search for existing markdown documentation files across the project (excluding standard files like README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE.md, CODE_OF_CONDUCT.md, SECURITY.md).
Find markdown files that look like documentation (not standard repo files)
- find
- .
- -name
- '*.md'
- -not
- -path
- '/node_modules/'
- -not
- -path
- '/.git/'
- |
- grep
- -viE
- '(README|CHANGELOG|CONTRIBUTING|LICENSE|CODE_OF_CONDUCT|SECURITY).md$'
- If documentation files found
- (e.g., REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, docs in non-standard locations):
- Use AskUserQuestion:
- question: "Found existing documentation: {file_list}. Migrate these to Blueprint-managed paths? (Strongly recommended)"
- options:
- - label: "Yes, migrate documents (Recommended)"
- description: "Move docs into docs/prds/, docs/adrs/, docs/prps/ based on content type. Prevents stale and orphaned documents."
- - label: "No, leave them in place"
- description: "Warning: unmigrated docs may become stale or duplicated as Blueprint creates its own documents"
- If "Yes" selected:
- a. Analyze each file to determine type:
- Contains requirements, features, user stories →
- docs/prds/
- Contains architecture decisions, trade-offs →
- docs/adrs/
- Contains implementation plans →
- docs/prps/
- General documentation →
- docs/
- b. Move files to appropriate
- docs/
- subdirectory
- c. Rename to kebab-case if needed (REQUIREMENTS.md → requirements.md)
- d. Report migration results:
- Migrated documentation:
- - REQUIREMENTS.md → docs/prds/requirements.md
- - ARCHITECTURE.md → docs/adrs/0001-initial-architecture.md
- If no documentation files found:
- Skip this step silently.
- Ask about maintenance task scheduling
- (use AskUserQuestion):
- question: "How should blueprint maintenance tasks run?"
- options:
- - label: "Prompt before running (Recommended)"
- description: "Always ask before running maintenance tasks like sync, validate"
- - label: "Auto-run safe tasks"
- description: "Read-only tasks (validate, sync, status) run automatically when due"
- - label: "Fully automatic"
- description: "All tasks run automatically on schedule, including writes like rule generation"
- - label: "Manual only"
- description: "Tasks only run when you explicitly invoke them"
- Store selection for task_registry defaults:
- Prompt
-
- all
- auto_run: false
- , default schedules
- Auto-run safe
-
- read-only tasks (
- adr-validate
- ,
- feature-tracker-sync
- ,
- sync-ids
- ) get
- auto_run: true
- ; write tasks get
- false
- Fully automatic
-
- all tasks get
- auto_run: true
- , default schedules
- Manual only
-
- all
- auto_run: false
- , all schedules set to
- on-demand
- Ask about decision detection
- (use AskUserQuestion):
- question: "Would you like to enable automatic decision detection?"
- options:
- - label: "Yes - Detect decisions worth documenting"
- description: "Claude will notice when conversations contain architecture decisions, feature requirements, or implementation plans that should be captured as ADR/PRD/PRP documents"
- - label: "No - Manual commands only"
- description: "Use /blueprint:derive-prd, /blueprint:derive-adr, /blueprint:prp-create explicitly when you want to create documents"
- Set
- has_document_detection
- in manifest based on response.
- If enabled:
- Copy
- document-management-rule.md
- template to
- .claude/rules/document-management.md
- .
- This rule instructs Claude to watch for:
- Architecture decisions being made during discussion → prompt to create ADR
- Feature requirements being discussed or refined → prompt to create/update PRD
- Implementation plans being formulated → prompt to create PRP
- Create directory structure
- :
- Blueprint structure (in docs/blueprint/):
- docs/
- ├── blueprint/
- │ ├── manifest.json # Version tracking and configuration
- │ ├── feature-tracker.json # Progress tracking (if enabled)
- │ ├── work-orders/ # Task packages for subagents
- │ │ ├── completed/
- │ │ └── archived/
- │ ├── ai_docs/ # Curated documentation (on-demand)
- │ │ ├── libraries/
- │ │ └── project/
- │ └── README.md # Blueprint documentation
- ├── prds/ # Product Requirements Documents
- ├── adrs/ # Architecture Decision Records
- └── prps/ # Product Requirement Prompts
- Claude configuration (in .claude/):
- .claude/
- ├── rules/ # Modular rules (including generated)
- │ ├── development.md # Development workflow rules
- │ ├── testing.md # Testing requirements
- │ └── document-management.md # Document organization rules (if detection enabled)
- └── skills/ # Custom skill overrides (optional)
- Create
- manifest.json
- (v3.2.0 schema):
- {
- "format_version"
- :
- "3.2.0"
- ,
- "created_at"
- :
- "[ISO timestamp]"
- ,
- "updated_at"
- :
- "[ISO timestamp]"
- ,
- "created_by"
- :
- {
- "blueprint_plugin"
- :
- "3.2.0"
- }
- ,
- "project"
- :
- {
- "name"
- :
- "[detected from package.json/pyproject.toml or directory name]"
- ,
- "detected_stack"
- :
- [
- ]
- }
- ,
- "structure"
- :
- {
- "has_prds"
- :
- true
- ,
- "has_adrs"
- :
- true
- ,
- "has_prps"
- :
- true
- ,
- "has_work_orders"
- :
- true
- ,
- "has_ai_docs"
- :
- false
- ,
- "has_modular_rules"
- :
- true
- ,
- "has_feature_tracker"
- :
- "[based on user choice]"
- ,
- "has_document_detection"
- :
- "[based on user choice]"
- ,
- "claude_md_mode"
- :
- "both"
- }
- ,
- "feature_tracker"
- :
- {
- "file"
- :
- "feature-tracker.json"
- ,
- "source_document"
- :
- "[auto-detected]"
- ,
- "sync_targets"
- :
- [
- "TODO.md"
- ]
- }
- ,
- "generated"
- :
- {
- "rules"
- :
- {
- }
- ,
- "commands"
- :
- {
- }
- }
- ,
- "custom_overrides"
- :
- {
- "skills"
- :
- [
- ]
- ,
- "commands"
- :
- [
- ]
- }
- ,
- "task_registry"
- :
- {
- "derive-prd"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- false
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "on-demand"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "derive-plans"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- false
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "weekly"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "derive-rules"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- false
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "weekly"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "generate-rules"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- false
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "on-change"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "adr-validate"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- "[based on maintenance task choice: true if auto-run safe, false otherwise]"
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "weekly"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "feature-tracker-sync"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- "[based on maintenance task choice: true if auto-run safe, false otherwise]"
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "daily"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "sync-ids"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- "[based on maintenance task choice: true if auto-run safe, false otherwise]"
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "on-change"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "claude-md"
- :
- {
- "enabled"
- :
- true
- ,
- "auto_run"
- :
- false
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "on-change"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- ,
- "curate-docs"
- :
- {
- "enabled"
- :
- false
- ,
- "auto_run"
- :
- false
- ,
- "last_completed_at"
- :
- null
- ,
- "last_result"
- :
- null
- ,
- "schedule"
- :
- "on-demand"
- ,
- "stats"
- :
- {
- }
- ,
- "context"
- :
- {
- }
- }
- }
- }
- Note: Include
- feature_tracker
- section only if feature tracking is enabled.
- Note: As of v3.2.0, progress tracking is consolidated into feature-tracker.json (work-overview.md removed).
- Create initial rules
- :
- development.md
-
- TDD workflow, commit conventions
- testing.md
-
- Test requirements, coverage expectations
- document-management.md
- Document organization rules (if decision detection enabled) Handle .gitignore : Always commit CLAUDE.md and .claude/rules/ (shared project instructions) Add docs/blueprint/work-orders/ to .gitignore (task-specific, may contain sensitive details) If secrets detected in .claude/ , warn user and suggest .gitignore entries Report : Blueprint Development initialized! (v3.2.0) Blueprint structure created: - docs/blueprint/manifest.json - docs/blueprint/work-orders/ - docs/blueprint/ai_docs/ - docs/blueprint/README.md [- docs/blueprint/feature-tracker.json (if feature tracking enabled)] Project documentation: - docs/prds/ (Product Requirements Documents) - docs/adrs/ (Architecture Decision Records) - docs/prps/ (Product Requirement Prompts) Claude configuration: - .claude/rules/ (modular rules, including generated) - .claude/skills/ (custom skill overrides) Configuration: - Rules mode: both (CLAUDE.md + .claude/rules/) [- Feature tracking: enabled] [- Decision detection: enabled (Claude will prompt when discussions should become ADR/PRD/PRP)] [- Task scheduling: {prompt|auto-run safe|fully automatic|manual only}] [Migrated documentation:] [- {original} → {destination} (for each migrated file)] Architecture: - Plugin layer: Generic commands from blueprint-plugin (auto-updated) - Generated layer: Rules/commands regeneratable from docs/prds/ - Custom layer: Your overrides in .claude/skills/ Prompt for next action (use AskUserQuestion): question: "Blueprint initialized. What would you like to do next?" options: - label: "Derive plans from git history (Recommended)" description: "Analyze commit history, PRs, and issues to build PRDs, ADRs, and PRPs from existing project decisions" - label: "Derive rules from codebase" description: "Analyze commit patterns and code conventions to generate .claude/rules/" - label: "Update CLAUDE.md" description: "Generate or update CLAUDE.md with project context and blueprint integration" - label: "I'm done for now" description: "Exit - you can run /blueprint:status anytime to see options" Based on selection: "Derive plans from git history" → Run /blueprint:derive-plans "Derive rules from codebase" → Run /blueprint:derive-rules "Update CLAUDE.md" → Run /blueprint:claude-md "I'm done for now" → Show quick reference and exit Quick Reference (show if user selects "I'm done for now"): Management commands: - /blueprint:status - Check version and configuration - /blueprint:upgrade - Upgrade to latest format version - /blueprint:derive-prd - Derive PRD from existing documentation - /blueprint:derive-adr - Derive ADRs from codebase analysis - /blueprint:derive-plans - Derive docs from git history - /blueprint:derive-rules - Derive rules from git commit decisions - /blueprint:prp-create - Create a Product Requirement Prompt - /blueprint:generate-rules - Generate rules from PRDs - /blueprint:sync - Check for stale generated content - /blueprint:promote - Move generated content to custom layer - /blueprint:rules - Manage modular rules - /blueprint:claude-md - Update CLAUDE.md - /blueprint:feature-tracker-status - View feature completion stats - /blueprint:feature-tracker-sync - Sync tracker with project files