fix: use inline code for Next Up commands (avoids nesting ambiguity)

This commit is contained in:
Lex Christopherson
2025-12-17 13:03:48 -06:00
parent 347e7bec61
commit c3273a50c1
16 changed files with 54 additions and 113 deletions

View File

@@ -169,9 +169,7 @@ Project state updated: .planning/STATE.md
**Phase {N}: {description}** **Phase {N}: {description}**
``` `/gsd:plan-phase {N}`
/gsd:plan-phase {N}
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -82,9 +82,7 @@ Roadmap created:
**Phase 1: [Name]** — [Goal from ROADMAP.md] **Phase 1: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase 1`
/gsd:plan-phase 1
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -188,9 +188,7 @@ Project state updated: .planning/STATE.md
**Phase {decimal_phase}: {description}** — urgent insertion **Phase {decimal_phase}: {description}** — urgent insertion
``` `/gsd:plan-phase {decimal_phase}`
/gsd:plan-phase {decimal_phase}
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -181,9 +181,7 @@ Project initialized:
**[Project Name]** — create roadmap **[Project Name]** — create roadmap
``` `/gsd:create-roadmap`
/gsd:create-roadmap
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -106,9 +106,7 @@ Check if `{phase}-{plan}-PLAN.md` exists for that number.
**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md] **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
``` `/gsd:execute-plan [full-path-to-PLAN.md]`
/gsd:execute-plan [full-path-to-PLAN.md]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -132,9 +130,7 @@ Check if `{phase}-{plan}-PLAN.md` exists for that number.
**Phase [N]: [Name]** — [Goal from ROADMAP.md] **Phase [N]: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase [phase-number]`
/gsd:plan-phase [phase-number]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -151,9 +147,7 @@ Check if `{phase}-{plan}-PLAN.md` exists for that number.
**Phase [N]: [Name]** — [Goal from ROADMAP.md] **Phase [N]: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase [phase]`
/gsd:plan-phase [phase]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -4,24 +4,22 @@ Standard format for presenting next steps after completing a command or workflow
## Core Structure ## Core Structure
```markdown ```
--- ---
## ▶ Next Up ## ▶ Next Up
**{identifier}: {name}** — {one-line description} **{identifier}: {name}** — {one-line description}
``` `{command to copy-paste}`
{command to copy-paste}
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
--- ---
**Also available:** **Also available:**
- {alternative option 1} - `{alternative option 1}` — description
- {alternative option 2} - `{alternative option 2}` — description
--- ---
``` ```
@@ -30,7 +28,7 @@ Standard format for presenting next steps after completing a command or workflow
1. **Always show what it is** — name + description, never just a command path 1. **Always show what it is** — name + description, never just a command path
2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans 2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
3. **Command in clean code block** — easy to copy-paste 3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
4. **`/clear` explanation** — always include, keeps it concise but explains why 4. **`/clear` explanation** — always include, keeps it concise but explains why
5. **"Also available" not "Other options"** — sounds more app-like 5. **"Also available" not "Other options"** — sounds more app-like
6. **Visual separators** — `---` above and below to make it stand out 6. **Visual separators** — `---` above and below to make it stand out
@@ -39,16 +37,14 @@ Standard format for presenting next steps after completing a command or workflow
### Execute Next Plan ### Execute Next Plan
```markdown ```
--- ---
## ▶ Next Up ## ▶ Next Up
**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
``` `/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -65,7 +61,7 @@ Standard format for presenting next steps after completing a command or workflow
Add note that this is the last plan and what comes after: Add note that this is the last plan and what comes after:
```markdown ```
--- ---
## ▶ Next Up ## ▶ Next Up
@@ -73,9 +69,7 @@ Add note that this is the last plan and what comes after:
**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
<sub>Final plan in Phase 2</sub> <sub>Final plan in Phase 2</sub>
``` `/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -90,16 +84,14 @@ Add note that this is the last plan and what comes after:
### Plan a Phase ### Plan a Phase
```markdown ```
--- ---
## ▶ Next Up ## ▶ Next Up
**Phase 2: Authentication** — JWT login flow with refresh tokens **Phase 2: Authentication** — JWT login flow with refresh tokens
``` `/gsd:plan-phase 2`
/gsd:plan-phase 2
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -117,7 +109,7 @@ Add note that this is the last plan and what comes after:
Show completion status before next action: Show completion status before next action:
```markdown ```
--- ---
## ✓ Phase 2 Complete ## ✓ Phase 2 Complete
@@ -128,9 +120,7 @@ Show completion status before next action:
**Phase 3: Core Features** — User dashboard, settings, and data export **Phase 3: Core Features** — User dashboard, settings, and data export
``` `/gsd:plan-phase 3`
/gsd:plan-phase 3
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -148,27 +138,18 @@ Show completion status before next action:
When there's no clear primary action: When there's no clear primary action:
```markdown ```
--- ---
## ▶ Next Up ## ▶ Next Up
**Phase 3: Core Features** — User dashboard, settings, and data export **Phase 3: Core Features** — User dashboard, settings, and data export
**To plan directly:** **To plan directly:** `/gsd:plan-phase 3`
```
/gsd:plan-phase 3
```
**To discuss context first:** **To discuss context first:** `/gsd:discuss-phase 3`
```
/gsd:discuss-phase 3
```
**To research unknowns:** **To research unknowns:** `/gsd:research-phase 3`
```
/gsd:research-phase 3
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -177,7 +158,7 @@ When there's no clear primary action:
### Milestone Complete ### Milestone Complete
```markdown ```
--- ---
## 🎉 Milestone v1.0 Complete ## 🎉 Milestone v1.0 Complete
@@ -188,9 +169,7 @@ All 4 phases shipped
**Plan v1.1** — Enhanced features and optimizations **Plan v1.1** — Enhanced features and optimizations
``` `/gsd:discuss-milestone`
/gsd:discuss-milestone
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -237,23 +216,19 @@ Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with slidi
### Don't: Command-only (no context) ### Don't: Command-only (no context)
```markdown ```
## To Continue ## To Continue
Run `/clear`, then paste: Run `/clear`, then paste:
```
/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md /gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
``` ```
```
User has no idea what 02-03 is about. User has no idea what 02-03 is about.
### Don't: Missing /clear explanation ### Don't: Missing /clear explanation
```markdown
```
/gsd:plan-phase 3
``` ```
`/gsd:plan-phase 3`
Run /clear first. Run /clear first.
``` ```
@@ -262,9 +237,19 @@ Doesn't explain why. User might skip it.
### Don't: "Other options" language ### Don't: "Other options" language
```markdown ```
Other options: Other options:
- Review roadmap - Review roadmap
``` ```
Sounds like an afterthought. Use "Also available:" instead. Sounds like an afterthought. Use "Also available:" instead.
### Don't: Fenced code blocks for commands
```
```
/gsd:plan-phase 3
```
```
Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

