95 lines
5.5 KiB
Markdown
95 lines
5.5 KiB
Markdown
## 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.
|