@opengsd/get-shit-done-redux 1.0.0

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

@@ -0,0 +1,298 @@
+<overview>
+Git integration for GSD framework.
+</overview>
+
+<core_principle>
+
+**Commit outcomes, not process.**
+
+The git log should read like a changelog of what shipped, not a diary of planning activity.
+</core_principle>
+
+<commit_points>
+
+| Event                   | Commit? | Why                                              |
+| ----------------------- | ------- | ------------------------------------------------ |
+| BRIEF + ROADMAP created | YES     | Project initialization                           |
+| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
+| RESEARCH.md created     | NO      | Intermediate                                     |
+| DISCOVERY.md created    | NO      | Intermediate                                     |
+| **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
+| **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
+| Handoff created         | YES     | WIP state preserved                              |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+If NO_GIT: Run `git init` silently. GSD projects always get their own repo.
+</git_check>
+
+<commit_formats>
+
+<format name="initialization">
+## Project Initialization (brief + roadmap together)
+
+```
+docs: initialize [project-name] ([N] phases)
+
+[One-liner from PROJECT.md]
+
+Phases:
+1. [phase-name]: [goal]
+2. [phase-name]: [goal]
+3. [phase-name]: [goal]
+```
+
+What to commit:
+
+```bash
+gsd-sdk query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+```
+
+</format>
+
+<format name="task-completion">
+## Task Completion (During Plan Execution)
+
+Each task gets its own commit immediately after completion.
+
+> **Parallel agents:** When running as a parallel executor (spawned by execute-phase),
+> run commits normally — let pre-commit hooks run. Do NOT pass `--no-verify` by default
+> (#2924). Hooks should fire on the introducing commit; silent bypass violates project
+> CLAUDE.md guidance. If a project explicitly opts out via
+> `workflow.worktree_skip_hooks=true`, the orchestrator surfaces that flag in the
+> executor prompt; absent that signal, hooks run normally.
+
+```
+{type}({phase}-{plan}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+```
+
+**Commit types:**
+- `feat` - New feature/functionality
+- `fix` - Bug fix
+- `test` - Test-only (TDD RED phase)
+- `refactor` - Code cleanup (TDD REFACTOR phase)
+- `perf` - Performance improvement
+- `chore` - Dependencies, config, tooling
+
+**Examples:**
+
+```bash
+# Standard task
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08-02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# TDD task - RED phase
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07-02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour
+- Tests signature verification
+"
+
+# TDD task - GREEN phase
+git add src/utils/jwt.ts
+git commit -m "feat(07-02): implement JWT generation
+
+- Uses jose library for signing
+- Includes user ID and expiry claims
+- Signs with HS256 algorithm
+"
+```
+
+</format>
+
+<format name="plan-completion">
+## Plan Completion (After All Tasks Done)
+
+After all tasks committed, one final metadata commit captures plan completion.
+
+```
+docs({phase}-{plan}): complete [plan-name] plan
+
+Tasks completed: [N]/[N]
+- [Task 1 name]
+- [Task 2 name]
+- [Task 3 name]
+
+SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
+```
+
+What to commit:
+
+```bash
+gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+```
+
+**Note:** Code files NOT included - already committed per-task.
+
+</format>
+
+<format name="handoff">
+## Handoff (WIP)
+
+```
+wip: [phase-name] paused at task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+What to commit:
+
+```bash
+gsd-sdk query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+**Old approach (per-plan commits):**
+```
+a7f2d1 feat(checkout): Stripe payments with webhook verification
+3e9c4b feat(products): catalog with search, filters, and pagination
+8a1b2c feat(auth): JWT with refresh rotation using jose
+5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
+2f4a8d docs: initialize ecommerce-app (5 phases)
+```
+
+**New approach (per-task commits):**
+```
+# Phase 04 - Checkout
+1a2b3c docs(04-01): complete checkout flow plan
+4d5e6f feat(04-01): add webhook signature verification
+7g8h9i feat(04-01): implement payment session creation
+0j1k2l feat(04-01): create checkout page component
+
+# Phase 03 - Products
+3m4n5o docs(03-02): complete product listing plan
+6p7q8r feat(03-02): add pagination controls
+9s0t1u feat(03-02): implement search and filters
+2v3w4x feat(03-01): create product catalog schema
+
+# Phase 02 - Auth
+5y6z7a docs(02-02): complete token refresh plan
+8b9c0d feat(02-02): implement refresh token rotation
+1e2f3g test(02-02): add failing test for token refresh
+4h5i6j docs(02-01): complete JWT setup plan
+7k8l9m feat(02-01): add JWT generation and validation
+0n1o2p chore(02-01): install jose library
+
+# Phase 01 - Foundation
+3q4r5s docs(01-01): complete scaffold plan
+6t7u8v feat(01-01): configure Tailwind and globals
+9w0x1y feat(01-01): set up Prisma with database
+2z3a4b feat(01-01): create Next.js 15 project
+
+# Initialization
+5c6d7e docs: initialize ecommerce-app (5 phases)
+```
+
+Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
+
+</example_log>
+
+<anti_patterns>
+
+**Still don't commit (intermediate artifacts):**
+- PLAN.md creation (commit with plan completion)
+- RESEARCH.md (intermediate)
+- DISCOVERY.md (intermediate)
+- Minor planning tweaks
+- "Fixed typo in roadmap"
+
+**Do commit (outcomes):**
+- Each task completion (feat/fix/test/refactor)
+- Plan completion metadata (docs)
+- Project initialization (docs)
+
+**Key principle:** Commit working code and shipped outcomes, not planning process.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Why Per-Task Commits?
+
+**Context engineering for AI:**
+- Git history becomes primary context source for future Claude sessions
+- `git log --grep="{phase}-{plan}"` shows all work for a plan
+- `git diff <hash>^..<hash>` shows exact changes per task
+- Less reliance on parsing SUMMARY.md = more context for actual work
+
+**Failure recovery:**
+- Task 1 committed ✅, Task 2 failed ❌
+- Claude in next session: sees task 1 complete, can retry task 2
+- Can `git reset --hard` to last successful task
+
+**Debugging:**
+- `git bisect` finds exact failing task, not just failing plan
+- `git blame` traces line to specific task context
+- Each commit is independently revertable
+
+**Observability:**
+- Solo developer + Claude workflow benefits from granular attribution
+- Atomic commits are git best practice
+- "Commit noise" irrelevant when consumer is Claude, not humans
+
+</commit_strategy_rationale>
+
+<sub_repos_support>
+
+## Multi-Repo Workspace Support (sub_repos)
+
+For workspaces with separate git repos (e.g., `backend/`, `frontend/`, `shared/`), GSD routes commits to each repo independently.
+
+### Configuration
+
+In `.planning/config.json`, list sub-repo directories under `planning.sub_repos`:
+
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "sub_repos": ["backend", "frontend", "shared"]
+  }
+}
+```
+
+Set `commit_docs: false` so planning docs stay local and are not committed to any sub-repo.
+
+### How It Works
+
+1. **Auto-detection:** During `/gsd:new-project`, directories with their own `.git` folder are detected and offered for selection as sub-repos. On subsequent runs, `loadConfig` auto-syncs the `sub_repos` list with the filesystem — adding newly created repos and removing deleted ones. This means `config.json` may be rewritten automatically when repos change on disk.
+2. **File grouping:** Code files are grouped by their sub-repo prefix (e.g., `backend/src/api/users.ts` belongs to the `backend/` repo).
+3. **Independent commits:** Each sub-repo receives its own atomic commit via `gsd-tools.cjs commit-to-subrepo`. File paths are made relative to the sub-repo root before staging.
+4. **Planning stays local:** The `.planning/` directory is not committed; it acts as cross-repo coordination.
+
+### Commit Routing
+
+Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
+
+```bash
+gsd-sdk query commit-to-subrepo "feat(02-01): add user API" \
+  --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
+```
+
+This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, and `src/components/UserForm.tsx` in the `frontend/` repo, then commits each independently with the same message.
+
+Files that don't match any configured sub-repo are reported as unmatched.
+
+</sub_repos_support>

package/get-shit-done/references/git-planning-commit.md

@@ -0,0 +1,40 @@
+# Git Planning Commit
+
+Commit planning artifacts via `gsd-sdk query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `gsd-tools.cjs commit`).
+
+## Commit via CLI
+
+Pass the message first, then file paths via `--files`. Both `commit` and `commit-to-subrepo` use `--files` to declare the paths to commit.
+
+Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
+
+```bash
+gsd-sdk query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+```
+
+The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
+
+## Amend previous commit
+
+To fold `.planning/` file changes into the previous commit:
+
+```bash
+gsd-sdk query commit "" --files .planning/codebase/*.md --amend
+```
+
+## Commit Message Patterns
+
+| Command | Scope | Example |
+|---------|-------|---------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## When to Skip
+
+- `commit_docs: false` in config
+- `.planning/` is gitignored
+- No changes to commit (check with `git status --porcelain .planning/`)