View File

@@ -430,9 +430,7 @@ Tag: v[X.Y]
**Plan Next Milestone** — define v[X.Y+1] features and scope **Plan Next Milestone** — define v[X.Y+1] features and scope
``` `/gsd:discuss-milestone`
/gsd:discuss-milestone
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -329,9 +329,7 @@ Milestone v[X.Y] [Name] created:
**Phase [N]: [Name]** — [Goal from ROADMAP.md] **Phase [N]: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase [N]`
/gsd:plan-phase [N]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -388,9 +388,7 @@ Project initialized:
**Phase 1: [Name]** — [Goal from ROADMAP.md] **Phase 1: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase 1`
/gsd:plan-phase 1
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -144,9 +144,7 @@ Ready to create the milestone structure.
**Create Milestone v[X.Y]** — [Theme Name] **Create Milestone v[X.Y]** — [Theme Name]
``` `/gsd:new-milestone`
/gsd:new-milestone
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -200,9 +200,7 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md] **Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase ${PHASE}`
/gsd:plan-phase ${PHASE}
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -1262,9 +1262,7 @@ Summary: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
**{phase}-{next-plan}: [Plan Name]** — [objective from next PLAN.md] **{phase}-{next-plan}: [Plan Name]** — [objective from next PLAN.md]
``` `/gsd:execute-plan .planning/phases/XX-name/{phase}-{next-plan}-PLAN.md`
/gsd:execute-plan .planning/phases/XX-name/{phase}-{next-plan}-PLAN.md
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -1318,9 +1316,7 @@ This milestone is 100% done.
**Complete Milestone** — archive and prepare for next **Complete Milestone** — archive and prepare for next
``` `/gsd:complete-milestone`
/gsd:complete-milestone
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -1349,9 +1345,7 @@ All [Y] plans finished.
**Phase [X+1]: [Name]** — [Goal from ROADMAP.md] **Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase [X+1]`
/gsd:plan-phase [X+1]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -385,9 +385,7 @@ Created .planning/codebase/:
**Initialize project** — use codebase context for planning **Initialize project** — use codebase context for planning
``` `/gsd:new-project`
/gsd:new-project
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -771,9 +771,7 @@ Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
**{phase}-01: [Plan Name]** — [objective summary] **{phase}-01: [Plan Name]** — [objective summary]
``` `/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md`
/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -802,9 +800,7 @@ Total: [X] tasks across [Y] focused plans.
**{phase}-01: [Plan Name]** — [objective summary] **{phase}-01: [Plan Name]** — [objective summary]
``` `/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md`
/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -182,9 +182,7 @@ Based on user selection, route to appropriate workflow:
**{phase}-{plan}: [Plan Name]** — [objective from PLAN.md] **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
``` `/gsd:execute-plan [path]`
/gsd:execute-plan [path]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -198,9 +196,7 @@ Based on user selection, route to appropriate workflow:
**Phase [N]: [Name]** — [Goal from ROADMAP.md] **Phase [N]: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase [phase-number]`
/gsd:plan-phase [phase-number]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>

View File

@@ -397,9 +397,7 @@ Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1]")
**Phase [X+1]: [Name]** — [Goal from ROADMAP.md] **Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
``` `/gsd:plan-phase [X+1]`
/gsd:plan-phase [X+1]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>
@@ -440,9 +438,7 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]")
**Complete Milestone [version]** — archive and prepare for next **Complete Milestone [version]** — archive and prepare for next
``` `/gsd:complete-milestone [version]`
/gsd:complete-milestone [version]
```
<sub>`/clear` first → fresh context window</sub> <sub>`/clear` first → fresh context window</sub>