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

package/content/agents/finalize.md

@@ -486,12 +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:
-- **Always READ existing STATE.md first** to preserve the Plans table and per-plan task sections
+- **Always READ existing STATE.md first** to preserve `## Overview` table and `## Plans` sections
 - Update the header fields: `**Phase**`, `**Status**`, `**Updated**`
-- Update task statuses in the per-plan task tables (`⏳` → `✅` for completed tasks)
+- Update task statuses in the task tables under `## Plans` (`⏳` → `✅` 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
+- Update the Progress column in `## Overview` table (e.g., `12/18 tasks`)
+- If all plan phases are complete, set `**Active**` to `None`, `**File**` and `**Phase**` to `—`, and update the plan's status to `✅ Complete` in the `## Overview` table
 
 ## Final Checks
 

package/content/agents/implement.md

@@ -157,13 +157,13 @@ Ready to commit this phase before moving to Phase 2? (yes/no/review)
 ```
 
 5. **Update STATE.md** after phase completion:
-   - **Always READ existing STATE.md first** to preserve the Plans table and per-plan task sections
+   - **Always READ existing STATE.md first** to preserve `## Overview` table and `## Plans` 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
+   - Mark completed tasks as `✅` in the task tables under `## Plans`
    - Update phase status emoji in phase headers (`⏳` → `🚧` → `✅`)
-   - Update the Progress column in the Plans overview table
+   - Update the Progress column in `## Overview` table
 
 ### 6. Handle Blockers
 

package/content/agents/plan.md

@@ -329,10 +329,10 @@ Examples (assuming 2 plans already exist — `PLAN_00_INITIAL.md` and `PLAN_01_A
 mkdir -p $(dirname {{STATE_FILE}})
 ```
 
-Write to `{{STATE_FILE}}` using this **exact format** (other agents parse the header fields):
+Write to `{{STATE_FILE}}` using this **exact format**. This format MUST be followed precisely — other agents parse the header fields and the structure.
 
 ```markdown
-# Project State
+# State
 
 **Active**: {NN}_{NAME}
 **File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
@@ -342,7 +342,7 @@ Write to `{{STATE_FILE}}` using this **exact format** (other agents parse the he
 
 ---
 
-## Plans
+## Overview
 
 | # | Plan | File | Status | Progress |
 |---|------|------|--------|----------|
@@ -350,16 +350,18 @@ Write to `{{STATE_FILE}}` using this **exact format** (other agents parse the he
 
 ---
 
-## PLAN_{NN}_{NAME}
+## Plans
+
+### PLAN_{NN}_{NAME}
 
-### Phase 1: {Phase Name} 🚧
+#### Phase 1: {Phase Name} 🚧
 
 | Task | Status |
 |------|--------|
 | {Task 1 from plan} | ⏳ |
 | {Task 2 from plan} | ⏳ |
 
-### Phase 2: {Phase Name} ⏳
+#### Phase 2: {Phase Name} ⏳
 
 | Task | Status |
 |------|--------|
@@ -369,12 +371,24 @@ Write to `{{STATE_FILE}}` using this **exact format** (other agents parse the he
 [Continue for all phases...]
 ```
 
-**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.
+**When no plan is active** (all complete or none started), use `—` for empty fields:
+```markdown
+**Active**: None
+**File**: —
+**Phase**: —
+**Status**: ✅ Complete
+```
+
+**If previous plans already exist in STATE.md**, read the existing STATE.md first and:
+- **Append** the new plan row to the Overview table
+- **Append** the new plan's phase/task sections under `## Plans`
+- **Update** the header fields (`Active`, `File`, `Phase`, `Status`, `Updated`) to point to the new plan
+- **Never remove or rewrite** existing plan sections — only append and update statuses
 
 **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)
+- **File** — path to the active plan document, or `—` if none active
+- **Phase** — current phase number of the active plan, or `—` if none active
 - **Status** — one of: `🚧 In Progress`, `⏸️ Paused`, `✅ Complete`
 - **Updated** — ISO timestamp of last update (e.g., `2025-01-15T14:30:00Z`)
 

package/content/commands/auto.md

@@ -65,7 +65,7 @@ Read `{{STATE_FILE}}`. If it contains an active plan (status is `In Progress` or
 
 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**: 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:
+- **STATE UPDATE**: Update `{{STATE_FILE}}` to activate this plan. Read the existing STATE.md first to preserve the `## Overview` table and `## Plans` sections. Update the header fields:
   ```markdown
   **Active**: {NN}_{NAME}
   **File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
@@ -73,7 +73,7 @@ If a plan name was provided, find the matching plan file in `{{PLANS_DIR}}/` (ma
   **Status**: 🚧 In Progress
   **Updated**: [ISO timestamp]
   ```
-- Update the plan's status in the Plans table to `🚧 In Progress`
+- Update the plan's status in the Overview table to `🚧 In Progress`
 - Skip to **Step 3** (branch) then **Step 4** (execute)
 
 #### 1c. No Active Work — Enter Brainstorm
@@ -192,9 +192,9 @@ Present the blockers to the user and ask how to proceed. Do NOT continue until b
 - 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
+- Mark completed tasks as `✅` in the task tables under `## Plans`
 - Update completed phase headers from `🚧` to `✅`
-- Update the Progress column in the Plans overview table
+- Update the Progress column in the Overview table
 
 #### 4d. Continue to Next Phase
 
@@ -257,11 +257,11 @@ Review security report:
 ### Step 6: Report
 
 **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 all phases and validation passed: set `**Active**` to `None`, update plan's status to `✅ Complete` in Overview 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
+- Update all task statuses in the task tables under `## Plans` to reflect final state
 
 After everything is done (or stopped), provide a final summary:
 
@@ -342,7 +342,7 @@ Auto mode commits **early and often** using the commit agent (`subagent_type="co
 
 **STATE.md header fields** (always keep these parseable at the top):
 ```markdown
-# Project State
+# State
 
 **Active**: {NN}_{NAME}
 **File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
@@ -352,16 +352,16 @@ Auto mode commits **early and often** using the commit agent (`subagent_type="co
 ```
 
 **When updating STATE.md**:
-- Always READ existing STATE.md first to preserve the Plans table and per-plan task sections
+- Always READ existing STATE.md first to preserve `## Overview` table and `## Plans` 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 the active plan's status in `## Overview` table
+- Update task statuses (`⏳` → `🚧` → `✅`) in the task tables under `## Plans`
 - Update phase status emoji in phase headers (`⏳` → `🚧` → `✅`)
-- Update the Progress column in the Plans table (e.g., `5/18 tasks`)
+- Update the Progress column in `## Overview` 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`
+- Update the plan's status in the Overview table to `✅ Complete`
 - Mark all tasks as `✅` in the plan's task tables
 - Set `**Status**` to `✅ Complete`
 

package/package.json

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