@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/workflows/ultraplan-phase.md

@@ -0,0 +1,199 @@
+# Ultraplan Phase Workflow [BETA]
+
+Offload GSD's plan phase to Claude Code's ultraplan cloud infrastructure.
+
+⚠ **BETA feature.** Ultraplan is in research preview and may change. This workflow is
+intentionally isolated from /gsd:plan-phase so upstream changes to ultraplan cannot
+affect the core planning pipeline.
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► ULTRAPLAN PHASE  ⚠ BETA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Ultraplan is in research preview (Claude Code v2.1.91+).
+Use /gsd:plan-phase for stable local planning.
+```
+
+</step>
+
+---
+
+<step name="runtime_gate">
+
+Check that the session is running inside Claude Code:
+
+```bash
+if [ "$CLAUDECODE" = "1" ] || [ -n "$CLAUDE_CODE_ENTRYPOINT" ]; then
+  CC_VERSION="$(claude --version 2>/dev/null | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)"
+  if [ -n "$CC_VERSION" ] && [ "$(printf '%s\n' "2.1.91" "$CC_VERSION" | sort -V | head -n1)" = "2.1.91" ]; then
+    echo "claude-code:${CC_VERSION}"
+  else
+    echo ""
+  fi
+else
+  echo ""
+fi
+```
+
+If the output is empty or unset, display the following error and exit:
+
+```text
+╔══════════════════════════════════════════════════════════════╗
+║  RUNTIME ERROR                                               ║
+╚══════════════════════════════════════════════════════════════╝
+
+/gsd:ultraplan-phase requires Claude Code.
+ultraplan is not available in this runtime.
+
+Use /gsd:plan-phase for local planning instead.
+```
+
+</step>
+
+---
+
+<step name="initialize">
+
+Parse phase number from `$ARGUMENTS`. If no phase number is provided, detect the next
+unplanned phase from the roadmap (same logic as /gsd:plan-phase).
+
+Load GSD phase context:
+
+```bash
+_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}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run query init.plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_found`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`,
+`phase_dir`, `roadmap_path`, `requirements_path`, `research_path`, `planning_exists`.
+
+**If `planning_exists` is false:** Error and exit:
+
+```text
+No .planning directory found. Initialize the project first:
+
+/gsd:new-project
+```
+
+**If `phase_found` is false:** Error with the phase number provided and exit.
+
+Display detected phase:
+
+```text
+Phase {N}: {phase name}
+```
+
+</step>
+
+---
+
+<step name="build_prompt">
+
+Build the ultraplan prompt from GSD context.
+
+1. Read the phase scope from ROADMAP.md — extract the goal, deliverables, and scope for
+   the target phase.
+
+2. Read REQUIREMENTS.md if it exists (`requirements_path` is not null) — extract a
+   concise summary (key requirements relevant to this phase, not the full document).
+
+3. Read RESEARCH.md if it exists (`research_path` is not null) — extract a concise
+   summary of technical findings. Including this reduces redundant cloud research.
+
+Construct the prompt:
+
+```text
+Plan phase {phase_number}: {phase_name}
+
+## Phase Scope (from ROADMAP.md)
+
+{phase scope block extracted from ROADMAP.md}
+
+## Requirements Context
+
+{requirements summary, or "No REQUIREMENTS.md found — infer from phase scope."}
+
+## Existing Research
+
+{research summary, or "No RESEARCH.md found — research from scratch."}
+
+## Output Format
+
+Produce a GSD PLAN.md with the following YAML frontmatter:
+
+---
+phase: "{padded_phase}-{phase_slug}"
+plan: "{padded_phase}-01"
+type: "feature"
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths: []
+  artifacts: []
+---
+
+Then a ## Plan section with numbered tasks. Each task should have:
+- A clear imperative title
+- Files to create or modify
+- Specific implementation steps
+
+Keep the plan focused and executable.
+```
+
+</step>
+
+---
+
+<step name="return_path_card">
+
+Display the return-path instructions **before** triggering ultraplan so they are visible
+in the terminal scroll-back after ultraplan launches:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WHEN THE PLAN IS READY — WHAT TO DO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+When ◆ ultraplan ready appears in your terminal:
+
+  1. Open the session link in your browser
+  2. Review the plan — use inline comments and emoji reactions to give feedback
+  3. Ask Claude to revise until you're satisfied
+  4. Click "Approve plan and teleport back to terminal"
+  5. At the terminal dialog, choose Cancel  ← saves the plan to a file
+  6. Note the file path Claude prints
+  7. Run: /gsd:import --from <the file path>
+
+/gsd:import will run conflict detection, convert to GSD format,
+validate via plan-checker, update ROADMAP.md, and commit.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Launching ultraplan for Phase {N}: {phase_name}...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+---
+
+<step name="trigger">
+
+Trigger ultraplan with the constructed prompt:
+
+```text
+/ultraplan {constructed prompt from build_prompt step}
+```
+
+Your terminal will show a `◇ ultraplan` status indicator while the remote session works.
+Use `/tasks` to open the detail view with the session link, agent activity, and a stop action.
+
+</step>

