git:20260905.1736449 to git:20260905.f4ed5cf

---

alwaysApply: true

---

# GSD and local planning — coexistence

This repo uses **GSD** (global Cursor install: `/gsd-*`) for milestone scaffolding and **local rules/skills** for delivery quality. Prefer one owner per workstream; when both apply, **local hard rules win** on conflicts listed below.

## Vocabulary

| Term | Owner | Meaning |

|------|--------|---------|

| **Milestone** | GSD | Versioned increment |

| **Phase** | GSD | Roadmap capability. `### Phase N:`, `.planning/phases/NN-slug/`, `/gsd-plan-phase`, `/gsd-execute-phase` |

| **Story decomposition** | Local | One parent problem with ordered 3V candidate stories; stored as a non-executable seed |

| **Story** | Local | One Valuable, Visible, Vertical product outcome |

| **Plan** | Shared | One `PLAN.md` |

| **Slice** | Local | One Behavior or one Structure. Stop-safe. Commit+push grain |

## Compatible (use together)

| Area | How they fit |

|------|----------------|

| **Folder layout** | Use GSD paths: `.planning/{PROJECT,REQUIREMENTS,ROADMAP,STATE,PRODUCT-BACKLOG}.md`, `config.json`, `.planning/seeds/`, `.planning/phases/NN-slug/`, `.planning/codebase/`, `.planning/quick/`. |

| **Discuss / plan / verify artifacts** | GSD CONTEXT, PLAN, SUMMARY, VERIFICATION are fine **while the plan is active** (resume across sessions). |

| **Execution engine** | Prefer `/gsd-execute-phase` **or** local `execute-plan` on the same PLAN — both must run the **local wrap-up per slice** (Jidoka, fresh refactor agent, one coordinator-run selective formatting command, plan update, commit+push). |

| **Parallel waves** | OK when file sets / mutable state do not overlap; otherwise sequential. |

| **Observable verification** | GSD goal-backward verify + local TDD/E2E/`@wip` — same intent; run relevant local tests as the evidence. |

| **Codebase maps** | `.planning/codebase/*` shared. |

| **Capability naming in product** | Local rule: GSD phase numbers only under `.planning/`. |

## Must keep local (non-compatible with plain GSD defaults)

These are **hard** in this repo even when GSD workflows omit them:

| Local requirement | When it is needed | Why not drop it |

|-------------------|-------------------|-----------------|

| **Problem → 3V story → Behavior/Structure gates** | Every requirement decomposition and every GSD PLAN task split | Reject unresolved outcomes, horizontal stories, and speculative Structure — see `problem-decomposition.mdc` |

| **Resolution-specific sizing (story: ~30 min–few hours; leaf: ~5 min fuzzy, >10 min hard finer-decompose)** | Story shaping and agents making a test pass / solving one execution leaf | Keeps stories comparable and execution loops bounded without pretending estimates are precise — see `problem-decomposition.mdc` |

| **Before- and after-slice Jidoka** | Every slice start/end | Stops autonomous runs on value/design/credential forks |

| **After-slice plan update** | Every completed slice | Keeps remaining work accurate for resume |

| **After-slice post-change-refactor** | Every slice before commit | Cohesion / dead code / 250-line discipline |

| **After-slice selective formatting** | Every slice after refactor/API generation and before the PLAN update/staging | The coordinator runs `./scripts/run.sh pnpm format:changed` once and lets it select affected components (including a planning-only no-op); routine wrap-up does not spawn `format-changed`, and the pre-commit hook remains the independent check-only lint pass |

| **Active history cleanup when the plan is done** | When the last slice is done and outcomes are in code/permanent docs | GSD tends to keep SUMMARYs; we prune spent planning diary |

| **Nix prefix (`CURSOR_DEV=true nix develop -c`); assume `pnpm sut` running; no restart nag** | All tooling | Env contract GSD does not know |

| **Stack/domain rules** (backend, frontend, e2e, cli, mcp, db-migration, …) | Matching globs / skills | Product architecture |

## When to prefer which entrypoint

| Scenario | Prefer |

|----------|--------|

| Broad problem, unclear value/outcome, or several candidate stories | Local `story-decomposition` → one enriched `.planning/seeds/SEED-NNN-*.md`; select a story before planning execution |

| Queue or reprioritize unfinished stories | Local `product-backlog` → `.planning/PRODUCT-BACKLOG.md`; details stay in home seeds |

| New or ongoing **milestone / roadmap** | GSD: `/gsd-onboard` or `/gsd-new-milestone`, then discuss → plan → execute |

| One clear story-sized ad-hoc outcome | Local `slice-planning` → `.planning/quick/NNN-slug/` (or a new `phases/` entry), then `execute-plan` when straightforward |

| Existing PLAN has complex, low-confidence, or overrun leaves | Local `slice-plan-refinement` edits the same PLAN, then `execute-plan` |

| Completed plan needs aggregate code/process review | Local `execution-retrospective` reconstructs plan + commits and may generate, but never execute, a follow-up PLAN |

| **Test optimization / domain tools** (API client, ERD, …) | Local skills; plans still under `.planning/phases/` or `quick/` |

| Resuming after a break | GSD progress/resume uses `STATE.md` as the project index. `execute-plan` resumes from the PLAN file (next undone slice) and must not write `STATE.md`. |

## Anti-patterns

- Flat new plans at `.planning/random.md` when a `phases/` or `quick/` dir would do.

- Passing a story-decomposition seed directly to execute-plan without selecting

one story and producing a slice plan.

- Creating a second PLAN for refinement instead of editing the existing PLAN.

- Leaving completed plan diaries forever under `.planning/`.

- Running GSD execute **without** local Jidoka / fresh refactor agent / one

coordinator-run `format:changed` command / commit+push wrap-up per slice.

- Encoding GSD phase numbers in product file/test/feature names.

- Parallel agents on the same files or the same PLAN without coordination.

- Enabling GSD `generate-claude-md` **workflow-enforcement** that forbids work outside GSD — conflicts with local domain skills and ad-hoc planning.

- Updating `.planning/STATE.md` from `execute-plan` — slice status and learnings live in the PLAN being executed.