## Overview

We turn ideas into an implementation plan using one or two documents:

- **APP.yaml**: a single specification that is organized by feature/domain area but as free-form as needed within each section, via inline `notes` / `rationale` / `examples` / `decisions_log` / `open_questions` fields.
- **MILESTONES.yaml**: a fully detailed, ordered list of milestones written from `APP.yaml`.

`APP.yaml` always comes first. Work only on the document named in the current prompt. Do not create or update `MILESTONES.yaml` until asked. If `APP.yaml` changes later, update `MILESTONES.yaml` only when asked.

Once `APP.yaml` is final, there are two possible paths forward, decided with the user at that point:

- **Milestone path**: create `MILESTONES.yaml` from `APP.yaml`, then move to the Execution phase, and build the application milestone by milestone.
- **Direct-build path**: skip `MILESTONES.yaml` entirely and move straight to the Execution phase, building the whole application from `APP.yaml` in one go. Any further work after that initial build (bug fixes and/or additions) is handled as separate follow-up tasks rather than milestones.

If any of the files `NOTES.md`, `SPECS.md`, or `MILESTONES.md` exist, do not read them unless specifically asked to.

When filling out open_questions, for each question, provide the `question`, provide the `options`, and provide an empty `answer` block.

When an answer is provided to an open_question, move the question and answer to the relevant decisions_log, and provide a rationale for the answer given. If no rationale is given and cannot be logically deduced from the answer provided, ask for one.

## Paradigms/Principles
Keep the following paradigms/principles in mind when planning:
[Principles](.junie/Principles.md)

## Pillars
View [Pillars](.junie/Pillars.md) for the Pillars that guide our planning.

## Read these files now
- [Principles](.junie/Principles.md)
- [Pillars](.junie/Pillars.md)

## Authoring phase

Use this while building the planning documents. Once `APP.yaml` is final and a path forward has been chosen (see Overview), switch to the Execution phase and start a new session - either once `MILESTONES.yaml` is also final (Milestone path), or right after `APP.yaml` (Direct-build path).

### Starting from raw ideas

When raw ideas are shared at the start of a project, review them for gaps, ambiguities, and conflicts, and ask about anything unclear — same review discipline as before, just applied directly against `APP.yaml` as it's written, instead of against a separate upstream document.

### APP.yaml structure

Organize top-level keys by feature/domain area (e.g. `app`, `glossary`, `scope`, `features_overview`, per-domain `*_architecture`/`*_requirements` sections, `ui`, `data_model`, `testing`, etc. — adapt the exact set of sections to the project at hand). Within any section, use these conventions to carry the ideation trail:

- `notes`: free-form rationale, considerations, examples — plain prose or a short list.
- `decisions_log`: an append-only list of resolved questions, in the shape `{question: ..., decision: ..., rationale: ...}`, capturing what was asked, what was decided, and why — so the "why" behind a choice is never lost.
- `open_questions`: a structured list of items still to be clarified with the user (empty list when none remain); each entry should name the question and, if relevant, the options under consideration.

### MILESTONES.yaml structure

Write `MILESTONES.yaml` as an ordered YAML structure (e.g. a top-level `milestones:` list, each entry keyed by number/id with `goal`, `steps`, `details`, and `tests` keys). 
Each milestone is a self-contained unit of work and must explicitly include all details necessary to complete it — URLs, file paths, DB table schemas, config settings, etc. — 
transposed from `APP.yaml` and any documents it references. Every milestone lists the tests that cover what it implements; a milestone is complete only when those tests pass. 
End `MILESTONES.yaml` with a final "Full Verification" milestone that runs the whole suite and checks the app end to end. `MILESTONES.yaml` must be usable standalone, without 
`APP.yaml` present.

### Milestone Rules

Each milestone must complete exactly one independently verifiable capability.
A capability may be:
- User-facing
- Administrator-facing
- Developer-facing
- Internal infrastructure
- A data, processing, or architectural subsystem

The milestone must include all work necessary to make that capability function as a coherent whole, but no work belonging to another capability.

#### Example Milestone Schema
```yaml
milestones:
  # ---- Milestone 0: Project Foundation & Setup ----
  milestone_{id}_{name}:
    status: [TODO|IN_PROGRESS|COMPLETE]
    description: >
      [The description of the purpose of the milestone]
    what_is_built:
      - [List of application sections/functionality that will be built during this milestone. This is a companion to the description]
    tests_to_run:
      - [List of tests that test the modifications (create/edit/delete) performed in this milestone]
    artifacts:
      created:
        - [List of files to be created]
      modified:
        - [List of files to be modified]
      deleted:
        - [List of files to be deleted]
    completion_criteria:
      - [list of all things that MUST be done before milestone is considered "done"]
      - Every test listed above passes without flakiness (no warnings, no errors, no failures).
```

### Scope while authoring

Edit only `APP.yaml` and, if the Milestone path was chosen, `MILESTONES.yaml`. This is planning, not building yet.