gsd-antigravity-kit 2.0.0 → 2.1.0

package/.agent/skills/gsd/references/docs/sketch-variant-patterns.md

@@ -0,0 +1,81 @@
+# Multi-Variant HTML Patterns
+
+Every sketch produces 2-3 variants in the same HTML file. The user switches between them to compare.
+
+## Tab-Based Variants
+
+The standard approach: a tab bar at the top of the page, each tab shows a different variant.
+
+```html
+<div id="variant-nav" style="position:fixed;top:0;left:0;right:0;z-index:9998;background:var(--color-surface, #fff);border-bottom:1px solid var(--color-border, #e5e5e5);padding:8px 16px;display:flex;gap:8px;font-family:system-ui;">
+  <button class="variant-tab active" onclick="showVariant('a')">A: Sidebar Layout</button>
+  <button class="variant-tab" onclick="showVariant('b')">B: Top Nav</button>
+  <button class="variant-tab" onclick="showVariant('c')">C: Floating Panels</button>
+</div>
+
+<div id="variant-a" class="variant active">
+  <!-- Variant A content -->
+</div>
+<div id="variant-b" class="variant" style="display:none">
+  <!-- Variant B content -->
+</div>
+<div id="variant-c" class="variant" style="display:none">
+  <!-- Variant C content -->
+</div>
+
+<script>
+function showVariant(id) {
+  document.querySelectorAll('.variant').forEach(v => v.style.display = 'none');
+  document.querySelectorAll('.variant-tab').forEach(t => t.classList.remove('active'));
+  document.getElementById('variant-' + id).style.display = 'block';
+  event.target.classList.add('active');
+}
+</script>
+```
+
+Add `padding-top` to the body to account for the fixed tab bar.
+
+## Marking the Winner
+
+After the user picks a direction, add a visual indicator to the winning tab:
+
+```html
+<button class="variant-tab active">A: Sidebar Layout ★ Selected</button>
+```
+
+Keep all variants visible and navigable — the winner is highlighted, not the only option.
+
+## Side-by-Side (for small variants)
+
+When comparing small elements (button styles, card layouts, icon treatments), render them next to each other with labels rather than using tabs:
+
+```html
+<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:24px;padding:24px;">
+  <div>
+    <h3>A: Rounded</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>B: Sharp</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>C: Pill</h3>
+    <!-- variant content -->
+  </div>
+</div>
+```
+
+## Variant Count
+
+- **First round (dramatic):** 2-3 meaningfully different approaches
+- **Refinement rounds:** 2-3 subtle variations within the chosen direction
+- **Never more than 4** — more than that overwhelms. If there are 5+ options, narrow before showing.
+
+## Synthesis Variants
+
+When the user cherry-picks elements across variants, create a new variant tab labeled descriptively:
+
+```html
+<button class="variant-tab" onclick="showVariant('synth1')">Synthesis: A's layout + C's palette</button>
+```

package/.agent/skills/gsd/references/docs/tdd.md

@@ -247,6 +247,73 @@ Both follow same format: `{type}({phase}-{plan}): {description}`
 - Consistent with overall commit strategy
 </commit_pattern>
 
