Blueprint Execute

Intelligent meta command that analyzes repository state and executes the appropriate blueprint action.

When to Use This Skill

Concept: Run this command anytime to automatically determine what should happen next in your blueprint workflow. Safe to run repeatedly - it's idempotent and will always figure out the right action.

Usage: /blueprint:execute

How it works: This command acts as an orchestrator, detecting your project's current state and delegating to specific blueprint commands as needed. It uses parallel agents for efficient context gathering.

For detailed AskUserQuestion templates, examples, and common workflows, see REFERENCE.md.

---

Phase 0: Parallel Context Gathering

Launch these agents simultaneously to gather context:

Consolidate findings into unified context: git quality, documentation coverage, blueprint health, actionable items.

---

State Detection & Action Flow

Run through these checks in order, executing the first matching action:

1. Check Initialization

test -f docs/blueprint/manifest.json

If NOT initialized: Run /blueprint:init, then Exit.

2. Check for Upgrades

cat docs/blueprint/manifest.json | grep '"format_version"'

Current format version: 3.0.0

If manifest version < 3.0.0: Run /blueprint:upgrade, then Exit.

2.5. Check Task Registry for Due Tasks

If manifest has task_registry:

jq -r '.task_registry | to_entries[] | select(.value.enabled == true) | select(.value.auto_run == true) | .key' docs/blueprint/manifest.json

For each enabled auto_run task, check if due based on schedule:

• daily: Due if last_completed_at is null or > 24h ago
• weekly: Due if last_completed_at is null or > 7d ago
• on-change: Due if source inputs changed (checked by individual task)
• on-demand: Never auto-triggered

If auto_run tasks are due: Execute them silently in order (read-only tasks like validate, sync). Report results briefly. Continue to next check.

If non-auto_run tasks are due: Note them for display in status. Don't prompt here - let specific checks handle them.

3. Check for Missing Documentation (Derive Phase)

git rev-list --count HEAD 2>/dev/null || echo 0
find docs/prds -name "*.md" 2>/dev/null | wc -l
find docs/adrs -name "*.md" 2>/dev/null | wc -l
cat docs/blueprint/manifest.json | jq -r '.derived_rules.last_derived_at // empty'

If git history (>10 commits) but NO PRDs and NO ADRs: Prompt for derivation method (derive all, PRD only, ADRs only, or skip). Execute selected action, then Exit.

If git history but NO derived rules: Prompt to derive rules from git. If yes, run /blueprint:derive-rules, then Exit.

4. Check for Stale/Modified Generated Content

Check each generated rule hash against manifest:

If stale (PRDs changed since generation): Prompt to regenerate or skip. If regenerate, run /blueprint:generate-rules, then Exit.

If modified (user edited generated files): Prompt to review, promote to custom layer, or skip. Execute selected action, then Exit.

5. Check for PRDs Without Generated Rules

prd_count=$(find docs/prds -name "*.md" 2>/dev/null | wc -l)
generated_count=$(cat docs/blueprint/manifest.json | jq '.generated.rules | length')

If PRDs exist but no generated rules: Run /blueprint:generate-rules, then Exit.

6. Check for Ready PRPs

find docs/prps -name "*.md" -type f 2>/dev/null

If multiple high-confidence PRPs (>= 2 with score >= 9): Prompt for parallel work-order creation or single PRP execution.

If single PRP or user selects one: Run /blueprint:prp-execute {selected-prp}, then Exit.

7. Check for Pending Work-Orders

find docs/blueprint/work-orders -maxdepth 1 -name "*.md" -type f 2>/dev/null

If work-orders found: Prompt for selection. Execute chosen work-order, move to completed/ when done, sync feature tracker if enabled, then Exit.

8. Check Feature Tracker for Active Tasks

cat docs/blueprint/feature-tracker.json | jq '{
  in_progress: .tasks.in_progress,
  pending: .tasks.pending,
  current_phase: .current_phase
}'

If in-progress tasks: Prompt to continue, create work-order, or skip. Execute selection, then Exit.

If pending tasks (no in-progress): Prompt to start task, create PRP, create work-order, or skip. Execute selection, then Exit.

9. Check Feature Tracker (If Enabled)

