SiteWeaver_CMS/AGENTS.md

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

Pillars

View Pillars for the Pillars that guide our planning.

Read these files now

• Principles
• Pillars

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

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.