gsd-antigravity-kit 2.0.1 → 2.1.0

package/.agent/skills/gsd/references/docs/planner-antipatterns.md

@@ -0,0 +1,89 @@
+# Planner Anti-Patterns and Specificity Examples
+
+> Reference file for gsd-planner 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.
+
+## Checkpoint Anti-Patterns
+
+### Bad — Asking human to automate
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com, import repo, click deploy...</instructions>
+</task>
+```
+
+**Why bad:** Vercel has a CLI. Antigravity should run `vercel --yes`. Never ask the user to do what Antigravity can automate via CLI/API.
+
+### Bad — Too many checkpoints
+
+```xml
+<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>
+```
+
+**Why bad:** Verification fatigue. Users should not be asked to verify every small step. Combine into one checkpoint at the end of meaningful work.
+
+### Good — Single verification checkpoint
+
+```xml
+<task type="auto">Create schema</task>
+<task type="auto">Create API</task>
+<task type="auto">Create UI</task>
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+</task>
+```
+
+### Bad — Mixing checkpoints with implementation
+
+A plan should not interleave multiple checkpoint types with implementation tasks. Checkpoints belong at natural verification boundaries, not scattered throughout.
+
+## Specificity Examples
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "Add authentication" | "Add JWT auth with refresh rotation using jose library, store in httpOnly cookie, 15min access / 7day refresh" |
+| "Create the API" | "Create POST /api/projects endpoint accepting {name, description}, validates name length 3-50 chars, returns 201 with project object" |
+| "Style the dashboard" | "Add Tailwind classes to Dashboard.tsx: grid layout (3 cols on lg, 1 on mobile), card shadows, hover states on action buttons" |
+| "Handle errors" | "Wrap API calls in try/catch, return {error: string} on 4xx/5xx, show toast via sonner on client" |
+| "Set up the database" | "Add User and Project models to schema.prisma with UUID ids, email unique constraint, createdAt/updatedAt timestamps, run prisma db push" |
+
+**Specificity test:** Could a different Antigravity instance execute the task without asking clarifying questions? If not, add more detail.
+
+## Context Section Anti-Patterns
+
+### Bad — Reflexive SUMMARY chaining
+
+```markdown
+<context>
+@.planning/phases/01-foundation/01-01-SUMMARY.md
+@.planning/phases/01-foundation/01-02-SUMMARY.md  <!-- Does Plan 02 actually need Plan 01's output? -->
+@.planning/phases/01-foundation/01-03-SUMMARY.md  <!-- Chain grows, context bloats -->
+</context>
+```
+
+**Why bad:** Plans are often independent. Reflexive chaining (02 refs 01, 03 refs 02...) wastes context. Only reference prior SUMMARY files when the plan genuinely uses types/exports from that prior plan or a decision from it affects the current plan.
+
+### Good — Selective context
+
+```markdown
+<context>
+@.planning/PROJECT.md
+@.planning/STATE.md
+@.planning/phases/01-foundation/01-01-SUMMARY.md  <!-- Uses User type defined in Plan 01 -->
+</context>
+```
+
+## Scope Reduction Anti-Patterns
+
+**Prohibited language in task actions:**
+- "v1", "v2", "simplified version", "static for now", "hardcoded for now"
+- "future enhancement", "placeholder", "basic version", "minimal implementation"
+- "will be wired later", "dynamic in future phase", "skip for now"
+
+If a decision from CONTEXT.md says "display cost calculated from billing table in impulses", the plan must deliver exactly that. Not "static label /min" as a "v1". If the phase is too complex, recommend a phase split instead of silently reducing scope.

package/.agent/skills/gsd/references/docs/planner-revision.md

@@ -1,87 +1,87 @@
-# Revision Mode — Planner Reference
-
-Triggered when orchestrator provides `<revision_context>` with checker issues. NOT starting fresh — making targeted updates to existing plans.
-
-**Mindset:** Surgeon, not architect. Minimal changes for specific issues.
-
-### Step 1: Load Existing Plans
-
-```bash
-cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
-```
-
-Build mental model of current plan structure, existing tasks, must_haves.
-
-### Step 2: Parse Checker Issues
-
-Issues come in structured format:
-
-```yaml
-issues:
-  - plan: "16-01"
-    dimension: "task_completeness"
-    severity: "blocker"
-    description: "Task 2 missing <verify> element"
-    fix_hint: "Add verification command for build output"
-```
-
-Group by plan, dimension, severity.
-
-### Step 3: Revision Strategy
-
-| Dimension | Strategy |
-|-----------|----------|
-| requirement_coverage | Add task(s) for missing requirement |
-| task_completeness | Add missing elements to existing task |
-| dependency_correctness | Fix depends_on, recompute waves |
-| key_links_planned | Add wiring task or update action |
-| scope_sanity | Split into multiple plans |
-| must_haves_derivation | Derive and add must_haves to frontmatter |
-
-### Step 4: Make Targeted Updates
-
-**DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
-
-**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
-
-### Step 5: Validate Changes
-
-- [ ] All flagged issues addressed
-- [ ] No new issues introduced
-- [ ] Wave numbers still valid
-- [ ] Dependencies still correct
-- [ ] Files on disk updated
-
-### Step 6: Commit
-
-```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
-```
-
-### Step 7: Return Revision Summary
-
-```markdown
-## REVISION COMPLETE
-
-**Issues addressed:** {N}/{M}
-
-### Changes Made
-
-| Plan | Change | Issue Addressed |
-|------|--------|-----------------|
-| 16-01 | Added <verify> to Task 2 | task_completeness |
-| 16-02 | Added logout task | requirement_coverage (AUTH-02) |
-
-### Files Updated
-
-- .planning/phases/16-xxx/16-01-PLAN.md
-- .planning/phases/16-xxx/16-02-PLAN.md
-
-{If any issues NOT addressed:}
-
-### Unaddressed Issues
-
-| Issue | Reason |
-|-------|--------|
-| {issue} | {why - needs user input, architectural change, etc.} |
-```
+# Revision Mode — Planner Reference
+
+Triggered when orchestrator provides `<revision_context>` with checker issues. NOT starting fresh — making targeted updates to existing plans.
+
+**Mindset:** Surgeon, not architect. Minimal changes for specific issues.
+
+### Step 1: Load Existing Plans
+
+```bash
+cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+Build mental model of current plan structure, existing tasks, must_haves.
+
+### Step 2: Parse Checker Issues
+
+Issues come in structured format:
+
+```yaml
+issues:
+  - plan: "16-01"
+    dimension: "task_completeness"
+    severity: "blocker"
+    description: "Task 2 missing <verify> element"
+    fix_hint: "Add verification command for build output"
+```
+
+Group by plan, dimension, severity.
+
+### Step 3: Revision Strategy
+
+| Dimension | Strategy |
+|-----------|----------|
+| requirement_coverage | Add task(s) for missing requirement |
+| task_completeness | Add missing elements to existing task |
+| dependency_correctness | Fix depends_on, recompute waves |
+| key_links_planned | Add wiring task or update action |
+| scope_sanity | Split into multiple plans |
+| must_haves_derivation | Derive and add must_haves to frontmatter |
+
+### Step 4: Make Targeted Updates
+
+**DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
+
+**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
+
+### Step 5: Validate Changes
+
+- [ ] All flagged issues addressed
+- [ ] No new issues introduced
+- [ ] Wave numbers still valid
+- [ ] Dependencies still correct
+- [ ] Files on disk updated
+
+### Step 6: Commit
+
+```bash
+gsd-sdk query commit "fix($PHASE): revise plans based on checker feedback" .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+```
+
+### Step 7: Return Revision Summary
+
+```markdown
+## REVISION COMPLETE
+
+**Issues addressed:** {N}/{M}
+
+### Changes Made
+
+| Plan | Change | Issue Addressed |
+|------|--------|-----------------|
+| 16-01 | Added <verify> to Task 2 | task_completeness |
+| 16-02 | Added logout task | requirement_coverage (AUTH-02) |
+
+### Files Updated
+
+- .planning/phases/16-xxx/16-01-PLAN.md
+- .planning/phases/16-xxx/16-02-PLAN.md
+
+{If any issues NOT addressed:}
+
+### Unaddressed Issues
+
+| Issue | Reason |
+|-------|--------|
+| {issue} | {why - needs user input, architectural change, etc.} |
+```