test -f docs/blueprint/feature-tracker.json

Auto-sync if due per task_registry schedule (default: daily) or after PRP execution/work-order completion. See REFERENCE.md for sync details.

If completion < 100%: Show status and prompt for next feature work.

If completion == 100%: Report all features complete, continue to step 10.

10. No Clear Next Action - Show Status & Options

Run /blueprint:status to display full blueprint status with available next actions.

---

Registry Updates

After executing any task action, update the corresponding task_registry entry in manifest.json:

jq --arg task "$TASK_NAME" --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg result "$RESULT" \
  '.task_registry[$task].last_completed_at = $now | .task_registry[$task].last_result = $result | .task_registry[$task].stats.runs_total = ((.task_registry[$task].stats.runs_total // 0) + 1)' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

This ensures every execute run updates operational metadata for tracking and future scheduling decisions.

Idempotency Guarantees

Integration with Existing Commands

This meta command delegates to existing blueprint commands rather than replacing them. Users can still run specific commands directly when they know what they want. /blueprint:execute is for when you want the system to decide.

Agentic Optimizations

---

Note: This is a meta-orchestrator command. It analyzes state and delegates to specific blueprint commands. It's designed to be the "smart entry point" for blueprint workflow while preserving access to individual commands for power users.

Blueprint Execute - Reference

Detailed reference material for the blueprint-execute meta command, including AskUserQuestion templates, examples, and common workflows.

AskUserQuestion Templates

Step 3: Missing Documentation Prompt

question: "This project has git history but no PRDs/ADRs. How would you like to derive documentation?"
options:
  - label: "Derive all from git history (Recommended)"
    description: "Run /blueprint:derive-plans for comprehensive analysis"
  - label: "Derive PRD only"
    description: "Run /blueprint:derive-prd from README and docs"
  - label: "Derive ADRs only"
    description: "Run /blueprint:derive-adr from codebase analysis"
  - label: "Skip derivation"
    description: "I'll create documentation manually"

Step 3: Derived Rules Prompt

question: "Would you like to derive rules from git commit decisions?"
options:
  - label: "Yes, derive rules from git"
    description: "Run /blueprint:derive-rules to extract decisions from commits"
  - label: "Skip for now"
    description: "Continue with other actions"

Step 4: Stale Content Prompt

question: "Generated content is out of sync with PRDs. What would you like to do?"
options:
  - label: "Regenerate from PRDs (Recommended)"
    description: "Update generated rules to match current PRD content"
  - label: "Skip for now"
    description: "Continue with other actions"

Step 4: Modified Content Prompt

question: "You've modified generated content. What would you like to do?"
options:
  - label: "Review changes"
    description: "Run /blueprint:sync to see what changed"
  - label: "Promote to custom layer"
    description: "Move edited files to custom layer to prevent regeneration"
  - label: "Skip for now"
    description: "Continue with other actions"

Step 6: Multiple Ready PRPs Prompt

question: "Multiple PRPs are ready for parallel execution. What would you like to do?"
options:
  - label: "Create work-orders for all (parallel delegation)"
    description: "Generate work-orders for {count} PRPs to execute in parallel"
  - label: "Execute one PRP now"
    description: "Choose a single PRP to execute in this session"
  - label: "Skip PRP execution"
    description: "Continue to other actions"

Step 6: PRP Selection Prompt

question: "Found {count} PRP(s). Which would you like to execute?"
options:
  - label: "{prp-1-name} (confidence: {score})"
    description: "Execute this PRP with TDD workflow"
  - label: "{prp-2-name} (confidence: {score})"
    description: "Execute this PRP with TDD workflow"
  - label: "Skip PRP execution"
    description: "Continue to other actions"

Step 7: Pending Work-Orders Prompt

question: "Found {count} pending work-order(s). What would you like to do?"
options:
  - label: "Execute: {work-order-1}"
    description: "Run this work-order"
  - label: "Execute: {work-order-2}"
    description: "Run this work-order"
  - label: "Skip work-orders"
    description: "Continue to other actions"

Step 8: In-Progress Tasks Prompt

