gsd-opencode 1.30.0 → 1.33.0

package/get-shit-done/references/domain-probes.md

@@ -0,0 +1,125 @@
+# Domain-Aware Probing Patterns
+
+Shared reference for `/gsd-begin`, `/gsd-discuss-phase`, and domain exploration workflows.
+
+When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist -- pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
+
+---
+
+## Authentication
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "login" or "auth" | OAuth (which providers?), JWT, or session-based? Do you need social login or just email/password? |
+| "users" or "accounts" | MFA required? Password reset flow? Email verification? |
+| "sessions" | Session duration and refresh strategy? Server-side sessions or stateless tokens? |
+| "roles" or "permissions" | RBAC, ABAC, or simple role checks? How many distinct roles? |
+| "API keys" | Key rotation strategy? Scoped permissions per key? Rate limiting per key? |
+
+---
+
+## Real-Time Updates
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "real-time" or "live updates" | WebSockets, SSE, or polling? What specifically needs to be real-time vs. eventual? |
+| "notifications" | Push notifications (browser/mobile), in-app only, or both? Persistence and read receipts? |
+| "collaboration" or "multiplayer" | Conflict resolution strategy? Operational transforms or CRDTs? Expected concurrent users? |
+| "chat" or "messaging" | Message history and search? Typing indicators? read receipts? |
+| "streaming" | Reconnection strategy? What happens when the connection drops -- queue or discard? |
+
+---
+
+## Dashboard
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "dashboard" | What data sources feed it? How many distinct views? |
+| "charts" or "graphs" | Interactive or static? Drill-down capability? Export to CSV/PDF? |
+| "metrics" or "KPIs" | Refresh strategy -- real-time, periodic polling, or on-demand? Acceptable staleness? |
+| "admin panel" | Role-based visibility? Which actions beyond viewing (edit, delete, approve)? |
+| "mobile" or "responsive" | Simplified mobile view or full parity? Touch interactions for charts? |
+
+---
+
+## API Design
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "API" | REST, GraphQL, or RPC-style? Internal only or public-facing? |
+| "endpoints" or "routes" | Versioning strategy (URL path, header, query param)? Breaking change policy? |
+| "pagination" | Cursor-based or offset? Expected result set sizes? Stable ordering guarantee? |
+| "rate limiting" | Per-user, per-IP, or per-API-key? Burst allowance? How to communicate limits to clients? |
+| "errors" | Structured error format? Error codes vs. messages? How much detail in production errors? |
+
+---
+
+## Database
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "database" or "storage" | SQL or NoSQL? What drives the choice -- relational integrity, flexibility, scale? |
+| "ORM" or "queries" | ORM (which one?) or raw queries? Query builder as middle ground? |
+| "migrations" | Migration tool? Rollback strategy? How do you handle data migrations vs. schema migrations? |
+| "seeding" or "test data" | Seed data for development? Realistic fake data or minimal fixtures? |
+| "scale" or "performance" | read/write ratio? read replicas? Connection pooling strategy? |
+
+---
+
+## Search
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "search" | Full-text or exact match? Dedicated search engine (Elasticsearch, Meilisearch) or database-level? |
+| "filtering" or "facets" | Faceted filtering? How many filter dimensions? Combined filters (AND/OR)? |
+| "autocomplete" or "typeahead" | Debounce strategy? Minimum character threshold? Result ranking? |
+| "indexing" | Index size and update frequency? Real-time indexing or batch? Acceptable index lag? |
+| "fuzzy" or "typo tolerance" | Fuzzy matching? Synonym support? Language-specific stemming? |
+
+---
+
+## File Upload/Storage
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "upload" or "file upload" | Local filesystem or cloud (S3, GCS, Azure Blob)? Direct upload or through server? |
+| "images" or "media" | Processing pipeline -- resize, compress, thumbnail generation? Format conversion? |
+| "size limits" | Max file size? Max total storage per user? What happens when limits are hit? |
+| "CDN" | CDN for delivery? Cache invalidation for updated files? Signed URLs for access control? |
+| "documents" or "attachments" | Virus scanning? Preview generation? Versioning of uploaded files? |
+
+---
+
+## Caching
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "caching" or "performance" | Where to cache -- browser, CDN, application layer, database query cache? |
+| "invalidation" | Invalidation strategy -- TTL, event-driven, or manual? Cache-aside vs. write-through? |
+| "stale data" | Acceptable staleness window? Stale-while-revalidate pattern? |
+| "Redis" or "Memcached" | Cache topology -- single node or clustered? Persistence needed or pure cache? |
+| "CDN" or "edge" | Edge caching for static assets? Dynamic content at the edge? Cache key strategy? |
+
+---
+
+## Testing
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "testing" or "tests" | Unit, integration, and E2E balance? Where do you invest most testing effort? |
+| "mocking" or "stubs" | Mock external services or use test containers? Database mocking strategy? |
+| "CI" or "pipeline" | Tests in CI? Parallel test execution? Test-on-PR or test-on-push? |
+| "coverage" | Coverage targets? Coverage as gate or advisory? Which metrics (line, branch, function)? |
+| "E2E" or "browser testing" | Playwright, Cypress, or other? Headed vs. headless? Visual regression testing? |
+
+---
+
+## Deployment
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "deploy" or "hosting" | Container, serverless, or traditional VM/VPS? Managed platform (Vercel, Railway) or self-hosted? |
+| "CI/CD" or "pipeline" | GitHub Actions, GitLab CI, or other? Deploy on merge to main or manual trigger? |
+| "environments" | How many environments (dev, staging, prod)? Environment parity strategy? |
+| "rollback" | Rollback strategy? Blue-green, canary, or instant rollback? Database rollback considerations? |
+| "secrets" or "config" | Secret management -- env vars, vault, or platform-native? Per-environment config strategy? |

