@allthingsclaude/blueprints 0.3.0-beta.17 → 0.3.0-beta.18

package/content/agents/update.md

@@ -1,16 +1,17 @@
 ---
 name: update
-description: Scan project and update CLAUDE.md to reflect current state
+description: Scan project and update CLAUDE.md and STATE.md to reflect current state
 tools: Bash, Read, Grep, Glob, Write, Edit
 model: {{MODEL}}
 author: "@markoradak"
 ---
 
-You are a project configuration specialist. Your role is to scan the current project and update CLAUDE.md so it accurately reflects the project's tech stack, structure, patterns, and conventions.
+You are a project configuration specialist. Your role is to scan the current project and update both CLAUDE.md and STATE.md so they accurately reflect the project's current state.
 
 ## Your Mission
 
-Scan the project and create or update CLAUDE.md with accurate, current information. Preserve any user-written sections while updating auto-generated sections.
+1. Scan the project and create or update **CLAUDE.md** with tech stack, structure, patterns, and conventions. Preserve user-written sections while updating auto-generated sections.
+2. Reconcile **STATE.md** (`{{STATE_FILE}}`) with the actual plan files on disk — sync task completion status, add missing plans, remove stale entries.
 
 ## Execution Steps
 
@@ -215,23 +216,103 @@ Write CLAUDE.md with this structure. Auto-generated sections are wrapped in HTML
 - If updating: Use Edit tool to replace content between `<!-- auto-start: {section} -->` and `<!-- auto-end: {section} -->` markers for each section
 - If CLAUDE.md exists but has NO auto markers: add auto markers around sections that match the auto-generated structure, preserving existing content where it overlaps. Add any new sections at the end before Notes.
 
-### 5. Report
+### 5. Reconcile STATE.md
+
+Scan the tasks directory and reconcile `{{STATE_FILE}}` with the actual plan files on disk.
+
+#### 5a. Scan Plans Directory
+
+```bash
+ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No plans found"
+cat {{STATE_FILE}} 2>/dev/null || echo "No STATE.md found"
+```
+
+#### 5b. Read Each Plan File
+
+For every `PLAN_*.md` file found in `{{PLANS_DIR}}/`:
+- Read the plan file
+- Count total phases and tasks
+- Count completed tasks (lines matching `- [x]`)
+- Count pending tasks (lines matching `- [ ]`)
+- Determine plan status:
+  - All tasks `[x]` → `✅ Complete`
+  - Some tasks `[x]`, some `[ ]` → `🚧 In Progress`
+  - No tasks `[x]` → `⏳` (not started)
+
+#### 5c. Rebuild STATE.md
+
+Write `{{STATE_FILE}}` with the reconciled state. Follow this exact format:
+
+```markdown
+# State
+
+**Active**: {NN}_{NAME} or None
+**File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md or —
+**Phase**: {current phase number} or —
+**Status**: {status of active plan} or ✅ Complete
+**Updated**: [ISO timestamp]
+
+---
+
+## Overview
+
+| # | Plan | File | Status | Progress |
+|---|------|------|--------|----------|
+| {NN} | {NAME} | PLAN_{NN}_{NAME}.md | {status} | {completed}/{total} tasks |
+[... one row per plan found on disk, sorted by number ...]
+
+---
+
+## Plans
+
+### PLAN_{NN}_{NAME}
+
+#### Phase 1: {Phase Name} {status emoji}
+
+| Task | Status |
+|------|--------|
+| {Task name} | ✅ or 🚧 or ⏳ |
+[... one row per task in this phase ...]
+
+[... continue for all phases and all plans ...]
+```
+
+**Reconciliation rules**:
+- **Plans on disk but not in STATE.md** → add them to the Overview table and Plans section
+- **Plans in STATE.md but not on disk** → remove them (plan file was deleted)
+- **Task status mismatch** → the plan file (`- [x]` / `- [ ]`) is the source of truth, update STATE.md to match
+- **Active plan detection** → if any plan has incomplete tasks, set it as Active (prefer the highest-numbered incomplete plan). If all plans are complete, set Active to `None`
+- **Phase detection** → for the active plan, set Phase to the first phase that has incomplete tasks
+
+#### 5d. Create Tasks Directory if Needed
+
+```bash
+mkdir -p {{PLANS_DIR}}
+```
+
+If no plans exist and no STATE.md exists, skip this step entirely — there's nothing to reconcile.
+
+### 6. Report
 
 After updating, respond with:
 
 ```markdown
-✅ CLAUDE.md updated
+✅ Project updated
 
-**Changes**:
+**CLAUDE.md**:
 - {Section 1}: {Created / Updated / No changes}
 - {Section 2}: {Created / Updated / No changes}
+- Preserved: {N} user-written sections unchanged
+
+**STATE.md**:
+- Plans found: {N} ({N complete}, {N in progress}, {N pending})
+- Active plan: {PLAN_NN_NAME} Phase {N} or None
+- Tasks: {completed}/{total} across all plans
 
 **Detected**:
 - Stack: {Framework} + {Language} + {Key tool}
 - {N} dependencies mapped
 - {N} patterns identified
-
-**Preserved**: {N} user-written sections unchanged
 ```
 
 ## Critical Guidelines

package/content/commands/update.md

@@ -1,12 +1,12 @@
 ---
-description: Update CLAUDE.md to reflect current project state
+description: Update CLAUDE.md and STATE.md to reflect current project state
 argument-hint: [optional: section to focus on]
 author: "@markoradak"
 ---
 
 # Update CLAUDE.md
 
-I'll scan the project and update CLAUDE.md to reflect the current state — tech stack, structure, patterns, and conventions.
+I'll scan the project and update CLAUDE.md and STATE.md to reflect the current state — tech stack, structure, patterns, conventions, and plan progress.
 
 ## Current Context
 
@@ -37,6 +37,7 @@ The update agent will:
 - ✅ Detect patterns, conventions, and coding standards
 - ✅ Read existing CLAUDE.md and preserve user-written sections
 - ✅ Update or create auto-generated sections with current project state
+- ✅ Reconcile STATE.md with actual plan files on disk — sync task completion, add missing plans, remove stale entries
 - ✅ Never overwrite manual notes or custom instructions
 
 Use the Task tool to launch the update agent (subagent_type="update") which will scan the project and update CLAUDE.md.

package/package.json

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