From fedd9a92f04b6a9f6610e3140629980497d9e03a Mon Sep 17 00:00:00 2001 From: quangdo126 Date: Fri, 27 Mar 2026 22:14:49 +0700 Subject: [PATCH] fix: enforce plan file naming convention in gsd-planner agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit gsd-tools detects plan files by matching the glob `*-PLAN.md` (e.g. 01-01-PLAN.md). When the planner generates files using a different convention — wave-based names, wrong prefix order, or lowercase — the tool returns plan_count: 0 and execution cannot proceed. Root cause: the write_phase_prompt step only said "Write to .../XX-name/{phase}-{NN}-PLAN.md" — ambiguous enough for the agent to produce PLAN-01-auth.md, 01-PLAN-01.md, etc. Observed across real usage (306 sessions analyzed): - Phases 2, 3, 4: plan files used wave-based names instead of the numeric format gsd-tools expects; required manual detection and adaptation before execution could proceed each time - gsd-tools roadmap get-phase failed on Phase 3 due to format mismatch; Claude fell back to parsing ROADMAP.md manually - Naming mismatch caused friction in at least 4 separate sessions, each requiring a manual workaround Fix: add a CRITICAL naming block in write_phase_prompt with the exact required pattern, component definitions, correct/incorrect examples, and explicit ❌ markers for variants that break detection. Co-Authored-By: Claude Opus 4.6 --- agents/gsd-planner.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index 9c01b4bd7..377c4996f 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -1193,7 +1193,26 @@ Use template structure for each PLAN.md. **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation. -Write to `.planning/phases/XX-name/{phase}-{NN}-PLAN.md` +**CRITICAL — File naming convention (enforced):** + +The filename MUST follow the exact pattern: `{padded_phase}-{NN}-PLAN.md` + +- `{padded_phase}` = zero-padded phase number received from the orchestrator (e.g. `01`, `02`, `03`, `02.1`) +- `{NN}` = zero-padded sequential plan number within the phase (e.g. `01`, `02`, `03`) +- The suffix is always `-PLAN.md` — NEVER `PLAN-NN.md`, `NN-PLAN.md`, or any other variation + +**Correct examples:** +- Phase 1, Plan 1 → `01-01-PLAN.md` +- Phase 3, Plan 2 → `03-02-PLAN.md` +- Phase 2.1, Plan 1 → `02.1-01-PLAN.md` + +**Incorrect (will break gsd-tools detection):** +- ❌ `PLAN-01-auth.md` +- ❌ `01-PLAN-01.md` +- ❌ `plan-01.md` +- ❌ `01-01-plan.md` (lowercase) + +Full write path: `.planning/phases/{padded_phase}-{slug}/{padded_phase}-{NN}-PLAN.md` Include all frontmatter fields.