gsd-antigravity-kit 1.32.0 → 2.0.0

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

@@ -0,0 +1,70 @@
+# Gates Taxonomy
+
+Canonical gate types used across GSD workflows. Every validation checkpoint maps to one of these four types.
+
+---
+
+## Gate Types
+
+### Pre-flight Gate
+**Purpose:** Validates preconditions before starting an operation.
+**Behavior:** Blocks entry if conditions unmet. No partial work created.
+**Recovery:** Fix the missing precondition, then retry.
+**Examples:**
+- Plan-phase checks for REQUIREMENTS.md before planning
+- Execute-phase validates PLAN.md exists before execution
+- Discuss-phase confirms phase exists in ROADMAP.md
+
+### Revision Gate
+**Purpose:** Evaluates output quality and routes to revision if insufficient.
+**Behavior:** Loops back to producer with specific feedback. Bounded by iteration cap.
+**Recovery:** Producer addresses feedback; checker re-evaluates. The loop also escalates early if issue count does not decrease between consecutive iterations (stall detection). After max iterations, escalates unconditionally.
+**Examples:**
+- Plan-checker reviewing PLAN.md (max 3 iterations)
+- Verifier checking phase deliverables against success criteria
+
+### Escalation Gate
+**Purpose:** Surfaces unresolvable issues to the developer for a decision.
+**Behavior:** Pauses workflow, presents options, waits for human input.
+**Recovery:** Developer chooses action; workflow resumes on selected path.
+**Examples:**
+- Revision loop exhausted after 3 iterations
+- Merge conflict during worktree cleanup
+- Ambiguous requirement needing clarification
+
+### Abort Gate
+**Purpose:** Terminates the operation to prevent damage or waste.
+**Behavior:** Stops immediately, preserves state, reports reason.
+**Recovery:** Developer investigates root cause, fixes, restarts from checkpoint.
+**Examples:**
+- Context window critically low during execution
+- STATE.md in error state blocking /gsd-next
+- Verification finds critical missing deliverables
+
+---
+
+## Gate Matrix
+
+| Workflow | Phase | Gate Type | Artifacts Checked | Failure Behavior |
+|----------|-------|-----------|-------------------|------------------|
+| plan-phase | Entry | Pre-flight | REQUIREMENTS.md, ROADMAP.md | Block with missing-file message |
+| plan-phase | Step 12 | Revision | PLAN.md quality | Loop to planner (max 3) |
+| plan-phase | Post-revision | Escalation | Unresolved issues | Surface to developer |
+| execute-phase | Entry | Pre-flight | PLAN.md | Block with missing-plan message |
+| execute-phase | Completion | Revision | SUMMARY.md completeness | Re-run incomplete tasks |
+| verify-work | Entry | Pre-flight | SUMMARY.md | Block with missing-summary |
+| verify-work | Evaluation | Escalation | Failed criteria | Surface gaps to developer |
+| next | Entry | Abort | Error state, checkpoints | Stop with diagnostic |
+
+---
+
+## Implementing Gates
+
+Use this taxonomy when designing or auditing workflow validation points:
+
+- **Pre-flight** gates belong at workflow entry points. They are cheap, deterministic checks that prevent wasted work. If you can verify a precondition with a file-existence check or a config read, use a pre-flight gate.
+- **Revision** gates belong after a producer step where quality varies. Always pair them with an iteration cap to prevent infinite loops. The cap should reflect the cost of each iteration -- expensive operations get fewer retries.
+- **Escalation** gates belong wherever automated resolution is impossible or ambiguous. They are the safety valve between revision loops and abort. Present the developer with clear options and enough context to decide.
+- **Abort** gates belong at points where continuing would cause damage, waste significant resources, or produce meaningless output. They should preserve state so work can resume after the root cause is fixed.
+
+**Selection heuristic:** Start with pre-flight. If the check happens after work is produced, it is a revision gate. If the revision loop cannot resolve the issue, escalate. If continuing is dangerous, abort.