+<gate_enforcement>
+## Gate Enforcement Rules
+
+When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate sequence is enforced for all `type: tdd` plans.
+
+### Gate Definitions
+
+| Gate | Required | Commit Pattern | Validation |
+|------|----------|---------------|------------|
+| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation |
+| GREEN | Yes | `feat({phase}-{plan}): ...` | Test passes after implementation |
+| REFACTOR | No | `refactor({phase}-{plan}): ...` | Tests still pass after cleanup |
+
+### Fail-Fast Rules
+
+1. **Unexpected GREEN in RED phase:** If the test passes before any implementation code is written, STOP. The feature may already exist or the test is wrong. Investigate before proceeding.
+2. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
+3. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
+
+### Executor Gate Validation
+
+After completing a `type: tdd` plan, the executor validates the git log:
+```bash
+# Check for RED gate commit
+git log --oneline --grep="^test(${PHASE}-${PLAN})" | head -1
+# Check for GREEN gate commit  
+git log --oneline --grep="^feat(${PHASE}-${PLAN})" | head -1
+# Check for optional REFACTOR gate commit
+git log --oneline --grep="^refactor(${PHASE}-${PLAN})" | head -1
+```
+
+If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
+</gate_enforcement>
+
+<end_of_phase_review>
+## End-of-Phase TDD Review Checkpoint
+
+When `workflow.tdd_mode` is enabled, the execute-phase orchestrator inserts a collaborative review checkpoint after all waves complete but before phase verification.
+
+### Review Checkpoint Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ TDD REVIEW — Phase {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TDD Plans: {count} | Gate violations: {count}
+
+| Plan | RED | GREEN | REFACTOR | Status |
+|------|-----|-------|----------|--------|
+| {id} |  ✓  |   ✓   |    ✓     | Pass   |
+| {id} |  ✓  |   ✗   |    —     | FAIL   |
+
+{If violations exist:}
+⚠ Gate violations are advisory — review before advancing.
+```
+
+### What the Review Checks
+
+1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order
+2. **Test quality:** RED phase tests fail for the right reason (not import errors or syntax)
+3. **Minimal GREEN:** Implementation is minimal — no premature optimization in GREEN phase
+4. **Refactor discipline:** If REFACTOR commit exists, tests still pass
+
+This checkpoint is advisory — it does not block phase completion but surfaces TDD discipline issues for human review.
+</end_of_phase_review>
+
 <context_budget>
 ## Context Budget
 

package/.agent/skills/gsd/references/docs/universal-anti-patterns.md

@@ -56,3 +56,8 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
 26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
 27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
+
+## iOS / Apple Platform Rules
+
+28. **NEVER use `Package.swift` + `.executableTarget` (or `.target`) as the primary build system for iOS apps.** SPM executable targets produce macOS CLI binaries, not iOS `.app` bundles. They cannot be installed on iOS devices or submitted to the App Store. Use XcodeGen (`project.yml` + `xcodegen generate`) to create a proper `.xcodeproj`. See `references/ios-scaffold.md` for the full pattern.
+29. **Verify SwiftUI API availability before use.** Many SwiftUI APIs require a specific minimum iOS version (e.g., `NavigationSplitView` is iOS 16+, `List(selection:)` with multi-select and `@Observable` require iOS 17). If a plan uses an API that exceeds the declared `IPHONEOS_DEPLOYMENT_TARGET`, raise the deployment target or add `#available` guards.

package/.agent/skills/gsd/references/docs/workstream-flag.md

@@ -93,19 +93,19 @@ This ensures workstream scope chains automatically through the workflow:
 ## CLI Usage
 
 ```bash
-# All gsd-tools commands accept --ws
-node gsd-tools.cjs state json --ws feature-a
-node gsd-tools.cjs find-phase 3 --ws feature-b
+# All gsd-sdk query commands accept --ws
+gsd-sdk query state.json --ws feature-a
+gsd-sdk query find-phase 3 --ws feature-b
 
 # Session-local switching without --ws on every command
-GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs workstream set feature-a
-GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs state json
-GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs workstream set feature-b
-GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs state json
+GSD_SESSION_KEY=my-terminal-a gsd-sdk query workstream.set feature-a
+GSD_SESSION_KEY=my-terminal-a gsd-sdk query state.json
+GSD_SESSION_KEY=my-terminal-b gsd-sdk query workstream.set feature-b
+GSD_SESSION_KEY=my-terminal-b gsd-sdk query state.json
 
 # Workstream CRUD
-node gsd-tools.cjs workstream create <name>
-node gsd-tools.cjs workstream list
-node gsd-tools.cjs workstream status <name>
-node gsd-tools.cjs workstream complete <name>
+gsd-sdk query workstream.create <name>
+gsd-sdk query workstream.list
+gsd-sdk query workstream.status <name>
+gsd-sdk query workstream.complete <name>
 ```

package/.agent/skills/gsd/references/mapping.md

@@ -19,4 +19,4 @@ When converting from a standard GSD installation to an Antigravity Skill, paths
 References to `@.planning/` are **preserved**, as these refer to the active project's local planning directory, not the skill's own resources.
 
 ---
-*Generated by gsd-converter on 2026-04-08*
+*Generated by gsd-converter on 2026-04-18*

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

