101 lines
6 KiB
Markdown
101 lines
6 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_ref`: a relative path to the decisions log file (see `Decisions Logs` section below)
|
|
- `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.
|
|
|
|
### Decisions Logs
|
|
|
|
Every top level item will contain a decisions log located in `.decisions/{top_level_item_name}_decisions.yaml`.
|
|
This decisions log is 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.
|
|
|
|
### 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.
|
|
|
|
Milestones should be written in an order that produces the least amount of work overall. If Milestone ABC relies on work from Milestone DEF, don't build Milestone ABC with stubs, and push Milestone DEF to later (with replacing the stubs with the real thing). Order the milestones so that Milestone DEF comes first.
|
|
|
|
#### Example Milestone Schema
|
|
```yaml
|
|
milestones:
|
|
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.
|