package/.agent/skills/gsd/references/docs/model-profile-resolution.md

@@ -26,6 +26,8 @@ Task(
 
 **Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
 
+If `model_profile` is `"adaptive"`, agents resolve to role-based assignments (opus/sonnet/haiku based on agent type).
+
 If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode `/model`).
 
 ## Usage

package/.agent/skills/gsd/references/docs/model-profiles.md

@@ -4,20 +4,20 @@ Model profiles control which Antigravity model each GSD agent uses. This allows
 
 ## Profile Definitions
 
-| Agent | `quality` | `balanced` | `budget` | `inherit` |
-|-------|-----------|------------|----------|-----------|
-| gsd-planner | opus | opus | sonnet | inherit |
-| gsd-roadmapper | opus | sonnet | sonnet | inherit |
-| gsd-executor | opus | sonnet | sonnet | inherit |
-| gsd-phase-researcher | opus | sonnet | haiku | inherit |
-| gsd-project-researcher | opus | sonnet | haiku | inherit |
-| gsd-research-synthesizer | sonnet | sonnet | haiku | inherit |
-| gsd-debugger | opus | sonnet | sonnet | inherit |
-| gsd-codebase-mapper | sonnet | haiku | haiku | inherit |
-| gsd-verifier | sonnet | sonnet | haiku | inherit |
-| gsd-plan-checker | sonnet | sonnet | haiku | inherit |
-| gsd-integration-checker | sonnet | sonnet | haiku | inherit |
-| gsd-nyquist-auditor | sonnet | sonnet | haiku | inherit |
+| Agent | `quality` | `balanced` | `budget` | `adaptive` | `inherit` |
+|-------|-----------|------------|----------|------------|-----------|
+| gsd-planner | opus | opus | sonnet | opus | inherit |
+| gsd-roadmapper | opus | sonnet | sonnet | sonnet | inherit |
+| gsd-executor | opus | sonnet | sonnet | sonnet | inherit |
+| gsd-phase-researcher | opus | sonnet | haiku | sonnet | inherit |
+| gsd-project-researcher | opus | sonnet | haiku | sonnet | inherit |
+| gsd-research-synthesizer | sonnet | sonnet | haiku | haiku | inherit |
+| gsd-debugger | opus | sonnet | sonnet | opus | inherit |
+| gsd-codebase-mapper | sonnet | haiku | haiku | haiku | inherit |
+| gsd-verifier | sonnet | sonnet | haiku | sonnet | inherit |
+| gsd-plan-checker | sonnet | sonnet | haiku | haiku | inherit |
+| gsd-integration-checker | sonnet | sonnet | haiku | haiku | inherit |
+| gsd-nyquist-auditor | sonnet | sonnet | haiku | haiku | inherit |
 
 ## Profile Philosophy
 
@@ -37,6 +37,12 @@ Model profiles control which Antigravity model each GSD agent uses. This allows
 - Haiku for research and verification
 - Use when: conserving quota, high-volume work, less critical phases
 
+**adaptive** — Role-based cost optimization
+- Opus for planning and debugging (where reasoning quality has highest impact)
+- Sonnet for execution, research, and verification (follows explicit instructions)
+- Haiku for mapping, checking, and auditing (high volume, structured output)
+- Use when: optimizing cost without sacrificing plan quality, solo development on paid API tiers
+
 **inherit** - Follow the current session model
 - All agents resolve to `inherit`
 - Best when you switch models interactively (for example OpenCode or Kilo `/model`)

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

