gsd-antigravity-kit 1.32.0 → 2.0.0

package/.agent/skills/gsd/references/workflows/review.md

@@ -43,8 +43,28 @@ Then run /gsd-review again.
 ```
 Exit.
 
-If only one CLI is the current runtime (e.g. running inside Antigravity), skip it for the review
-to ensure independence. At least one DIFFERENT CLI must be available.
+Determine which CLI to skip based on the current runtime environment:
+
+```bash
+# Environment-based runtime detection (priority order)
+if [ "$ANTIGRAVITY_AGENT" = "1" ]; then
+  # Antigravity is a separate client — all CLIs are external, skip none
+  SELF_CLI="none"
+elif [ -n "$ANTIGRAVITY_ENTRYPOINT" ]; then
+  # Running inside Antigravity CLI — skip antigravity for independence
+  SELF_CLI="antigravity"
+else
+  # Other environments (Gemini CLI, Codex CLI, etc.)
+  # Fall back to AI self-identification to decide which CLI to skip
+  SELF_CLI="auto"
+fi
+```
+
+Rules:
+- If `SELF_CLI="none"` → invoke ALL available CLIs (no skip)
+- If `SELF_CLI="antigravity"` → skip antigravity, use gemini/codex
+- If `SELF_CLI="auto"` → the executing AI identifies itself and skips its own CLI
+- At least one DIFFERENT CLI must be available for the review to proceed.
 </step>
 
 <step name="gather_context">
@@ -128,7 +148,7 @@ gemini -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-revi
 
 **Antigravity (separate session):**
 ```bash
-antigravity -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" --no-input 2>/dev/null > /tmp/gsd-review-antigravity-{phase}.md
+antigravity -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-antigravity-{phase}.md
 ```
 
 **Codex:**

package/.agent/skills/gsd/references/workflows/scan.md

@@ -0,0 +1,102 @@
+<purpose>
+Lightweight codebase assessment. Spawns a single gsd-codebase-mapper agent for one focus area,
+producing targeted documents in `.planning/codebase/`.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-codebase-mapper — Maps project structure and dependencies
+</available_agent_types>
+
+<process>
+
+## Focus-to-Document Mapping
+
+| Focus | Documents Produced |
+|-------|-------------------|
+| `tech` | STACK.md, INTEGRATIONS.md |
+| `arch` | ARCHITECTURE.md, STRUCTURE.md |
+| `quality` | CONVENTIONS.md, TESTING.md |
+| `concerns` | CONCERNS.md |
+| `tech+arch` | STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md |
+
+## Step 1: Parse arguments and resolve focus
+
+Parse the user's input for `--focus <area>`. Default to `tech+arch` if not specified.
+
+Validate that the focus is one of: `tech`, `arch`, `quality`, `concerns`, `tech+arch`.
+
+If invalid:
+```
+Unknown focus area: "{input}". Valid options: tech, arch, quality, concerns, tech+arch
+```
+Exit.
+
+## Step 2: Check for existing documents
+
+```bash
+.agent/skills/gsd/bin/gsd-tools.cjs" init map-codebase 2>/dev/null || echo "{}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Look up which documents would be produced for the selected focus (from the mapping table above).
+
+For each target document, check if it already exists in `.planning/codebase/`:
+```bash
+ls -la .planning/codebase/{DOCUMENT}.md 2>/dev/null
+```
+
+If any exist, show their modification dates and ask:
+```
+Existing documents found:
+  - STACK.md (modified 2026-04-03)
+  - INTEGRATIONS.md (modified 2026-04-01)
+
+Overwrite with fresh scan? [y/N]
+```
+
+If user says no, exit.
+
+## Step 3: Create output directory
+
+```bash
+mkdir -p .planning/codebase
+```
+
+## Step 4: Spawn mapper agent
+
+Spawn a single `gsd-codebase-mapper` agent with the selected focus area:
+
+```
+Task(
+  prompt="Scan this codebase with focus: {focus}. Write results to .planning/codebase/. Produce only: {document_list}",
+  subagent_type="gsd-codebase-mapper",
+  model="{resolved_model}"
+)
+```
+
+## Step 5: Report
+
+```
+## Scan Complete
+
+**Focus:** {focus}
+**Documents produced:**
+{list of documents written with line counts}
+
+Use `/gsd-map-codebase` for a comprehensive 4-area parallel scan.
+```
+
+</process>
+
+<success_criteria>
+- [ ] Focus area correctly parsed (default: tech+arch)
+- [ ] Existing documents detected with modification dates shown
+- [ ] User prompted before overwriting
+- [ ] Single mapper agent spawned with correct focus
+- [ ] Output documents written to .planning/codebase/
+</success_criteria>

package/.agent/skills/gsd/references/workflows/settings.md