question: "You have in-progress tasks. What would you like to do?"
options:
  - label: "Continue: {first-task.description}"
    description: "Resume work on [{first-task.id}]"
  - label: "Create work-order for delegation"
    description: "Package current task for subagent execution"
  - label: "Skip to pending tasks"
    description: "Move to pending items instead"

Step 8: Pending Tasks Prompt

question: "You have pending tasks. What would you like to do?"
options:
  - label: "Start: {first-task.description}"
    description: "Begin work on [{first-task.id}]"
  - label: "Create PRP for task"
    description: "Create detailed PRP for systematic execution"
  - label: "Create work-order for task"
    description: "Package task for subagent execution"
  - label: "Skip for now"
    description: "Continue to other checks"

Step 9: Feature Tracker Prompt

question: "Feature tracker: {complete}/{total} complete ({percentage}%). What's next?"
options:
  - label: "Work on: {next-incomplete-feature}"
    description: "Start implementing this feature"
  - label: "Create PRP for feature"
    description: "Create detailed implementation plan"
  - label: "View detailed status"
    description: "Run /blueprint:feature-tracker-status"
  - label: "Continue to other actions"
    description: "Skip feature work for now"

Examples

Example 1: Uninitialized Project

$ /blueprint:execute

Output:

Blueprint not initialized in this project.

Initializing blueprint structure...
[Runs /blueprint:init]

Example 2: Has Ready PRPs

$ /blueprint:execute

Output:

Blueprint Status: Up to date (v3.0.0)

Found 2 ready PRPs:
1. add-authentication.md (confidence: 9/10)
2. optimize-performance.md (confidence: 8/10)

[Prompts: Which PRP to execute?]

Example 3: All Caught Up

$ /blueprint:execute

Output:

Blueprint Status: Up to date (v3.0.0)

No pending PRPs, work-orders, or stale content detected.

[Shows full status from /blueprint:status]
[Prompts: What would you like to do next?]

Example 4: Stale Generated Content

$ /blueprint:execute

Output:

Blueprint Status: Attention needed

Stale generated content detected: 2 files
- architecture-patterns.md (PRD changed on 2026-01-13)
- testing-strategies.md (PRD changed on 2026-01-12)

[Prompts: Regenerate from PRDs?]

Common Workflows

Morning Start Routine

$ /blueprint:execute  # Figures out where you left off

After Pulling Changes

$ /blueprint:execute  # Checks for stale content, upgrades, etc.

Periodic Check-in

$ /blueprint:execute  # Shows progress, suggests next work

Stuck or Unsure

$ /blueprint:execute  # Always knows what to do next

Benefits

1. Reduced cognitive load: No need to remember which command to run 2. Progressive workflow: Naturally guides through blueprint methodology 3. Safe exploration: Can run anytime without breaking things 4. Smart defaults: Automatically picks the right action for current state 5. Flexible: Can skip actions and continue to next check 6. Always actionable: Always suggests next steps, never leaves you stuck

Feature Tracker Auto-Sync Details

When feature tracker exists and is stale (> 1 day old), or a PRP was just executed, or a work-order was completed:

1. Read current feature-tracker.json 2. Read TODO.md (if exists) for checkbox states 3. Detect any discrepancies (checked boxes vs tracker status) 4. Auto-resolve discrepancies by trusting TODO.md (most recently edited by user) 5. Update feature-tracker.json with new statistics and task states 6. Report changes made (if any)

Auto-sync is silent when no changes - only reports if something was updated.

Task Registry Schedule Logic

Due Calculation

Priority Order for Due Tasks

When multiple tasks are due, execute in this order: 1. sync-ids (fast, foundational) 2. feature-tracker-sync (fast, updates status) 3. adr-validate (fast, read-only check) 4. generate-rules (may modify files) 5. derive-rules (may modify files) 6. derive-plans (longer running) 7. claude-md (depends on other outputs)

Auto-Run Task Prompt (for due non-auto tasks)

question: "These maintenance tasks are due. Which would you like to run?"
options:
  - label: "Run all due tasks"
    description: "Execute {N} due tasks in priority order"
  - label: "Choose specific tasks"
    description: "Select which tasks to run"
  - label: "Skip maintenance"
    description: "Continue to other actions"