@@ -35,7 +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). |
-| `manager.flags.discuss` | `""` | Flags passed to `/gsd:discuss-phase` when dispatched from manager (e.g. `"--auto --analyze"`) |
+| `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 |
 | `response_language` | `null` | Language for user-facing questions and prompts across all phases/subagents (e.g. `"Portuguese"`, `"Japanese"`, `"Spanish"`). When set, all spawned agents include a directive to respond in this language. |
@@ -214,4 +214,219 @@ Squash merge is recommended — keeps main branch history clean while preserving
 
 </branching_strategy_behavior>
 
+<complete_field_reference>
+
+## Complete Field Reference
+
+Generated from `CONFIG_DEFAULTS` (core.cjs) and `VALID_CONFIG_KEYS` (config.cjs).
+
+### Core Fields
+
+| 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 |
+| `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` |
+| `phase_naming` | string | `"sequential"` | `"sequential"`, `"custom"` | Phase numbering: auto-increment or arbitrary string IDs |
+| `project_code` | string\|null | `null` | Any short string | Prefix for phase dirs (e.g., `"CK"` produces `CK-01-foundation`) |
+| `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 |
+
+### Workflow Fields
+
+Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research": true }`).
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `workflow.research` | boolean | `true` | `true`, `false` | Run research agent before planning |
+| `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_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.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.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._auto_chain_active` | boolean | `false` | `true`, `false` | Internal: tracks whether autonomous chaining is active |
+
+### Git Fields
+
+Set via `git.*` namespace (e.g., `"git": { "branching_strategy": "phase" }`).
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `git.branching_strategy` | string | `"none"` | `"none"`, `"phase"`, `"milestone"` | Git branching approach for phase/milestone isolation |
+| `git.base_branch` | string\|null | `null` (auto-detect) | Any branch name | Target branch for PRs and merges; auto-detects from `origin/HEAD` when `null` |
+| `git.phase_branch_template` | string | `"gsd/phase-{phase}-{slug}"` | Template with `{phase}`, `{slug}` | Branch naming template for `phase` strategy |
+| `git.milestone_branch_template` | string | `"gsd/{milestone}-{slug}"` | Template with `{milestone}`, `{slug}` | Branch naming template for `milestone` strategy |
+| `git.quick_branch_template` | string\|null | `null` | Template with `{slug}` | Optional branch template for quick-task runs |
+
+### Search & API Fields
+
+These toggle external search integrations. Auto-detected at project creation when API keys are present.
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `brave_search` | boolean | `false` | `true`, `false` | Enable Brave web search for research agent (requires `BRAVE_API_KEY`) |
+| `firecrawl` | boolean | `false` | `true`, `false` | Enable Firecrawl page scraping (requires `FIRECRAWL_API_KEY`) |
+| `exa_search` | boolean | `false` | `true`, `false` | Enable Exa semantic search (requires `EXA_API_KEY`) |
+
+### Features Fields
+
+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) |
+
+### Hook Fields
+
+Set via `hooks.*` namespace (e.g., `"hooks": { "context_warnings": true }`).
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `hooks.context_warnings` | boolean | `true` | `true`, `false` | Show warnings when context budget is exceeded |
+
+### Manager Fields
+
+Set via `manager.*` namespace (e.g., `"manager": { "flags": { "discuss": "--auto" } }`).
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `manager.flags.discuss` | string | `""` | Any CLI flags string | Flags passed to `/gsd-discuss-phase` from manager (e.g., `"--auto --analyze"`) |
+| `manager.flags.plan` | string | `""` | Any CLI flags string | Flags passed to plan workflow from manager |
+| `manager.flags.execute` | string | `""` | Any CLI flags string | Flags passed to execute workflow from manager |
+
+### Advanced Fields
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `parallelization` | boolean\|object | `true` | `true`, `false`, `{ "enabled": true }` | Enable parallel wave execution; object form allows additional sub-keys |
+| `model_overrides` | object\|null | `null` | `{ "<agent-type>": "<model-id>" }` | Override model selection per agent type |
+| `agent_skills` | object | `{}` | `{ "<agent-type>": "<skill-set>" }` | Assign skill sets to specific agent types |
+| `sub_repos` | array | `[]` | Array of relative path strings | Child directories with independent `.git` repos (auto-detected) |
+
+### Planning Fields
+
+These can be set at top level or nested under `planning.*` (e.g., `"planning": { "commit_docs": false }`). Both forms are equivalent; top-level takes precedence if both exist.
+
+| Key | Type | Default | Allowed Values | Description |
+|-----|------|---------|----------------|-------------|
+| `planning.commit_docs` | boolean | `true` | `true`, `false` | Alias for top-level `commit_docs` |
+| `planning.search_gitignored` | boolean | `false` | `true`, `false` | Alias for top-level `search_gitignored` |
+
+---
+
+## Field Interactions
+
+Several config fields affect each other or trigger special behavior:
+
+1. **`commit_docs` auto-detection** -- When no explicit value is set in config.json and `.planning/` is in `.gitignore`, `commit_docs` automatically resolves to `false`. An explicit `true` or `false` in config always overrides auto-detection.
+
+2. **`branching_strategy` controls branch templates** -- The `phase_branch_template` and `milestone_branch_template` fields are only used when `branching_strategy` is set to `"phase"` or `"milestone"` respectively. When `branching_strategy` is `"none"`, all template fields are ignored.
+
+3. **`context_window` threshold triggers** -- When `context_window >= 500000`, workflows enable adaptive context enrichment: full-body reads of prior phase SUMMARYs, cross-phase context injection in plan-phase, and deeper read depth for anti-pattern references. Below 500000, only frontmatter and summaries are read.
+
+4. **`parallelization` polymorphism** -- Accepts both a simple boolean and an object with an `enabled` field. `loadConfig()` normalizes either form to a boolean. `{ "enabled": true }` is equivalent to `true`.
+
+5. **Search API keys and flags** -- `brave_search`, `firecrawl`, and `exa_search` are auto-set to `true` during project creation if the corresponding API key is detected (environment variable or `~/.gsd/<name>_api_key` file). Setting them to `true` without the API key has no effect.
+
+6. **`planning.*` and top-level equivalence** -- `planning.commit_docs` and `commit_docs` are equivalent; `planning.search_gitignored` and `search_gitignored` are equivalent. If both are set, the top-level value takes precedence.
+
+7. **`depth` to `granularity` migration** -- The deprecated `depth` key (`quick`/`standard`/`comprehensive`) is automatically migrated to `granularity` (`coarse`/`standard`/`fine`) on config load and persisted back to disk.
+
+8. **`sub_repos` auto-sync** -- On every config load, GSD scans for child directories with `.git` and updates the `sub_repos` array if the filesystem has changed. Legacy `multiRepo: true` is automatically migrated to a detected `sub_repos` array.
+
+---
+
+## Example Configurations
+
+### Minimal -- Solo Developer
+
+```json
+{
+  "model_profile": "balanced",
+  "commit_docs": true,
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "use_worktrees": false
+  }
+}
+```
+
+### Team Project with Branching
+
+```json
+{
+  "model_profile": "quality",
+  "commit_docs": true,
+  "project_code": "APP",
+  "git": {
+    "branching_strategy": "phase",
+    "base_branch": "develop",
+    "phase_branch_template": "gsd/phase-{phase}-{slug}"
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "use_worktrees": true,
+    "discuss_mode": "discuss"
+  },
+  "manager": {
+    "flags": {
+      "discuss": "",
+      "plan": "",
+      "execute": ""
+    }
+  },
+  "response_language": "English"
+}
+```
+
+### Large Codebase -- 1M Context with Extended Timeouts
+
+```json
+{
+  "model_profile": "quality",
+  "context_window": 1000000,
+  "commit_docs": true,
+  "project_code": "MEGA",
+  "phase_naming": "sequential",
+  "git": {
+    "branching_strategy": "milestone",
+    "milestone_branch_template": "gsd/{milestone}-{slug}"
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "subagent_timeout": 600000,
+    "use_worktrees": true,
+    "node_repair": true,
+    "node_repair_budget": 3,
+    "auto_advance": true
+  },
+  "brave_search": true,
+  "hooks": {
+    "context_warnings": true
+  }
+}
+```
+
+</complete_field_reference>
+
 </planning_config>

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