@@ -1,112 +1,112 @@
-<purpose>
-Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="parse_arguments">
-Parse the command arguments:
-- All arguments become the phase description
-- Example: `/gsd-add-phase Add authentication` → description = "Add authentication"
-- Example: `/gsd-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
-
-If no arguments provided:
-
-```
-ERROR: Phase description required
-Usage: /gsd-add-phase <description>
-Example: /gsd-add-phase Add authentication system
-```
-
-Exit.
-</step>
-
-<step name="init_context">
-Load phase operation context:
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" init phase-op "0")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Check `roadmap_exists` from init JSON. If false:
-```
-ERROR: No roadmap found (.planning/ROADMAP.md)
-Run /gsd-new-project to initialize.
-```
-Exit.
-</step>
-
-<step name="add_phase">
-**Delegate the phase addition to gsd-tools:**
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" phase add "${description}")
-```
-
-The CLI handles:
-- Finding the highest existing integer phase number
-- Calculating next phase number (max + 1)
-- Generating slug from description
-- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
-- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
-
-Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
-</step>
-
-<step name="update_project_state">
-Update STATE.md to reflect the new phase:
-
-1. Read `.planning/STATE.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {N} added: {description}
-   ```
-
-If "Roadmap Evolution" section doesn't exist, create it.
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-Phase {N} added to current milestone:
-- Description: {description}
-- Directory: .planning/phases/{phase-num}-{slug}/
-- Status: Not planned yet
-
-Roadmap updated: .planning/ROADMAP.md
-
----
-
-## ▶ Next Up
-
-**Phase {N}: {description}**
-
-`/clear` then:
-
-`/gsd-plan-phase {N}`
-
----
-
-**Also available:**
-- `/gsd-add-phase <description>` — add another phase
-- Review roadmap
-
----
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] `gsd-tools phase add` executed successfully
-- [ ] Phase directory created
-- [ ] Roadmap updated with new phase entry
-- [ ] STATE.md updated with roadmap evolution note
-- [ ] User informed of next steps
-</success_criteria>
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/gsd-add-phase Add authentication` → description = "Add authentication"
+- Example: `/gsd-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /gsd-add-phase <description>
+Example: /gsd-add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(gsd-sdk query init.phase-op "0")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /gsd-new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="add_phase">
+**Delegate the phase addition to `gsd-sdk query phase.add`:**
+
+```bash
+RESULT=$(gsd-sdk query phase.add "${description}")
+```
+
+The CLI handles:
+- Finding the highest existing integer phase number
+- Calculating next phase number (max + 1)
+- Generating slug from description
+- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
+- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: .planning/ROADMAP.md
+
+---
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Phase {N}: {description}**
+
+`/clear` then:
+
+`/gsd-plan-phase {N}`
+
+---
+
+**Also available:**
+- `/gsd-add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `gsd-sdk query phase.add` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>

package/.agent/skills/gsd/references/workflows/add-tests.md

@@ -33,7 +33,7 @@ Exit.
 Load phase operation context:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+INIT=$(gsd-sdk query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -108,6 +108,9 @@ Read each file to verify classification. Don't classify based on filename alone.
 <step name="present_classification">
 Present the classification to the user for confirmation before proceeding:
 
+
+**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.
+
 ```
 AskUserQuestion(
   header: "Test Classification",
@@ -297,7 +300,7 @@ Create a test coverage report and present to user:
 
 Record test generation in project state:
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" state-snapshot
+gsd-sdk query state-snapshot
 ```
 
 If there are passing tests to commit:
@@ -312,7 +315,7 @@ Present next steps:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 {if bugs discovered:}
 **Fix discovered bugs:** `/gsd-quick fix the {N} test failures discovered in phase ${phase_number}`

package/.agent/skills/gsd/references/workflows/add-todo.md

@@ -12,7 +12,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 Load todo context:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" init todos)
+INIT=$(gsd-sdk query init.todos)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -70,6 +70,8 @@ If potential duplicate found:
 1. Read the existing todo
 2. Compare scope
 
+
+**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.
 If overlapping, use AskUserQuestion:
 - header: "Duplicate?"
 - question: "Similar todo exists: [title]. What would you like to do?"
@@ -84,7 +86,7 @@ Use values from init context: `timestamp` and `date` are already available.
 
 Generate slug for the title:
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" generate-slug "$title" --raw)
+slug=$(gsd-sdk query generate-slug "$title" --raw)
 ```
 
 Write to `.planning/todos/pending/${date}-${slug}.md`:
@@ -119,7 +121,7 @@ If `.planning/STATE.md` exists:
 Commit the todo and any updated state:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+gsd-sdk query commit "docs: capture todo - [title]" .planning/todos/pending/[filename] .planning/STATE.md
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.