Cursor rule

1---
2alwaysApply: true
3---
4# Principles for Phased Development
5 
6**Hard rule for every plan** (local or GSD): each phase is either **Behavior** or **Structure**, **stop-safe**, and delivers **one observable behavior** (or one structure change that enables only the immediate next behavior). See below. GSD roadmap/phase scaffolding is welcome; it must still obey this grammar when writing or splitting plans.
7 
8## Behavior and Structure distinction
9 
10**Behavior** (external behavior) has 3 parts: **pre-condition**, **trigger**, and **post-condition**. Each part is:
11 
12  * externally observable
13  * of user value
14  * typically involves state change.
15 
16**Structure** (internal structure) is how code is organized. We want structure to be cohesive, mapped to the domain, and exposing as little information as possible from each module.
17 
18## Phase principles
19 
20Every phase is one of two types:
21 
22| Type | What it does | Constraint |
23|------|-------------|------------|
24| **Behavior** | Delivers user value directly observable from the external perspective. | Must be externally observable and testable. **One** observable behavior per phase. |
25| **Structure** | Restructures internals to prepare for the **immediate next** behavior phase, without changing any external behavior. | All changes must be **verifiable from the external perspective** (existing tests still pass, no observable difference). No speculative prep for phases beyond the next behavior phase. |
26 
27### Sequencing rules
28 
291. **Stop-safe ordering** — The user may decide to stop after **any** phase. The value delivered must be proportional to (or greater than) the number of completed phases, with close to **zero waste** if remaining phases are never implemented.
302. **Order by value** — Earlier phases = higher user value and usability first.
313. **Many phases are good** — Split as finely as you can while each phase still meets the type constraints above.
324. **Structure phases only justify themselves through the next behavior phase** — A structure phase that is not immediately followed by the behavior phase it enables is speculative waste.
33 
34**To decompose a task into phases**, use the **phased-planning** skill (or GSD `/gsd-plan-phase` / discuss — still apply this grammar to every plan task).
35 
36### Time budget (one problem slice)
37 
38Applies to any agent or sub-agent working on **one** breakdown — e.g. making a specific test pass, or solving one Behavior/Structure unit. Wall-clock includes implementation **and** test execution.
39 
40| Elapsed | Expectation |
41|---------|-------------|
42| **≤ ~5 min** | Fuzzy goal. Size each slice so it can finish in about five minutes. |
43| **> 5 min** | Scrutinize the breakdown. Prefer finer decompose → revert WIP → retry a smaller slice when the slice was oversized or thrashing. |
44| **> 10 min** | **Hard trigger:** stop, revert uncommitted WIP for that attempt, finer-decompose with **phased-planning**, and retry — **unless** there is a stated good reason to continue (e.g. a single targeted test that itself needs >10 min, blocked on developer input, or irreversible mid-migration already validated). |
45 
46Do not use Cursor timer hooks for this; agents self-enforce while working.
47 
48---
49 
50## Planning layout (GSD-aligned)
51 
52Active work lives under `.planning/`:
53 
54| Path | Role |
55|------|------|
56| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json` | GSD project memory (create via `/gsd-new-project` or `/gsd-onboard`) |
57| `.planning/phases/NN-slug/` | Phase directory: `*-CONTEXT.md`, `*-PLAN.md`, `*-SUMMARY.md`, `*-VERIFICATION.md`, … |
58| `.planning/codebase/` | Codebase maps |
59| `.planning/quick/` | Ad-hoc plans that are not yet on the roadmap |
60| `ongoing/` | Legacy only — do not put new plans here |
61 
62Prefer GSD phase dirs and filenames. Local flat `.planning/<name>.md` is legacy-compatible for execute-plan but **new** plans should use `.planning/phases/NN-slug/` or `.planning/quick/NNN-slug/`.
63 
64**Product code, tests, and permanent docs** stay capability-named — never encode phase numbers there. Phase numbers belong only under `.planning/`.
65 
66### Plan history (resume vs cleanup)
67 
68- **While a plan is in progress:** keep enough history under `.planning/` (STATE, CONTEXT, PLAN status, brief learnings, SUMMARY for completed steps) so work can **stop and resume across sessions and environments**.
69- **As soon as the plan is fully executed** and outcomes live in code and permanent docs: **actively clean up** spent planning history (prune done-phase detail, delete disposable notes, drop obsolete SUMMARY/discussion noise). Keep only what still helps a future reader of the *product*, or a short pointer in ROADMAP/STATE if the milestone continues.
70- Do **not** leave completed plans as a permanent diary under `.planning/`.
71 
72---
73 
74## Testing And Completion
75 
76- Name tests and permanent artifacts by capability, not phase number.
77- Prefer observable behavior tests through high-level entry points; use direct unit tests for pure helpers and edge paths.
78- Run targeted E2E for touched behavior, not the full suite unless explicitly required.
79- Do not leave failing tests at a phase boundary; remove `@wip` once scenarios pass.
80- Clean up dead code and update the plan before closing a phase.
81 
82## Phase discipline (checklist)
83 
84Before closing a phase and starting the next:
85 
861. **Clean up** — Remove dead or unreachable code; run **post-change-refactor** on the uncommitted change.
872. **No failing tests** — All unit tests and existing E2E tests must pass at the **merge / CI** gate. No test may be left in a failing state at the end of any phase or sub-phase. **Locally and for AI agents:** satisfy this by running **targeted** E2E (`cypress run --spec` for the feature(s) you touched); do **not** run the **full** E2E suite unless CI, the workflow, or the user **explicitly** requires it.
883. **`@wip` for not-yet-passing E2E scenarios** — Tag test-first E2E `@wip` until they pass. CI skips `@wip` and caps count at 5.
894. **Jidoka** — Before starting a phase and after finishing it: stop for developer judgment on value/design forks, credentials, or unexpected blockers (see **execute-plan**).
905. **Update the plan** — Mark the phase done; prune obsolete detail; adjust remaining phases from what you learned. Keep resume-useful history until the whole plan completes, then clean up (see **Plan history** above).
916. **Deploy gate** — **Commit and push** (and let **CD deploy** when applicable) before the next phase. Required for local execute-plan and for GSD execute in this repo.
927. **Parallelism** — Safe parallel execution (GSD waves / multiple sub-agents) is allowed when plans do not conflict on the same files or shared mutable state; otherwise run sequentially.
93 
94### Test-driven workflow (when adding or changing behavior)
95 
96For **multi-step** E2E scenarios, prefer **E2E-led decomposition** (see phased-planning skill). Tag new E2E scenarios `@wip` while working toward making them pass.
97 
981. Add or change the **E2E or unit** test; **run it** and confirm it **fails**.
992. Confirm it fails for the **right reason** (not a typo or env issue).
1003. If the failure is unclear, **improve the assertion or message** so the next reader learns what was wrong.
1014. Implement the **smallest** change that makes the test pass.
1025. **Refactor** with tests green, then continue.
1036. Remove the `@wip` tag from any E2E scenario that now passes.
104 
105---
106 
107## Interim behavior
108 
109- **Allowed** when it gets the feature to users faster **or** gives the team **earlier end-to-end feedback**.
110- **Remove** interim behavior when a **later phase** replaces it with the intended design.
111 
112## GSD coexistence
113 
114Compatible defaults and **must-keep local** overlays: see `.cursor/rules/gsd-coexistence.mdc`.
115