@@ -0,0 +1,97 @@
+# Revision Loop Pattern
+
+Standard pattern for iterative agent revision with feedback. Used when a checker/validator finds issues and the producing agent needs to revise its output.
+
+---
+
+## Pattern: Check-Revise-Escalate (max 3 iterations)
+
+This pattern applies whenever:
+1. An agent produces output (plans, imports, gap-closure plans)
+2. A checker/validator evaluates that output
+3. Issues are found that need revision
+
+### Flow
+
+```
+prev_issue_count = Infinity
+iteration = 0
+
+LOOP:
+  1. Run checker/validator on current output
+  2. Read checker results
+  3. If PASSED or only INFO-level issues:
+     -> Accept output, exit loop
+  4. If BLOCKER or WARNING issues found:
+     a. iteration += 1
+     b. If iteration > 3:
+        -> Escalate to user (see "After 3 Iterations" below)
+     c. Parse issue count from checker output
+     d. If issue_count >= prev_issue_count:
+        -> Escalate to user: "Revision loop stalled (issue count not decreasing)"
+     e. prev_issue_count = issue_count
+     f. Re-spawn the producing agent with checker feedback appended
+     g. After revision completes, go to LOOP
+```
+
+### Issue Count Tracking
+
+Track the number of BLOCKER + WARNING issues returned by the checker on each iteration. If the count does not decrease between consecutive iterations, the producing agent is stuck and further iterations will not help. Break early and escalate to the user.
+
+Display iteration progress before each revision spawn:
+`Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings`
+
+### Re-spawn Prompt Structure
+
+When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
+
+```
+<checker_issues>
+The issues below are in YAML format. Each has: dimension, severity, finding,
+affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
+issues where feasible.
+
+{YAML issues block from checker output -- passed verbatim}
+</checker_issues>
+
+<revision_instructions>
+Address ALL BLOCKER and WARNING issues identified above.
+- For each BLOCKER: make the required change
+- For each WARNING: address or explain why it's acceptable
+- Do NOT introduce new issues while fixing existing ones
+- Preserve all content not flagged by the checker
+This is revision iteration {N} of max 3. Previous iteration had {prev_count}
+issues. You must reduce the count or the loop will terminate.
+</revision_instructions>
+```
+
+### After 3 Iterations
+
+If issues persist after 3 revision cycles:
+
+1. Present remaining issues to the user
+2. Use gate prompt (pattern: yes-no from `references/gate-prompts.md`):
+   question: "Issues remain after 3 revision attempts. Proceed with current output?"
+   header: "Proceed?"
+   options:
+     - label: "Proceed anyway"   description: "Accept output with remaining issues"
+     - label: "Adjust approach"  description: "Discuss a different approach"
+3. If "Proceed anyway": accept current output and continue
+4. If "Adjust approach" or "Other": discuss with user, then re-enter the producing step with updated context
+
+### Workflow-Specific Variations
+
+| Workflow | Producer Agent | Checker Agent | Notes |
+|----------|---------------|---------------|-------|
+| plan-phase | gsd-planner | gsd-plan-checker | Revision prompt via planner-revision.md |
+| execute-phase | gsd-executor | gsd-verifier | Post-execution verification |
+| discuss-phase | orchestrator | gsd-plan-checker | Inline revision by orchestrator |
+
+---
+
+## Important Notes
+
+- **INFO-level issues are always acceptable** -- they don't trigger revision
+- **Each iteration gets a fresh agent spawn** -- don't try to continue in the same context
+- **Checker feedback must be inlined** -- the revision agent needs to see exactly what failed
+- **Don't silently swallow issues** -- always present the final state to the user after exiting the loop