package/get-shit-done/workflows/undo.md

@@ -0,0 +1,314 @@
+<purpose>
+Safe git revert workflow. Rolls back GSD phase or plan commits using the phase manifest with dependency checks and a confirmation gate. Uses git revert --no-commit (NEVER git reset) to preserve history.
+</purpose>
+
+<required_reading>
+@~/.claude/get-shit-done/references/ui-brand.md
+@~/.claude/get-shit-done/references/gate-prompts.md
+</required_reading>
+
+<process>
+
+<step name="banner" priority="first">
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► UNDO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="parse_arguments">
+Parse $ARGUMENTS for the undo mode:
+
+- `--last N` → MODE=last, COUNT=N (integer, default 10 if N missing)
+- `--phase NN` → MODE=phase, TARGET_PHASE=NN (two-digit phase number)
+- `--plan NN-MM` → MODE=plan, TARGET_PLAN=NN-MM (phase-plan ID)
+
+If no valid argument is provided, display usage and exit:
+
+```
+Usage: /gsd:undo --last N | --phase NN | --plan NN-MM
+
+Modes:
+  --last N      Show last N GSD commits for interactive selection
+  --phase NN    Revert all commits for phase NN
+  --plan NN-MM  Revert all commits for plan NN-MM
+
+Examples:
+  /gsd:undo --last 5
+  /gsd:undo --phase 03
+  /gsd:undo --plan 03-02
+```
+</step>
+
+<step name="gather_commits">
+Based on MODE, gather candidate commits.
+
+**MODE=last:**
+
+Run:
+```bash
+git log --oneline --no-merges -${COUNT}
+```
+
+Filter for GSD conventional commits matching `type(scope): message` pattern (e.g., `feat(04-01):`, `docs(03):`, `fix(02-03):`).
+
+Display a numbered list of matching commits:
+```
+Recent GSD commits:
+  1. abc1234 feat(04-01): implement auth endpoint
+  2. def5678 docs(03-02): complete plan summary
+  3. ghi9012 fix(02-03): correct validation logic
+```
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+Use AskUserQuestion to ask:
+- question: "Which commits to revert? Enter numbers (e.g., 1,3) or 'all'"
+- header: "Select"
+
+Parse the user's selection into COMMITS list.
+
+---
+
+**MODE=phase:**
+
+Read `.planning/.phase-manifest.json` if it exists.
+
+If the file exists and `manifest.phases?.[TARGET_PHASE]?.commits` is a non-empty array:
+  - Use `manifest.phases[TARGET_PHASE].commits` entries as COMMITS (each entry is a commit hash)
+
+If the file does not exist, or `manifest.phases?.[TARGET_PHASE]` is missing:
+  - Display: "Manifest has no entry for phase ${TARGET_PHASE} (or file missing), falling back to git log search"
+  - Fallback: run git log and filter for the target phase scope:
+    ```bash
+    git log --oneline --no-merges --all | grep -E "\(0*${TARGET_PHASE}(-[0-9]+)?\):" | head -50
+    ```
+  - Use matching commits as COMMITS
+
+---
+
+**MODE=plan:**
+
+Run:
+```bash
+git log --oneline --no-merges --all | grep -E "\(${TARGET_PLAN}\)" | head -50
+```
+
+Use matching commits as COMMITS.
+
+---
+
+**Empty check:**
+
+If COMMITS is empty after gathering:
+```
+No commits found for ${MODE} ${TARGET}. Nothing to revert.
+```
+Exit cleanly.
+</step>
+
+<step name="dependency_check">
+**Applies when MODE=phase or MODE=plan.**
+
+Skip this step entirely for MODE=last.
+
+---
+
+**MODE=phase:**
+
+Read `.planning/ROADMAP.md` inline.
+
+Search for phases that list a dependency on the target phase. Look for patterns like:
+- "Depends on: Phase ${TARGET_PHASE}"
+- "Depends on: ${TARGET_PHASE}"
+- "depends_on: [${TARGET_PHASE}]"
+
+For each dependent phase N found:
+1. Check if `.planning/phases/${N}-*/` directory exists
+2. If directory exists, check for any PLAN.md or SUMMARY.md files inside it
+
+If any downstream phase has started work, collect warnings:
+```
+⚠  Downstream dependency detected:
+   Phase ${N} depends on Phase ${TARGET_PHASE} and has started work.
+```
+
+---
+
+**MODE=plan:**
+
+Extract the phase number from TARGET_PLAN (the NN part of NN-MM). Extract the plan number (the MM part).
+
+Look for later plans in the same phase directory (`.planning/phases/${NN}-*/`). For each later plan (plans with number > MM):
+1. Read the later plan's PLAN.md
+2. Check if its `<files>` sections or `consumes` fields reference outputs from the target plan
+
+If any later plan references the target plan's outputs, collect warnings:
+```
+⚠  Intra-phase dependency detected:
+   Plan ${LATER_PLAN} in phase ${NN} references outputs from plan ${TARGET_PLAN}.
+```
+
+---
+
+If any warnings exist (from either mode):
+- Display all warnings
+- Use AskUserQuestion with approve-revise-abort pattern:
+  - question: "Downstream work depends on the target being reverted. Proceed anyway?"
+  - header: "Confirm"
+  - options: Proceed | Abort
+
+If user selects "Abort": exit with "Revert cancelled. No changes made."
+</step>
+
+<step name="confirm_revert">
+Display the confirmation gate using approve-revise-abort pattern from gate-prompts.md.
+
+Show:
+```
+The following commits will be reverted (in reverse chronological order):
+
+  {hash} — {message}
+  {hash} — {message}
+  ...
+
+Total: {N} commit(s) to revert
+```
+
+Use AskUserQuestion:
+- question: "Proceed with revert?"
+- header: "Approve?"
+- options: Approve | Abort
+
+If "Abort": display "Revert cancelled. No changes made." and exit.
+If "Approve": ask for a reason:
+
+```
+AskUserQuestion(
+  header: "Reason",
+  question: "Brief reason for the revert (used in commit message):",
+  options: []
+)
+```
+
+Store the response as REVERT_REASON. Continue to execute_revert.
+</step>
+
+<step name="execute_revert">
+**HARD CONSTRAINT: Use git revert --no-commit. NEVER use git reset (except for conflict cleanup as documented below).**
+
+**Dirty-tree guard (run first, before any revert):**
+
+Run `git status --porcelain`. If the output is non-empty, display the dirty files and abort:
+```
+Working tree has uncommitted changes. Commit or stash them before running /gsd:undo.
+```
+Exit immediately — do not proceed to any revert operations.
+
+---
+
+Sort COMMITS in reverse chronological order (newest first). If commits came from git log (already newest-first), they are already in correct order.
+
+For each commit hash in COMMITS:
+```bash
+git revert --no-commit ${HASH}
+```
+
+If any revert fails (merge conflict or error):
+1. Display the error message
+2. Run cleanup — handle both first-call and mid-sequence cases:
+   ```bash
+   # Try git revert --abort first (works if this is the first failed revert)
+   git revert --abort 2>/dev/null
+   # If prior --no-commit reverts already staged cleanly before this failure,
+   # revert --abort may be a no-op. Clean up staged and working tree changes:
+   git reset HEAD 2>/dev/null
+   git restore . 2>/dev/null
+   ```
+3. Display:
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  ERROR                                                       ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Revert failed on commit ${HASH}.
+   Likely cause: merge conflict with subsequent changes.
+
+   **To fix:** Resolve the conflict manually or revert commits individually.
+   All pending reverts have been aborted — working tree is clean.
+   ```
+4. Exit with error.
+
+After all reverts are staged successfully, create a single commit:
+
+For MODE=phase:
+```bash
+git commit -m "revert(${TARGET_PHASE}): undo phase ${TARGET_PHASE} — ${REVERT_REASON}"
+```
+
+For MODE=plan:
+```bash
+git commit -m "revert(${TARGET_PLAN}): undo plan ${TARGET_PLAN} — ${REVERT_REASON}"
+```
+
+For MODE=last:
+```bash
+git commit -m "revert: undo ${N} selected commits — ${REVERT_REASON}"
+```
+</step>
+
+<step name="summary">
+Display the completion banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► UNDO COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show summary:
+```
+  ✓ ${N} commit(s) reverted
+  ✓ Single revert commit created: ${REVERT_HASH}
+```
+
+Show next steps:
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Review state** — verify project is in expected state after revert
+
+/clear then:
+
+/gsd:progress
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/gsd:execute-phase ${PHASE}` — re-execute if needed
+- `/gsd:undo --last 1` — undo the revert itself if something went wrong
+
+───────────────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Arguments parsed correctly for all three modes
+- [ ] --phase mode reads .planning/.phase-manifest.json using manifest.phases[TARGET_PHASE].commits
+- [ ] --phase mode falls back to git log if manifest entry missing
+- [ ] Dependency check warns when downstream phases have started (MODE=phase)
+- [ ] Dependency check warns when later plans reference target plan outputs (MODE=plan)
+- [ ] Dirty-tree guard aborts if working tree has uncommitted changes
+- [ ] Confirmation gate shown before any revert execution
+- [ ] Reverts use git revert --no-commit in reverse chronological order
+- [ ] Single commit created after all reverts staged
+- [ ] Error handling cleans up both first-call and mid-sequence conflict cases
+- [ ] git reset --hard is NEVER used anywhere in this workflow
+</success_criteria>