---
alwaysApply: true
---
# Principles for Phased Development

**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.

## Behavior and Structure distinction

**Behavior** (external behavior) has 3 parts: **pre-condition**, **trigger**, and **post-condition**. Each part is:

  * externally observable
  * of user value
  * typically involves state change.

**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.

## Phase principles

Every phase is one of two types:

| Type | What it does | Constraint |
|------|-------------|------------|
| **Behavior** | Delivers user value directly observable from the external perspective. | Must be externally observable and testable. **One** observable behavior per phase. |
| **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. |

### Sequencing rules

1. **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.
2. **Order by value** — Earlier phases = higher user value and usability first.
3. **Many phases are good** — Split as finely as you can while each phase still meets the type constraints above.
4. **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.

**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).

### Time budget (one problem slice)

Applies 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.

| Elapsed | Expectation |
|---------|-------------|
| **≤ ~5 min** | Fuzzy goal. Size each slice so it can finish in about five minutes. |
| **> 5 min** | Scrutinize the breakdown. Prefer finer decompose → revert WIP → retry a smaller slice when the slice was oversized or thrashing. |
| **> 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). |

Do not use Cursor timer hooks for this; agents self-enforce while working.

---

## Planning layout (GSD-aligned)

Active work lives under `.planning/`:

| Path | Role |
|------|------|
| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json` | GSD project memory (create via `/gsd-new-project` or `/gsd-onboard`) |
| `.planning/phases/NN-slug/` | Phase directory: `*-CONTEXT.md`, `*-PLAN.md`, `*-SUMMARY.md`, `*-VERIFICATION.md`, … |
| `.planning/codebase/` | Codebase maps |
| `.planning/quick/` | Ad-hoc plans that are not yet on the roadmap |
| `ongoing/` | Legacy only — do not put new plans here |

Prefer 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/`.

**Product code, tests, and permanent docs** stay capability-named — never encode phase numbers there. Phase numbers belong only under `.planning/`.

### Plan history (resume vs cleanup)

- **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**.
- **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.
- Do **not** leave completed plans as a permanent diary under `.planning/`.

---

## Testing And Completion

- Name tests and permanent artifacts by capability, not phase number.
- Prefer observable behavior tests through high-level entry points; use direct unit tests for pure helpers and edge paths.
- Run targeted E2E for touched behavior, not the full suite unless explicitly required.
- Do not leave failing tests at a phase boundary; remove `@wip` once scenarios pass.
- Clean up dead code and update the plan before closing a phase.

## Phase discipline (checklist)

Before closing a phase and starting the next:

1. **Clean up** — Remove dead or unreachable code; run **post-change-refactor** on the uncommitted change.
2. **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.
3. **`@wip` for not-yet-passing E2E scenarios** — Tag test-first E2E `@wip` until they pass. CI skips `@wip` and caps count at 5.
4. **Jidoka** — Before starting a phase and after finishing it: stop for developer judgment on value/design forks, credentials, or unexpected blockers (see **execute-plan**).
5. **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).
6. **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.
7. **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.

### Test-driven workflow (when adding or changing behavior)

For **multi-step** E2E scenarios, prefer **E2E-led decomposition** (see phased-planning skill). Tag new E2E scenarios `@wip` while working toward making them pass.

1. Add or change the **E2E or unit** test; **run it** and confirm it **fails**.
2. Confirm it fails for the **right reason** (not a typo or env issue).
3. If the failure is unclear, **improve the assertion or message** so the next reader learns what was wrong.
4. Implement the **smallest** change that makes the test pass.
5. **Refactor** with tests green, then continue.
6. Remove the `@wip` tag from any E2E scenario that now passes.

---

## Interim behavior

- **Allowed** when it gets the feature to users faster **or** gives the team **earlier end-to-end feedback**.
- **Remove** interim behavior when a **later phase** replaces it with the intended design.

## GSD coexistence

Compatible defaults and **must-keep local** overlays: see `.cursor/rules/gsd-coexistence.mdc`.