package/.agent/skills/gsd/references/docs/thinking-models-debug.md

@@ -0,0 +1,44 @@
+# Thinking Models: Debug Cluster
+
+Structured reasoning models for the **debugger** agent. Apply these at decision points during investigation, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to GSD debugging workflow.
+
+## Conflict Resolution
+
+**Fault Tree and Hypothesis-Driven are sequential:** Fault Tree FIRST (generate the tree of possible causes), Hypothesis-Driven SECOND (test each branch systematically). Fault Tree provides the map; Hypothesis-Driven provides the discipline to traverse it.
+
+## 1. Fault Tree Analysis
+
+**Counters:** Jumping to conclusions without systematically mapping failure paths.
+
+Before testing any hypothesis, build a fault tree: start with the observed symptom as the root node, then branch into all possible causes at each level (hardware, software, configuration, data, environment). Use AND/OR gates -- some failures require multiple conditions (AND), others have independent triggers (OR). This tree becomes your investigation roadmap. Prioritize branches by likelihood and testability, but do NOT prune branches just because they seem unlikely -- unlikely causes that are easy to test should be tested early.
+
+## 2. Hypothesis-Driven Investigation
+
+**Counters:** Making random changes and hoping something works -- the "shotgun debugging" anti-pattern.
+
+For each hypothesis from the fault tree, follow the strict protocol: PREDICT ("If hypothesis H is correct, then test T should produce result R"), TEST (execute exactly one test), OBSERVE (record the actual result), CONCLUDE (matched = SUPPORTED, failed = ELIMINATED, unexpected = new evidence). Never skip the PREDICT step -- without a prediction, you cannot distinguish a meaningful result from noise. Never change more than one variable per test -- if you change two things and the bug disappears, you don't know which change fixed it.
+
+## 3. Occam's Razor
+
+**Counters:** Pursuing elaborate explanations when simple ones have not been ruled out.
+
+Before investigating complex multi-component interaction bugs, race conditions, or framework-level issues, verify the simple explanations first: typo in variable name, wrong file path, missing import, incorrect config value, stale cache, wrong environment variable. These "boring" causes account for the majority of bugs. Only escalate to complex hypotheses AFTER the simple ones are eliminated. If your current hypothesis requires 3+ things to go wrong simultaneously, step back and look for a single-point failure.
+
+## 4. Counterfactual Thinking
+
+**Counters:** Failing to isolate causation by not asking "what if we changed just this one thing?"
+
+When you have a hypothesis about the root cause, construct a counterfactual: "If I change ONLY this one variable/config/line, the bug should disappear (or appear)." Execute the counterfactual test. If the bug persists after your targeted change, your hypothesis is wrong -- the cause is elsewhere. If the bug disappears, you have strong causal evidence. This is more powerful than correlation ("the bug appeared after deploy X") because it tests the mechanism, not just the timeline.
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Obvious single-cause bugs** -- If the error message names the exact file, line, and cause (e.g., `TypeError: Cannot read property 'x' of undefined at foo.js:42`), fix it directly. Do not build a fault tree for a null reference with a stack trace.
+- **Reproducing a known fix** -- If you already know the root cause from a previous investigation or the user told you exactly what is wrong, skip hypothesis-driven investigation and go straight to the fix.
+- **Typos, missing imports, wrong paths** -- If Occam's Razor would immediately resolve it, apply the fix without invoking the full model. The model exists for when simple checks fail, not to gate simple checks.
+- **Reading error logs** -- Reading and understanding error output is normal debugging, not a "decision point." Only invoke models when you have multiple plausible hypotheses and need to choose which to test first.

