gsd-antigravity-kit 2.0.0 → 2.1.0

package/.agent/skills/gsd/references/workflows/diagnose-issues.md

@@ -1,238 +1,238 @@
-<purpose>
-Orchestrate parallel debug agents to investigate UAT gaps and find root causes.
-
-After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses.
-
-Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT.
-</purpose>
-
-<available_agent_types>
-Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
-- gsd-debugger — Diagnoses and fixes issues
-</available_agent_types>
-
-<paths>
-DEBUG_DIR=.planning/debug
-
-Debug files use the `.planning/debug/` path (hidden directory with leading dot).
-</paths>
-
-<core_principle>
-**Diagnose before planning fixes.**
-
-UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-phase --gaps then creates targeted fixes based on actual causes, not guesses.
-
-Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong
-With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix
-</core_principle>
-
-<process>
-
-<step name="parse_gaps">
-**Extract gaps from UAT.md:**
-
-Read the "Gaps" section (YAML format):
-```yaml
-- truth: "Comment appears immediately after submission"
-  status: failed
-  reason: "User reported: works but doesn't show until I refresh the page"
-  severity: major
-  test: 2
-  artifacts: []
-  missing: []
-```
-
-For each gap, also read the corresponding test from "Tests" section to get full context.
-
-Build gap list:
-```
-gaps = [
-  {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
-  {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
-  ...
-]
-```
-</step>
-
-<step name="report_plan">
-**Read worktree config:**
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" config-get workflow.use_worktrees 2>/dev/null || echo "true")
-```
-
-**Report diagnosis plan to user:**
-
-```
-## Diagnosing {N} Gaps
-
-Spawning parallel debug agents to investigate root causes:
-
-| Gap (Truth) | Severity |
-|-------------|----------|
-| Comment appears immediately after submission | major |
-| Reply button positioned correctly | minor |
-| Delete removes comment | blocker |
-
-Each agent will:
-1. Create DEBUG-{slug}.md with symptoms pre-filled
-2. Investigate autonomously (read code, form hypotheses, test)
-3. Return root cause
-
-This runs in parallel - all gaps investigated simultaneously.
-```
-</step>
-
-<step name="spawn_agents">
-**Load agent skills:**
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" agent-skills gsd-debugger 2>/dev/null)
-EXPECTED_BASE=$(git rev-parse HEAD)
-```
-
-**Spawn debug agents in parallel:**
-
-For each gap, fill the debug-subagent-prompt template and spawn:
-
-```
-Task(
-  prompt=filled_debug_subagent_prompt + "\n\n<worktree_branch_check>\nFIRST ACTION: run git merge-base HEAD {EXPECTED_BASE} — if result differs from {EXPECTED_BASE}, run git reset --soft {EXPECTED_BASE} to correct the branch base (fixes Windows EnterWorktree creating branches from main).\n</worktree_branch_check>\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>\n${AGENT_SKILLS_DEBUGGER}",
-  subagent_type="gsd-debugger",
-  ${USE_WORKTREES !== "false" ? 'isolation="worktree",' : ''}
-  description="Debug: {truth_short}"
-)
-```
-
-**All agents spawn in single message** (parallel execution).
-
-Template placeholders:
-- `{truth}`: The expected behavior that failed
-- `{expected}`: From UAT test
-- `{actual}`: Verbatim user description from reason field
-- `{errors}`: Any error messages from UAT (or "None reported")
-- `{reproduction}`: "Test {test_num} in UAT"
-- `{timeline}`: "Discovered during UAT"
-- `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
-- `{slug}`: Generated from truth
-</step>
-
-<step name="collect_results">
-**Collect root causes from agents:**
-
-Each agent returns with:
-```
-## ROOT CAUSE FOUND
-
-**Debug Session:** ${DEBUG_DIR}/{slug}.md
-
-**Root Cause:** {specific cause with evidence}
-
-**Evidence Summary:**
-- {key finding 1}
-- {key finding 2}
-- {key finding 3}
-
-**Files Involved:**
-- {file1}: {what's wrong}
-- {file2}: {related issue}
-
-**Suggested Fix Direction:** {brief hint for plan-phase --gaps}
-```
-
-Parse each return to extract:
-- root_cause: The diagnosed cause
-- files: Files involved
-- debug_path: Path to debug session file
-- suggested_fix: Hint for gap closure plan
-
-If agent returns `## INVESTIGATION INCONCLUSIVE`:
-- root_cause: "Investigation inconclusive - manual review needed"
-- Note which issue needs manual attention
-- Include remaining possibilities from agent return
-</step>
-
-<step name="update_uat">
-**Update UAT.md gaps with diagnosis:**
-
-For each gap in the Gaps section, add artifacts and missing fields:
-
-```yaml
-- truth: "Comment appears immediately after submission"
-  status: failed
-  reason: "User reported: works but doesn't show until I refresh the page"
-  severity: major
-  test: 2
-  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
-  artifacts:
-    - path: "src/components/CommentList.tsx"
-      issue: "useEffect missing dependency"
-  missing:
-    - "Add commentCount to useEffect dependency array"
-    - "Trigger re-render when new comment added"
-  debug_session: .planning/debug/comment-not-refreshing.md
-```
-
-Update status in frontmatter to "diagnosed".
-
-Commit the updated UAT.md:
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs({phase_num}): add root causes from diagnosis" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
-```
-</step>
-
-<step name="report_results">
-**Report diagnosis results and hand off:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► DIAGNOSIS COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-| Gap (Truth) | Root Cause | Files |
-|-------------|------------|-------|
-| Comment appears immediately | useEffect missing dependency | CommentList.tsx |
-| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
-| Delete removes comment | API missing auth header | api/comments.ts |
-
-Debug sessions: ${DEBUG_DIR}/
-
-Proceeding to plan fixes...
-```
-
-Return to verify-work orchestrator for automatic planning.
-Do NOT offer manual next steps - verify-work handles the rest.
-</step>
-
-</process>
-
-<context_efficiency>
-Agents start with symptoms pre-filled from UAT (no symptom gathering).
-Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
-</context_efficiency>
-
-<failure_handling>
-**Agent fails to find root cause:**
-- Mark gap as "needs manual review"
-- Continue with other gaps
-- Report incomplete diagnosis
-
-**Agent times out:**
-- Check DEBUG-{slug}.md for partial progress
-- Can resume with /gsd-debug
-
-**All agents fail:**
-- Something systemic (permissions, git, etc.)
-- Report for manual investigation
-- Fall back to plan-phase --gaps without root causes (less precise)
-</failure_handling>
-
-<success_criteria>
-- [ ] Gaps parsed from UAT.md
-- [ ] Debug agents spawned in parallel
-- [ ] Root causes collected from all agents
-- [ ] UAT.md gaps updated with artifacts and missing
-- [ ] Debug sessions saved to ${DEBUG_DIR}/
-- [ ] Hand off to verify-work for automatic planning
-</success_criteria>
+<purpose>
+Orchestrate parallel debug agents to investigate UAT gaps and find root causes.
+
+After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses.
+
+Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT.
+</purpose>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-debugger — Diagnoses and fixes issues
+</available_agent_types>
+
+<paths>
+DEBUG_DIR=.planning/debug
+
+Debug files use the `.planning/debug/` path (hidden directory with leading dot).
+</paths>
+
+<core_principle>
+**Diagnose before planning fixes.**
+
+UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-phase --gaps then creates targeted fixes based on actual causes, not guesses.
+
+Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong
+With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix
+</core_principle>
+
+<process>
+
+<step name="parse_gaps">
+**Extract gaps from UAT.md:**
+
+Read the "Gaps" section (YAML format):
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  artifacts: []
+  missing: []
+```
+
+For each gap, also read the corresponding test from "Tests" section to get full context.
+
+Build gap list:
+```
+gaps = [
+  {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
+  {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
+  ...
+]
+```
+</step>
+
+<step name="report_plan">
+**Read worktree config:**
+
+```bash
+USE_WORKTREES=$(gsd-sdk query config-get workflow.use_worktrees 2>/dev/null || echo "true")
+```
+
+**Report diagnosis plan to user:**
+
+```
+## Diagnosing {N} Gaps
+
+Spawning parallel debug agents to investigate root causes:
+
+| Gap (Truth) | Severity |
+|-------------|----------|
+| Comment appears immediately after submission | major |
+| Reply button positioned correctly | minor |
+| Delete removes comment | blocker |
+
+Each agent will:
+1. Create DEBUG-{slug}.md with symptoms pre-filled
+2. Investigate autonomously (read code, form hypotheses, test)
+3. Return root cause
+
+This runs in parallel - all gaps investigated simultaneously.
+```
+</step>
+
+<step name="spawn_agents">
+**Load agent skills:**
+
+```bash
+AGENT_SKILLS_DEBUGGER=$(gsd-sdk query agent-skills gsd-debugger 2>/dev/null)
+EXPECTED_BASE=$(git rev-parse HEAD)
+```
+
+**Spawn debug agents in parallel:**
+
+For each gap, fill the debug-subagent-prompt template and spawn:
+
+```
+Task(
+  prompt=filled_debug_subagent_prompt + "\n\n<worktree_branch_check>\nFIRST ACTION: run git merge-base HEAD {EXPECTED_BASE} — if result differs from {EXPECTED_BASE}, run git reset --hard {EXPECTED_BASE} to correct the branch base (safe — runs before any agent work). Then verify: if [ \"$(git rev-parse HEAD)\" != \"{EXPECTED_BASE}\" ]; then echo \"ERROR: Could not correct worktree base\"; exit 1; fi. Fixes EnterWorktree creating branches from main on all platforms.\n</worktree_branch_check>\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>\n${AGENT_SKILLS_DEBUGGER}",
+  subagent_type="gsd-debugger",
+  ${USE_WORKTREES !== "false" ? 'isolation="worktree",' : ''}
+  description="Debug: {truth_short}"
+)
+```
+
+**All agents spawn in single message** (parallel execution).
+
+Template placeholders:
+- `{truth}`: The expected behavior that failed
+- `{expected}`: From UAT test
+- `{actual}`: Verbatim user description from reason field
+- `{errors}`: Any error messages from UAT (or "None reported")
+- `{reproduction}`: "Test {test_num} in UAT"
+- `{timeline}`: "Discovered during UAT"
+- `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
+- `{slug}`: Generated from truth
+</step>
+
+<step name="collect_results">
+**Collect root causes from agents:**
+
+Each agent returns with:
+```
+## ROOT CAUSE FOUND
+
+**Debug Session:** ${DEBUG_DIR}/{slug}.md
+
+**Root Cause:** {specific cause with evidence}
+
+**Evidence Summary:**
+- {key finding 1}
+- {key finding 2}
+- {key finding 3}
+
+**Files Involved:**
+- {file1}: {what's wrong}
+- {file2}: {related issue}
+
+**Suggested Fix Direction:** {brief hint for plan-phase --gaps}
+```
+
+Parse each return to extract:
+- root_cause: The diagnosed cause
+- files: Files involved
+- debug_path: Path to debug session file
+- suggested_fix: Hint for gap closure plan
+
+If agent returns `## INVESTIGATION INCONCLUSIVE`:
+- root_cause: "Investigation inconclusive - manual review needed"
+- Note which issue needs manual attention
+- Include remaining possibilities from agent return
+</step>
+
+<step name="update_uat">
+**Update UAT.md gaps with diagnosis:**
+
+For each gap in the Gaps section, add artifacts and missing fields:
+
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+    - "Trigger re-render when new comment added"
+  debug_session: .planning/debug/comment-not-refreshing.md
+```
+
+Update status in frontmatter to "diagnosed".
+
+Commit the updated UAT.md:
+```bash
+gsd-sdk query commit "docs({phase_num}): add root causes from diagnosis" ".planning/phases/XX-name/{phase_num}-UAT.md"
+```
+</step>
+
+<step name="report_results">
+**Report diagnosis results and hand off:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► DIAGNOSIS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Gap (Truth) | Root Cause | Files |
+|-------------|------------|-------|
+| Comment appears immediately | useEffect missing dependency | CommentList.tsx |
+| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
+| Delete removes comment | API missing auth header | api/comments.ts |
+
+Debug sessions: ${DEBUG_DIR}/
+
+Proceeding to plan fixes...
+```
+
+Return to verify-work orchestrator for automatic planning.
+Do NOT offer manual next steps - verify-work handles the rest.
+</step>
+
+</process>
+
+<context_efficiency>
+Agents start with symptoms pre-filled from UAT (no symptom gathering).
+Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
+</context_efficiency>
+
+<failure_handling>
+**Agent fails to find root cause:**
+- Mark gap as "needs manual review"
+- Continue with other gaps
+- Report incomplete diagnosis
+
+**Agent times out:**
+- Check DEBUG-{slug}.md for partial progress
+- Can resume with /gsd-debug
+
+**All agents fail:**
+- Something systemic (permissions, git, etc.)
+- Report for manual investigation
+- Fall back to plan-phase --gaps without root causes (less precise)
+</failure_handling>
+
+<success_criteria>
+- [ ] Gaps parsed from UAT.md
+- [ ] Debug agents spawned in parallel
+- [ ] Root causes collected from all agents
+- [ ] UAT.md gaps updated with artifacts and missing
+- [ ] Debug sessions saved to ${DEBUG_DIR}/
+- [ ] Hand off to verify-work for automatic planning
+</success_criteria>

package/.agent/skills/gsd/references/workflows/discovery-phase.md

@@ -214,6 +214,8 @@ Write `.planning/phases/XX-name/DISCOVERY.md`:
 After creating DISCOVERY.md, check confidence level.
 
 If confidence is LOW:
+
+**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-Antigravity runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 Use AskUserQuestion:
 
 - header: "Low Conf."

package/.agent/skills/gsd/references/workflows/discuss-phase-assumptions.md

@@ -64,9 +64,9 @@ plain-text numbered list and ask the user to type their choice number.
 Phase number from argument (required).
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" init phase-op "${PHASE}")
+INIT=$(gsd-sdk query init.phase-op "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-.agent/skills/gsd/bin/gsd-tools.cjs" agent-skills gsd-assumptions-analyzer 2>/dev/null)
+AGENT_SKILLS_ANALYZER=$(gsd-sdk query agent-skills gsd-assumptions-analyzer 2>/dev/null)
 ```
 
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`,
@@ -171,7 +171,7 @@ Structure the extracted information for use in assumption generation.
 Check if any pending todos are relevant to this phase's scope.
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" todo match-phase "${PHASE_NUMBER}")
+TODO_MATCHES=$(gsd-sdk query todo.match-phase "${PHASE_NUMBER}")
 ```
 
 Parse JSON for: `todo_count`, `matches[]`.
@@ -548,7 +548,7 @@ Write file.
 Commit phase context and discussion log:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context (assumptions mode)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
+gsd-sdk query commit "docs(${padded_phase}): capture phase context (assumptions mode)" "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
 ```
 
 Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions mode)"
@@ -558,7 +558,7 @@ Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions m
 Update STATE.md with session info:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" state record-session \
+gsd-sdk query state.record-session \
   --stopped-at "Phase ${PHASE} context gathered (assumptions mode)" \
   --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
@@ -566,7 +566,7 @@ Update STATE.md with session info:
 Commit STATE.md:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
+gsd-sdk query commit "docs(state): record phase ${PHASE} context session" .planning/STATE.md
 ```
 </step>
 
@@ -593,7 +593,7 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase ${PHASE}: {phase_name}** — {Goal from ROADMAP.md}
 
@@ -619,18 +619,18 @@ Check for auto-advance trigger:
 2. Sync chain flag:
    ```bash
    if [[ ! "$ARGUMENTS" =~ --auto ]]; then
-.agent/skills/gsd/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
+     gsd-sdk query config-set workflow._auto_chain_active false 2>/dev/null
    fi
    ```
 3. Read chain flag and user preference:
    ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-.agent/skills/gsd/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
+   AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
+   AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
    ```
 
 **If `--auto` flag present AND `AUTO_CHAIN` is not true:**
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" config-set workflow._auto_chain_active true
+gsd-sdk query config-set workflow._auto_chain_active true
 ```
 
 **If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**