@@ -174,7 +174,7 @@ Merge new settings into existing config.json:
 ```json
 {
   ...existing_config,
-  "model_profile": "quality" | "balanced" | "budget" | "inherit",
+  "model_profile": "quality" | "balanced" | "budget" | "adaptive" | "inherit",
   "workflow": {
     "research": true/false,
     "plan_check": true/false,

package/.agent/skills/gsd/references/workflows/ui-review.md

@@ -140,8 +140,8 @@ Full review: {path to UI-REVIEW.md}
 
 `/clear` then one of:
 
-- `/gsd:verify-work {N}` — UAT testing
-- `/gsd:plan-phase {N+1}` — plan next phase
+- `/gsd-verify-work {N}` — UAT testing
+- `/gsd-plan-phase {N+1}` — plan next phase
 
 - `/gsd-verify-work {N}` — UAT testing
 - `/gsd-plan-phase {N+1}` — plan next phase

package/.agent/skills/gsd/references/workflows/undo.md

@@ -0,0 +1,312 @@
+<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>
+@references/docs/ui-brand.md
+@references/docs/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
+```
+
+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
+
+**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>

package/.agent/skills/gsd/references/workflows/update.md

@@ -66,7 +66,7 @@ if [ -z "$PREFERRED_RUNTIME" ]; then
     PREFERRED_RUNTIME="kilo"
   elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
     PREFERRED_RUNTIME="opencode"
-  elif [ -n "$CLAUDE_CONFIG_DIR" ]; then
+  elif [ -n "$ANTIGRAVITY_CONFIG_DIR" ]; then
     PREFERRED_RUNTIME="antigravity"
   else
     PREFERRED_RUNTIME="antigravity"