package/.agent/skills/gsd/references/docs/planner-source-audit.md

@@ -0,0 +1,73 @@
+# Planner Source Audit & Authority Limits
+
+Reference for `agents/gsd-planner.md` — extended rules for multi-source coverage audits and planner authority constraints.
+
+## Multi-Source Coverage Audit Format
+
+Before finalizing plans, produce a **source audit** covering ALL four artifact types:
+
+```
+SOURCE    | ID      | Feature/Requirement          | Plan  | Status    | Notes
+--------- | ------- | ---------------------------- | ----- | --------- | ------
+GOAL      | —       | {phase goal from ROADMAP.md}  | 01-03 | COVERED   |
+REQ       | REQ-14  | OAuth login with Google + GH | 02    | COVERED   |
+REQ       | REQ-22  | Email verification flow      | 03    | COVERED   |
+RESEARCH  | —       | Rate limiting on auth routes | 01    | COVERED   |
+RESEARCH  | —       | Refresh token rotation       | NONE  | ⚠ MISSING | No plan covers this
+CONTEXT   | D-01    | Use jose library for JWT     | 02    | COVERED   |
+CONTEXT   | D-04    | 15min access / 7day refresh  | 02    | COVERED   |
+```
+
+### Four Source Types
+
+1. **GOAL** — The `goal:` field from ROADMAP.md for this phase. The primary success condition.
+2. **REQ** — Every REQ-ID in `phase_req_ids`. Cross-reference REQUIREMENTS.md for descriptions.
+3. **RESEARCH** — Technical approaches, discovered constraints, and features identified in RESEARCH.md. Exclude items explicitly marked "out of scope" or "future work" by the researcher.
+4. **CONTEXT** — Every D-XX decision from CONTEXT.md `<decisions>` section.
+
+### What is NOT a Gap
+
+Do not flag these as MISSING:
+- Items in `## Deferred Ideas` in CONTEXT.md — developer chose to defer these
+- Items scoped to a different phase via `phase_req_ids` — not assigned to this phase
+- Items in RESEARCH.md explicitly marked "out of scope" or "future work" by the researcher
+
+### Handling MISSING Items
+
+If ANY row is `⚠ MISSING`, do NOT finalize the plan set silently. Return to the orchestrator:
+
+```
+## ⚠ Source Audit: Unplanned Items Found
+
+The following items from source artifacts have no corresponding plan:
+
+1. **{SOURCE}: {item description}** (from {artifact file}, section "{section}")
+   - {why this was identified as required}
+
+   Options:
+   A) Add a plan to cover this item
+   B) Split phase: move to a sub-phase
+   C) Defer explicitly: add to backlog with developer confirmation
+
+   → Awaiting developer decision before finalizing plan set.
+```
+
+If ALL rows are COVERED → return `## PLANNING COMPLETE` as normal.
+
+---
+
+## Authority Limits — Constraint Examples
+
+The planner's only legitimate reasons to split or flag a feature are **constraints**, not judgments about difficulty:
+
+**Valid (constraints):**
+- ✓ "This task touches 9 files and would consume ~45% context — split into two tasks"
+- ✓ "No API key or endpoint is defined in any source artifact — need developer input"
+- ✓ "This feature depends on the auth system built in Phase 03, which is not yet complete"
+
+**Invalid (difficulty judgments):**
+- ✗ "This is complex and would be difficult to implement correctly"
+- ✗ "Integrating with an external service could take a long time"
+- ✗ "This is a challenging feature that might be better left to a future phase"
+
+If a feature has none of the three legitimate constraints (context cost, missing information, dependency conflict), it gets planned. Period.

