feat: improved continuation UI with context and visual hierarchy

- Add continuation-format.md reference defining the standard format
- Replace "## To Continue" with "## ▶ Next Up"
- Show plan/phase name + description instead of just command paths
- Add `/clear` explanation: "fresh context window"
- Change "Other options" to "Also available"
- Add /gsd:research-phase to phase planning options
- Add visual separators and completion headers

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commands/gsd/add-phase.md

@@ -163,16 +163,25 @@ Phase {N} added to current milestone:
 Roadmap updated: {roadmap-path}
 Project state updated: .planning/STATE.md
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
 
-Run `/clear`, then paste:
 ```
 /gsd:plan-phase {N}
 ```
 
-Other options:
-- Add another phase: `/gsd:add-phase <description>`
-- Review roadmap: `cat .planning/ROADMAP.md`
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:add-phase <description>` — add another phase
+- Review roadmap
+
+---
 ```
 </step>
 

commands/gsd/create-roadmap.md

@@ -112,19 +112,26 @@ Roadmap created:
 - State: .planning/STATE.md
 - [N] phases defined
 
-## To Continue
+---
 
-Run `/clear`, then paste one of:
+## ▶ Next Up
 
-**To discuss Phase 1 context first:**
-```
-/gsd:discuss-phase 1
-```
+**Phase 1: [Name]** — [Goal from ROADMAP.md]
 
-**To plan Phase 1 directly:**
 ```
 /gsd:plan-phase 1
 ```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 1` — gather context first
+- `/gsd:research-phase 1` — investigate unknowns
+- Review roadmap
+
+---
 ```
 </step>
 

commands/gsd/insert-phase.md

@@ -182,16 +182,25 @@ Phase {decimal_phase} inserted after Phase {after_phase}:
 Roadmap updated: {roadmap-path}
 Project state updated: .planning/STATE.md
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**Phase {decimal_phase}: {description}** — urgent insertion
 
-Run `/clear`, then paste:
 ```
 /gsd:plan-phase {decimal_phase}
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
 - Review insertion impact: Check if Phase {next_integer} dependencies still make sense
-- Review roadmap: `cat .planning/ROADMAP.md`
+- Review roadmap
+
+---
 ```
 </step>
 

commands/gsd/new-project.md

@@ -133,7 +133,7 @@ EOF
 </step>
 
 <step name="done">
-Present completion inline (not as a question):
+Present completion with next steps (see ~/.claude/get-shit-done/references/continuation-format.md):
 
 ```
 Project initialized:
@@ -141,19 +141,25 @@ Project initialized:
 - Project: .planning/PROJECT.md
 - Config: .planning/config.json (mode: [chosen mode])
 
-## To Continue
+---
 
-Run `/clear`, then paste one of:
+## ▶ Next Up
 
-**For niche/complex domains (recommended):**
+**[Project Name]** — research domain or create roadmap
+
+**Research first (recommended for niche/complex domains):**
 ```
 /gsd:research-project
 ```
 
-**To skip research and go straight to planning:**
+**Create roadmap directly:**
 ```
 /gsd:create-roadmap
 ```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
 ```
 </step>
 

commands/gsd/progress.md

@@ -98,14 +98,21 @@ Check if `{phase}-{plan}-PLAN.md` exists for that number.
 
 - Read its `<objective>` section
 - Show: "Ready to execute: [path] - [objective summary]"
-- Display:
+- Display (see ~/.claude/get-shit-done/references/continuation-format.md):
   ```
-  ## To Continue
+  ---
+
+  ## ▶ Next Up
+
+  **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
 
-  Run `/clear`, then paste:
   ```
   /gsd:execute-plan [full-path-to-PLAN.md]
   ```
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
   ```
 
 **If PLAN.md does NOT exist:**
@@ -119,36 +126,45 @@ Check if `{phase}-{plan}-PLAN.md` exists for that number.
 - Display: "✓ Context gathered, ready to plan"
 - Display:
   ```
-  ## To Continue
+  ---
+
+  ## ▶ Next Up
+
+  **Phase [N]: [Name]** — [Goal from ROADMAP.md]
 
-  Run `/clear`, then paste:
   ```
   /gsd:plan-phase [phase-number]
   ```
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
   ```
 
 **If CONTEXT.md does NOT exist:**
 
 - Display:
   ```
-  ## To Continue
+  ---
 
-  Run `/clear`, then paste one of:
+  ## ▶ Next Up
 
-  **See Claude's assumptions:**
-  ```
-  /gsd:list-phase-assumptions [phase]
-  ```
+  **Phase [N]: [Name]** — [Goal from ROADMAP.md]
 
-  **Discuss context first:**
-  ```
-  /gsd:discuss-phase [phase]
-  ```
-
-  **Plan directly:**
   ```
   /gsd:plan-phase [phase]
   ```
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+
+  **Also available:**
+  - `/gsd:discuss-phase [phase]` — gather context first
+  - `/gsd:research-phase [phase]` — investigate unknowns
+  - `/gsd:list-phase-assumptions [phase]` — see Claude's assumptions
+
+  ---
   ```
 
 **If all plans complete for current phase:**

