@opengsd/get-shit-done-redux 1.0.0

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/scout-codebase.md

@@ -0,0 +1,51 @@
+# Codebase scout — map selection table
+
+> Lazy-loaded reference for the `scout_codebase` step in
+> `workflows/discuss-phase.md` (extracted via #2551 progressive-disclosure
+> refactor). Read this only when prior `.planning/codebase/*.md` maps exist
+> and the workflow needs to pick which 2–3 to load.
+
+## Phase-type → recommended maps
+
+Read 2–3 maps based on inferred phase type. Do NOT read all seven —
+that inflates context without improving discussion quality.
+
+| Phase type (infer from title + ROADMAP entry) | Read these maps |
+|---|---|
+| UI / frontend / styling / design | CONVENTIONS.md, STRUCTURE.md, STACK.md |
+| Backend / API / service / data model | STACK.md, ARCHITECTURE.md, INTEGRATIONS.md |
+| Integration / third-party / provider | STACK.md, INTEGRATIONS.md, ARCHITECTURE.md |
+| Infrastructure / DevOps / CI / deploy | STACK.md, ARCHITECTURE.md, INTEGRATIONS.md |
+| Testing / QA / coverage | TESTING.md, CONVENTIONS.md, STRUCTURE.md |
+| Documentation / content | CONVENTIONS.md, STRUCTURE.md |
+| Mixed / unclear | STACK.md, ARCHITECTURE.md, CONVENTIONS.md |
+
+Read CONCERNS.md only if the phase explicitly addresses known concerns or
+security issues.
+
+## Single-read rule
+
+Read each map file in a **single** Read call. Do not read the same file at
+two different offsets — split reads break prompt-cache reuse and cost more
+than a single full read.
+
+## No-maps fallback
+
+If `.planning/codebase/*.md` does not exist:
+1. Extract key terms from the phase goal (e.g., "feed" → "post", "card",
+   "list"; "auth" → "login", "session", "token")
+2. `grep -rlE "{term1}|{term2}" src/ app/ --include="*.ts" ...` (use `-E`
+   for extended regex so the `|` alternation works on both GNU grep and BSD
+   grep / macOS), and `ls` the conventional component/hook/util dirs
+3. Read the 3–5 most relevant files
+
+## Output (internal `<codebase_context>`)
+
+From the scan, identify:
+- **Reusable assets** — components, hooks, utilities usable in this phase
+- **Established patterns** — state management, styling, data fetching
+- **Integration points** — routes, nav, providers where new code connects
+- **Creative options** — approaches the architecture enables or constrains
+
+Used in `analyze_phase` and `present_gray_areas`. NOT written to a file —
+session-only.

package/get-shit-done/references/skeleton-template.md

@@ -0,0 +1,48 @@
+# SKELETON.md Template
+
+> Emitted by `gsd-planner` when `WALKING_SKELETON=true` (Phase 1 + `--mvp` + new project). Records the architectural decisions the rest of the project will build on.
+
+```markdown
+# Walking Skeleton — [Project Name]
+
+**Phase:** 1
+**Generated:** {ISO date}
+
+## Capability Proven End-to-End
+
+> One sentence: the smallest user-visible capability that exercises the full stack.
+
+Example: "A signed-in user can view their email on a dashboard page served by the deployed app."
+
+## Architectural Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Framework | (e.g., Next.js 15 App Router) | Why this fits the project |
+| Data layer | (e.g., Postgres + Drizzle) | Why |
+| Auth | (e.g., session cookies + bcrypt) | Why |
+| Deployment target | (e.g., Vercel preview) | Why |
+| Directory layout | (e.g., feature-folders under src/features/*) | Why |
+
+## Stack Touched in Phase 1
+
+- [ ] Project scaffold (framework, build, lint, test runner)
+- [ ] Routing — at least one real route
+- [ ] Database — at least one real read AND one real write
+- [ ] UI — at least one interactive element wired to the API
+- [ ] Deployment — running on dev environment OR documented local full-stack run command
+
+## Out of Scope (Deferred to Later Slices)
+
+> Anything that is *not* in the skeleton. Be explicit — this list prevents future phases from re-litigating Phase 1's minimalism.
+
+- (e.g., password reset, email verification, multi-tenancy)
+
+## Subsequent Slice Plan
+
+Each later phase adds one vertical slice on top of this skeleton without altering its architectural decisions:
+
+- Phase 2: [next user capability]
+- Phase 3: [next user capability]
+- ...
+```

package/get-shit-done/references/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/get-shit-done/references/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/get-shit-done/references/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).

package/get-shit-done/references/sketch-variant-patterns.md

