gsd-antigravity-kit 2.0.1 → 2.1.0

package/.agent/skills/gsd/references/docs/decimal-phase-calculation.md

@@ -1,64 +1,64 @@
-# Decimal Phase Calculation
-
-Calculate the next decimal phase number for urgent insertions.
-
-## Using gsd-tools
-
-```bash
-# Get next decimal phase after phase 6
-.agent/skills/gsd/bin/gsd-tools.cjs" phase next-decimal 6
-```
-
-Output:
-```json
-{
-  "found": true,
-  "base_phase": "06",
-  "next": "06.1",
-  "existing": []
-}
-```
-
-With existing decimals:
-```json
-{
-  "found": true,
-  "base_phase": "06",
-  "next": "06.3",
-  "existing": ["06.1", "06.2"]
-}
-```
-
-## Extract Values
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick next)
-.agent/skills/gsd/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick base_phase)
-```
-
-Or with --raw flag:
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
-# Returns just: 06.1
-```
-
-## Examples
-
-| Existing Phases | Next Phase |
-|-----------------|------------|
-| 06 only | 06.1 |
-| 06, 06.1 | 06.2 |
-| 06, 06.1, 06.2 | 06.3 |
-| 06, 06.1, 06.3 (gap) | 06.4 |
-
-## Directory Naming
-
-Decimal phase directories use the full decimal number:
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
-PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
-mkdir -p "$PHASE_DIR"
-```
-
-Example: `.planning/phases/06.1-fix-critical-auth-bug/`
+# Decimal Phase Calculation
+
+Calculate the next decimal phase number for urgent insertions.
+
+## Using gsd-tools
+
+```bash
+# Get next decimal phase after phase 6
+gsd-sdk query phase.next-decimal 6
+```
+
+Output:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+With existing decimals:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## Extract Values
+
+```bash
+DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
+```
+
+Or with --raw flag:
+```bash
+DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --raw)
+# Returns just: 06.1
+```
+
+## Examples
+
+| Existing Phases | Next Phase |
+|-----------------|------------|
+| 06 only | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3 (gap) | 06.4 |
+
+## Directory Naming
+
+Decimal phase directories use the full decimal number:
+
+```bash
+SLUG=$(gsd-sdk query generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+Example: `.planning/phases/06.1-fix-critical-auth-bug/`

package/.agent/skills/gsd/references/docs/executor-examples.md

@@ -0,0 +1,110 @@
+# Executor Extended Examples
+
+> Reference file for gsd-executor agent. Loaded on-demand via `@` reference.
+> For sub-200K context windows, this content is stripped from the agent prompt and available here for on-demand loading.
+
+## Deviation Rule Examples
+
+### Rule 1 — Auto-fix bugs
+
+**Examples of Rule 1 triggers:**
+- Wrong queries returning incorrect data
+- Logic errors in conditionals
+- Type errors and type mismatches
+- Null pointer exceptions / undefined access
+- Broken validation (accepts invalid input)
+- Security vulnerabilities (XSS, SQL injection)
+- Race conditions in async code
+- Memory leaks from uncleaned resources
+
+### Rule 2 — Auto-add missing critical functionality
+
+**Examples of Rule 2 triggers:**
+- Missing error handling (unhandled promise rejections, no try/catch on I/O)
+- No input validation on user-facing endpoints
+- Missing null checks before property access
+- No auth on protected routes
+- Missing authorization checks (user can access other users' data)
+- No CSRF/CORS configuration
+- No rate limiting on public endpoints
+- Missing DB indexes on frequently queried columns
+- No error logging (failures silently swallowed)
+
+### Rule 3 — Auto-fix blocking issues
+
+**Examples of Rule 3 triggers:**
+- Missing dependency not in package.json
+- Wrong types preventing compilation
+- Broken imports (wrong path, wrong export name)
+- Missing env var required at runtime
+- DB connection error (wrong URL, missing credentials)
+- Build config error (wrong entry point, missing loader)
+- Missing referenced file (import points to non-existent module)
+- Circular dependency preventing module load
+
+### Rule 4 — Ask about architectural changes
+
+**Examples of Rule 4 triggers:**
+- New DB table (not just adding a column)
+- Major schema changes (renaming tables, changing relationships)
+- New service layer (adding a queue, cache, or message bus)
+- Switching libraries/frameworks (e.g., replacing Express with Fastify)
+- Changing auth approach (switching from session to JWT)
+- New infrastructure (adding Redis, S3, etc.)
+- Breaking API changes (removing or renaming endpoints)
+
+## Edge Case Decision Guide
+
+| Scenario | Rule | Rationale |
+|----------|------|-----------|
+| Missing validation on input | Rule 2 | Security requirement |
+| Crashes on null input | Rule 1 | Bug — incorrect behavior |
+| Need new database table | Rule 4 | Architectural decision |
+| Need new column on existing table | Rule 1 or 2 | Depends on context |
+| Pre-existing linting warnings | Out of scope | Not caused by current task |
+| Unrelated test failures | Out of scope | Not caused by current task |
+
+**Decision heuristic:** "Does this affect correctness, security, or ability to complete the current task?"
+- YES → Rules 1-3 (fix automatically)
+- MAYBE → Rule 4 (ask the user)
+- NO → Out of scope (log to deferred-items.md)
+
+## Checkpoint Examples
+
+### Good checkpoint placement
+
+```xml
+<!-- Automate everything, then verify at the end -->
+<task type="auto">Create database schema</task>
+<task type="auto">Create API endpoints</task>
+<task type="auto">Create UI components</task>
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>
+    1. Visit http://localhost:3000/register
+    2. Create account with test@example.com
+    3. Log in with those credentials
+    4. Verify dashboard loads with user name
+  </how-to-verify>
+</task>
+```
+
+### Bad checkpoint placement
+
+```xml
+<!-- Too many checkpoints — causes verification fatigue -->
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API</task>
+<task type="checkpoint:human-verify">Check API</task>
+<task type="auto">Create UI</task>
+<task type="checkpoint:human-verify">Check UI</task>
+```
+
+### Auth gate handling
+
+When an auth error occurs during `type="auto"` execution:
+1. Recognize it as an auth gate (not a bug) — indicators: "Not authenticated", "401", "403", "Please run X login"
+2. STOP the current task
+3. Return a `checkpoint:human-action` with exact auth steps
+4. In SUMMARY.md, document auth gates as normal flow, not deviations

package/.agent/skills/gsd/references/docs/git-integration.md

@@ -51,7 +51,7 @@ Phases:
 What to commit:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+gsd-sdk query commit "docs: initialize [project-name] ([N] phases)" .planning/
 ```
 
 </format>
@@ -133,7 +133,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 What to commit:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -153,7 +153,7 @@ Current: [task name]
 What to commit:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+gsd-sdk query commit "wip: [phase-name] paused at task [X]/[Y]" .planning/
 ```
 
 </format>
@@ -284,7 +284,7 @@ Set `commit_docs: false` so planning docs stay local and are not committed to an
 Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs commit-to-subrepo "feat(02-01): add user API" \
+gsd-sdk query commit-to-subrepo "feat(02-01): add user API" \
   --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
 ```
 

package/.agent/skills/gsd/references/docs/git-planning-commit.md

@@ -1,38 +1,40 @@
-# Git Planning Commit
-
-Commit planning artifacts using the gsd-tools CLI, which automatically checks `commit_docs` config and gitignore status.
-
-## Commit via CLI
-
-Always use `gsd-tools.cjs commit` for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
-```
-
-The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
-
-## Amend previous commit
-
-To fold `.planning/` file changes into the previous commit:
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
-```
-
-## Commit Message Patterns
-
-| Command | Scope | Example |
-|---------|-------|---------|
-| plan-phase | phase | `docs(phase-03): create authentication plans` |
-| execute-phase | phase | `docs(phase-03): complete authentication phase` |
-| new-milestone | milestone | `docs: start milestone v1.1` |
-| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
-| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
-| add-phase | phase | `docs: add phase 07 (settings page)` |
-
-## When to Skip
-
-- `commit_docs: false` in config
-- `.planning/` is gitignored
-- No changes to commit (check with `git status --porcelain .planning/`)
+# Git Planning Commit
+
+Commit planning artifacts via `gsd-sdk query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `gsd-tools.cjs commit`).
+
+## Commit via CLI
+
+Pass the message first, then file paths (positional). Do not use `--files` for `commit` (that flag is only for `commit-to-subrepo`).
+
+Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
+
+```bash
+gsd-sdk query commit "docs({scope}): {description}" .planning/STATE.md .planning/ROADMAP.md
+```
+
+The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
+
+## Amend previous commit
+
+To fold `.planning/` file changes into the previous commit:
+
+```bash
+gsd-sdk query commit "" .planning/codebase/*.md --amend
+```
+
+## Commit Message Patterns
+
+| Command | Scope | Example |
+|---------|-------|---------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## When to Skip
+
+- `commit_docs: false` in config
+- `.planning/` is gitignored
+- No changes to commit (check with `git status --porcelain .planning/`)

package/.agent/skills/gsd/references/docs/ios-scaffold.md

@@ -0,0 +1,123 @@
+# iOS App Scaffold Reference
+
+Rules and patterns for scaffolding iOS applications. Apply when any plan involves creating a new iOS app target.
+
+---
+
+## Critical Rule: Never Use Package.swift as the Primary Build System for iOS Apps
+
+**NEVER use `Package.swift` with `.executableTarget` (or `.target`) to scaffold an iOS app.** Swift Package Manager executable targets compile as macOS command-line tools — they do not produce `.app` bundles, cannot be signed for iOS devices, and cannot be submitted to the App Store.
+
+**Prohibited pattern:**
+```swift
+// Package.swift — DO NOT USE for iOS apps
+.executableTarget(name: "MyApp", dependencies: [])
+// or
+.target(name: "MyApp", dependencies: [])
+```
+
+Using this pattern produces a macOS CLI binary, not an iOS app. The app will not build for any iOS simulator or device.
+
+---
+
+## Required Pattern: XcodeGen
+
+All iOS app scaffolding MUST use XcodeGen to generate the `.xcodeproj`.
+
+### Step 1 — Install XcodeGen (if not present)
+
+```bash
+brew install xcodegen
+```
+
+### Step 2 — Create `project.yml`
+
+`project.yml` is the XcodeGen spec that describes the project structure. Minimum viable spec:
+
+```yaml
+name: MyApp
+options:
+  bundleIdPrefix: com.example
+  deploymentTarget:
+    iOS: "17.0"
+settings:
+  SWIFT_VERSION: "5.10"
+  IPHONEOS_DEPLOYMENT_TARGET: "17.0"
+targets:
+  MyApp:
+    type: application
+    platform: iOS
+    sources: [Sources/MyApp]
+    settings:
+      PRODUCT_BUNDLE_IDENTIFIER: com.example.MyApp
+      INFOPLIST_FILE: Sources/MyApp/Info.plist
+    scheme:
+      testTargets:
+        - MyAppTests
+  MyAppTests:
+    type: bundle.unit-test
+    platform: iOS
+    sources: [Tests/MyAppTests]
+    dependencies:
+      - target: MyApp
+```
+
+### Step 3 — Generate the .xcodeproj
+
+```bash
+xcodegen generate
+```
+
+This creates `MyApp.xcodeproj` in the project root. Commit `project.yml` but add `*.xcodeproj` to `.gitignore` (regenerate on checkout).
+
+### Step 4 — Standard project layout
+
+```
+MyApp/
+├── project.yml              # XcodeGen spec — commit this
+├── .gitignore               # includes *.xcodeproj
+├── Sources/
+│   └── MyApp/
+│       ├── MyAppApp.swift   # @main entry point
+│       ├── ContentView.swift
+│       └── Info.plist
+└── Tests/
+    └── MyAppTests/
+        └── MyAppTests.swift
+```
+
+---
+
+## iOS Deployment Target Compatibility
+
+Always verify SwiftUI API availability against the project's `IPHONEOS_DEPLOYMENT_TARGET` before using any SwiftUI component.
+
+| API | Minimum iOS |
+|-----|-------------|
+| `NavigationView` | iOS 13 |
+| `NavigationStack` | iOS 16 |
+| `NavigationSplitView` | iOS 16 |
+| `List(selection:)` with multi-select | iOS 17 |
+| `ScrollView` scroll position APIs | iOS 17 |
+| `Observable` macro (`@Observable`) | iOS 17 |
+| `SwiftData` | iOS 17 |
+| `@Bindable` | iOS 17 |
+| `TipKit` | iOS 17 |
+
+**Rule:** If a plan requires a SwiftUI API that exceeds the project's deployment target, either:
+1. Raise the deployment target in `project.yml` (and document the decision), or
+2. Wrap the call in `if #available(iOS NN, *) { ... }` with a fallback implementation.
+
+Do NOT silently use an API that requires a higher iOS version than the declared deployment target — the app will crash at runtime on older devices.
+
+---
+
+## Verification
+
+After running `xcodegen generate`, verify the project builds:
+
+```bash
+xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' build
+```
+
+A successful build (exit code 0) confirms the scaffold is valid for iOS.

package/.agent/skills/gsd/references/docs/mandatory-initial-read.md

@@ -0,0 +1,2 @@
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.

package/.agent/skills/gsd/references/docs/phase-argument-parsing.md

@@ -1,61 +1,61 @@
-# Phase Argument Parsing
-
-Parse and normalize phase arguments for commands that operate on phases.
-
-## Extraction
-
-From `$ARGUMENTS`:
-- Extract phase number (first numeric argument)
-- Extract flags (prefixed with `--`)
-- Remaining text is description (for insert/add commands)
-
-## Using gsd-tools
-
-The `find-phase` command handles normalization and validation in one step:
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" find-phase "${PHASE}")
-```
-
-Returns JSON with:
-- `found`: true/false
-- `directory`: Full path to phase directory
-- `phase_number`: Normalized number (e.g., "06", "06.1")
-- `phase_name`: Name portion (e.g., "foundation")
-- `plans`: Array of PLAN.md files
-- `summaries`: Array of SUMMARY.md files
-
-## Manual Normalization (Legacy)
-
-Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
-
-```bash
-# Normalize phase number
-if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
-  # Integer: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
-elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-  # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
-fi
-```
-
-## Validation
-
-Use `roadmap get-phase` to validate phase exists:
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" --pick found)
-if [ "$PHASE_CHECK" = "false" ]; then
-  echo "ERROR: Phase ${PHASE} not found in roadmap"
-  exit 1
-fi
-```
-
-## Directory Lookup
-
-Use `find-phase` for directory lookup:
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" find-phase "${PHASE}" --raw)
-```
+# Phase Argument Parsing
+
+Parse and normalize phase arguments for commands that operate on phases.
+
+## Extraction
+
+From `$ARGUMENTS`:
+- Extract phase number (first numeric argument)
+- Extract flags (prefixed with `--`)
+- Remaining text is description (for insert/add commands)
+
+## Using gsd-tools
+
+The `find-phase` command handles normalization and validation in one step:
+
+```bash
+PHASE_INFO=$(gsd-sdk query find-phase "${PHASE}")
+```
+
+Returns JSON with:
+- `found`: true/false
+- `directory`: Full path to phase directory
+- `phase_number`: Normalized number (e.g., "06", "06.1")
+- `phase_name`: Name portion (e.g., "foundation")
+- `plans`: Array of PLAN.md files
+- `summaries`: Array of SUMMARY.md files
+
+## Manual Normalization (Legacy)
+
+Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
+
+```bash
+# Normalize phase number
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  # Integer: 8 → 08
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  # Decimal: 2.1 → 02.1
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+## Validation
+
+Use `roadmap get-phase` to validate phase exists:
+
+```bash
+PHASE_CHECK=$(gsd-sdk query roadmap.get-phase "${PHASE}" --pick found)
+if [ "$PHASE_CHECK" = "false" ]; then
+  echo "ERROR: Phase ${PHASE} not found in roadmap"
+  exit 1
+fi
+```
+
+## Directory Lookup
+
+Use `find-phase` for directory lookup:
+
+```bash
+PHASE_DIR=$(gsd-sdk query find-phase "${PHASE}" --raw)
+```