@sienklogic/plan-build-run 2.10.0 → 2.12.0

package/plugins/cursor-pbr/skills/build/SKILL.md

@@ -23,9 +23,9 @@ Additionally for this skill:
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► BUILDING PHASE {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► BUILDING PHASE {N}                         ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
@@ -64,7 +64,7 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number and flags
 2. Read `.planning/config.json` for parallelization, model, and gate settings (see config-loading.md for field reference)
 3. Resolve depth profile: run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
-4. Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
+4. **CRITICAL: Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
 5. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
    - PLAN.md files exist in the directory
@@ -197,6 +197,8 @@ Validate wave consistency:
 
 ### Step 5b: Write Checkpoint Manifest (inline)
 
+**CRITICAL: Write .checkpoint-manifest.json NOW before entering the wave loop.**
+
 Before entering the wave loop, write `.planning/phases/{NN}-{slug}/.checkpoint-manifest.json`:
 
 ```json
@@ -692,6 +694,8 @@ If triggered:
    ```
 4. Do NOT block on this — use `run_in_background: true` and continue to Step 8a. Report completion in Step 8f if it finishes in time.
 
+**CRITICAL: Update ROADMAP.md progress table NOW. Do NOT skip this step.**
+
 **8a. Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
 **Tooling shortcut**: Use the CLI for atomic ROADMAP.md table updates instead of manual editing:
@@ -708,6 +712,8 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 5. Update the `Status` column to the final_status determined in Step 8-pre
 6. Save the file — do NOT skip this step
 
+**CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
+
 **8b. Update STATE.md:**
 - Phase status: {final_status from Step 8-pre}
 - Plan completion count
@@ -802,18 +808,18 @@ Then present the appropriate branded banner:
 
 **If `passed` + more phases:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
 {X} plans executed
 Goal verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
 
@@ -821,28 +827,25 @@ Goal verified ✓
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - `/pbr:review {N}` — manual acceptance testing before continuing
 - `/pbr:discuss {N+1}` — talk through the next phase before planning
 - `/pbr:status` — see full project status
 
-───────────────────────────────────────────────────────────────
 ```
 
 **If `passed` + last phase:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} phases completed
 All phase goals verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Audit milestone** — verify requirements, cross-phase integration, E2E flows
 
@@ -850,20 +853,17 @@ All phase goals verified ✓
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - `/pbr:review` — manual acceptance testing
 - `/pbr:milestone complete` — archive milestone after audit passes
 
-───────────────────────────────────────────────────────────────
 ```
 
 **If `gaps_found`:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                     ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -874,9 +874,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 {Extract gap summaries from VERIFICATION.md}
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan gap closure** — create additional plans to complete the phase
 
@@ -884,13 +884,10 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - `cat .planning/phases/{phase_dir}/VERIFICATION.md` — see full report
 - `/pbr:review {N}` — manual testing before planning
 
-───────────────────────────────────────────────────────────────
 ```
 
 **8g. Display USER-SETUP.md (conditional):**

package/plugins/cursor-pbr/skills/config/SKILL.md

@@ -8,9 +8,9 @@ description: "Configure settings: depth, model profiles, features, git, and gate
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► CONFIGURATION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► CONFIGURATION                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -184,17 +184,18 @@ If user types something else (freeform): interpret as a direct setting command a
 
 Update config.json with new values. Show what changed with a branded completion:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► CONFIG UPDATED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► CONFIG UPDATED ✓                           ║
+╚══════════════════════════════════════════════════════════════╝
 
 Updated:
   depth: standard → quick
   models.executor: inherit → sonnet
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — settings saved
 
@@ -202,13 +203,11 @@ Updated:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:config` — change more settings
 
-───────────────────────────────────────────────────────────────
 ```
 
 ## Config Schema

package/plugins/cursor-pbr/skills/continue/SKILL.md

@@ -16,9 +16,9 @@ This skill runs **inline** and may delegate to other skills via agent invocation
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► NEXT STEP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► NEXT STEP                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -115,9 +115,9 @@ Where `{N}` is the current phase number determined from STATE.md in Step 1.
 
 After execution completes, display a branded completion:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STEP COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STEP COMPLETE                              ║
+╚══════════════════════════════════════════════════════════════╝
 
 Completed: {what was done}
 

package/plugins/cursor-pbr/skills/dashboard/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: "[--port N]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DASHBOARD
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DASHBOARD                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.

package/plugins/cursor-pbr/skills/debug/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: "[issue description]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DEBUGGING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DEBUGGING                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -65,9 +65,11 @@ Scan `.planning/debug/` for existing debug files:
 ```
 
 Read each file's frontmatter to check status:
-- `status: active` — session is in progress
-- `status: resolved` — session is complete
-- `status: stale` — session was abandoned
+- `status: gathering` — collecting symptoms from user
+- `status: investigating` — testing hypotheses
+- `status: fixing` — applying fix
+- `status: verifying` — confirming fix works
+- `status: resolved` — session complete
 
 **If active sessions found:**
 
@@ -126,7 +128,7 @@ Create `.planning/debug/{NNN}-{slug}.md`:
 ---
 id: "{NNN}"
 title: "{issue title}"
-status: active
+status: gathering
 created: "{ISO date}"
 updated: "{ISO date}"
 severity: "{critical|high|medium|low}"
@@ -230,18 +232,19 @@ Actions:
 3. Report to user with branded output:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► BUG RESOLVED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► BUG RESOLVED ✓                             ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Session #{NNN}:** {title}
 **Root cause:** {cause}
 **Fix:** {description}
 **Commit:** {hash}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — the bug is fixed
 
@@ -249,13 +252,11 @@ Actions:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:review {N}` — verify the current phase
 
-───────────────────────────────────────────────────────────────
 ```
 
 #### ROOT CAUSE FOUND (no fix)
@@ -275,9 +276,10 @@ Actions:
 2. Suggest next steps to user:
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Apply the fix** — root cause identified, fix needed
 
@@ -285,13 +287,11 @@ Actions:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
 
 **Also available:**
 - `/pbr:plan` — for complex fixes that need planning
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
 ```
 
 #### CHECKPOINT
@@ -401,7 +401,7 @@ Use AskUserQuestion:
     - label: "Escalate"  description: "Save context for manual debugging"
 
 - If "Extend": double the limit and continue
-- If "Wrap up": update debug file status to `stale`, record all findings, suggest next steps
+- If "Wrap up": update debug file `status: resolved` with `resolution: abandoned`, record all findings, suggest next steps
 - If "Escalate": write a detailed handoff document to the debug file with all hypotheses, evidence, and suggested manual investigation steps
 
 ---
@@ -411,15 +411,15 @@ Use AskUserQuestion:
 ### Lifecycle
 
 ```
-active → resolved     (root cause found and fixed)
-active → stale        (abandoned — no updates for 7+ days)
-active → active       (resumed after pause)
+gathering → investigating → fixing → verifying → resolved
+(any non-resolved) → resolved  (with resolution: abandoned, if 7+ days stale)
+(any non-resolved) → (same)    (resumed after pause)
 ```
 
 ### Staleness Detection
 
 When scanning for active sessions, check the `updated` date. If more than 7 days old:
-- Mark as `stale` in status
+- Set `status: resolved` with `resolution: abandoned` in frontmatter
 - Still offer to resume, but warn: "This session is {N} days old. Context may have changed."
 
 ### Cleanup

package/plugins/cursor-pbr/skills/discuss/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: "<phase-number>"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DISCUSSION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION                                 ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -150,17 +150,23 @@ If more than 3 concrete options exist for a gray area, present only the top 3 pl
 
 For each gray area where the user made a decision (not "Let Claude decide"), ask **4 follow-up questions** to fully capture their intent.
 
+**CRITICAL — STOP: Do NOT skip ANY of the 4 follow-up areas below. All 4 MUST be asked for each gray area where the user made a decision.**
+
 **Follow-up question types:**
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 1. **Scope boundary**: "Should {feature} also handle {edge case}?"
    Use the **yes-no** pattern — this is a binary decision.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 2. **Quality level**: "How polished should this be?"
    Do NOT use AskUserQuestion — this is freeform. Let the user describe their quality expectations in their own words.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 3. **Integration**: "How should this interact with {existing component}?"
    Do NOT use AskUserQuestion — this is freeform. The answer depends on the specific component and context.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 4. **Future-proofing**: "Should we design this to support {potential future need}, or keep it simple?"
    Use the **yes-no** pattern:
      question: "Design {feature} to support {future need}, or keep it simple for now?"
@@ -174,6 +180,8 @@ For each gray area where the user made a decision (not "Let Claude decide"), ask
 - If the user gives a short answer, capture it as-is
 - If the user says "you decide" on a follow-up, move that specific sub-decision to Claude's Discretion
 
+**Completion check:** After all follow-up questions for all gray areas, verify that all 4 follow-up areas produced output for each decided gray area. If any area was missed, go back and ask it before proceeding to Step 6.
+
 ### Step 6: Capture Deferred Ideas
 
 During the conversation, the user may mention ideas they want but not in this phase. Track these separately:
@@ -218,17 +226,19 @@ This creates a pointer so `/pbr:resume` and `progress-tracker.js` know that phas
 After writing CONTEXT.md, display branded output:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {name}**
 
 Decisions: {count} locked, {count} deferred, {count} discretion
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan this phase** — your decisions will be honored
 
@@ -236,13 +246,13 @@ Decisions: {count} locked, {count} deferred, {count} discretion
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:status` — see project status
 - `/pbr:explore` — explore ideas further
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---

package/plugins/cursor-pbr/skills/do/SKILL.md

@@ -13,9 +13,9 @@ You are running the **do** skill. Your job is to analyze freeform text from the
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► ROUTING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► ROUTING                                    ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.

package/plugins/cursor-pbr/skills/explore/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: "[topic]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► EXPLORING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► EXPLORING                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -175,7 +175,7 @@ Suggest specific outputs with reasoning. Present no more than 4 suggestions —
 | Phase decision | Clarifies an existing phase | Write/append to phase `CONTEXT.md` |
 | Research question | Needs deeper investigation | `.planning/research/questions.md` |
 | New phase | Big enough for its own phase | Append to `ROADMAP.md` |
-| Note | Not actionable yet, worth remembering | `.planning/notes/{slug}.md` |
+| Note | Not actionable yet, worth remembering | `.planning/notes/{YYYY-MM-DD}-{slug}.md` |
 | Quick capture | One-liner idea, no context needed | Suggest `/pbr:note <text>` to the user |
 | Seed | Idea with trigger conditions | `.planning/seeds/SEED-{NNN}-{slug}.md` |
 
@@ -215,15 +215,16 @@ Create only the approved artifacts. A single explore session can produce multipl
 After creating artifacts (or if user chose "Skip"), display:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
 
 {count} artifacts created: {list of artifact types}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Primary route based on what was created}**
 
@@ -239,14 +240,12 @@ After creating artifacts (or if user chose "Skip"), display:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
 
 **Also available:**
 - `/pbr:status` — see project status
 - `/pbr:continue` — execute next logical step
 - `/pbr:milestone new` — start a new milestone with new phases
 
-───────────────────────────────────────────────────────────────
 ```
 
 ---
@@ -289,7 +288,7 @@ Append to `.planning/ROADMAP.md` following the existing phase format. Assign the
 
 ### Note
 
-Write to `.planning/notes/{NNN}-{slug}.md` where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan `.planning/notes/` for the highest existing number prefix, increment by 1, and zero-pad.
+Write to `.planning/notes/{YYYY-MM-DD}-{slug}.md` where the date prefix is today's date in ISO format. Scan `.planning/notes/` to avoid filename collisions — if a file with the same date and slug exists, append `-2` (or increment).
 
 ```markdown
 ---