commands/gsd/research-project.md

@@ -156,15 +156,24 @@ Key implementation context:
 Open questions remaining:
 - [Any questions research couldn't answer]
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**Create Roadmap** — define phases based on research findings
 
-Run `/clear`, then paste:
 ```
 /gsd:create-roadmap
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
 - Review research files before continuing
+
+---
 ```
 </step>
 

get-shit-done/references/continuation-format.md

@@ -0,0 +1,270 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```markdown
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+```
+{command to copy-paste}
+```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- {alternative option 1}
+- {alternative option 2}
+
+---
+```
+
+## Format Rules
+
+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
+3. **Command in clean code block** — easy to copy-paste
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```markdown
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+```
+/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
+```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/gsd:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```markdown
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+```
+/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
+```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```markdown
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+```
+/gsd:plan-phase 2
+```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 2` — gather context first
+- `/gsd:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```markdown
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+```
+/gsd:plan-phase 3
+```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 3` — gather context first
+- `/gsd:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```markdown
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:**
+```
+/gsd:plan-phase 3
+```
+
+**To discuss context first:**
+```
+/gsd:discuss-phase 3
+```
+
+**To research unknowns:**
+```
+/gsd:research-phase 3
+```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```markdown
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Plan v1.1** — Enhanced features and optimizations
+
+```
+/gsd:discuss-milestone
+```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:new-milestone` — create directly if scope is clear
+- Review accomplishments before moving on
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```markdown
+## To Continue
+
+Run `/clear`, then paste:
+```
+/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
+```
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```markdown
+```
+/gsd:plan-phase 3
+```
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```markdown
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.

get-shit-done/workflows/complete-milestone.md

@@ -424,19 +424,24 @@ Shipped:
 Summary: .planning/MILESTONES.md
 Tag: v[X.Y]
 
-## To Continue
+---
 
-Run `/clear`, then paste one of:
+## ▶ Next Up
+
+**Plan Next Milestone** — define v[X.Y+1] features and scope
 
-**To discuss next milestone scope:**
 ```
 /gsd:discuss-milestone
 ```
 
-**To create next milestone directly:**
-```
-/gsd:new-milestone
-```
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:new-milestone` — create directly if scope is clear
+
+---
 ```
 </step>
 

get-shit-done/workflows/create-milestone.md

@@ -323,22 +323,26 @@ Milestone v[X.Y] [Name] created:
 - ROADMAP.md updated
 - STATE.md reset for new milestone
 
-## To Continue
+---
 
-Run `/clear`, then paste one of:
+## ▶ Next Up
 
-**To discuss Phase [N] context first:**
-```
-/gsd:discuss-phase [N]
-```
+**Phase [N]: [Name]** — [Goal from ROADMAP.md]
 
-**To plan Phase [N] directly:**
 ```
 /gsd:plan-phase [N]
 ```
 
-Other options:
-- Review roadmap before continuing
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase [N]` — gather context first
+- `/gsd:research-phase [N]` — investigate unknowns
+- Review roadmap
+
+---
 ```
 </step>
 

get-shit-done/workflows/create-roadmap.md

@@ -487,19 +487,26 @@ Project initialized:
 - State: .planning/STATE.md
 - Committed as: docs: initialize [project] ([N] phases)
 
-## To Continue
+---
 
-Run `/clear`, then paste one of:
+## ▶ Next Up
 
-**To discuss Phase 1 context first:**
-```
-/gsd:discuss-phase 1
-```
+**Phase 1: [Name]** — [Goal from ROADMAP.md]
 
-**To plan Phase 1 directly:**
 ```
 /gsd:plan-phase 1
 ```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 1` — gather context first
+- `/gsd:research-phase 1` — investigate unknowns
+- Review roadmap
+
+---
 ```
 </step>
 

get-shit-done/workflows/discuss-milestone.md

@@ -138,12 +138,19 @@ Milestone scope defined:
 
 Ready to create the milestone structure.
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**Create Milestone v[X.Y]** — [Theme Name]
 
-Run `/clear`, then paste:
 ```
 /gsd:new-milestone
 ```
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
 ```
 
 Pass context forward by summarizing:

get-shit-done/workflows/discuss-phase.md

@@ -194,22 +194,25 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
 ## Boundaries
 [What's out of scope]
 
-## To Continue
+---
 
-Run `/clear`, then paste one of:
+## ▶ Next Up
 
-**To research this phase first:**
-```
-/gsd:research-phase ${PHASE}
-```
+**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
 
-**To plan this phase directly:**
 ```
 /gsd:plan-phase ${PHASE}
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:research-phase ${PHASE}` — investigate unknowns
 - Review/edit CONTEXT.md before continuing
+
+---
 ```
 
 </step>

get-shit-done/workflows/execute-phase.md

@@ -1210,15 +1210,24 @@ Summary: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 
 [X] of [Y] plans complete for Phase Z.
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**{phase}-{next-plan}: [Plan Name]** — [objective from next PLAN.md]
 
-Run `/clear`, then paste:
 ```
 /gsd:execute-plan .planning/phases/XX-name/{phase}-{next-plan}-PLAN.md
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
 - Review what was built before continuing
+
+---
 ```
 
 Wait for user to clear and run next command.
@@ -1257,16 +1266,25 @@ All [N] phases complete!
 This milestone is 100% done.
 ════════════════════════════════════════
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**Complete Milestone** — archive and prepare for next
 
-Run `/clear`, then paste:
 ```
 /gsd:complete-milestone
 ```
 
-Other options:
-- Add another phase: `/gsd:add-phase <description>`
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:add-phase <description>` — add another phase
 - Review accomplishments before archiving
+
+---
 ```
 
 **If phase complete but more phases remain:**
@@ -1275,24 +1293,30 @@ Other options:
 Plan {phase}-{plan} complete.
 Summary: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 
-Phase [Z]: [Name] COMPLETE - all [Y] plans finished.
+## ✓ Phase [Z] Complete
 
-## To Continue
+All [Y] plans finished.
 
-Run `/clear`, then paste one of:
+---
 
-**To discuss Phase [X+1] context first:**
-```
-/gsd:discuss-phase [X+1]
-```
+## ▶ Next Up
+
+**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
 
-**To plan Phase [X+1] directly:**
 ```
 /gsd:plan-phase [X+1]
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase [X+1]` — gather context first
+- `/gsd:research-phase [X+1]` — investigate unknowns
 - Review phase accomplishments before continuing
+
+---
 ```
 
 </step>

get-shit-done/workflows/plan-phase.md

@@ -717,15 +717,24 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
 [X] tasks defined.
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**{phase}-01: [Plan Name]** — [objective summary]
 
-Run `/clear`, then paste:
 ```
 /gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
 - Review/adjust tasks before executing
+
+---
 ```
 
 **If multiple plans:**
@@ -739,15 +748,25 @@ Phase plans created:
 
 Total: [X] tasks across [Y] focused plans.
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**{phase}-01: [Plan Name]** — [objective summary]
 
-Run `/clear`, then paste:
 ```
 /gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
 - Review/adjust tasks before executing
+- View all plans: `ls .planning/phases/XX-name/*-PLAN.md`
+
+---
 ```
 </step>
 

get-shit-done/workflows/resume-project.md

@@ -176,21 +176,41 @@ Based on user selection, route to appropriate workflow:
 
 - **Execute plan** → Show command for user to run after clearing:
   ```
-  ## To Continue
+  ---
+
+  ## ▶ Next Up
+
+  **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
 
-  Run `/clear`, then paste:
   ```
   /gsd:execute-plan [path]
   ```
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
   ```
 - **Plan phase** → Show command for user to run after clearing:
   ```
-  ## To Continue
+  ---
+
+  ## ▶ Next Up
+
+  **Phase [N]: [Name]** — [Goal from ROADMAP.md]
 
-  Run `/clear`, then paste:
   ```
   /gsd:plan-phase [phase-number]
   ```
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+
+  **Also available:**
+  - `/gsd:discuss-phase [N]` — gather context first
+  - `/gsd:research-phase [N]` — investigate unknowns
+
+  ---
   ```
 - **Transition** → ./transition.md
 - **Review issues** → Read ISSUES.md, present summary

get-shit-done/workflows/transition.md

@@ -389,26 +389,28 @@ Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1]")
 
 <if mode="interactive" OR="custom with gates.confirm_transition true">
 ```
-Phase [X] marked complete.
+## ✓ Phase [X] Complete
 
-Next: Phase [X+1] - [Name]
+---
 
-## To Continue
+## ▶ Next Up
 
-Run `/clear`, then paste one of:
+**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
 
-**To discuss Phase [X+1] context first:**
-```
-/gsd:discuss-phase [X+1]
-```
-
-**To plan Phase [X+1] directly:**
 ```
 /gsd:plan-phase [X+1]
 ```
 
-Other options:
-- Review roadmap before continuing
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase [X+1]` — gather context first
+- `/gsd:research-phase [X+1]` — investigate unknowns
+- Review roadmap
+
+---
 ```
 </if>
 
@@ -428,19 +430,28 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]")
 
 <if mode="interactive" OR="custom with gates.confirm_transition true">
 ```
-Phase [X] marked complete.
+## ✓ Phase [X] Complete
 
 🎉 Milestone [version] is 100% complete - all phases finished!
 
-## To Continue
+---
+
+## ▶ Next Up
+
+**Complete Milestone [version]** — archive and prepare for next
 
-Run `/clear`, then paste:
 ```
 /gsd:complete-milestone [version]
 ```
 
-Other options:
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
 - Review accomplishments before archiving
+
+---
 ```
 </if>