package/.agent/skills/gsd/references/docs/planning-config.md

@@ -35,6 +35,7 @@ Configuration options for `.planning/` directory behavior.
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
 | `workflow.use_worktrees` | `true` | Whether executor agents run in isolated git worktrees. Set to `false` to disable worktrees — agents execute sequentially on the main working tree instead. Recommended for solo developers or when worktree merges cause issues. |
 | `workflow.subagent_timeout` | `300000` | Timeout in milliseconds for parallel subagent tasks (e.g. codebase mapping). Increase for large codebases or slower models. Default: 300000 (5 minutes). |
+| `workflow.inline_plan_threshold` | `2` | Plans with this many tasks or fewer execute inline (Pattern C) instead of spawning a subagent. Avoids ~14K token spawn overhead for small plans. Set to `0` to always spawn subagents. |
 | `manager.flags.discuss` | `""` | Flags passed to `/gsd-discuss-phase` when dispatched from manager (e.g. `"--auto --analyze"`) |
 | `manager.flags.plan` | `""` | Flags passed to plan workflow when dispatched from manager |
 | `manager.flags.execute` | `""` | Flags passed to execute workflow when dispatched from manager |
@@ -57,15 +58,15 @@ Configuration options for `.planning/` directory behavior.
 
 ```bash
 # Commit with automatic commit_docs + gitignore checks:
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+gsd-sdk query commit "docs: update state" .planning/STATE.md
 
 # Load config via state load (returns JSON):
-.agent/skills/gsd/bin/gsd-tools.cjs" state load)
+INIT=$(gsd-sdk query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is available in the JSON output
 
 # Or use init commands which include commit_docs:
-.agent/skills/gsd/bin/gsd-tools.cjs" init execute-phase "1")
+INIT=$(gsd-sdk query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # commit_docs is included in all init command outputs
 ```
