msd-core/gsd-core/workflows/edit-phase.md

Edit any field of an existing phase in ROADMAP.md in place. The phase number and position are always preserved. Guarded against in-progress and completed phases unless --force is passed. Validates depends_on references before writing. Shows a diff and requests confirmation before writing.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

Parse the command arguments: - First argument: phase number to edit (integer or decimal) - Optional flag: --force (allow editing in_progress/completed phases)

Examples: /gsd-edit-phase 5 → phase = 5, force = false /gsd-edit-phase 5 --force → phase = 5, force = true /gsd-edit-phase 12.1 → phase = 12.1, force = false

If no argument provided:

ERROR: Phase number required
Usage: /gsd-edit-phase <phase-number> [--force]
Example: /gsd-edit-phase 5
Example: /gsd-edit-phase 5 --force

Exit.

Load phase operation context:

_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
INIT=$(gsd_run query init.phase-op "${target}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

Check roadmap_exists from init JSON. If false:

ERROR: No roadmap found (.planning/ROADMAP.md)
Run /gsd:new-project to initialize.

Exit.

Read the current phase section from ROADMAP.md:

PHASE_DATA=$(gsd_run query roadmap get-phase "${target}")

Parse the JSON result. If found is false:

ERROR: Phase {target} not found in ROADMAP.md

Available phases can be seen with /gsd:progress.

Exit.

Extract from the result:

• phase_name — the phase title
• goal — the phase goal/description
• success_criteria — array of criteria
• section — full raw section text (preserves depends_on, requirements, plans, etc.)

Also parse the full section text to extract additional fields not in the SDK result:

• depends_on — from **Depends on:** ... or **Depends on**: ... line
• requirements — from **Requirements:** ... block if present

Determine the phase status from disk. Compare against STATE.md current phase:

ANALYZE=$(gsd_run query roadmap analyze)

Find the phase entry in the phases array. Extract disk_status.

Map disk_status to a user-friendly status:

• complete → status = completed
• planned or partial → status = in_progress
• empty, no_directory, discussed, researched → status = future

If status is in_progress or completed AND --force was NOT passed:

ERROR: Cannot edit Phase {target} — status is {status}

Editing an in-progress or completed phase may invalidate executed plans.

To edit anyway, run:
  /gsd-edit-phase {target} --force

Exit.

If --force was passed and status is in_progress or completed, continue with a warning printed to the user:

WARNING: Editing Phase {target} which is {status}. Proceeding due to --force.

Display the current phase fields clearly:

Current values for Phase {target}: {phase_name}

Title:            {phase_name}
Goal:             {goal}
Depends on:       {depends_on or "(none)"}
Requirements:     {requirements or "(none)"}
Success Criteria:
  1. {criterion_1}
  2. {criterion_2}
  ...

Then ask the user what they want to change:

What would you like to do?

  [1] Edit specific fields (title, goal, depends_on, requirements, success_criteria)
  [2] Regenerate all fields from a clarified intent
  [3] Cancel

Enter choice (1, 2, or 3):

Wait for user input.

If user chose [3] Cancel: Exit cleanly.

If user chose [1] Edit specific fields:

Ask which fields to edit. For each field the user wants to change, prompt for the new value. Only fields the user explicitly answers become updates; empty answers preserve the existing value.

Which fields do you want to update? (comma-separated or "all")
Options: title, goal, depends_on, requirements, success_criteria

For each selected field, ask:

New value for {field} [current: {current_value}]:

Build an updates map of {field → new_value} for non-empty answers.

If user chose [2] Regenerate all from clarified intent:

Ask the user:

Describe the revised intent for Phase {target} (replace the current description):

Wait for user input. Use the clarified intent to rewrite all fields:

• Generate a clear, concise title from the intent
• Write a complete goal statement
• Produce updated requirements if the original had them
• Generate success_criteria (3-5 measurable criteria)
• Preserve depends_on unless the user explicitly mentioned changing it

If `depends_on` is being updated (or preserved as non-empty), validate that every referenced phase number exists in ROADMAP.md:

ALL_PHASES=$(gsd_run query roadmap analyze)

Parse the phases array to get all valid phase numbers.

For each phase number referenced in depends_on:

• Normalize it (strip whitespace, "Phase" prefix if present)
• Check it is in the valid phase numbers set
• It must not reference itself (phase {target})

If any reference is invalid:

ERROR: depends_on references invalid phase(s): {bad_refs}

Valid phase numbers: {valid_list}

Fix the depends_on field and try again.

Exit (do not write).

Build the updated phase section by applying the changes to the original `section` text:

• For title: replace the heading text after Phase {N}:
• For goal: replace the **Goal:** line value
• For depends_on: replace or add the **Depends on:** line
• For requirements: replace or add the requirements block
• For success_criteria: replace the numbered list under **Success Criteria**:
• For full regeneration: rebuild the entire section from the new field values

Show a unified-style diff of old vs. new:

Proposed changes to Phase {target}:

--- current
+++ updated
@@ ...
- **Goal:** {old_goal}
+ **Goal:** {new_goal}
...

Apply these changes? (y/n):

Wait for confirmation. If the user says n, exit without writing.

Before writing, capture the current milestone scope (window scope + phase set) so the write can be verified against it:

SCOPE_BEFORE=$(gsd_run query roadmap milestone-scope)

Write the updated phase back in place in ROADMAP.md.

Read the full ROADMAP.md content, locate the phase section by its header (## Phase {N}: or ### Phase {N}:), and replace exactly the old section text with the new section text. All content before and after the section (including other phases, milestone headers, and the summary checklist) must be left unchanged.

After writing, re-derive the milestone scope and compare it to the capture:

SCOPE_AFTER=$(gsd_run query roadmap milestone-scope)

If scope or phases differs from SCOPE_BEFORE, the replacement text introduced a heading that terminates the current milestone window (a level 1-3 heading carrying a version token, a ✅/📋/🚧/🔄 marker, or the word "Milestone"). Restore ROADMAP.md by replacing the new section text with the original section text, then report and stop — do NOT update STATE.md and do NOT retry the write:

ERROR: edit rejected — milestone scope changed
Phase set before: {SCOPE_BEFORE phases} / after: {SCOPE_AFTER phases}
ROADMAP.md rolled back to the original section.
The updated phase text must not introduce a milestone-scoping heading; rewrite the offending line as plain text or a list item.

Exit.

If the milestone scope is unchanged, update STATE.md Roadmap Evolution:

gsd_run query state.add-roadmap-evolution \
  --phase {target} \
  --action edited \
  --note "edited fields: {changed_field_list}"

Present completion summary:

Phase {target} updated in ROADMAP.md.

Fields changed: {changed_field_list}

---

## What's Next

- `/gsd:progress` — view updated roadmap
- `/gsd:plan-phase {target}` — re-plan this phase (if needed)
- `/gsd:discuss-phase {target}` — discuss implementation approach

---

<anti_patterns>

• Don't renumber the phase — number and position must be preserved exactly
• Don't modify other phases when editing one
• Don't skip depends_on validation (invalid references block writes)
• Don't write without showing a diff and getting confirmation
• Don't edit in_progress/completed phases without --force
• Don't use raw Write on ROADMAP.md without reading it first; always replace section in place
• Don't modify the phase directory structure — only ROADMAP.md changes
• Don't introduce a milestone-scoping heading (level 1-3 with a version token, ✅/📋/🚧/🔄 marker, or "Milestone") in field values — it terminates the current milestone window; the post-write scope check rolls the edit back
• Don't commit the change — that's the user's decision </anti_patterns>

<success_criteria> Edit-phase is complete when:

• Phase {target} found and loaded from ROADMAP.md
• Status check performed; in_progress/completed blocked without --force
• Current values presented to user
• User chose edit mode (specific fields or full regeneration)
• depends_on references validated; invalid references blocked
• Diff shown and confirmed by user
• Updated phase written back in place; number, position, and status preserved
• Milestone scope verified unchanged after the write (rollback + error on mismatch)
• STATE.md Roadmap Evolution updated
• User informed of next steps </success_criteria>