@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

package/src/resources/extensions/gsd/prompts/sketch.md

@@ -0,0 +1,59 @@
+You are running the GSD **sketch** workflow — explore UI/design ideas with throwaway HTML mockups that let the developer feel a design before committing to implementation.
+
+## Design Idea
+
+{{input}}
+
+## Flags
+
+- `--quick` — {{quickFlag}} (when true, skip decomposition and jump straight to a single mockup)
+- `--text` — {{textFlag}} (when true, use plain-text numbered lists instead of interactive prompts)
+- Frontier mode — {{frontierFlag}} (when true, analyze existing sketches and propose what to sketch next instead of a new one)
+
+## Process
+
+### 1. Route the input
+
+- If frontier mode is active (no idea given, or the word "frontier"): go to **Frontier mode**.
+- Otherwise: continue to **Setup**.
+
+### 2. Setup
+
+Create `.gsd/sketches/` if it does not exist and determine the next sketch number by listing existing `.gsd/sketches/[0-9][0-9][0-9]-*` directories.
+
+### 3. Decompose the design (skip if `--quick`)
+
+If the design idea has multiple surfaces (e.g. landing page, dashboard, empty state), break it into focused mockups. Each should explore one surface or one interaction. Order by the most uncertain design direction first.
+
+### 4. Align on direction
+
+Briefly confirm scope and any constraints (brand, target device, accessibility). Keep this short — sketches are cheap and disposable.
+
+### 5. Build
+
+Create `.gsd/sketches/{{sketchId}}/` and build each mockup as a self-contained `index.html` (inline CSS/JS, no build step). Open it in the browser via the project's tooling so the developer can see and react to it.
+
+### 6. Observe and refine
+
+Let the developer react to each mockup. Iterate quickly on the throwaway HTML. Capture the design decisions that emerge (layout, color, motion, copy).
+
+### 7. Document
+
+Write `.gsd/sketches/{{sketchId}}/README.md` with:
+- The design idea and the surfaces explored
+- The mockup files and what each demonstrates
+- Design decisions captured and their rationale
+- Recommendations for the real implementation
+
+Append a one-line summary to `.gsd/CAPTURES.md` linking the README.
+
+### 8. Frontier mode (only when frontier flag is active)
+
+Load the sketch landscape: read `.gsd/sketches/*/README.md`. Analyze for **integration sketches** (sketches that touch the same flow) and **frontier sketches** (unexplored surfaces, alternative directions, empty/loading/error states). Present concrete candidates and let the developer choose which to run.
+
+## Success criteria
+
+- Each mockup is a self-contained `index.html` with no build step.
+- Artifacts live under `.gsd/sketches/{{sketchId}}/`.
+- The README captures design decisions usable by the real implementation.
+- Iteration is fast and the sketches stay disposable.

package/src/resources/extensions/gsd/prompts/spec-phase.md

