@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/references/thinking-partner.md

@@ -0,0 +1,96 @@
+# Thinking Partner Integration
+
+Conditional extended thinking at workflow decision points. Activates when `features.thinking_partner: true` in `.planning/config.json` (default: false).
+
+---
+
+## Tradeoff Detection Signals
+
+The thinking partner activates when developer responses contain specific signals indicating competing priorities:
+
+**Keyword signals:**
+- "or" / "versus" / "vs" connecting two approaches
+- "tradeoff" / "trade-off" / "tradeoffs"
+- "on one hand" / "on the other hand"
+- "pros and cons"
+- "not sure between" / "torn between"
+
+**Structural signals:**
+- Developer lists 2+ competing options
+- Developer asks "which is better" or "what would you recommend"
+- Developer reverses a previous decision ("actually, maybe we should...")
+
+**When NOT to activate:**
+- Developer has already made a clear choice
+- The "or" is rhetorical or trivial (e.g., "tabs or spaces" — use project convention)
+- Simple yes/no questions
+- Developer explicitly asks to move on
+
+---
+
+## Integration Points
+
+### 1. Discuss Phase — Tradeoff Deep-Dive
+
+**When:** During `discuss_areas` step, after a developer answer reveals competing priorities.
+
+**What:** Pause the normal question flow and offer a brief structured analysis:
+```
+I notice competing priorities here — {X} optimizes for {A} while {Y} optimizes for {B}.
+
+Want me to think through the tradeoffs before we decide?
+[Yes, analyze tradeoffs] / [No, I've decided]
+```
+
+If yes, provide a brief (3-5 bullet) analysis covering:
+- What each approach optimizes for
+- What each approach sacrifices
+- Which aligns better with the project's stated goals (from PROJECT.md)
+- A recommendation with reasoning
+
+Then return to the normal discussion flow.
+
+### 2. Plan Phase — Architectural Decision Analysis
+
+**When:** During step 11 (Handle Checker Return), when the plan-checker flags issues containing architectural tradeoff keywords.
+
+**What:** Before sending to the revision loop, analyze the architectural decision:
+```
+The plan-checker flagged an architectural tradeoff: {issue description}
+
+Brief analysis:
+- Option A: {approach} — {pros/cons}
+- Option B: {approach} — {pros/cons}
+- Recommendation: {choice} because {reasoning aligned with phase goals}
+
+Apply this recommendation to the revision? [Yes] / [No, let me decide]
+```
+
+### 3. Explore — Approach Comparison (requires #1729)
+
+**When:** During Socratic conversation, when multiple viable approaches emerge.
+**Note:** This integration point will be added when /gsd:explore (#1729) lands.
+
+---
+
+## Configuration
+
+```json
+{
+  "features": {
+    "thinking_partner": true
+  }
+}
+```
+
+Default: `false`. The thinking partner is opt-in because it adds latency to interactive workflows.
+
+---
+
+## Design Principles
+
+1. **Lightweight** — inline analysis, not a separate interactive session
+2. **Opt-in** — must be explicitly enabled, never activates by default
+3. **Skippable** — always offer "No, I've decided" to bypass
+4. **Brief** — 3-5 bullets max, not a full research report
+5. **Aligned** — recommendations reference PROJECT.md goals when available

package/get-shit-done/references/ui-brand.md

@@ -0,0 +1,160 @@
+<ui_patterns>
+
+Visual patterns for user-facing GSD output. Orchestrators @-reference this file.
+
+## Stage Banners
+
+Use for major workflow transitions.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► {STAGE NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Stage names (uppercase):**
+- `QUESTIONING`
+- `RESEARCHING`
+- `DEFINING REQUIREMENTS`
+- `CREATING ROADMAP`
+- `PLANNING PHASE {N}`
+- `EXECUTING WAVE {N}`
+- `VERIFYING`
+- `PHASE {N} COMPLETE ✓`
+- `MILESTONE COMPLETE 🎉`
+
+---
+
+## Checkpoint Boxes
+
+User action required. 62-character width.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Content}
+
+──────────────────────────────────────────────────────────────
+→ {ACTION PROMPT}
+──────────────────────────────────────────────────────────────
+```
+
+**Types:**
+- `CHECKPOINT: Verification Required` → `→ Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` → `→ Select: option-a / option-b`
+- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
+
+---
+
+## Status Symbols
+
+```
+✓  Complete / Passed / Verified
+✗  Failed / Missing / Blocked
+◆  In Progress
+○  Pending
+⚡ Auto-approved
+⚠  Warning
+🎉 Milestone complete (only in banner)
+```
+
+---
+
+## Progress Display
+
+**Phase/milestone level:**
+```
+Progress: ████████░░ 80%
+```
+
+**Task level:**
+```
+Tasks: 2/4 complete
+```
+
+**Plan level:**
+```
+Plans: 3/5 complete
+```
+
+---
+
+## Spawning Indicators
+
+```
+◆ Spawning researcher...
+
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+
+✓ Researcher complete: STACK.md written
+```
+
+---
+
+## Next Up Block
+
+Always at end of major completions.
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{Identifier}: {Name}** — {one-line description}
+
+`/clear` then:
+
+`{copy-paste command}`
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/gsd-alternative-1` — description
+- `/gsd-alternative-2` — description
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## Error Box
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Tables
+
+```
+| Phase | Status | Plans | Progress |
+|-------|--------|-------|----------|
+| 1     | ✓      | 3/3   | 100%     |
+| 2     | ◆      | 1/4   | 25%      |
+| 3     | ○      | 0/2   | 0%       |
+```
+
+---
+
+## Anti-Patterns
+
+- Varying box/banner widths
+- Mixing banner styles (`===`, `---`, `***`)
+- Skipping `GSD ►` prefix in banners
+- Random emoji (`🚀`, `✨`, `💫`)
+- Missing Next Up block after completions
+
+</ui_patterns>

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

@@ -0,0 +1,63 @@
+# 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`) -- `subagent_type` 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` 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 < 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-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "gsd-{agent}"` (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 query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. 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. **Prefer `gsd-tools query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
+26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
+27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
+
+## iOS / Apple Platform Rules
+
+28. **NEVER use `Package.swift` + `.executableTarget` (or `.target`) as the primary build system for iOS apps.** SPM executable targets produce macOS CLI binaries, not iOS `.app` bundles. They cannot be installed on iOS devices or submitted to the App Store. Use XcodeGen (`project.yml` + `xcodegen generate`) to create a proper `.xcodeproj`. See `references/ios-scaffold.md` for the full pattern.
+29. **Verify SwiftUI API availability before use.** Many SwiftUI APIs require a specific minimum iOS version (e.g., `NavigationSplitView` is iOS 16+, `List(selection:)` with multi-select and `@Observable` require iOS 17). If a plan uses an API that exceeds the declared `IPHONEOS_DEPLOYMENT_TARGET`, raise the deployment target or add `#available` guards.