silver-phase

/silver:phase — Phase CRUD Management

SB-owned skill for managing phases in .planning/ROADMAP.md. Direct edits to ROADMAP.md are blocked by the planning-file-guard; this skill is the sanctioned path for all phase list mutations.

Do not use this skill to add execution work or change acceptance criteria — that belongs in /silver:context. This skill only manages the roadmap structure.

Output

The skill writes updates to .planning/ROADMAP.md and .planning/STATE.md (when a phase is removed or reordered).

After any mutation, display a summary:

SILVER BULLET > PHASE

Action: <add|insert|remove|edit|list>
Phase: <number or range>
Result: <brief description of what changed>

ROADMAP after:
<the relevant ROADMAP.md section>

Operations

--list (default when no flags)

Display all phases with status, goal, and current phase pointer.

/silver:phase --list

--add "<goal>"

Append a new phase at the end of the active milestone with the given goal.

/silver:phase --add "Add real-time notifications via WebSocket"

Requires: .planning/ROADMAP.md exists. Produces: New phase entry at the bottom of the active milestone. Asks: Confirm goal text before writing if not --auto.

--insert N "<goal>"

Insert urgent or prerequisite work as a decimal phase after phase N. Example: inserting after phase 3 creates phase 3.1.

/silver:phase --insert 3 "Fix auth race condition before feature work"

Requires: Phase N exists in ROADMAP.md. Produces: New decimal phase inserted in sequence. Safety: Warns if phase N is completed; refuses if N is in_progress without --force.

--remove N

Remove a future phase and renumber subsequent phases to preserve numeric continuity.

/silver:phase --remove 7

Requires: Phase N must be pending (not started, not completed). Safety: Lists phases that would be renumbered and requires confirmation. Refuses: Removing in_progress or completed phases without --force.

--edit N

Edit any field of an existing phase interactively: goal, requirements coverage, mode annotation, or acceptance criteria reference.

/silver:phase --edit 5

Requires: Phase N exists. Asks: Which field to edit; presents current value; confirms before writing. With --force: Allows editing in_progress or completed phases.

Flags

Flag	Effect
--auto	Skip confirmation prompts; apply change immediately
--force	Allow editing or removing in-progress/completed phases
--dry-run	Show what would change without writing to ROADMAP.md

Process

1. Display SILVER BULLET > PHASE.
2. Verify .planning/ROADMAP.md exists. If not, ask whether to run /silver:init first.
3. Read ROADMAP.md and STATE.md to understand current phase status.
4. Validate the operation against the safety rules below.
5. In interactive mode (no --auto), show the planned change and require explicit confirmation before writing.
6. Planning guard bypass: planning-file-guard blocks direct ROADMAP.md and STATE.md edits. Before any Write/Edit to those files, create the override marker, then remove it when mutations finish:

   touch "${SB_RUNTIME_STATE_DIR}/roadmap-edit-override"
   # ... Write/Edit ROADMAP.md and STATE.md ...
   rm -f "${SB_RUNTIME_STATE_DIR}/roadmap-edit-override"
   

7. Write the change to ROADMAP.md.
8. Update STATE.md phase_count and current_phase if affected by a removal or reorder.
9. Display the post-mutation ROADMAP.md section.

Safety Rules

• Never remove a phase whose status is in_progress or completed unless --force is supplied. Removing executed work loses planning artifacts.
• Never renumber a phase below the current current_phase pointer in STATE.md without warning.
• Never set a phase goal to empty. A phase must have a goal to be plannable.
• Always confirm destructive operations (remove, force-edit of completed) with the user unless --auto is set.
• Decimal phases (e.g., 3.1) are valid for urgent inserts but must be promoted to integer numbering when the milestone is re-baselined.

Exit Gate

The skill is complete when:

• ROADMAP.md reflects the intended state;
• STATE.md is consistent with the new phase list;
• the user has confirmed any destructive or force-overridden change.