@@ -0,0 +1,29 @@
+You are running the GSD **spec-phase** workflow — clarify WHAT a milestone/slice delivers, with ambiguity scoring, before discussion or planning.
+
+## Target
+
+{{target}}
+
+## Flags
+
+- `--auto` — {{autoFlag}}
+- `--text` — {{textFlag}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice's stated goal, requirements, and any discuss/research context.
+
+2. **Draft the SPEC.** State, in plain language: what this delivers, for whom, the inputs/outputs, the success criteria, and explicit non-goals.
+
+3. **Score ambiguity.** For each part of the spec, score ambiguity (low/medium/high) and identify the specific phrase causing it. High-ambiguity items become discussion questions.
+
+4. **Resolve ambiguity.** For each high-ambiguity item: in `--auto`, infer and flag; otherwise ask one targeted question at a time to resolve it. Update the spec with the resolved language.
+
+5. **Write the SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd discuss-phase` (deeper discussion) or `/gsd plan-phase` (the spec is clear enough to plan).
+
+## Success criteria
+
+- The spec states WHAT, not HOW.
+- Every high-ambiguity item is resolved or explicitly deferred with a reason.
+- Non-goals are explicit.
+- The recommended next step reflects remaining ambiguity.

package/src/resources/extensions/gsd/prompts/spike.md

@@ -0,0 +1,59 @@
+You are running the GSD **spike** workflow — experiential exploration that builds focused experiments to validate feasibility and produce verified knowledge for the real build.
+
+## Spike Input
+
+{{input}}
+
+## Flags
+
+- `--quick` — {{quickFlag}} (when true, skip decomposition/alignment and jump straight to building)
+- `--text` — {{textFlag}} (when true, use plain-text numbered lists instead of interactive prompts)
+- Frontier mode — {{frontierFlag}} (when true, analyze existing spikes and propose integration/frontier spikes instead of a new one)
+
+## Process
+
+### 1. Route the input
+
+- If frontier mode is active (no idea given, or the word "frontier"): go to **Frontier mode**.
+- Otherwise: continue to **Setup**.
+
+### 2. Setup
+
+Create `.gsd/spikes/` if it does not exist and determine the next spike number by listing existing `.gsd/spikes/[0-9][0-9][0-9]-*` directories. Use the project's detected stack (check `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`) to choose technology. Avoid heavy tooling — pick whatever reaches a runnable result fastest.
+
+### 3. Decompose the idea (skip if `--quick`)
+
+Break the idea into 1–3 focused experiments. Each experiment should validate one specific risk or assumption with a clear **Given/When/Then** validation question. Order by highest risk first.
+
+### 4. Research (brief)
+
+For each experiment, do the minimum research needed to start building — library docs, API shape, known gotchas. Use `resolve_library`/docs lookups. Do not over-research.
+
+### 5. Build
+
+Create `.gsd/spikes/{{spikeId}}/` and build each experiment as a small, self-contained, runnable artifact. Prefer throwaway code that proves the point. Hardcode configuration — do not build config systems.
+
+### 6. Verify
+
+For each experiment, run the validation question and record a verdict: `VALIDATED`, `PARTIAL`, or `INVALIDATED`, with the evidence (command output, observed behavior).
+
+### 7. Document
+
+Write `.gsd/spikes/{{spikeId}}/README.md` with:
+- The original idea and the experiments run
+- Per-experiment verdict + evidence
+- Conclusions and recommendations for the real build
+- Any conventions discovered worth recording (stack, patterns)
+
+Append a one-line summary to `.gsd/CAPTURES.md` linking the README so the spike is discoverable.
+
+### 8. Frontier mode (only when frontier flag is active)
+
+Load the spike landscape: read `.gsd/spikes/*/README.md` and any `CONVENTIONS.md`. Analyze for **integration spikes** (validated spikes that share resources, hand off data, or contend) and **frontier spikes** (gaps, discovered dependencies, alternative approaches). Present concrete candidates with Given/When/Then questions and let the developer choose which to run.
+
+## Success criteria
+
+- Each experiment has a clear validation question and a recorded verdict with evidence.
+- Artifacts live under `.gsd/spikes/{{spikeId}}/`.
+- The README captures conclusions usable by the real build.
+- No heavy infrastructure, build systems, or config layers unless the spike specifically requires them.

package/src/resources/extensions/gsd/prompts/stats.md

@@ -0,0 +1,43 @@
+You are running the GSD **stats** workflow — display comprehensive project statistics.
+
+## Process
+
+Read the canonical gsd-pi state and present a statistics summary. Use gsd-pi's own tooling to gather the data — do not hand-parse files when a command or query exists.
+
+Gather:
+- Active milestone id/title and overall milestone progress (completed/total).
+- Slice and task progress for the active milestone (completed/total per slice where available).
+- Requirements coverage if tracked.
+- Git metrics: total commits, first commit date, last activity date, current branch.
+- Project age in days.
+
+Present the summary in this shape:
+
+```
+# 📊 Project Statistics — {milestone} {title}
+
+## Progress
+[████████░░] X/Y milestones (Z%)
+
+## Slices (active milestone)
+| Slice | Tasks | Completed | Status |
+
+## Requirements
+✅ X/Y requirements complete
+
+## Git
+- Commits: N
+- Started: YYYY-MM-DD
+- Last activity: YYYY-MM-DD
+
+## Timeline
+- Project age: N days
+```
+
+If no `.gsd/` project exists, say so and suggest `/gsd init`.
+
+## Success criteria
+
+- Numbers come from canonical gsd-pi state, not estimates.
+- The summary is readable in a terminal (ASCII progress bar, tables).
+- Missing sections are omitted rather than printed with zeroes.

package/src/resources/extensions/gsd/prompts/surface.md

@@ -0,0 +1,25 @@
+You are running the GSD **surface** workflow — manage which skills/extensions are surfaced in the active session.
+
+## Action
+
+{{action}}
+
+## Process
+
+Parse the action:
+
+- **list / status** (default): Show every installed skill/extension with its current surfaced state (enabled/disabled) and source (bundled, project, global). Group by cluster where applicable.
+- **profile <name>**: Apply a named surfacing profile — enable a curated cluster of skills and disable the rest. Confirm the change set before applying.
+- **disable <cluster>**: Disable a cluster of skills so they stop loading into context. Record the change so it persists.
+- **enable <cluster>**: Re-enable a previously disabled cluster.
+- **reset**: Restore the default surfacing state.
+
+Use gsd-pi's own extension/skill management (`/gsd extensions`, `/gsd skill-health`) as the backing store for these changes — do not invent a separate state file.
+
+If the action names an unknown cluster or profile, list the valid options rather than failing silently.
+
+## Success criteria
+
+- The current surfaced state is reported accurately from the backing store.
+- Changes persist via gsd-pi's extension/skill management, not a parallel mechanism.
+- Unknown names produce a helpful list of valid options.

package/src/resources/extensions/gsd/prompts/system.md

@@ -110,9 +110,12 @@ Templates are in `{{templatesDir}}`.
 
 **External facts:** Use `search-the-web` + `fetch_page`, or `search_and_read`; use `freshness` for recency. Never state current facts from training data without verification.
 
-**Background processes:** Use `bg_shell` `start` + `wait_for_ready` for servers/watchers/daemons. Never use `bash` with `&` or `nohup`; inherited stdout can hang. Never poll with `sleep`; use `wait_for_ready`. For status use `digest`, `highlights` for significant lines, and `output` only when debugging.
+**Choosing a shell tool — decide by how the command runs, not how long it takes:**
 
-**One-shot commands:** Use `async_bash` for builds, tests, and installs. Results are pushed on exit; use `await_job` only to block on a specific job.
+- **Runs and exits (a batch command):** anything that does work and finishes — `terraform apply`, DB migrations, builds, tests, installs, long scripts. Use synchronous `bash` when you want to block and read the result now (uncapped; in auto-mode genuine hangs are caught by the stalled-tool watchdog, interactively they end on human ESC). Use `async_bash` when you want it non-blocking — it returns a job ID immediately and you `await_job` later. **Never** put a run-to-completion command under `bg_shell` `wait_for_ready`: it exits instead of staying alive, so readiness never trips and a clean exit looks like a failure.
+- **Stays alive and you interact with it over time:** servers, watchers, daemons, REPLs. Use `bg_shell` `start`, then `wait_for_ready` (block until it listens/prints its ready pattern), `output`/`digest`/`highlights` to inspect, `send`/`send_and_wait` to drive it, and `kill`/`restart` to manage it. Never use `bash` with `&` or `nohup` (inherited stdout can hang); never poll with `sleep` (use `wait_for_ready`).
+
+Quick rule of thumb: if the command would exit on its own, it's `bash`/`async_bash`; if it would keep running until you stop it, it's `bg_shell`.
 
 **Stale job hygiene:** After editing source to fix a failure, `cancel_job` every in-flight `async_bash` job before rerunning. Changed inputs make in-flight outputs untrusted.
 
@@ -158,7 +161,7 @@ Fix root causes, not symptoms. If applying temporary mitigation, label it and pr
 - State uncertainty plainly: "Not sure this handles X - testing it." No performed confidence, no hedging paragraphs.
 - All user-visible narration must be grammatical English. Do not emit compressed planner notes like "Need inspect X". If it fits a commit comment or standup note, it is acceptable.
 - When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
-- After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats.
+- After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats, or when the active workflow prompt already ends with its own explicit "Next steps:" handoff block — in that case follow the workflow's handoff and do not add a second list.
 
   If any next step is destructive/outward-facing, present it via `ask_user_questions` and wait for the user's answer before execution. Do not execute a next-step item from a prior plain-text numbered list without fresh confirmation.
 

package/src/resources/extensions/gsd/prompts/thread.md

@@ -0,0 +1,24 @@
+You are running the GSD **thread** workflow — manage persistent context threads for cross-session work, backed by the memory store so threads survive across sessions.
+
+## Action
+
+{{action}}
+
+## Process
+
+A thread is a named, resumable context line: a topic, the open question, decisions so far, and the next step. Threads live in the gsd-pi memory store so they persist and are queryable.
+
+Parse the action:
+
+- **list [--open|--resolved]** (default): list threads filtered by state. Each entry: slug, status, last-updated, one-line topic.
+- **close <slug>**: mark a thread resolved (record the resolution as a knowledge lesson if durable).
+- **status <slug>**: show a thread's full context (topic, decisions, open question, next step).
+- **<name> / <description>** (bare text): create or update a thread with the given name/description, stamping the current state and next step.
+
+Use `/gsd memory` as the backing store for thread persistence. When closing a thread whose resolution is a reusable lesson, also record it via `/gsd knowledge lesson`.
+
+## Success criteria
+
+- Threads persist in the memory store, not in a throwaway file.
+- Listing honors the open/resolved filter.
+- Resolved threads with durable lessons feed the knowledge store.

package/src/resources/extensions/gsd/prompts/triage-captures.md

@@ -65,4 +65,4 @@ Classify each capture as one of:
 
 **Important:** Do NOT execute any resolutions. Only classify and update CAPTURES.md. Resolution execution happens separately (in auto-mode dispatch or manually by the user).
 
-When done, say: "Triage complete."
+When done, say: "Triage closeout submitted." Do not say triage is complete — GSD announces completion only after post-unit verification passes. Say this exactly once — if you already said it in a prior message, do not repeat it.

package/src/resources/extensions/gsd/prompts/ui-phase.md

@@ -0,0 +1,29 @@
+You are running the GSD **ui-phase** workflow — produce a UI design contract (UI-SPEC) for a frontend milestone/slice before implementation.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice goal, requirements, and any existing brand/design references.
+
+2. **Inventory the surfaces.** List every screen/state/component the milestone touches: pages, key states (empty, loading, error, success), and shared components.
+
+3. **Define the design contract per surface:**
+   - Layout (structure, responsive behavior)
+   - Key interactions and their feedback states
+   - Content/copy essentials
+   - Accessibility requirements
+   - Entry/exit points to other surfaces
+
+4. **Align on constraints.** Brand, type scale, color tokens, spacing system, component library — use existing design tokens where they exist; flag gaps.
+
+5. **Write the UI-SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd sketch` to prototype high-uncertainty surfaces, or `/gsd plan-phase` to plan implementation.
+
+## Success criteria
+
+- Every surface the milestone touches is inventoried.
+- Each surface's contract is concrete enough to implement against.
+- Existing design tokens are reused; gaps are flagged.
+- The recommended next step reflects design readiness.

package/src/resources/extensions/gsd/prompts/ui-review.md

@@ -0,0 +1,29 @@
+You are running the GSD **ui-review** workflow — retroactive visual audit of implemented frontend code against design intent.
+
+## Target
+
+{{target}}
+
+## Process
+
+Audit the implemented UI across these pillars, grounding each finding in actual code (component files, styles, markup) with file paths:
+
+1. **Layout & spacing** — alignment, grid/flex correctness, responsive behavior, spacing rhythm.
+2. **Color & contrast** — palette consistency, accessible contrast ratios, dark/light coherence.
+3. **Typography** — type scale, hierarchy, line-height, legibility.
+4. **Interaction & feedback** — hover/focus/active states, loading/empty/error states, motion.
+5. **Consistency** — shared components reused, design tokens applied, no one-off magic numbers.
+6. **Accessibility** — semantic markup, keyboard navigation, ARIA correctness, focus management.
+
+For each pillar, give a score (0–5) with bullet findings (location + issue + suggested fix).
+
+## Output
+
+Write `.gsd/reviews/{{reviewId}}-UI-REVIEW.md` with the per-pillar scores, findings, and a prioritized fix list (critical first). Print the overall score and the critical findings.
+
+## Success criteria
+
+- Every finding cites a component/file path.
+- Each pillar has an explicit score, not just prose.
+- Critical findings are surfaced first and are actionable.
+- The review lives under `.gsd/reviews/`.

package/src/resources/extensions/gsd/prompts/ultraplan-phase.md

@@ -0,0 +1,24 @@
+You are running the GSD **ultraplan-phase** workflow — offload heavy planning of a milestone/slice to an extended-reasoning plan pass, review the result, and import it back. This uses a local extended-reasoning pass (an external cloud service is not available in this runtime).
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Assemble the planning brief.** Gather the milestone/slice goal, CONTEXT, RESEARCH, decisions, requirements, and a codebase snapshot into a single self-contained brief.
+
+2. **Run the extended-reasoning plan pass.** Produce a thorough plan from the brief using high reasoning effort: full task decomposition, dependency graph, verification per task, risks. This is the "ultraplan" — more exhaustive than a standard plan pass.
+
+3. **Review in the open.** Present the plan for review (the human reviews it before it's imported). Flag anything uncertain, risky, or that diverges from the stated goal.
+
+4. **Import.** On approval, write the plan to the milestone/slice plan artifact in `.gsd/` and record durable decisions. Note that this replaces the cloud review-and-import with a local review.
+
+5. **Route.** Recommend `/gsd dispatch execute` or `/gsd plan-review-convergence` for a convergence pass.
+
+## Success criteria
+
+- The plan is more exhaustive than a standard pass (that's the point of the offload).
+- The human reviews before import (no silent overwrite of an existing plan).
+- The brief is self-contained so the reasoning isn't context-starved.
+- Durable decisions are persisted on import.

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -87,4 +87,4 @@ If verdict is `needs-remediation`:
 
 **File system safety:** When scanning milestone directories, use `ls` or `find` first. Never pass a directory path such as `tasks/` or `slices/` directly to `read`; it only accepts files.
 
-When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."
+When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/src/resources/extensions/gsd/prompts/validate-phase.md

@@ -0,0 +1,26 @@
+You are running the GSD **validate-phase** workflow — retroactively audit and fill validation coverage gaps for completed work, using Nyquist-style coverage sampling.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Map the verification surface.** For the target's tasks, list what behaviors/outputs each claims to verify, and the test (or manual check) that verifies it.
+
+2. **Find coverage gaps.** Identify: behaviors with no test, error/edge paths untested, boundaries between slices untested, and claims verified only by happy-path tests. Apply a Nyquist lens — sample at the rate needed to catch the behavior changing, not just once.
+
+3. **Generate the missing tests.** For each gap that is safe to fill deterministically, write the test (matching the project's test framework and conventions). Run the test suite after adding tests. For gaps that need a human (UI, exploratory), record them as UAT items instead of auto-generating.
+
+4. **Update the validation record.** Write/append the slice's VALIDATION note (or `.gsd/` equivalent) with the coverage map before/after, the tests added, and the remaining human-UAT items.
+
+5. **Report.** Summarize: gaps found, tests added (passing), and remaining human-UAT items.
+
+Prefer delegating test generation to `/gsd add-tests` where it fits, rather than hand-writing every test.
+
+## Success criteria
+
+- Every claimed behavior is mapped to a test (or flagged as needing human UAT).
+- Generated tests pass and match the project's conventions.
+- The validation record reflects the new coverage honestly.
+- Human-only gaps are recorded as UAT items, not silently skipped.

package/src/resources/extensions/gsd/prompts/verify-work.md

@@ -0,0 +1,24 @@
+You are running the GSD **verify-work** workflow — validate built features through conversational UAT.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load what was built.** Read the target slice/milestone plan and SUMMARY to understand what features were delivered and what their acceptance criteria are.
+
+2. **Draft a UAT script.** Turn each acceptance criterion into a concrete, observable test step the human can perform (or that you can perform via tooling where possible). Group by feature; order so earlier steps set up later ones.
+
+3. **Walk through the script conversationally.** Present one step (or a small group) at a time. For each, record the outcome: `pass`, `fail` (with what happened), `blocked` (with the blocker), or `skipped` (intentionally). Do not advance past a fail without acknowledging it.
+
+4. **Where you can self-verify** (deterministic checks: type checks, tests, lint, schema), run them and include the result alongside the human step.
+
+5. **Produce the verdict.** After all steps: `pass` (all criteria met), `needs-attention` (some steps failed but none blocking), or `needs-remediation` (a blocking failure). Record the UAT outcome against the slice via the appropriate gsd-pi mechanism.
+
+## Success criteria
+
+- Every acceptance criterion becomes a concrete, observable step.
+- Outcomes are recorded honestly — fails are not hidden.
+- Deterministic checks are run where possible, not just asked about.
+- The final verdict maps to a canonical gsd-pi outcome.

package/src/resources/extensions/gsd/prompts/workflow-start.md

@@ -25,4 +25,5 @@ Follow the workflow defined below. Execute each phase in order, completing one b
 3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
 4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
 5. **Decision gates, not ceremony.** After each phase, summarize what changed. For low/medium complexity, ask for confirmation only when the next phase depends on a real user choice or external approval. For high complexity, confirm before proceeding to each new phase.
-6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.
+6. **Persist workflow state.** If the artifact directory contains `STATE.json`, update it after each phase: mark the finished phase `completed`, mark the next phase `active`, set `currentPhase` to the active phase index, and refresh `updatedAt`. When every phase is completed, set `completedAt` to the completion timestamp.
+7. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/src/resources/extensions/gsd/prompts/workspace.md

@@ -0,0 +1,22 @@
+You are running the GSD **workspace** workflow — manage isolated workspace environments for parallel or experimental work.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workspace is an isolated environment backed by a git worktree. Map workspace actions onto worktrees:
+
+- **--list / list** (default): show all worktrees with state (current, merged, clean, dirty) — `/gsd worktree list`.
+- **--remove <name>**: remove a worktree — `/gsd worktree remove`.
+- **--merge <name>**: merge a worktree — `/gsd worktree merge`.
+- **--clean / clean**: clean stale worktree records — `/gsd worktree clean`.
+
+Route every structural action to `/gsd worktree` rather than hand-managing git worktrees.
+
+## Success criteria
+
+- Listing reflects canonical worktree state.
+- Structural actions route to `/gsd worktree`, keeping state canonical.
+- Removing a dirty worktree is guarded (confirm first).

package/src/resources/extensions/gsd/prompts/workstreams.md

@@ -0,0 +1,24 @@
+You are running the GSD **workstreams** workflow — manage parallel workstreams that run multiple milestones concurrently with isolation.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workstream is a parallel worker running its own milestone in its own branch/worktree. Map workstream actions onto parallel workers:
+
+- **list / status** (default): show all parallel workers — milestone, branch/worktree, progress, state (running/paused/done/failed).
+- **create / start**: start parallel workers for all eligible milestones (`/gsd parallel start`). Does not accept a milestone target; use `/gsd parallel start` directly to start all eligible milestones.
+- **switch**: focus the dashboard on the most active worker (`/gsd parallel watch`). Does not accept a milestone target; use `/gsd parallel watch` directly to monitor workers.
+- **progress**: show all workers' progress (`/gsd parallel status`). Does not accept a milestone target; use `/gsd parallel status` directly for worker status.
+- **pause / resume <milestone>**: pause or resume a worker (`/gsd parallel pause|resume`).
+- **complete <milestone>**: complete and merge a worker's milestone (`/gsd parallel merge`).
+
+Route every structural action to `/gsd parallel <subcommand>` rather than reimplementing worktree/merge logic.
+
+## Success criteria
+
+- Status reflects canonical parallel-worker state.
+- Structural actions route to `/gsd parallel`, not duplicates.
+- Unknown milestones list the valid options rather than failing silently.

package/src/resources/extensions/gsd/provider-error-guidance.ts

@@ -1,7 +1,10 @@
 /**
  * Actionable remediation hints when auto-mode pauses on provider/model errors.
+ * Render with formatGuidance from the Guidance module.
  */
 
+import type { Guidance } from "./guidance.js";
+
 export interface ProviderErrorGuidanceInput {
   errorMsg: string;
   provider?: string;
@@ -12,10 +15,7 @@ export interface ProviderErrorGuidanceInput {
   hasConfiguredFallbacks?: boolean;
 }
 
-export interface ProviderErrorGuidance {
-  summary: string;
-  steps: string[];
-}
+export type ProviderErrorGuidance = Guidance;
 
 /** Map auto unit types to the `models:` key in PREFERENCES.md. */
 export function unitTypeToPrefsPhaseKey(unitType: string | undefined): string | undefined {
@@ -60,6 +60,34 @@ function defaultAlternateModel(provider: string | undefined, modelId: string | u
   return undefined;
 }
 
+function isGeminiCliDeprecatedError(errorMsg: string): boolean {
+  return (
+    /IneligibleTierError/i.test(errorMsg)
+    || /UNSUPPORTED_CLIENT/i.test(errorMsg)
+    || /no longer supported for Gemini Code Assist for individuals/i.test(errorMsg)
+    || /migrate to the Antigravity suite/i.test(errorMsg)
+  );
+}
+
+function resolveGeminiCliDeprecationGuidance(input: ProviderErrorGuidanceInput): ProviderErrorGuidance {
+  const { provider, modelId, unitType } = input;
+  const modelLabel =
+    provider && modelId ? `${provider}/${modelId}` : modelId ?? provider ?? "google-gemini-cli";
+  const unitSuffix = unitType ? ` during ${unitType}` : "";
+
+  return {
+    summary:
+      `Provider error on ${modelLabel}${unitSuffix}. ` +
+      "Google no longer supports Gemini CLI for individual-tier users — migrate to Antigravity CLI.",
+    steps: [
+      "Install Antigravity CLI: curl -fsSL https://antigravity.google/cli/install.sh | bash",
+      "Run `agy` in a terminal and complete authentication.",
+      "In GSD, run `/login` and select Antigravity, or restart GSD to auto-migrate when `agy` is on PATH.",
+      "Run /gsd next to resume the paused unit.",
+    ],
+  };
+}
+
 /**
  * Build concrete next steps for a provider/model rejection pause.
  */
@@ -73,6 +101,10 @@ export function resolveProviderErrorGuidance(input: ProviderErrorGuidanceInput):
     hasConfiguredFallbacks,
   } = input;
 
+  if (isGeminiCliDeprecatedError(errorMsg)) {
+    return resolveGeminiCliDeprecationGuidance(input);
+  }
+
   const modelLabel =
     provider && modelId ? `${provider}/${modelId}` : modelId ?? provider ?? "current model";
   const phaseKey = unitTypeToPrefsPhaseKey(unitType);
@@ -129,8 +161,3 @@ export function resolveProviderErrorGuidance(input: ProviderErrorGuidanceInput):
   return { summary, steps };
 }
 
-/** Flatten guidance into a pause banner / notification string. */
-export function formatProviderErrorGuidance(guidance: ProviderErrorGuidance): string {
-  const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
-  return `${guidance.summary}\n\n${numbered}`;
-}