package/get-shit-done/references/ios-scaffold.md

@@ -0,0 +1,123 @@
+# iOS App Scaffold Reference
+
+Rules and patterns for scaffolding iOS applications. Apply when any plan involves creating a new iOS app target.
+
+---
+
+## Critical Rule: Never Use Package.swift as the Primary Build System for iOS Apps
+
+**NEVER use `Package.swift` with `.executableTarget` (or `.target`) to scaffold an iOS app.** Swift Package Manager executable targets compile as macOS command-line tools — they do not produce `.app` bundles, cannot be signed for iOS devices, and cannot be submitted to the App Store.
+
+**Prohibited pattern:**
+```swift
+// Package.swift — DO NOT USE for iOS apps
+.executableTarget(name: "MyApp", dependencies: [])
+// or
+.target(name: "MyApp", dependencies: [])
+```
+
+Using this pattern produces a macOS CLI binary, not an iOS app. The app will not build for any iOS simulator or device.
+
+---
+
+## Required Pattern: XcodeGen
+
+All iOS app scaffolding MUST use XcodeGen to generate the `.xcodeproj`.
+
+### Step 1 — Install XcodeGen (if not present)
+
+```bash
+brew install xcodegen
+```
+
+### Step 2 — Create `project.yml`
+
+`project.yml` is the XcodeGen spec that describes the project structure. Minimum viable spec:
+
+```yaml
+name: MyApp
+options:
+  bundleIdPrefix: com.example
+  deploymentTarget:
+    iOS: "17.0"
+settings:
+  SWIFT_VERSION: "5.10"
+  IPHONEOS_DEPLOYMENT_TARGET: "17.0"
+targets:
+  MyApp:
+    type: application
+    platform: iOS
+    sources: [Sources/MyApp]
+    settings:
+      PRODUCT_BUNDLE_IDENTIFIER: com.example.MyApp
+      INFOPLIST_FILE: Sources/MyApp/Info.plist
+    scheme:
+      testTargets:
+        - MyAppTests
+  MyAppTests:
+    type: bundle.unit-test
+    platform: iOS
+    sources: [Tests/MyAppTests]
+    dependencies:
+      - target: MyApp
+```
+
+### Step 3 — Generate the .xcodeproj
+
+```bash
+xcodegen generate
+```
+
+This creates `MyApp.xcodeproj` in the project root. Commit `project.yml` but add `*.xcodeproj` to `.gitignore` (regenerate on checkout).
+
+### Step 4 — Standard project layout
+
+```
+MyApp/
+├── project.yml              # XcodeGen spec — commit this
+├── .gitignore               # includes *.xcodeproj
+├── Sources/
+│   └── MyApp/
+│       ├── MyAppApp.swift   # @main entry point
+│       ├── ContentView.swift
+│       └── Info.plist
+└── Tests/
+    └── MyAppTests/
+        └── MyAppTests.swift
+```
+
+---
+
+## iOS Deployment Target Compatibility
+
+Always verify SwiftUI API availability against the project's `IPHONEOS_DEPLOYMENT_TARGET` before using any SwiftUI component.
+
+| API | Minimum iOS |
+|-----|-------------|
+| `NavigationView` | iOS 13 |
+| `NavigationStack` | iOS 16 |
+| `NavigationSplitView` | iOS 16 |
+| `List(selection:)` with multi-select | iOS 17 |
+| `ScrollView` scroll position APIs | iOS 17 |
+| `Observable` macro (`@Observable`) | iOS 17 |
+| `SwiftData` | iOS 17 |
+| `@Bindable` | iOS 17 |
+| `TipKit` | iOS 17 |
+
+**Rule:** If a plan requires a SwiftUI API that exceeds the project's deployment target, either:
+1. Raise the deployment target in `project.yml` (and document the decision), or
+2. Wrap the call in `if #available(iOS NN, *) { ... }` with a fallback implementation.
+
+Do NOT silently use an API that requires a higher iOS version than the declared deployment target — the app will crash at runtime on older devices.
+
+---
+
+## Verification
+
+After running `xcodegen generate`, verify the project builds:
+
+```bash
+xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' build
+```
+
+A successful build (exit code 0) confirms the scaffold is valid for iOS.

package/get-shit-done/references/mandatory-initial-read.md

@@ -0,0 +1,2 @@
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.

package/get-shit-done/references/model-profile-resolution.md

@@ -0,0 +1,38 @@
+# Model Profile Resolution
+
+Resolve model profile once at the start of orchestration, then use it for all Task spawns.
+
+## Resolution Pattern
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default: `balanced` if not set or config missing.
+
+## Lookup Table
+
+@~/.claude/get-shit-done/references/model-profiles.md
+
+Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+
+```
+Task(
+  prompt="...",
+  subagent_type="gsd-planner",
+  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+)
+```
+
+**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
+
+1. Resolve once at orchestration start
+2. Store the profile value
+3. Look up each agent's model from the table when spawning
+4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)