package/get-shit-done/references/gate-prompts.md

@@ -0,0 +1,100 @@
+# Gate Prompt Patterns
+
+Reusable prompt patterns for structured gate checks in workflows and agents.
+
+**For checkpoint box format details, see `references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
+
+## Rules
+
+- `header` must be max 12 characters
+- `multiSelect` is always `false` for gate checks
+- Always handle the "Other" case (user typed a freeform response instead of selecting)
+- Max 4 options per prompt -- if more are needed, use a 2-step flow
+
+---
+
+## Pattern: approve-revise-abort
+3-option gate for plan approval, gap-closure approval.
+- question: "Approve these {noun}?"
+- header: "Approve?"
+- options: Approve | Request changes | Abort
+
+## Pattern: yes-no
+Simple 2-option confirmation for re-planning, rebuild, replace plans, commit.
+- question: "{Specific question about the action}"
+- header: "Confirm"
+- options: Yes | No
+
+## Pattern: stale-continue
+2-option refresh gate for staleness warnings, timestamp freshness.
+- question: "{Artifact} may be outdated. Refresh or continue?"
+- header: "Stale"
+- options: Refresh | Continue anyway
+
+## Pattern: yes-no-pick
+3-option selection for seed selection, item inclusion.
+- question: "Include {items} in planning?"
+- header: "Include?"
+- options: Yes, all | Let me pick | No
+
+## Pattern: multi-option-failure
+4-option failure handler for build failures.
+- question: "Plan {id} failed. How should we proceed?"
+- header: "Failed"
+- options: Retry | Skip | Rollback | Abort
+
+## Pattern: multi-option-escalation
+4-option escalation for review escalation (max retries exceeded).
+- question: "Phase {N} has failed verification {attempt} times. How should we proceed?"
+- header: "Escalate"
+- options: Accept gaps | Re-plan (via /gsd-plan-phase) | Debug (via /gsd-debug) | Retry
+
+## Pattern: multi-option-gaps
+4-option gap handler for review gaps-found.
+- question: "{count} verification gaps need attention. How should we proceed?"
+- header: "Gaps"
+- options: Auto-fix | Override | Manual | Skip
+
+## Pattern: multi-option-priority
+4-option priority selection for milestone gap priority.
+- question: "Which gaps should we address?"
+- header: "Priority"
+- options: Must-fix only | Must + should | Everything | Let me pick
+
+## Pattern: toggle-confirm
+2-option confirmation for enabling/disabling boolean features.
+- question: "Enable {feature_name}?"
+- header: "Toggle"
+- options: Enable | Disable
+
+## Pattern: action-routing
+Up to 4 suggested next actions with selection (status, resume workflows).
+- question: "What would you like to do next?"
+- header: "Next Step"
+- options: {primary action} | {alternative 1} | {alternative 2} | Something else
+- Note: Dynamically generate options from workflow state. Always include "Something else" as last option.
+
+## Pattern: scope-confirm
+3-option confirmation for quick task scope validation.
+- question: "This task looks complex. Proceed as quick task or use full planning?"
+- header: "Scope"
+- options: Quick task | Full plan (via /gsd-plan-phase) | Revise
+
+## Pattern: depth-select
+3-option depth selection for planning workflow preferences.
+- question: "How thorough should planning be?"
+- header: "Depth"
+- options: Quick (3-5 phases, skip research) | Standard (5-8 phases, default) | Comprehensive (8-12 phases, deep research)
+
+## Pattern: context-handling
+3-option handler for existing CONTEXT.md in discuss workflow.
+- question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
+- header: "Context"
+- options: Overwrite | Append | Cancel
+
+## Pattern: gray-area-option
+Dynamic template for presenting gray area choices in discuss workflow.
+- question: "{Gray area title}"
+- header: "Decision"
+- options: {Option 1} | {Option 2} | Let OpenCode decide
+- Note: Options generated at runtime. Always include "Let OpenCode decide" as last option.

package/get-shit-done/references/model-profiles.md

@@ -39,11 +39,11 @@ Model profiles control which OpenCode model each GSD agent uses. This allows bal
 
 **inherit** - Follow the current session model
 - All agents resolve to `inherit`
-- Best when you switch models interactively (for example OpenCode `/model`)
+- Best when you switch models interactively (for example OpenCode or Kilo `/model`)
 - **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise GSD may call Anthropic models directly, incurring unexpected costs
 - Use when: you want GSD to follow your currently selected runtime model
 
-## Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI)
+## Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
 
 When installed for a non-OpenCode runtime, the GSD installer sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed.
 

package/get-shit-done/references/planner-gap-closure.md

@@ -0,0 +1,62 @@
+# Gap Closure Mode — Planner Reference
+
+Triggered by `--gaps` flag. Creates plans to address verification or UAT failures.
+
+**Important: Skip deferred items.** When reading VERIFICATION.md, only the `gaps:` section contains actionable items that need closure plans. The `deferred:` section (if present) lists items explicitly addressed in later milestone phases — these are NOT gaps and must be ignored during gap closure planning. Creating plans for deferred items wastes effort on work already scheduled for future phases.
+
+**1. Find gap sources:**
+
+Use init context (from load_project_state) which provides `phase_dir`:
+
+```bash
+# Check for VERIFICATION.md (code verification gaps)
+ls "$phase_dir"/*-VERIFICATION.md 2>/dev/null
+
+# Check for UAT.md with diagnosed status (user testing gaps)
+grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
+```
+
+**2. Parse gaps:** Each gap has: truth (failed behavior), reason, artifacts (files with issues), missing (things to add/fix).
+
+**3. Load existing SUMMARYs** to understand what's already built.
+
+**4. Find next plan number:** If plans 01-03 exist, next is 04.
+
+**5. Group gaps into plans** by: same artifact, same concern, dependency order (can't wire if artifact is stub → fix stub first).
+
+**6. Create gap closure tasks:**
+
+```xml
+<task name="{fix_description}" type="auto">
+  <files>{artifact.path}</files>
+  <action>
+    {For each item in gap.missing:}
+    - {missing item}
+
+    Reference existing code: {from SUMMARYs}
+    Gap reason: {gap.reason}
+  </action>
+  <verify>{How to confirm gap is closed}</verify>
+  <done>{Observable truth now achievable}</done>
+</task>
+```
+
+**7. Assign waves using standard dependency analysis** (same as `assign_waves` step):
+- Plans with no dependencies → wave 1
+- Plans that depend on other gap closure plans → max(dependency waves) + 1
+- Also consider dependencies on existing (non-gap) plans in the phase
+
+**8. write PLAN.md files:**
+
+```yaml
+---
+phase: XX-name
+plan: NN              # Sequential after existing
+type: execute
+wave: N               # Computed from depends_on (see assign_waves)
+depends_on: [...]     # Other plans this depends on (gap or existing)
+files_modified: [...]
+autonomous: true
+gap_closure: true     # Flag for tracking
+---
+```

package/get-shit-done/references/planner-reviews.md

@@ -0,0 +1,39 @@
+# Reviews Mode — Planner Reference
+
+Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with REVIEWS.md feedback as additional context.
+
+**Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
+
+### Step 1: Load REVIEWS.md
+read the reviews file from `<files_to_read>`. Parse:
+- Per-reviewer feedback (strengths, concerns, suggestions)
+- Consensus Summary (agreed concerns = highest priority to address)
+- Divergent Views (investigate, make a judgment call)
+
+### Step 2: Categorize Feedback
+Group review feedback into:
+- **Must address**: HIGH severity consensus concerns
+- **Should address**: MEDIUM severity concerns from 2+ reviewers
+- **Consider**: Individual reviewer suggestions, LOW severity items
+
+### Step 3: Plan Fresh with Review Context
+Create new plans following the standard planning process, but with review feedback as additional constraints:
+- Each HIGH severity consensus concern MUST have a task that addresses it
+- MEDIUM concerns should be addressed where feasible without over-engineering
+- Note in task actions: "Addresses review concern: {concern}" for traceability
+
+### Step 4: Return
+Use standard PLANNING COMPLETE return format, adding a reviews section:
+
+```markdown
+### Review Feedback Addressed
+
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```

package/get-shit-done/references/planner-revision.md

@@ -0,0 +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
+node "$HOME/.config/opencode/get-shit-done/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.} |
+```

package/get-shit-done/references/planning-config.md

@@ -10,9 +10,17 @@ Configuration options for `.planning/` directory behavior.
 },
 "git": {
   "branching_strategy": "none",
+  "base_branch": null,
   "phase_branch_template": "gsd/phase-{phase}-{slug}",
   "milestone_branch_template": "gsd/{milestone}-{slug}",
   "quick_branch_template": null
+},
+"manager": {
+  "flags": {
+    "discuss": "",
+    "plan": "",
+    "execute": ""
+  }
 }
 ```
 
@@ -21,9 +29,16 @@ Configuration options for `.planning/` directory behavior.
 | `commit_docs` | `true` | Whether to commit planning artifacts to git |
 | `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
 | `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.base_branch` | `null` (auto-detect) | Target branch for PRs and merges (e.g. `"master"`, `"develop"`). When `null`, auto-detects from `git symbolic-ref refs/remotes/origin/HEAD`, falling back to `"main"`. |
 | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `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.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. |
 </config_schema>
 
 <commit_docs_behavior>

package/get-shit-done/references/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/get-shit-done/references/ui-brand.md

@@ -108,9 +108,9 @@ Always at end of major completions.
 
 **{Identifier}: {Name}** — {one-line description}
 
-`{copy-paste command}`
+`/new` then:
 
-*`/new` first → fresh context window*
+`{copy-paste command}`
 
 ───────────────────────────────────────────────────────────────
 

package/get-shit-done/references/universal-anti-patterns.md

@@ -0,0 +1,58 @@
+# Universal Anti-Patterns
+
+Rules that apply to ALL workflows and agents. Individual workflows may have additional specific anti-patterns.
+
+---
+
+## Context Budget Rules
+
+1. **Never** read agent definition files (`agents/*.md`) -- `@<custom_agent>` call auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
+2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
+3. **read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
+5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## File Reading Rules
+
+6. **SUMMARY.md read depth scales with context window** -- at context_window_tokens < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
+7. **Never** read full PLAN.md files from other phases -- only current phase plans.
+8. **Never** read `.planning/logs/` files -- only the health workflow reads these.
+9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields. Exception: at >= 500000, re-reading full body is acceptable when semantic content is needed.
+
+## Subagent Rules
+
+10. **NEVER** use non-GSD agent types (`general`, `Explore`, `Plan`, `bash`, `feature-dev`, etc.) -- ALWAYS use `@gsd-{agent}` call (e.g., `@gsd-phase-researcher`, `@gsd-executor`, `@gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
+11. **Do not** re-litigate decisions that are already locked in CONTEXT.md (or PROJECT.md ## Context section) -- respect locked decisions unconditionally.
+
+## Questioning Anti-Patterns
+
+Reference: `references/questioning.md` for the full anti-pattern list.
+
+12. **Do not** walk through checklists -- checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
+13. **Do not** use corporate speak -- avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
+14. **Do not** apply premature constraints -- don't narrow the solution space before understanding the problem. Ask about the problem first, then constrain.
+
+## State Management Anti-Patterns
+
+15. **No direct write/edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+
+## Behavioral Rules
+
+16. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
+17. **Do not** modify files outside the workflow's stated scope -- check the plan's files_modified list.
+18. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
+19. **Do not** use `git add .` or `git add -A` -- stage specific files only.
+20. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules
+
+21. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically).
+22. **Config fallback awareness**: Config loading returns `null` silently on invalid JSON. If your workflow depends on config values, check for null and warn the user: "config.json is invalid or missing -- running with defaults."
+23. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest diagnosing the mismatch.
+
+## GSD-Specific Rules
+
+24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
+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.