@@ -75,7 +76,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **Commit via CLI (handles checks automatically):**
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+gsd-sdk query commit "docs: update state" .planning/STATE.md
 ```
 
 The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
@@ -163,14 +164,14 @@ To use uncommitted mode:
 
 Use `init execute-phase` which returns all config as JSON:
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" init execute-phase "1")
+INIT=$(gsd-sdk query init.execute-phase "1")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
 ```
 
 Or use `state load` for the config values:
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" state load)
+INIT=$(gsd-sdk query state.load)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
 ```
@@ -225,7 +226,7 @@ Generated from `CONFIG_DEFAULTS` (core.cjs) and `VALID_CONFIG_KEYS` (config.cjs)
 | Key | Type | Default | Allowed Values | Description |
 |-----|------|---------|----------------|-------------|
 | `model_profile` | string | `"balanced"` | `"quality"`, `"balanced"`, `"budget"`, `"inherit"` | Model selection preset for subagents |
-| `mode` | string | (none) | `"code-first"`, `"plan-first"`, `"hybrid"` | Per-phase workflow mode controlling discuss/plan/execute flow |
+| `mode` | string | `"interactive"` | `"interactive"`, `"yolo"` | Operation mode: `"interactive"` shows gates and confirmations; `"yolo"` runs autonomously without prompts |
 | `granularity` | string | (none) | `"coarse"`, `"standard"`, `"fine"` | Planning depth for phase plans (migrated from deprecated `depth`) |
 | `commit_docs` | boolean | `true` | `true`, `false` | Commit .planning/ artifacts to git (auto-false if .planning/ is gitignored) |
 | `search_gitignored` | boolean | `false` | `true`, `false` | Include gitignored paths in broad rg searches via `--no-ignore` |
@@ -234,6 +235,8 @@ Generated from `CONFIG_DEFAULTS` (core.cjs) and `VALID_CONFIG_KEYS` (config.cjs)
 | `response_language` | string\|null | `null` | Any language name | Language for user-facing prompts (e.g., `"Portuguese"`, `"Japanese"`) |
 | `context_window` | number | `200000` | `200000`, `1000000` | Context window size; set `1000000` for 1M-context models |
 | `resolve_model_ids` | boolean\|string | `false` | `false`, `true`, `"omit"` | Map model aliases to full Antigravity IDs; `"omit"` returns empty string |
+| `context` | string\|null | `null` | `"dev"`, `"research"`, `"review"` | Execution context profile that adjusts agent behavior: `"dev"` for development tasks, `"research"` for investigation/exploration, `"review"` for code review workflows |
+| `review.models.<cli>` | string\|null | `null` | Any model ID string | Per-CLI model override for /gsd-review (e.g., `review.models.gemini`). Falls back to CLI default when null. |
 
 ### Workflow Fields
 
@@ -245,17 +248,22 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.plan_check` | boolean | `true` | `true`, `false` | Run plan-checker agent to validate plans. _Alias:_ `plan_checker` is the flat-key form used in `CONFIG_DEFAULTS`; `workflow.plan_check` is the canonical namespaced form. |
 | `workflow.verifier` | boolean | `true` | `true`, `false` | Run verifier agent after execution |
 | `workflow.nyquist_validation` | boolean | `true` | `true`, `false` | Enable Nyquist-inspired validation gates |