package/.agent/skills/gsd/references/docs/thinking-models-execution.md

@@ -0,0 +1,50 @@
+# Thinking Models: Execution Cluster
+
+Structured reasoning models for the **executor** agent. Apply these at decision points during task execution, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to GSD execution workflow.
+
+## Conflict Resolution
+
+**Forcing Function and First Principles both push toward "do it now".** Run First Principles FIRST (understand the constraint), Forcing Function SECOND (create the mechanism). Sequential, not competing.
+
+## 1. Circle of Concern vs Circle of Control
+
+**Counters:** Executor trying to fix things outside its scope -- upstream bugs, unrelated tech debt, infrastructure issues.
+
+Before modifying any code not explicitly listed in the plan's `<files>` section, ask: Is this in my Circle of Control (plan scope) or my Circle of Concern (things I notice but shouldn't fix)? If Circle of Concern: document it as a deviation note or deferred item, do NOT fix it. The executor's job is to build what the plan says, not to improve the codebase. Scope creep from "while I'm here" fixes is the #1 cause of executor overruns.
+
+## 2. Forcing Function
+
+**Counters:** Deferring hard decisions to runtime instead of resolving them at build time.
+
+When you encounter an ambiguous requirement or unclear integration point, create a forcing function that makes the decision explicit NOW rather than hiding it behind a TODO or runtime check. Examples: use a TypeScript `never` type to force exhaustive switches, add a build-time assertion for required config values, create an interface that forces callers to handle error cases. If a decision truly cannot be made at build time, document it as a `checkpoint:decision` deviation -- do not silently defer.
+
+## 3. First Principles Thinking
+
+**Counters:** Copying patterns from existing code without understanding whether they fit the current task.
+
+Before copying a pattern from another file or phase, decompose WHY that pattern exists: What constraint does it satisfy? Does your current task have the same constraint? If not, the pattern may be cargo cult. Build your implementation from the task's actual requirements, not from the nearest existing example. When in doubt, the plan's `<action>` steps define what to build -- derive the implementation from those, not from adjacent code.
+
+## 4. Occam's Razor
+
+**Counters:** Over-engineering simple tasks with unnecessary abstractions, generics, or future-proofing.
+
+Before adding an abstraction layer, generic type parameter, factory pattern, or configuration option, ask: Does the plan REQUIRE this flexibility? If the plan says "create a function that does X", create a function that does X -- not a configurable, extensible, pluggable framework that could theoretically do X through Y through Z. The simplest implementation that satisfies the plan's `<done>` condition is the correct one. Add complexity only when the plan explicitly calls for it.
+
+## 5. Chesterton's Fence
+
+**Counters:** Removing or modifying existing code without understanding why it was written that way.
+
+Before removing, replacing, or significantly modifying existing code that the plan touches, determine WHY it exists. Check: git blame for the commit that introduced it, comments explaining the rationale, test cases that exercise it, the PLAN.md or SUMMARY.md that created it. If the purpose is unclear, keep it and add a comment noting the uncertainty -- do NOT remove code whose purpose you don't understand. If the plan explicitly says to remove it, still document what it did in the deviation notes.
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Straightforward task actions** -- If the plan says "create file X with content Y" and the action is unambiguous, execute it directly. Do not invoke First Principles to analyze why you are creating a file the plan told you to create.
+- **Following established project patterns** -- If the codebase has a clear, consistent pattern (e.g., every route handler follows the same structure) and the plan says to add another one, follow the pattern. Chesterton's Fence applies to removing patterns, not to following them.
+- **Trivial file edits** -- Adding an import, fixing a typo, updating a version number. These are mechanical changes that do not involve design decisions.
+- **Running verify commands** -- Executing the plan's `<verify>` steps is procedural. Only invoke models if a verify step fails and you need to decide how to respond.