@@ -0,0 +1,81 @@
+# Multi-Variant HTML Patterns
+
+Every sketch produces 2-3 variants in the same HTML file. The user switches between them to compare.
+
+## Tab-Based Variants
+
+The standard approach: a tab bar at the top of the page, each tab shows a different variant.
+
+```html
+<div id="variant-nav" style="position:fixed;top:0;left:0;right:0;z-index:9998;background:var(--color-surface, #fff);border-bottom:1px solid var(--color-border, #e5e5e5);padding:8px 16px;display:flex;gap:8px;font-family:system-ui;">
+  <button class="variant-tab active" onclick="showVariant('a')">A: Sidebar Layout</button>
+  <button class="variant-tab" onclick="showVariant('b')">B: Top Nav</button>
+  <button class="variant-tab" onclick="showVariant('c')">C: Floating Panels</button>
+</div>
+
+<div id="variant-a" class="variant active">
+  <!-- Variant A content -->
+</div>
+<div id="variant-b" class="variant" style="display:none">
+  <!-- Variant B content -->
+</div>
+<div id="variant-c" class="variant" style="display:none">
+  <!-- Variant C content -->
+</div>
+
+<script>
+function showVariant(id) {
+  document.querySelectorAll('.variant').forEach(v => v.style.display = 'none');
+  document.querySelectorAll('.variant-tab').forEach(t => t.classList.remove('active'));
+  document.getElementById('variant-' + id).style.display = 'block';
+  event.target.classList.add('active');
+}
+</script>
+```
+
+Add `padding-top` to the body to account for the fixed tab bar.
+
+## Marking the Winner
+
+After the user picks a direction, add a visual indicator to the winning tab:
+
+```html
+<button class="variant-tab active">A: Sidebar Layout ★ Selected</button>
+```
+
+Keep all variants visible and navigable — the winner is highlighted, not the only option.
+
+## Side-by-Side (for small variants)
+
+When comparing small elements (button styles, card layouts, icon treatments), render them next to each other with labels rather than using tabs:
+
+```html
+<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:24px;padding:24px;">
+  <div>
+    <h3>A: Rounded</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>B: Sharp</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>C: Pill</h3>
+    <!-- variant content -->
+  </div>
+</div>
+```
+
+## Variant Count
+
+- **First round (dramatic):** 2-3 meaningfully different approaches
+- **Refinement rounds:** 2-3 subtle variations within the chosen direction
+- **Never more than 4** — more than that overwhelms. If there are 5+ options, narrow before showing.
+
+## Synthesis Variants
+
+When the user cherry-picks elements across variants, create a new variant tab labeled descriptively:
+
+```html
+<button class="variant-tab" onclick="showVariant('synth1')">Synthesis: A's layout + C's palette</button>
+```

package/get-shit-done/references/spidr-splitting.md

@@ -0,0 +1,69 @@
+# SPIDR Story Splitting Rules
+
+> Used by `mvp-phase` workflow when the user-supplied story is too large for a single phase. Per PRD decision Q3, SPIDR runs as a **full interactive flow** — not a lightweight check.
+
+## When SPIDR triggers
+
+Trigger SPIDR splitting if **any** of these size signals fire on the user story:
+
+1. **Compound capabilities.** The story names two or more independent user actions joined by "and" (e.g., "register **and** log in **and** reset their password"). Each "and" is a candidate split point.
+2. **Multi-actor.** The story names more than one `[user role]` (e.g., "As a user or admin..."). Each role is a candidate split.
+3. **Length.** The assembled story exceeds ~120 chars on a single line.
+4. **Vague capability.** The capability is a noun phrase, not a verb-noun pair (e.g., "I want to use the dashboard" — needs to specify *which interaction* with the dashboard).
+
+If none of these fire, skip SPIDR entirely and proceed to ROADMAP write.
+
+## The five SPIDR axes
+
+For each axis, ask one targeted question. The user picks the axis that best fits their story; only one axis is applied per split.
+
+### Spike
+
+> "Is there an unknown that needs research before this can be implemented? If so, the spike is its own phase."
+
+If yes: split out a research phase (no acceptance criteria except "we know enough to plan the rest"). The remaining story becomes a follow-up phase.
+
+### Paths
+
+> "Does this feature have a happy path and one or more error/edge paths?"
+
+If yes: split happy path into the first phase, edge paths into follow-ups. Order: happy path first (it proves the slice works), then progressively edge cases.
+
+### Interfaces
+
+> "Does this feature need to work on more than one interface (web, mobile, API, CLI)?"
+
+If yes: split by interface. Web first if user-facing; API first if integration-driven; mobile last unless it's the primary platform.
+
+### Data
+
+> "Does this feature touch multiple data scopes (one user vs. many, single team vs. multi-tenant, small CSV vs. large dataset)?"
+
+If yes: split by scope. Smallest scope first (one user, single team, small data), then expand.
+
+### Rules
+
+> "Does this feature have multiple business rules that could be added incrementally (basic validation first, then complex policy)?"
+
+If yes: split by rule complexity. Minimum viable rules first; complex policy in follow-ups.
+
+## Workflow
+
+When SPIDR triggers, the workflow:
+
+1. Restates the user-supplied story.
+2. Asks "Which SPIDR axis fits best?" with the five options above.
+3. Walks through the chosen axis interactively (one focused question), produces a split proposal: "Phase N (this one): X. Phase N+1: Y. Phase N+2: Z."
+4. Confirms the split with the user.
+5. On accept: writes the FIRST phase's story to the current ROADMAP entry; defers creating new phases for the splits to a follow-up step (the workflow surfaces a list of `/gsd add-phase` invocations the user can run after `mvp-phase` completes — but does not run them automatically, to preserve user control over phase numbering).
+6. On reject: proceeds with the original story unchanged.
+
+## Anti-patterns to reject
+
+- **Splitting by technical layer.** "Phase 1: schema. Phase 2: API. Phase 3: UI." That's horizontal planning. Reject.
+- **Pre-splitting before the user even sees the original.** Always show the user-supplied story first; only offer split if it triggers a size signal.
+- **Splitting more than one axis at once.** SPIDR is one axis per split. If a story needs splitting on two axes (e.g., paths AND data), do paths first, then re-evaluate the resulting smaller stories.
+
+## Reference
+
+See [Mike Cohn — Five Simple But Powerful Ways to Split User Stories](https://www.mountaingoatsoftware.com/blog/five-simple-but-powerful-ways-to-split-user-stories).