+| `workflow.auto_prune_state` | boolean | `false` | `true`, `false` | Automatically prune old STATE.md entries on phase completion (keeps 3 most recent phases) |
 | `workflow.auto_advance` | boolean | `false` | `true`, `false` | Auto-advance to next phase after completion |
 | `workflow.node_repair` | boolean | `true` | `true`, `false` | Attempt automatic repair of failed plan nodes |
 | `workflow.node_repair_budget` | number | `2` | Any positive integer | Max repair retries per failed node |
+| `workflow.ai_integration_phase` | boolean | `true` | `true`, `false` | Run /gsd-ai-integration-phase before planning AI system phases |
 | `workflow.ui_phase` | boolean | `true` | `true`, `false` | Generate UI-SPEC.md for frontend phases |
 | `workflow.ui_safety_gate` | boolean | `true` | `true`, `false` | Require safety gate approval for UI changes |
 | `workflow.text_mode` | boolean | `false` | `true`, `false` | Use plain-text numbered lists instead of AskUserQuestion menus |
 | `workflow.research_before_questions` | boolean | `false` | `true`, `false` | Run research before interactive questions in discuss phase |
-| `workflow.discuss_mode` | string | `"discuss"` | `"discuss"`, `"auto"`, `"analyze"` | Default mode for discuss-phase agent |
+| `workflow.discuss_mode` | string | `"discuss"` | `"discuss"`, `"assumptions"` | Default mode for discuss-phase: `"discuss"` runs interactive questioning; `"assumptions"` analyzes codebase and surfaces assumptions instead |
 | `workflow.skip_discuss` | boolean | `false` | `true`, `false` | Skip discuss phase entirely |
 | `workflow.use_worktrees` | boolean | `true` | `true`, `false` | Run executor agents in isolated git worktrees |
 | `workflow.subagent_timeout` | number | `300000` | Any positive integer (ms) | Timeout for parallel subagent tasks (default: 5 minutes) |
+| `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
+| `workflow.code_review` | boolean | `true` | `true`, `false` | Enable built-in code review step in the ship workflow |
+| `workflow.code_review_depth` | string | `"standard"` | `"light"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow |
 | `workflow._auto_chain_active` | boolean | `false` | `true`, `false` | Internal: tracks whether autonomous chaining is active |
 
 ### Git Fields
