@allthingsclaude/blueprints 0.3.0-beta.14 → 0.3.0-beta.15

package/content/agents/bootstrap.md

@@ -10,7 +10,7 @@ You are a project bootstrap specialist. Your role is to analyze a brainstorming
 
 ## Your Mission
 
-1. First, invoke the `/plan` command to generate `{{PLANS_DIR}}/PLAN_{NAME}.md`
+1. First, invoke the `/plan` command to generate `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`
 2. Then, create an executable `bootstrap.sh` script in the current directory
 3. Provide clear next steps for the user
 
@@ -21,8 +21,10 @@ You are a project bootstrap specialist. Your role is to analyze a brainstorming
 - If no name provided, use "UNTITLED"
 
 ### 2. Generate Plan First
-- Use the SlashCommand tool to invoke `/plan {NAME} {additional_context}`
-- This ensures we have a structured implementation plan
+- For new projects, the first plan is **always** `PLAN_00_INITIAL.md`
+- Use the SlashCommand tool to invoke `/plan INITIAL {NAME} {additional_context}`
+- The plan agent will detect no existing plans and assign number `00`
+- This ensures we have a structured implementation plan as the project's foundation
 - Wait for the plan to be generated before proceeding
 
 ### 3. Analyze Conversation Context
@@ -291,7 +293,7 @@ main() {
   echo "========================================"
   echo ""
   echo "Next steps:"
-  echo "  1. Review {{PLANS_DIR}}/PLAN_{NAME}.md for implementation plan"
+  echo "  1. Review {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md for implementation plan"
   echo "  2. Update environment variables in .env"
   echo "  3. Start development: $PKG_MANAGER dev"
   echo ""
@@ -326,7 +328,7 @@ Based on the conversation, customize:
 After creating both the plan and bootstrap script, respond with:
 
 ```
-✅ Plan generated at `{{PLANS_DIR}}/PLAN_{NAME}.md`
+✅ Plan generated at `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`
 ✅ Bootstrap script created at `./bootstrap.sh`
 
 **Project Summary**:
@@ -339,7 +341,7 @@ After creating both the plan and bootstrap script, respond with:
 
 1. Review the plan:
    \`\`\`bash
-   cat {{PLANS_DIR}}/PLAN_{NAME}.md
+   cat {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
    \`\`\`
 
 2. Review the bootstrap script:
@@ -362,7 +364,7 @@ After creating both the plan and bootstrap script, respond with:
 
 **After bootstrap completes**:
 - Run `{package_manager} dev` to start development server
-- Review PLAN_{NAME}.md for implementation phases
+- Review PLAN_{NN}_{NAME}.md for implementation phases
 - Use `/kickoff {NAME}` when ready to start coding
 ```
 
@@ -398,7 +400,7 @@ If the required Node.js version, package manager, or other tools aren't installe
 
 ## Execution Order
 
-1. Use SlashCommand to invoke `/plan {NAME} {context}`
+1. Use SlashCommand to invoke `/plan INITIAL {NAME} {context}` (always `PLAN_00_INITIAL` for new projects)
 2. Wait for plan completion
 3. Analyze conversation for project requirements
 4. Generate bootstrap.sh with all necessary steps

package/content/agents/finalize.md

@@ -486,10 +486,12 @@ Would you like me to:
 ### 10. Update Active Plan Tracker
 
 If an active plan exists, update `{{STATE_FILE}}` to reflect the current status:
-- Update the `**Phase**` field if a phase was completed
-- Update the `**Status**` field (`🚧 In Progress`, `⏸️ Paused`, or `✅ Complete`)
-- Update the `**Updated**` timestamp
-- If all plan phases are complete, change the first line to `# Complete: {NAME}` and set status to `✅ Complete`
+- **Always READ existing STATE.md first** to preserve the Plans table and per-plan task sections
+- Update the header fields: `**Phase**`, `**Status**`, `**Updated**`
+- Update task statuses in the per-plan task tables (`⏳` → `✅` for completed tasks)
+- Update phase status emoji in phase headers (`⏳` → `🚧` → `✅`)
+- Update the Progress column in the Plans overview table (e.g., `12/18 tasks`)
+- If all plan phases are complete, set `**Active**` to `None` and update the plan's status to `✅ Complete` in the Plans table
 
 ## Final Checks
 

package/content/agents/implement.md

@@ -10,7 +10,7 @@ You are an implementation execution specialist. Your role is to systematically e
 
 ## Your Mission
 
-Load a PLAN_{NAME}.md file from `{{PLANS_DIR}}/` and execute it methodically, task by task, phase by phase, until complete or blocked.
+Load a PLAN_{NN}_{NAME}.md file from `{{PLANS_DIR}}/` and execute it methodically, task by task, phase by phase, until complete or blocked.
 
 ## Execution Steps
 
@@ -32,7 +32,7 @@ cat package.json 2>/dev/null | head -30
 ### 1. Load the Plan
 
 Extract the plan name from the arguments (first word after /kickoff):
-- Read `{{PLANS_DIR}}/PLAN_{NAME}.md`
+- Read `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`
 - If no plan name given, check `{{STATE_FILE}}` for the active plan
 - If file doesn't exist, list available plans and ask user to specify
 - Parse the plan structure (Objective, Phases, Tasks, Files)
@@ -157,9 +157,13 @@ Ready to commit this phase before moving to Phase 2? (yes/no/review)
 ```
 
 5. **Update STATE.md** after phase completion:
-   - Update the `**Phase**` field in `{{STATE_FILE}}` to the next phase number
+   - **Always READ existing STATE.md first** to preserve the Plans table and per-plan task sections
+   - Update the `**Phase**` field in the header to the next phase number
    - Update the `**Status**` field if needed (keep `🚧 In Progress` during work, set `✅ Complete` when all phases done)
    - Update the `**Updated**` timestamp
+   - Mark completed tasks as `✅` in the per-plan task tables
+   - Update phase status emoji in phase headers (`⏳` → `🚧` → `✅`)
+   - Update the Progress column in the Plans overview table
 
 ### 6. Handle Blockers
 

package/content/agents/parallelize.md

@@ -10,7 +10,7 @@ You are a parallel execution orchestrator. Your role is to analyze plans or task
 
 ## Your Mission
 
-Take a plan (from `{{PLANS_DIR}}/PLAN_{NAME}.md`) or task description and:
+Take a plan (from `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`) or task description and:
 1. Analyze for parallelization opportunities
 2. Partition into independent work streams
 3. Spawn agents for each stream
@@ -45,7 +45,7 @@ cat {{STATE_FILE}} 2>/dev/null || echo "No active plan"
 ls -1 {{PLANS_DIR}}/PLAN_*.md
 
 # Read the specified plan
-cat {{PLANS_DIR}}/PLAN_{NAME}.md
+cat {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
 ```
 
 If no plan exists, create one from the task description using the plan structure.

package/content/agents/plan.md

@@ -10,13 +10,22 @@ You are a plan documentation specialist. Your role is to capture findings from a
 
 ## Your Mission
 
-Generate a comprehensive PLAN_{NAME}.md file at `{{PLANS_DIR}}/PLAN_{NAME}.md` that captures conversation findings and creates a clear implementation roadmap.
+Generate a comprehensive PLAN_{NN}_{NAME}.md file at `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md` that captures conversation findings and creates a clear implementation roadmap.
 
 ## Analysis Steps
 
-1. **Extract Plan Name**
+1. **Extract Plan Name & Determine Number**
    - Parse the plan name from the arguments (first word after /plan)
    - If no name provided, use "UNTITLED"
+   - Scan existing plans to determine the next sequence number:
+     ```bash
+     ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null | sort -t_ -k2 -n | tail -1
+     ```
+   - Extract the highest number from existing plans (e.g., `PLAN_02_AUTH.md` → 02)
+   - Use the next number (e.g., 03) for the new plan
+   - If no plans exist, start at `00`
+   - Zero-pad to 2 digits: `00`, `01`, `02`, ... `09`, `10`, etc.
+   - Final filename: `PLAN_{NN}_{NAME}.md` (e.g., `PLAN_03_PAYMENTS.md`)
 
 2. **Collect Reference Files**
    - Check if the conversation includes any reference files (images, videos, screenshots, mockups, PDFs, etc.)
@@ -47,7 +56,7 @@ Before writing, ensure the output directory exists:
 mkdir -p {{PLANS_DIR}}
 ```
 
-Generate `{{PLANS_DIR}}/PLAN_{NAME}.md` with this exact structure:
+Generate `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md` with this exact structure:
 
 ```markdown
 # 📋 Plan: {NAME}
@@ -307,9 +316,9 @@ Generate `{{PLANS_DIR}}/PLAN_{NAME}.md` with this exact structure:
 
 The first word after `/plan` is the plan name. Everything after is additional context.
 
-Examples:
-- `/plan AUTH` → PLAN_AUTH.md
-- `/plan responsive-images some context here` → PLAN_RESPONSIVE_IMAGES.md
+Examples (assuming 2 plans already exist — `PLAN_00_INITIAL.md` and `PLAN_01_AUTH.md`):
+- `/plan PAYMENTS` → `PLAN_02_PAYMENTS.md`
+- `/plan responsive-images some context here` → `PLAN_02_RESPONSIVE_IMAGES.md`
 - Additional context should be incorporated into the Background section
 
 ## Update Active Plan Tracker (MANDATORY)
@@ -320,27 +329,70 @@ Examples:
 mkdir -p $(dirname {{STATE_FILE}})
 ```
 
-Write to `{{STATE_FILE}}` using this **exact format** (other agents parse these fields):
+Write to `{{STATE_FILE}}` using this **exact format** (other agents parse the header fields):
+
 ```markdown
-# Active: {NAME}
-**File**: {{PLANS_DIR}}/PLAN_{NAME}.md
+# Project State
+
+**Active**: {NN}_{NAME}
+**File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
 **Phase**: 1
 **Status**: 🚧 In Progress
 **Updated**: [ISO timestamp]
+
+---
+
+## Plans
+
+| # | Plan | File | Status | Progress |
+|---|------|------|--------|----------|
+| {NN} | {NAME} | PLAN_{NN}_{NAME}.md | 🚧 In Progress | 0/{total} tasks |
+
+---
+
+## PLAN_{NN}_{NAME}
+
+### Phase 1: {Phase Name} 🚧
+
+| Task | Status |
+|------|--------|
+| {Task 1 from plan} | ⏳ |
+| {Task 2 from plan} | ⏳ |
+
+### Phase 2: {Phase Name} ⏳
+
+| Task | Status |
+|------|--------|
+| {Task 1 from plan} | ⏳ |
+| {Task 2 from plan} | ⏳ |
+
+[Continue for all phases...]
 ```
 
-**STATE.md contract** — all agents MUST follow this format:
-- Line 1 is always `# Active: {NAME}` or `# Complete: {NAME}`
-- **File** — path to the plan document (must be valid, readable path)
-- **Phase** — current phase number (starts at 1, incremented after each phase by `/auto`, `/implement`, `/finalize`)
+**If previous plans already exist in STATE.md**, read the existing STATE.md first and **append** the new plan to the Plans table and add its phase/task sections below the existing ones. Update the **Active** field to point to the new plan.
+
+**STATE.md contract** — all agents MUST preserve these parseable header fields:
+- **Active** — the currently active plan identifier (`{NN}_{NAME}`) or `None`
+- **File** — path to the active plan document (must be valid, readable path)
+- **Phase** — current phase number of the active plan (starts at 1, incremented after each phase)
 - **Status** — one of: `🚧 In Progress`, `⏸️ Paused`, `✅ Complete`
 - **Updated** — ISO timestamp of last update (e.g., `2025-01-15T14:30:00Z`)
 
+**Task status symbols**:
+- `✅` — completed
+- `🚧` — in progress
+- `⏳` — pending
+
+**Phase status symbols** (appended to phase header):
+- `✅` — all tasks complete
+- `🚧` — currently being worked on
+- `⏳` — not started yet
+
 ## Final Step
 
-After writing `{{PLANS_DIR}}/PLAN_{NAME}.md`, respond with:
+After writing `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`, respond with:
 
-"✅ Plan document created at `{{PLANS_DIR}}/PLAN_{NAME}.md`
+"✅ Plan document created at `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`
 
 **Plan Summary**:
 - **Objective**: [One sentence]

package/content/commands/auto.md

@@ -42,7 +42,7 @@ You are now in **AUTO MODE** — a full development loop that orchestrates the e
 
 Parse `$ARGUMENTS` for:
 - **`--full`** flag: If present, run the entire loop without stopping for confirmation — commit automatically, skip approval prompts, maximize autonomy. Remove this flag from the remaining arguments before further processing.
-- **Plan name**: If the first remaining word matches an existing plan in `{{PLANS_DIR}}/PLAN_{NAME}.md`, treat it as a plan name to execute.
+- **Plan name**: If the first remaining word matches an existing plan in `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`, treat it as a plan name to execute.
 - **Feature description**: Otherwise, treat remaining arguments as a feature description for brainstorming.
 
 Store the `--full` preference — you'll check it at every commit checkpoint and decision point.
@@ -63,16 +63,17 @@ Read `{{STATE_FILE}}`. If it contains an active plan (status is `In Progress` or
 
 #### 1b. Check if Arguments Match an Existing Plan
 
-If a plan name was provided and `{{PLANS_DIR}}/PLAN_{NAME}.md` exists:
+If a plan name was provided, find the matching plan file in `{{PLANS_DIR}}/` (match by name portion, e.g., `AUTH` matches `PLAN_01_AUTH.md`):
 - Load that plan
-- **STATE UPDATE**: Write `{{STATE_FILE}}` to activate this plan:
+- **STATE UPDATE**: Update `{{STATE_FILE}}` to activate this plan. Read the existing STATE.md first to preserve the Plans table and other plan sections. Update the header fields:
   ```markdown
-  # Active: {NAME}
-  **File**: {{PLANS_DIR}}/PLAN_{NAME}.md
+  **Active**: {NN}_{NAME}
+  **File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
   **Phase**: 1
   **Status**: 🚧 In Progress
   **Updated**: [ISO timestamp]
   ```
+- Update the plan's status in the Plans table to `🚧 In Progress`
 - Skip to **Step 3** (branch) then **Step 4** (execute)
 
 #### 1c. No Active Work — Enter Brainstorm
@@ -125,7 +126,7 @@ After the bootstrap agent completes, ask the user: "Bootstrap script is ready. S
 - Use the Task tool to launch the commit agent (`subagent_type="commit"`) with context: "chore: bootstrap {NAME} project scaffolding"
 
 **If existing project:**
-Use the Task tool to launch the plan agent (`subagent_type="plan"`) with the feature name and brainstorm context. This will generate `{{PLANS_DIR}}/PLAN_{NAME}.md` and update `{{STATE_FILE}}`.
+Use the Task tool to launch the plan agent (`subagent_type="plan"`) with the feature name and brainstorm context. This will generate `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md` and update `{{STATE_FILE}}`.
 
 Wait for the plan agent to complete, then load and display a brief summary of the plan.
 
@@ -154,7 +155,7 @@ Report: "Working on branch: `feat/{name}`"
 
 ### Step 4: Execute the Plan (Phase by Phase)
 
-Load the plan from `{{PLANS_DIR}}/PLAN_{NAME}.md` and identify all phases.
+Load the plan from `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md` and identify all phases.
 
 **For each phase**, repeat this cycle:
 
@@ -187,10 +188,13 @@ Present the blockers to the user and ask how to proceed. Do NOT continue until b
 - The commit agent will determine the appropriate prefix (`feat:`, `fix:`, `refactor:`, `chore:`, etc.) based on the nature of the changes
 - The commit message should reference the plan and phase (e.g., "feat: implement user authentication (PLAN_AUTH Phase 1)")
 
-**STATE UPDATE**: After committing, update `{{STATE_FILE}}`:
+**STATE UPDATE**: Read and update `{{STATE_FILE}}`:
 - Increment `**Phase**` to the next phase number
 - Keep `**Status**` as `🚧 In Progress`
 - Update `**Updated**` timestamp
+- Mark completed tasks as `✅` in the per-plan task tables
+- Update completed phase headers from `🚧` to `✅`
+- Update the Progress column in the Plans overview table
 
 #### 4d. Continue to Next Phase
 
@@ -252,11 +256,12 @@ Review security report:
 
 ### Step 6: Report
 
-**STATE UPDATE**: Before reporting, update `{{STATE_FILE}}` to reflect final status:
-- If all phases and validation passed: change first line to `# Complete: {NAME}` and set `**Status**: ✅ Complete`
-- If partially complete (blockers, user stopped): keep `# Active: {NAME}` and set `**Status**: ⏸️ Paused`
+**STATE UPDATE**: Before reporting, read and update `{{STATE_FILE}}` to reflect final status:
+- If all phases and validation passed: set `**Active**` to `None`, update plan's status to `✅ Complete` in Plans table, set `**Status**: ✅ Complete`
+- If partially complete (blockers, user stopped): keep `**Active**` pointing to the plan, set `**Status**: ⏸️ Paused`
 - Update `**Phase**` to the last completed phase number
 - Update `**Updated**` timestamp
+- Update all task statuses in the per-plan task tables to reflect final state
 
 After everything is done (or stopped), provide a final summary:
 
@@ -332,26 +337,33 @@ Auto mode commits **early and often** using the commit agent (`subagent_type="co
 `{{STATE_FILE}}` must ALWAYS reflect current progress. Update it at these points:
 1. **Step 1b** — when activating an existing plan (set Phase 1, Status In Progress)
 2. **Step 2** — plan agent creates it (verify it exists after plan agent completes)
-3. **Step 4c** — after each phase commit (increment Phase, update timestamp)
+3. **Step 4c** — after each phase commit (increment Phase, update timestamp, mark completed tasks as ✅ in task tables)
 4. **Step 6** — final status (Complete or Paused)
 
-**STATE.md format** (never deviate):
+**STATE.md header fields** (always keep these parseable at the top):
 ```markdown
-# Active: {NAME}
-**File**: {{PLANS_DIR}}/PLAN_{NAME}.md
+# Project State
+
+**Active**: {NN}_{NAME}
+**File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
 **Phase**: {current_phase_number}
 **Status**: 🚧 In Progress
 **Updated**: {ISO timestamp}
 ```
 
-When all work is done, change to:
-```markdown
-# Complete: {NAME}
-**File**: {{PLANS_DIR}}/PLAN_{NAME}.md
-**Phase**: {final_phase_number}
-**Status**: ✅ Complete
-**Updated**: {ISO timestamp}
-```
+**When updating STATE.md**:
+- Always READ existing STATE.md first to preserve the Plans table and per-plan task sections
+- Update the header fields (Active, File, Phase, Status, Updated)
+- Update the active plan's status in the Plans overview table
+- Update task statuses (`⏳` → `🚧` → `✅`) in the per-plan task tables
+- Update phase status emoji in phase headers (`⏳` → `🚧` → `✅`)
+- Update the Progress column in the Plans table (e.g., `5/18 tasks`)
+
+**When all work on a plan is done**:
+- Set `**Active**` to `None` (or the next plan if one exists)
+- Update the plan's status in the Plans table to `✅ Complete`
+- Mark all tasks as `✅` in the plan's task tables
+- Set `**Status**` to `✅ Complete`
 
 If `/auto` is interrupted or paused, ensure STATE.md reflects where it stopped so the next `/auto` run can resume correctly. Plan document checkboxes are updated by the implement/parallelize agents.
 

package/content/commands/bootstrap.md

@@ -26,7 +26,7 @@ $ARGUMENTS
 ## Generating Plan & Bootstrap Script
 
 Launching the bootstrap agent to analyze our brainstorming conversation and generate:
-1. `{{PLANS_DIR}}/PLAN_{NAME}.md` (via `/plan` command)
+1. `{{PLANS_DIR}}/PLAN_00_INITIAL.md` — the first plan is always numbered `00` for new projects
 2. `./bootstrap.sh` (executable setup script)
 
 The agent will:

package/content/commands/implement.md

@@ -31,7 +31,7 @@ Launching the **implement agent** which will work independently in a separate co
 
 ### What the Agent Will Do
 
-- ✅ Load `{{PLANS_DIR}}/PLAN_{NAME}.md`
+- ✅ Load `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`
 - ✅ Parse all phases, tasks, and dependencies
 - ✅ Create comprehensive task tracking (TodoWrite)
 - ✅ Execute tasks systematically with validation

package/content/commands/kickoff.md

@@ -55,7 +55,7 @@ I'll work through this plan collaboratively with you:
 
 Now let me load the plan and we'll get started together.
 
-Use Read to load `{{PLANS_DIR}}/PLAN_{NAME}.md`, display a comprehensive summary with:
+Use Read to load `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`, display a comprehensive summary with:
 - Objective
 - Phases and task counts
 - Key files involved

package/content/commands/plan.md

@@ -25,7 +25,7 @@ $ARGUMENTS
 
 ## Generating Plan
 
-Launching the plan agent to analyze our conversation and generate `{{PLANS_DIR}}/PLAN_{NAME}.md`...
+Launching the plan agent to analyze our conversation and generate `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`...
 
 The agent will:
 - ✅ Summarize key findings from our discussion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allthingsclaude/blueprints",
-  "version": "0.3.0-beta.14",
+  "version": "0.3.0-beta.15",
   "description": "Claude Code commands and agents for enhanced AI-assisted development workflows",
   "type": "module",
   "main": "dist/index.js",