Cursor rule

1---
2alwaysApply: true
3---
4# GSD and local planning — coexistence
5 
6This 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.
7 
8## Compatible (use together)
9 
10| Area | How they fit |
11|------|----------------|
12| **Folder layout** | Use GSD paths: `.planning/{PROJECT,REQUIREMENTS,ROADMAP,STATE}.md`, `config.json`, `.planning/phases/NN-slug/`, `.planning/codebase/`, `.planning/quick/`. |
13| **Discuss / plan / verify artifacts** | GSD CONTEXT, PLAN, SUMMARY, VERIFICATION are fine **while the plan is active** (resume across sessions). |
14| **Execution engine** | Prefer `/gsd-execute-phase` **or** local `execute-plan` on the same PLAN — both must run the **local phase wrap-up** (Jidoka, refactor, plan update, commit+push). |
15| **Parallel waves** | OK when file sets / mutable state do not overlap; otherwise sequential. |
16| **Observable verification** | GSD goal-backward verify + local TDD/E2E/`@wip` — same intent; run relevant local tests as the evidence. |
17| **Codebase maps** | `.planning/codebase/*` shared. |
18| **Capability naming in product** | Local rule: phase numbers only under `.planning/`. |
19 
20## Must keep local (non-compatible with plain GSD defaults)
21 
22These are **hard** in this repo even when GSD workflows omit them:
23 
24| Local requirement | When it is needed | Why not drop it |
25|-------------------|-------------------|-----------------|
26| **Behavior vs Structure; stop-safe; one observable behavior per phase** | Every plan decomposition and every GSD PLAN task split | Prevents speculative structure and half-finished value if work stops mid-roadmap |
27| **Time budget per slice (~5 min fuzzy; >10 min hard finer-decompose)** | Agents/sub-agents making a test pass or solving one problem unit | Keeps breakdowns small; self-enforced (no Cursor timer hooks) — see `planning.mdc` |
28| **Before- and after-phase Jidoka** | Every phase start/end | Stops autonomous runs on value/design/credential forks |
29| **After-phase plan update** | Every completed phase | Keeps remaining work accurate for resume |
30| **After-phase post-change-refactor** | Every phase before commit | Cohesion / dead code / 250-line discipline |
31| **After-phase commit + push (+ CD when applicable)** | Every closed phase before the next | Deploy gate; remote/CI catch issues early |
32| **Active history cleanup when the plan is done** | When the last phase is done and outcomes are in code/permanent docs | GSD tends to keep SUMMARYs; we prune spent planning diary |
33| **Nix prefix (`CURSOR_DEV=true nix develop -c`); assume `pnpm sut` running; no restart nag** | All tooling | Env contract GSD does not know |
34| **Stack/domain rules** (backend, frontend, e2e, cli, mcp, db-migration, …) | Matching globs / skills | Product architecture |
35 
36## When to prefer which entrypoint
37 
38| Scenario | Prefer |
39|----------|--------|
40| New or ongoing **milestone / roadmap** | GSD: `/gsd-onboard` or `/gsd-new-milestone`, then discuss → plan → execute |
41| Small ad-hoc slice | Local `phased-planning` → `.planning/quick/NNN-slug/` (or a new `phases/` entry), then `execute-plan` |
42| **Test optimization / domain tools** (API client, ERD, …) | Local skills; plans still under `.planning/phases/` or `quick/` |
43| Resuming after a break | Read `.planning/STATE.md` and the active phase dir; continue with GSD progress/resume **or** `execute-plan` on remaining PLAN tasks |
44 
45## Anti-patterns
46 
47- Flat new plans at `.planning/random.md` when a `phases/` or `quick/` dir would do (legacy flat files still executable).
48- Leaving completed phase diaries forever under `.planning/`.
49- Running GSD execute **without** local Jidoka / refactor / commit+push wrap-up.
50- Encoding phase numbers in product file/test/feature names.
51- Parallel agents on the same files or the same PLAN without coordination.
52- Enabling GSD `generate-claude-md` **workflow-enforcement** that forbids work outside GSD — conflicts with local domain skills and ad-hoc planning.
53