@@ -287,6 +295,7 @@ Set via `features.*` namespace (e.g., `"features": { "thinking_partner": true }`
 | Key | Type | Default | Allowed Values | Description |
 |-----|------|---------|----------------|-------------|
 | `features.thinking_partner` | boolean | `false` | `true`, `false` | Enable conditional extended thinking at workflow decision points (used by discuss-phase and plan-phase for architectural tradeoff analysis) |
+| `features.global_learnings` | boolean | `false` | `true`, `false` | Enable injection of global learnings from `~/.gsd/learnings/` into agent prompts |
 
 ### Hook Fields
 
@@ -296,6 +305,22 @@ Set via `hooks.*` namespace (e.g., `"hooks": { "context_warnings": true }`).
 |-----|------|---------|----------------|-------------|
 | `hooks.context_warnings` | boolean | `true` | `true`, `false` | Show warnings when context budget is exceeded |
 
+### Learnings Fields
+
+Set via `learnings.*` namespace (e.g., `"learnings": { "max_inject": 5 }`). Used together with `features.global_learnings`.
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `learnings.max_inject` | number | `10` | Any positive integer | Maximum number of global learning entries to inject into agent prompts per session |
+
+### Intel Fields
+
+Set via `intel.*` namespace (e.g., `"intel": { "enabled": true }`). Controls the queryable codebase intelligence system consumed by `/gsd-intel`.
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `intel.enabled` | boolean | `false` | `true`, `false` | Enable queryable codebase intelligence system. When `true`, `/gsd-intel` commands build and query a JSON index in `.planning/intel/`. |
+
 ### Manager Fields
 
 Set via `manager.*` namespace (e.g., `"manager": { "flags": { "discuss": "--auto" } }`).

package/.agent/skills/gsd/references/docs/project-skills-discovery.md

@@ -0,0 +1,19 @@
+# Project Skills Discovery
+
+Before execution, check for project-defined skills and apply their rules.
+
+**Discovery steps (shared across all GSD agents):**
+1. Check `.antigravity/skills/` or `.agents/skills/` directory — if neither exists, skip.
+2. List available skills (subdirectories).
+3. Read `SKILL.md` for each skill (lightweight index, typically ~130 lines).
+4. Load specific `rules/*.md` files only as needed during the current task.
+5. Do NOT load full `AGENTS.md` files — they are large (100KB+) and cost significant context.
+
+**Application** — how to apply the loaded rules depends on the calling agent:
+- Planners account for project skill patterns and conventions in the plan.
+- Executors follow skill rules relevant to the task being implemented.
+- Researchers ensure research output accounts for project skill patterns.
+- Verifiers apply skill rules when scanning for anti-patterns and verifying quality.
+- Debuggers follow skill rules relevant to the bug being investigated and the fix being applied.
+
+The caller's agent file should specify which application applies.

package/.agent/skills/gsd/references/docs/sketch-interactivity.md

@@ -0,0 +1,41 @@
+# Making Sketches Feel Alive
+
+Static mockups are barely better than screenshots. Every interactive element in a sketch must respond to interaction.
+
+## Required Interactivity
+
+| Element | Must Have |
+|---------|-----------|
+| Buttons | Click handler with visible feedback (state change, animation, toast) |
+| Forms | Input validation on blur, submit handler that shows success state |
+| Lists | Add/remove items, empty state, populated state |
+| Toggles/switches | Working toggle with visible state change |
+| Tabs/nav | Click to switch content |
+| Modals/drawers | Open/close with transition |
+| Hover states | Every clickable element needs a hover effect |
+| Dropdowns | Open/close, item selection |
+
+## Transitions
+
+Add `transition: all 0.15s ease` as a baseline to interactive elements. Subtle motion makes the sketch feel real and helps judge whether the interaction pattern works.
+
+## Fake the Backend
+
+If the sketch shows a "Save" button, clicking it should show a brief loading state then a success message. If it shows a search bar, typing should filter hardcoded results. The goal is to feel the full interaction loop, not just see the resting state.
+
+## State Cycling
+
+If the sketch has multiple states (empty, loading, populated, error), include buttons to cycle through them. Label each state clearly. This lets the user experience how the design handles different data conditions.
+
+## Implementation
+
+Use vanilla JS in inline `<script>` tags. No frameworks, no build step. Keep it simple:
+
+```html
+<script>
+  // Toggle a panel
+  document.querySelector('.panel-toggle').addEventListener('click', (e) => {
+    e.target.closest('.panel').classList.toggle('collapsed');
+  });
+</script>
+```

package/.agent/skills/gsd/references/docs/sketch-theme-system.md

@@ -0,0 +1,94 @@
+# Shared Theme System
+
+All sketches share a CSS variable theme so design decisions compound across sketches.
+
+## Setup
+
+On the first sketch, create `.planning/sketches/themes/` with a default theme:
+
+```
+.planning/sketches/
+  themes/
+    default.css         <- all sketches link to this
+  001-dashboard-layout/
+    index.html          <- links to ../themes/default.css
+```
+
+## Theme File Structure
+
+Each theme defines CSS custom properties only — no component styles, no layout rules. Just the visual vocabulary:
+
+```css
+:root {
+  /* Colors */
+  --color-bg: #fafafa;
+  --color-surface: #ffffff;
+  --color-border: #e5e5e5;
+  --color-text: #1a1a1a;
+  --color-text-muted: #6b6b6b;
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --color-accent: #f59e0b;
+  --color-danger: #ef4444;
+  --color-success: #22c55e;
+
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+
+  /* Spacing */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+
+  /* Shapes */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-md: 0 4px 6px rgba(0,0,0,0.07);
+  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
+}
+```
+
+Adapt the default theme to match the mood/direction established during intake. The values above are a starting point — change colors, fonts, spacing, and shapes to match the agreed aesthetic.
+
+## Linking
+
+Every sketch links to the theme:
+
+```html
+<link rel="stylesheet" href="../themes/default.css">
+```
+
+## Creating New Themes
+
+When a sketch reveals an aesthetic fork ("should this feel clinical or warm?"), create both as theme files rather than arguing about it. The user can switch and feel the difference.
+
+Name themes descriptively: `midnight.css`, `warm-minimal.css`, `brutalist.css`.
+
+## Theme Switcher
+
+Include in every sketch (part of the sketch toolbar):
+
+```html
+<select id="theme-switcher" onchange="document.querySelector('link[href*=themes]').href='../themes/'+this.value+'.css'">
+  <option value="default">Default</option>
+</select>
+```
+
+Dynamically populate options by listing available theme files, or hardcode the known themes.

package/.agent/skills/gsd/references/docs/sketch-tooling.md

@@ -0,0 +1,45 @@
+# Sketch Toolbar
+
+Include a small floating toolbar in every sketch. It provides utilities without competing with the actual design.
+
+## Implementation
+
+A small `<div>` fixed to the bottom-right, semi-transparent, expands on hover:
+
+```html
+<div id="sketch-tools" style="position:fixed;bottom:12px;right:12px;z-index:9999;font-family:system-ui;font-size:12px;background:rgba(0,0,0,0.7);color:white;padding:8px 12px;border-radius:8px;opacity:0.4;transition:opacity 0.2s;" onmouseenter="this.style.opacity='1'" onmouseleave="this.style.opacity='0.4'">
+  <!-- Theme switcher -->
+  <!-- Viewport buttons -->
+  <!-- Annotation toggle -->
+</div>
+```
+
+## Components
+
+### Theme Switcher
+
+A dropdown that swaps the theme CSS file at runtime:
+
+```html
+<select onchange="document.querySelector('link[href*=themes]').href='../themes/'+this.value+'.css'">
+  <option value="default">Default</option>
+</select>
+```
+
+### Viewport Preview
+
+Three buttons that constrain the sketch content area to standard widths:
+
+- Phone: 375px
+- Tablet: 768px
+- Desktop: 1280px (or full width)
+
+Implemented by wrapping sketch content in a container and adjusting its `max-width`.
+
+### Annotation Mode
+
+A toggle that overlays spacing values, color hex codes, and font sizes on hover. Implemented as a JS snippet that reads computed styles and shows them in a tooltip. Helps understand visual decisions without opening dev tools.
+
+## Styling
+
+The toolbar should be unobtrusive — small, dark, semi-transparent. It should never compete with the sketch visually. Style it independently of the theme (hardcoded dark background, white text).