@@ -99,8 +99,8 @@ if [ -n "$PREFERRED_CONFIG_DIR" ] && { [ -f "$PREFERRED_CONFIG_DIR/get-shit-done
 fi
 
 # Absolute global candidates from env overrides (covers custom config dirs).
-if [ -n "$CLAUDE_CONFIG_DIR" ]; then
-  ENV_RUNTIME_DIRS+=( "antigravity:$(expand_home "$CLAUDE_CONFIG_DIR")" )
+if [ -n "$ANTIGRAVITY_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "antigravity:$(expand_home "$ANTIGRAVITY_CONFIG_DIR")" )
 fi
 if [ -n "$GEMINI_CONFIG_DIR" ]; then
   ENV_RUNTIME_DIRS+=( "gemini:$(expand_home "$GEMINI_CONFIG_DIR")" )
@@ -390,8 +390,8 @@ CACHE_DIRS=()
 if [ -n "$PREFERRED_CONFIG_DIR" ]; then
   CACHE_DIRS+=( "$(expand_home "$PREFERRED_CONFIG_DIR")" )
 fi
-if [ -n "$CLAUDE_CONFIG_DIR" ]; then
-  CACHE_DIRS+=( "$(expand_home "$CLAUDE_CONFIG_DIR")" )
+if [ -n "$ANTIGRAVITY_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$ANTIGRAVITY_CONFIG_DIR")" )
 fi
 if [ -n "$GEMINI_CONFIG_DIR" ]; then
   CACHE_DIRS+=( "$(expand_home "$GEMINI_CONFIG_DIR")" )

package/.agent/skills/gsd-converter/SKILL.md

@@ -1,59 +1,67 @@
----
-name: gsd-converter
-version: 1.27.0
-description: "A tool for converting standard GSD (Get Shit Done) installations into the Antigravity Skill format. Use this skill when you want to migrate `.claude/gsd` commands, agents, and templates into a portable, spec-driven skill structure for Claude Code."
----
-
-# GSD to Antigravity Skill Converter
-
-This skill provides the logic and resources to package a locally installed GSD system into a structured Antigravity Skill.
-
-## Why Convert?
-1. **Portability**: Skills can be shared and loaded across different projects more easily than local `.claude` commands.
-2. **Spec-Driven**: Leverages the Antigravity spec-driven coding system for better reliability.
-3. **Organized**: Separates commands, documentation, workflows, and templates into clear directories.
-
-## Conversion Workflow
-
-1. **Cleanup**: Deletes existing `.agent/skills/gsd/` folder to ensure a clean slate.
-
-2. **Installation**: Runs `npx get-shit-done-cc --claude --local --force-statusline` to fetch/refresh the source files in `.claude/`.
-
-3. **Detection**: The skill locates the fresh GSD files:
-   - Commands: `.claude/commands/gsd/`
-   - Docs/Workflows: `.claude/get-shit-done/`
-   - Agents: `.claude/agents/`
-
-4. **Initialization**: Re-creates the target skill structure in `.agent/skills/gsd/`.
-
-5. **Migration**:
-   - Copies command markdown files to `references/commands/`.
-   - Copies reference docs to `references/docs/`.
-   - Copies workflows to `references/workflows/`.
-   - Copies agents to `references/agents/`.
-   - Copies templates to `assets/templates/`.
-
-6. **Refactoring**:
-   - Rewrites file inclusion paths (e.g., `@./.claude/...`) to the new skill-relative format (e.g., `@references/...`).
-   - Updates `Task()` prompt paths for subagents.
-   - **Rebranding**: Automatically converts "Claude" and "Claude Code" mentions to "Antigravity" throughout all migrated files.
-
-7. **Optimization & Enhancement** (gsd-tools.cjs):
-    - Runs `optimize-gsd-tools.cjs` to apply DRY refactoring and **injection of advanced features**:
-      - Converts 4-space indentation to 2-space + LF line endings (~25KB savings).
-      - Condenses the 124-line header comment to 12 lines.
-      - **Injected Feature: Smart Inclusions**: Adds `parseIncludeFlag()`, `applyIncludes()`, and `buildPhaseBase()` to handle the `--include` flag.
-      - **Injected Feature: Artifact Discovery**: Adds `discoverPhaseArtifacts()` for automated lookup of phase documents.
-      - **Injected Feature: Model Profiles**: Adds `MODEL_PROFILES` for optimized model selection.
-      - Refactors existing commands to utilize these new helper functions.
-
-8. **Packaging**: Generates a comprehensive `SKILL.md` using the `assets/gsd_skill_template.md` template, ensuring compliance with skill-developer best practices.
-
-## Usage
-
-Run the conversion script:
-```bash
-python .agent/skills/gsd-converter/scripts/convert.py <target-skill-name>
-```
-
-Refer to `references/mapping.md` for details on how paths are translated.
+---
+name: gsd-converter
+version: 1.35.0
+description: "A tool for converting standard GSD (Get Shit Done) installations into the Antigravity Skill format. Use this skill when you want to migrate `.claude/gsd` commands, agents, and templates into a portable, spec-driven skill structure for Claude Code."
+---
+
+# GSD to Antigravity Skill Converter
+
+This skill provides the logic and resources to package a locally installed GSD system into a structured Antigravity Skill.
+
+## Why Convert?
+1. **Portability**: Skills can be shared and loaded across different projects more easily than local `.claude` commands.
+2. **Spec-Driven**: Leverages the Antigravity spec-driven coding system for better reliability.
+3. **Organized**: Separates commands, documentation, workflows, and templates into clear directories.
+
+## Conversion Workflow
+
+1. **Detection & Audit**: 
+   - Scans `.claude/` for directories and identifies components vs. unmapped folders.
+   - Audits the internal `mappings` list against the documented `mapping.md` spec to ensure synchronization.
+
+2. **Cleanup**: Deletes existing `.agent/skills/gsd/` folder to ensure a clean slate.
+
+3. **Installation**: Runs `npx get-shit-done-cc --claude --local --force-statusline` to fetch/refresh the source files in `.claude/`.
+
+4. **Detection**: The skill locates the fresh GSD files:
+   - Commands: `.claude/commands/gsd/`
+   - Docs/Workflows: `.claude/get-shit-done/`
+   - Agents: `.claude/agents/`
+
+5. **Initialization**: Re-creates the target skill structure in `.agent/skills/gsd/`.
+
+6. **Migration**:
+   - Copies command markdown files to `references/commands/`.
+   - Copies reference docs to `references/docs/`.
+   - Copies workflows to `references/workflows/`.
+   - Copies agents to `references/agents/`.
+   - Copies templates to `assets/templates/`.
+
+7. **Refactoring**:
+   - Rewrites file inclusion paths (e.g., `@./.claude/...`) to the new skill-relative format (e.g., `@references/...`).
+   - Updates `Task()` prompt paths for subagents.
+   - **Rebranding**: Automatically converts "Claude" and "Claude Code" mentions to "Antigravity" throughout all migrated files.
+
+8. **Optimization & Enhancement** (gsd-tools.cjs):
+    - Runs `optimize-gsd-tools.cjs` to apply DRY refactoring and **injection of advanced features**:
+      - Converts 4-space indentation to 2-space + LF line endings (~25KB savings).
+      - Condenses the 124-line header comment to 12 lines.
+      - **Injected Feature: Smart Inclusions**: Adds `parseIncludeFlag()`, `applyIncludes()`, and `buildPhaseBase()` to handle the `--include` flag.
+      - **Injected Feature: Artifact Discovery**: Adds `discoverPhaseArtifacts()` for automated lookup of phase documents.
+      - **Injected Feature: Model Profiles**: Adds `MODEL_PROFILES` for optimized model selection.
+      - Refactors existing commands to utilize these new helper functions.
+
+9. **Verification**: 
+    - Performs a pre-flight integrity check on the migrated skill (help manifest, router logic, command presence).
+    - Generates a `migration_report.md` artifact in the target skill folder.
+
+10. **Packaging**: Generates a comprehensive `SKILL.md` using the `assets/gsd_skill_template.md` template, ensuring compliance with skill-developer best practices.
+
+## Usage
+
+Run the conversion script:
+```bash
+python .agent/skills/gsd-converter/scripts/convert.py <target-skill-name>
+```
+
+Refer to `references/mapping.md` for details on how paths are translated.