package/.agent/skills/gsd/references/docs/thinking-models-planning.md

@@ -0,0 +1,62 @@
+# Thinking Models: Planning Cluster
+
+Structured reasoning models for the **planner** and **roadmapper** agents. Apply these at decision points during plan creation, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to GSD planning workflow.
+
+## Conflict Resolution
+
+Pre-Mortem and Constraint Analysis both analyze risk at different granularities. Run Constraint Analysis FIRST (identify the hardest constraint), then Pre-Mortem (enumerate failure modes around that constraint and the rest of the plan).
+
+## 1. Pre-Mortem Analysis
+
+**Counters:** Optimistic plan decomposition that ignores failure modes.
+
+Before finalizing this plan, assume it has already failed. List the 3 most likely reasons for failure -- missing dependency, wrong decomposition, underestimated complexity -- and add mitigation steps or acceptance criteria that would catch each failure early.
+
+## 2. MECE Decomposition
+
+**Counters:** Overlapping tasks (merge conflicts) or gapped tasks (missing requirements).
+
+Verify this task breakdown is MECE at the REQUIREMENT level: (1) list every requirement from the phase goal, (2) confirm each maps to exactly one task's `<done>`, (3) if two tasks modify the same file, confirm they modify DIFFERENT sections or serve DIFFERENT requirements, (4) flag any requirement not covered by any task.
+
+## 3. Constraint Analysis
+
+**Counters:** Deferring the hardest constraint to the last task, causing late-stage failures.
+
+Identify the single hardest constraint in this phase -- the one thing that, if it doesn't work, makes everything else irrelevant. Schedule that constraint as Task 1 or 2, not last. If the constraint involves an external API or unfamiliar library, add a spike/proof-of-concept task before the main implementation.
+
+## 4. Reversibility Test
+
+**Counters:** Over-analyzing cheap decisions, under-analyzing costly ones.
+
+For each significant decision in this plan, classify as REVERSIBLE (can change later with low cost) or IRREVERSIBLE (changing later requires migration, breaking changes, or significant rework). Spend analysis time proportional to irreversibility. For irreversible decisions, document the rationale in the plan.
+
+## 5. Curse of Knowledge Counter
+
+**Counters:** Plan-to-executor ambiguity from compressed instructions.
+
+For each `<action>` step, re-read it as if you have NEVER seen this codebase. Is every noun unambiguous (which file? which function? which endpoint?)? Is every verb specific (add WHERE? modify HOW?)? If a step could be interpreted two ways, rewrite it. Include file paths, function names, and expected behavior in every action step.
+
+## 6. Base Rate Neglect Counter
+
+**Counters:** Planners ignoring low-confidence research caveats.
+
+Before finalizing the plan, read ALL `[NEEDS DECISION]` items and LOW-confidence recommendations from SUMMARY.md. For each: either (a) create a `checkpoint:decision` task to resolve it, or (b) document why the risk is acceptable in the plan's deviation notes. LOW-confidence items that are silently accepted become undocumented technical debt.
+
+## Gap Closure Mode: Root-Cause Check
+
+**Applies only when:** Planner enters gap closure mode (triggered by `gaps_found` in VERIFICATION.md).
+
+Before writing the fix plan, apply a single "why" round: Why did this gap occur? Was it a plan deficiency (wrong task), an execution miss (correct task, wrong implementation), or a changed assumption (environment/dependency shift)? The fix plan must target the root cause category, not just the symptom.
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Single-task plans** -- If the phase has one clear requirement and one obvious task, do not run Pre-Mortem or MECE analysis. Write the task directly.
+- **Well-researched phases** -- If RESEARCH.md has HIGH-confidence recommendations for every decision and no `[NEEDS DECISION]` items, skip Base Rate Neglect Counter. The research already resolved uncertainty.
+- **Revision iterations** -- When revising a plan based on checker feedback, focus on fixing the flagged issues. Do not re-run the full model suite on every revision pass -- apply only the model relevant to the specific issue (e.g., MECE if the checker found a coverage gap).
+- **Boilerplate plans** -- Configuration changes, version bumps, documentation updates. These do not have failure modes worth pre-mortem analysis.