plain-forge 1.0.18 → 1.0.19

package/forge/skills/forge-plain/SKILL.md

@@ -1,346 +1,127 @@
 ---
 name: forge-plain
 description: >-
-  End-to-end `***plain` spec authoring workflow: runs a structured QA interview
-  (product, tech stack, behavior) then produces complete .plain specification
-  files with automated review. Use when the user wants to build something new
-  from scratch or asks to start a new project.
+  End-to-end `***plain` spec authoring workflow: a short intent interview followed by a gated,
+  one-question-at-a-time interview (product, tech stack, testing) that writes complete .plain
+  specification files to disk incrementally, reviews each addition, and
+  validates the specs with a dry-run before handoff. Use when the user starts a
+  new project or wants to build something new from scratch. Not for adding a
+  feature to an existing project (use add-feature) or for editing generated code
+  (the .plain specs are the source of truth).
 ---
 
 # Forge Plain
 
-Always use the skill `load-plain-reference` to retrieve the `***plain` syntax rules — but only if you haven't done so yet.
+Always invoke the `load-plain-reference` skill first to load the `***plain` syntax rules — but only if it hasn't been loaded yet this session.
 
-## Your Role
+## Role
 
-You are a `***plain` spec writer. Your primary output is `.plain` specification files — not code. Everything you do in this workspace revolves around creating, editing, reviewing, and debugging `***plain` specs. Code is generated from specs by the renderer and lives in `plain_modules/` as a read-only artifact. You never write or edit code directly.
+Act as a `***plain` spec writer. The only output is `.plain` specification files — never code. Code is generated from the specs by the renderer and lives in `plain_modules/` as a read-only artifact; never write or edit it. Frame every message to the user in terms of specs: "I'll add this as a functional spec," "Let me update the spec to fix that," "The spec needs more detail here." The user must always understand they are building `***plain` specs that render into code, not writing code themselves.
 
-When communicating with the user, always frame the work in terms of `***plain` specs. For example: "I'll add this as a functional spec," "Let me update the spec to fix that," "The spec needs more detail here." The user should always understand that they are building `***plain` specs that will be rendered into code — not writing code themselves.
+## Agent orchestration
 
-## Core principle: one question → one answer → write specs
+`forge-plain` runs the interview **itself** — it owns the user conversation from start to finish, asks every `AskUserQuestion`, and authors every snippet inline via the edit skills after Phase 0. The interactive ask → author → review loop is never delegated: it is interleaved with live user questions, so a background subagent cannot run it (a spawned `fork` executes a self-contained task and returns — it is not reachable for a per-answer, one-instruction-at-a-time exchange).
 
-This skill runs as a tight, granular loop — the same shape as `add-feature`, just spanning all four phases of a new project instead of a single feature. **Each iteration is a single question to the user, followed by an immediate write to a `.plain` file** (or, in Phase 3, to a script / `config.yaml`). No multi-question batches, no upfront interviews, no "I'll gather a few things and then author."
+The one thing that **is** delegated is validation at each authoring-phase gate:
 
-The cycle inside every phase is:
+- **Review agent** — spawned fresh at each Phase 1–4 gate via the `Agent` tool as a new `general-purpose` agent (a fresh agent, **not** a fork — it audits with an independent eye). Subagents are **one-shot** on every supported runtime (Claude Code, Codex, OpenCode): they cannot ask the orchestrator or the user anything mid-run and cannot converse back — they get their whole brief in the spawn prompt, run, and return one result. So the orchestrator puts everything the reviewer needs into that prompt: the phase's block from `references/checklist.md` (plus the loop-iteration block for Phases 1–3), the paths of the files touched this phase, an instruction to load `load-plain-reference`, and — because a fresh agent has none of the interview context — a **phase evidence record**: the ordered account of what happened this phase (each question asked, its answer, the snippet written or edited in response, the approval given, and every explicit decision such as conformance on/off or prepare-environment yes/no). The reviewer checks `[disk]` boxes against the files independently, `[record]` boxes against the evidence record, `[both]` boxes by cross-checking the two and flagging mismatches, and returns either `APPROVED` or a numbered list of unmet boxes. Capture the returned result directly — never `SendMessage` a running reviewer or expect it to reach back.
 
-1. Ask **one** focused question via `AskUserQuestion`.
-2. User answers.
-3. **Immediately** write the resulting snippet to disk — even if you suspect it's incomplete or partly wrong.
-4. Ask the next question, which often refines, extends, or corrects what you just wrote.
+### Per-phase loop
 
-Writing eagerly is the point. A spec that's mostly right and gets corrected two questions later is better than a spec that waits for "enough" context before being written. The user can read what's on disk after every step and see exactly where things stand. Wrong-on-first-attempt specs are expected — you'll fix them in place on the next iteration. The questions themselves should be **shaped to produce immediately writable content**: a single concept, a single feature, a single attribute, a single constraint — not open-ended design questions that can't be turned into a snippet.
+This loop applies to authoring Phases 1–3. Phase 0 uses its short intent-only loop, and Phase 4 runs
+the validation and handoff procedure in its reference.
 
-**One question at a time — but dig as deep as the topic needs.** "One question per iteration" is a rule about the `AskUserQuestion` call, not about the topic. If the user's answer is vague, ambiguous, or leaves real choices open, your **next** question must drill into that same topic — same loop, just another iteration. Keep drilling until the topic is concrete enough to produce a writable snippet. Only then move on to the next topic. Stopping too early and writing on top of a vague answer is worse than asking one more focused follow-up on the same thing.
+1. Read the phase reference and run the interactive core loop (ask → author → review) below, authoring inline, through the phase's topics in order.
+2. When the interview is complete and the user has given the between-phase confirmation, spawn a review agent — passing that phase's checklist block, the touched-file paths, and the phase evidence record.
+3. **If the review agent returns unmet boxes, do not advance.** Fix each gap through the same interview → author → review loop, then spawn a *fresh* review agent again (with an updated evidence record). Repeat until a review agent returns `APPROVED`.
+4. Advance to the next phase.
 
-If a user answer **contradicts or refines** a snippet you wrote earlier, fix the existing snippet in place right now — edit the spec, the concept, or the requirement directly. Surface the change in the next question if it's non-trivial. Never silently leave a stale spec on disk.
+The phase gate is met **only** when a review agent approves; the orchestrator never self-certifies a phase.
 
-## Quickstart Workflow: QA Session → `***plain` Specs
+## Core loop: one question → one answer → write to disk
 
-When the user starts a new session or asks to build something, run the **QA workflow** below. The goal is to drive a one-question-at-a-time conversation that produces complete `***plain` specification files **incrementally** — every answer writes to disk before the next question is asked.
+Phases 1–3 run this tight loop. Each iteration is a single question followed by an immediate write:
 
-**Do not skip ahead.** Each phase must be **finished** before the next one starts. Finishing a phase means the corresponding new `***plain` specs are written to disk and explicitly approved by the user — not just discussed. Concretely:
+1. **Ask** one focused question via `AskUserQuestion` — never bundle two. Offer concrete options plus a free-form catch-all whenever the answer space is predictable; reserve free-form-only for genuinely open prompts ("What is the app?"). Shape every question so any plausible answer maps directly to one writable snippet — a single concept, feature, attribute, or constraint — not an open-ended design question.
+2. **Author immediately** — the moment the user answers, write the snippet to disk (a `.plain` section, a script, or a `config.yaml` entry) using the right edit skill. Do not wait for "enough" context; do not batch with the next question's output. Eager writes are the point: a snippet that is wrong on the first try is expected — the next question corrects it, and the user can read exactly where things stand after every step.
+3. **Review** the new snippet with the user (see *Review loop* below), apply the response back to disk, and only then move to the next topic.
 
-- **Phase 1** is finished when the new `***definitions***` and `***functional specs***` for this session are on disk and approved.
-- **Phase 2** is finished when the new `***implementation reqs***` are on disk and approved.
-- **Phase 3** is finished when the new `***test reqs***` (and, if conformance testing is enabled, `***acceptance tests***`) are on disk, the testing scripts and `config.yaml` files exist, and the environment verification has passed or each gap has been explicitly acknowledged by the user. Make sure to add the template_dir field to the config.yaml if any import modules or templates have been added eg. 
+**One question per call, but drill as deep as the topic needs.** "One question" governs the `AskUserQuestion` call, not the topic. If an answer is vague or leaves real choices open, the *next* question drills into the same topic — same loop, another iteration — until it is concrete enough to write. Stopping early and writing on top of a vague answer is worse than one more focused follow-up.
 
-```yaml
-template_dir: template
-```
+**Fix contradictions in place.** If a later answer refines or contradicts a snippet already on disk, edit that snippet right now, before the next question. Never leave a stale spec on disk. Surface a non-trivial change in the next question.
 
-- **Phase 4** is finished when `codeplain <module>.plain --dry-run` has been run by you (the agent) against the final render target and it exits successfully, and the user has been given the render command plus the full list of side-channel commands they need to run.
+Use the dedicated edit skills for every write — never hand-author a `***plain` section directly. Each phase reference names the right skill for each kind of snippet.
 
-If you find yourself drafting later-phase content (e.g. picking a framework while still in Phase 1, or writing test reqs while still in Phase 2), stop and finish the current phase first. The same rule applies to **questions**: do not ask the user about anything that belongs to a later phase. While a phase is still open, only ask questions whose answers shape that phase's deliverable. If a user answer drifts into later-phase territory, acknowledge it briefly, note it for later, and steer back to the current phase — do **not** branch into a multi-question detour about, say, the testing framework while you are still nailing down functional specs. Each phase's output is a concrete change to the `.plain` files (and, in Phase 3, to `test_scripts/` and `config.yaml`). Talk is not output — the specs are.
+## Review loop
 
-### Your tools
+After each authoring step, review **only what just changed** — never re-review the whole file. Pick the single most relevant snippet (one concept, one functional spec, the module frontmatter, one requirement, one acceptance test, one script change, one `config.yaml` entry) and embed it directly in the `AskUserQuestion` prompt so the user sees exactly what they approve. Frame each question around one of:
 
-**AskUserQuestion** — use this tool to ask the user **exactly one** structured question per call. Never bundle a second question into the prompt. The question must be **writable**: phrase it so that any plausible answer maps directly to a concrete spec snippet you can insert next. Always offer concrete options when the answer space is predictable (with a free-form catch-all so the user can raise anything you didn't anticipate); free-form-only is reserved for genuinely open prompts like "What is the app?". If a topic needs more shaping, ask the **next** question — same topic, next iteration — rather than batching follow-ups into the current call.
-
----
-
-### Phase 1 — What are we building?
-
-Understand the product. This is the most important phase and needs to be done thoroughly. Drill into the behavior of the app.
-
-This phase is **incremental and one-question-at-a-time**. Do **not** ask everything up front and then write all the specs at the end. Walk through the topics below in order, and for each topic run a tight loop where **every iteration is one question followed by an immediate write to disk**:
-
-1. **Ask** — use **AskUserQuestion** with **exactly one** question per call. Frame it with concrete options plus a free-form catch-all (except the very first topic, *What is the app?*, which is free-form only). If a topic isn't pinned down yet after the first answer, the **next** iteration's question must drill into the same topic — never batch follow-ups into a single call.
-2. **Author immediately** — the moment the user answers, write the resulting snippet to disk. Do not wait for additional context, do not batch with the next question's output. Eager writes are the point; they may be wrong on the first try and that's expected. The next question lets the user correct them. Depending on the topic, the write goes to:
-   - **Module structure** — create or update the `.plain` file(s) (single module, template + modules, or chained modules). Set up YAML frontmatter (`import`, `requires`, description). If you use a template, create it in `template/` without `***functional specs***`. Use the `create-import-module` skill where applicable.
-   - **`***definitions***`** — add or refine concepts (entities, attributes, relationships). Define every concept before it is referenced. Use the `add-concept` skill.
-   - **`***functional specs***`** — translate the answer into a single chronological, incremental spec (≤200 lines of code change, language-agnostic, no conflicts). Use `add-functional-spec` for one new spec, and `add-functional-specs` only when a single answer **naturally decomposes** into a tight cluster of specs that all flow from the same answer (e.g. "list / create / delete" CRUD on a single entity). Never hand-author the `***functional specs***` section directly.
-   Do **not** add `***implementation reqs***`, `***test reqs***`, or `***acceptance tests***` in this phase — they belong to later phases.
-
-   If a later answer contradicts or refines content already on disk, **update the affected snippet in place right now**, before the next question.
-3. **Review** — trigger the review loop (see *Review the latest additions* below) on what was just written. Apply the user's response back to the `.plain` files and re-surface any snippet that materially changed. Only move on to the next topic once every flagged snippet has been explicitly approved.
-
-Walk through these topics in order, running ask → author → review for each. Skip a topic only if it genuinely doesn't apply, and say so explicitly:
-
-1. **What is the app?** — one-sentence description. What problem does it solve? Free-form, not multiple choice. Author: a stub `.plain` file with the description in the YAML frontmatter and the proposed module name. Review: the frontmatter and module split.
-2. **Who uses it?** — target users or personas; is it a CLI tool, web app, API, desktop app, mobile app, library, or something else? Author: any user/persona concepts that emerge. Review: those concepts.
-3. **What is the scope?** — MVP, prototype, or full product? What is explicitly out of scope? Author: tighten the description and (if needed) split modules to keep MVP scope cohesive. Review: the resulting module structure.
-4. **Core entities** — the main "things" in the system (Users, Tasks, Orders, Messages, …), their attributes, and relationships. Author: one concept per entity in `***definitions***`. Review: each concept snippet.
-5. **Key features** — every distinct thing the app should do. For each feature capture trigger, expected outcome, and edge cases / validation rules. Author: one or more functional specs per feature, in chronological build order, each ≤200 LOC. Break large features into smaller specs together with the user. Review: each new functional spec (or tight group of related specs).
-6. **User flows** — walk through the app from the user's perspective: what happens first, what happens next, decision points. Author: ordering and any missing intermediate functional specs. Review: the affected sequence of specs.
-7. **Constraints and rules** — business rules, validation, permissions, error handling behavior. Author: fold these into the relevant functional specs (and add concepts where they are first-class entities, e.g. roles). Review: the updated specs.
-8. **Optional — user interface.** Skip entirely if the project doesn't have a UI; otherwise ask:
-   - How does the UI look and feel?
-   - Where are the key UI elements located?
-   - What do the key UI elements do?
-   - What is the layout and design of the UI?
-   Author: UI-behavior functional specs (still language- and framework-agnostic). Review: those specs.
-9. **Anything else** — anything the user wants to add or change that hasn't already been covered.
-
-Keep asking follow-ups within a topic until every feature is specific enough to become a single `***plain` functional spec (implying ≤200 lines of code change each). If a feature is too large, break it down together with the user before authoring.
-
-When all topics are complete, summarize the full feature list and the final module/concept layout, and get an explicit overall confirmation before moving to Phase 2.
-
-#### Review the latest additions
-
-This is the review loop you trigger after each authoring step above. Walk through **only what just changed** with the user using **AskUserQuestion**, **one snippet at a time**. Do **not** re-review the whole file every iteration — pick the **single most relevant snippet** that warrants a decision (one concept, one functional spec, the module frontmatter) and embed it directly in the question prompt so the user sees exactly what they are approving.
-
-For each snippet you raise, frame the question around one of:
-
-- **Missing parts** — anything that should be in the spec but isn't (an attribute, a validation rule, an edge case, a missing concept).
+- **Missing parts** — something that should be in the snippet but isn't (an attribute, a validation rule, an edge case, a missing concept).
 - **Possible extensions** — behavior or detail that could reasonably be expanded.
-- **Ambiguities** — wording, ordering, or relationships that could be read multiple ways.
-
-Each `AskUserQuestion` call offers concrete options such as "Approve as written", "Extend with …", "Clarify …", plus a free-form catch-all. Never batch multiple review questions into one call — if more than one snippet needs review, ask about them sequentially, applying edits between each.
-
-Apply the user's response back to the `.plain` files (using the appropriate edit skills) **immediately after each answer**, even if the edit is partial or you expect a follow-up to refine it. Re-surface any snippet that materially changed. Continue until every snippet you flagged has been explicitly approved before returning to the topic loop and moving on to the next topic.
-
----
-
-### Phase 2 — What technologies should it use?
-
-Gather the technical stack **and** the project's structure/architecture. This phase only affects `***implementation reqs***` — testing-related concerns are handled later.
-
-This phase is **incremental and one-question-at-a-time**, just like Phase 1. Walk through the topics below in order, and for each topic run a tight loop where **every iteration is one question followed by an immediate write to disk**:
-
-1. **Ask** — use **AskUserQuestion** with **exactly one** question per call. Frame it with concrete options plus a free-form catch-all. When the user has no preference, propose a sensible default that fits earlier answers and ask them to confirm. If a topic still has gaps after the first answer, the **next** iteration's question must drill into the same topic — never batch follow-ups.
-2. **Author immediately** — the moment the user answers, write the resulting requirement to `***implementation reqs***`:
-   - If a template module exists, put shared stack-wide reqs (language, framework, architecture, coding standards) there.
-   - Put module-specific reqs (e.g. data storage choices, external service integrations only one module uses) on the module that needs them.
-   Do **not** add `***test reqs***` or `***acceptance tests***` in this phase — they belong to later phases.
-
-   If a later answer contradicts or refines a requirement already on disk, **update the affected req in place right now**, before the next question.
-3. **Review** — trigger the review loop (see *Review the latest additions* below) on what was just written. Apply the user's response back to the `.plain` files and re-surface any snippet that materially changed. Only move on to the next topic once every flagged snippet has been explicitly approved.
-
-Walk through these topics in order, running ask → author → review for each. Skip a topic only if it genuinely doesn't apply, and say so explicitly:
-
-1. **Programming language** — e.g. Python, TypeScript, Java, Go. Author: a language requirement at the appropriate scope (template if shared across modules, otherwise on the module). Review: that requirement snippet.
-2. **Frameworks** — e.g. Flask, FastAPI, Next.js, Spring Boot, Express, React, Vue. Author: framework requirement(s) and any framework-specific architectural conventions. Review: the new framework reqs.
-3. **Data storage** — e.g. PostgreSQL, SQLite, file-based, in-memory, none. Author: storage requirement on the module that owns persistence (or template if shared). Review: that snippet.
-4. **External services or APIs** — anything the app talks to (auth providers, payment gateways, email/SMS, third-party APIs, internal services). Author: one requirement per integration on the module that uses it. Review: each integration snippet.
-5. **Project structure & architecture** — the architectural style and the layers/components the project should be organized into (e.g. managers, services, models, repositories, controllers, views, adapters, DTOs). Discuss naming conventions, directory layout, and the responsibilities/boundaries of each layer. If the user has no preference, propose a layout that fits the language, framework, and feature set, and confirm it. Author: architecture/layering reqs in the template (if shared) and any module-specific deviations on the module. Review: the architecture reqs and the resulting layer split.
-6. **Other constraints** — deployment target, OS requirements, performance needs, coding standards, security policies, observability, anything stack-wide that hasn't already been covered. Author: each constraint as its own requirement at the appropriate scope. Review: the new constraint snippets.
-7. **Anything else** — anything the user wants to add or change that hasn't already been covered.
-
-When all topics are complete, summarize the full tech stack and the chosen architecture, and get an explicit overall confirmation before moving to Phase 3.
-
-#### Review the latest additions
-
-Same shape as the Phase 1 review loop. Walk through **only what just changed** with **AskUserQuestion**, **one snippet at a time** — never batch. Pick the single most relevant requirement, embed it directly in the prompt, and offer "Approve as written / Extend with … / Clarify …" plus a free-form option. Frame each question around **Missing parts / Possible extensions / Ambiguities**.
-
-Apply the user's response back to the `.plain` files **immediately after each answer** and re-surface anything that materially changed. Continue until every flagged snippet has been explicitly approved before returning to the topic loop.
-
----
-
-### Phase 3 — How should testing be done?
-
-Gather the testing strategy. This phase covers `***test reqs***`, `***acceptance tests***`, the testing scripts under `test_scripts/`, and the `config.yaml` file(s) that wire them in.
-
-This phase is **incremental and one-question-at-a-time**, just like Phase 1 and Phase 2. Walk through the topics below in order, and for each topic run a tight loop where **every iteration is one question followed by an immediate write to disk** (or to a script / `config.yaml`):
-
-1. **Ask** — use **AskUserQuestion** with **exactly one** question per call. Frame it with concrete options plus a free-form catch-all. When the user has no preference, propose a sensible default that fits the language and stack chosen in Phase 2 and ask them to confirm. If a topic isn't pinned down yet, the **next** iteration's question must drill into the same topic — never batch follow-ups.
-2. **Author immediately** — the moment the user answers, translate it into the right place:
-   - **`***test reqs***`** for testing rules and expectations (framework, layout, conventions, coverage, constraints). Use `add-test-requirement`. Put shared reqs on the template module if one exists; module-specific reqs (e.g. integration tests bound to a particular external service) go on the module that needs them.
-   - **`***acceptance tests***`** under the relevant functional spec, authored via `add-acceptance-test`. Only author these when conformance testing is opted in (see topic 3).
-   - **Scripts under `test_scripts/`** 
-      - Use skill `implement-unit-testing-script` to implement the unit testing script (Determine during 1. **Ask**)
-      - Use skill `implement-prepare-environment-script` to implement prepare environment script (Determine during 1. **Ask**)
-      - Use skill `implement-conformance-testing-script` to implement conformance testing script (Determine during 1. **Ask**)
-   - **`config.yaml`** entries — every time a script is generated, update the relevant `config.yaml`(s) to point at it. Only include entries for scripts that were actually generated.
-3. **Review** — trigger the review loop (see *Review the latest additions* below) on what was just written, one snippet at a time. Apply the user's response back to the `.plain` files, the scripts, and the `config.yaml`(s), and re-surface anything that materially changed. Only move on to the next topic once every flagged snippet has been explicitly approved.
-
-   If a later answer contradicts or refines content already on disk (a script, a `config.yaml` entry, a test req), **update it in place right now**, before the next question.
-
-#### Plan the `config.yaml` split
-
-Before topic 1, decide how many `config.yaml` files this project needs. The rule is **one `config.yaml` per part of the system that has its own testing scripts**:
-
-- A single-stack project (e.g. one Python service) gets one `config.yaml` at the project root.
-- A multi-part project gets one `config.yaml` **per part**. For example, a backend in Python/FastAPI and a frontend in React end up with two: `backend/config.yaml` referencing the Python scripts and `frontend/config.yaml` referencing the JS scripts. Each config only references its own scripts; do not mix them.
-- The split should follow the module boundaries from Phase 1 / Phase 2: if a module has its own language, framework, and test scripts, it gets its own `config.yaml` next to that module.
-
-State the planned split to the user (e.g. "I'll create `backend/config.yaml` and `frontend/config.yaml`") and confirm. The config files themselves don't need to exist yet — each one will be created the first time a script is generated for its part, and entries will accumulate as you walk the topics below. For reference, valid keys are:
+- **Ambiguities** — wording, ordering, or relationships open to more than one reading.
 
-```yaml
-unittests-script: test_scripts/run_unittests_<language>.<sh|ps1>
-conformance-tests-script: test_scripts/run_conformance_tests_<language>.<sh|ps1>
-prepare-environment-script: test_scripts/prepare_environment_<language>.<sh|ps1>
-```
+Offer options such as "Approve as written", "Extend with …", "Clarify …", plus a free-form catch-all. Ask about one snippet at a time — never batch review questions. Apply each answer back to the `.plain` files (and scripts / `config.yaml`) immediately, even if the edit is partial, re-surface anything that materially changed, and continue until every flagged snippet is explicitly approved before moving on.
 
-Use `.sh` on macOS/Linux and `.ps1` on Windows, matching what testing scripts. Preserve any existing fields in a `config.yaml` you are updating.
+## Phase sequencing
 
-**Hard partition reminder.** Throughout this phase:
+The workflow begins with a short Phase 0 intent interview, followed by four gated authoring phases.
 
-- **Everything about `:UnitTests:`** (framework, layout, packages, conventions, execution command, coverage, mocking policy — every fact) is authored into `***implementation reqs***` via `add-implementation-requirement`. The unit-test generator reads only that section
-- **Everything about `:ConformanceTests:`** (framework, layout, packages, execution command, mocking policy, environment prereqs — every fact) is authored into `***test reqs***` via `add-test-requirement`. The conformance-test generator reads only that section
-- A topic that mixes both kinds of facts is split: unit facts go to impl reqs, conformance facts go to test reqs. They never share a bullet
+Phase 0 is conversational only: read `references/phase-0-intent.md`, ask its five questions one at a
+time, write nothing to disk, summarize the resulting intent brief, and get explicit confirmation.
+Before advancing, check the Phase 0 checklist block inline. Do not spawn a review agent for Phase 0.
+Carry the confirmed brief into every later phase.
 
-Walk through these topics in order, running ask → author → review for each. Skip a topic only if it genuinely doesn't apply, and say so explicitly:
+For Phases 1–4, **finish each phase — its artifacts on disk *and* explicitly approved — before
+starting the next.** Do not draft, or even ask about, later-phase content while a phase is open: if
+an answer drifts ahead, acknowledge it briefly, note it for later, and steer back. Do not branch
+into a multi-question detour about later-phase topics. Talk is not output after Phase 0; the `.plain`
+files are.
 
-1. **Unit-test framework** — e.g. pytest, Jest, JUnit, Go's `testing` package. If the user has no preference, suggest one that fits the language chosen in Phase 2.
-   - Author: a `:UnitTests:` framework requirement in `***implementation reqs***` at the appropriate scope (template if shared, otherwise on the module) — e.g. "`:UnitTests:` should use pytest" plus "`:UnitTests:` are run via `pytest tests/`". Generate `run_unittests` (and any framework config files it needs, e.g. `pytest.ini`, `jest.config.js`) via `implement-unit-testing-script`. Add the `unittests-script:` entry to the relevant `config.yaml`(s), creating each file if it doesn't exist yet.
-   - Review: the framework req, the generated script paths, and the new `config.yaml` entry.
-2. **Unit-test types and architecture mapping** — unit tests and integration tests. Which combinations does the user want? How do tests map to the architectural layers established in Phase 2 (e.g. one test module per service, repository tests with an in-memory store, etc.)?
-   - Author: a `:UnitTests:` scope / architecture requirement in `***implementation reqs***` describing which types are in scope and how they map to the architecture — phrased in terms of `:UnitTests:` so the partition is visible.
-   - Review: that requirement.
-3. **Conformance testing** — explicitly ask whether conformance/end-to-end tests should be part of the project. Conformance testing drives whether `run_conformance_tests` is generated and whether `***acceptance tests***` are authored. If the user is unsure, briefly explain the tradeoff (extra scripts + per-spec acceptance tests vs. lighter setup) and let them choose.
-   - Author (if yes):
-     - A conformance-testing requirement in `***test reqs***` (framework, execution command, any constraints).
-     - `run_conformance_tests` via `implement-conformance-testing-script`.
-     - The `conformance-tests-script:` entry in the relevant `config.yaml`(s).
-     - **Walk every functional spec authored in Phase 1, one at a time.** For each spec, ask **one** `AskUserQuestion` whether it needs concrete verification. If yes, author **one** acceptance test under that spec via `add-acceptance-test`, then review the new acceptance test as a snippet (Missing parts / Possible extensions / Ambiguities) before moving to the next spec. Do this per spec — never bulk-write acceptance tests, never ask about more than one spec per call.
-   - Author (if no): record the decision; skip the conformance script, the conformance config entry, and acceptance-test authoring entirely.
-   - Review: the conformance req (if any), the new script and config entry (if any), and each acceptance test snippet (if any).
-4. **Environment preparation script** — explicitly ask whether a `prepare_environment` script should be generated. This is the single entry point for installing dependencies and setting up fixtures/services before tests run. If the user is unsure, briefly explain that it's recommended when there are dependencies to install or services to start, and skippable when the project genuinely has nothing to prepare.
-   - Author (if yes): `prepare_environment` via `implement-prepare-environment-script`; add the `prepare-environment-script:` entry to the relevant `config.yaml`(s); if the script's responsibilities are non-trivial and worth pinning in the spec, also add a brief `***test reqs***` entry describing what `prepare_environment` is responsible for.
-   - Author (if no): record the decision; skip the script and the config entry.
-   - Review: the script (if any), the new config entry (if any), and the test req (if any).
-5. **Test layout & conventions** — directory layout, naming conventions, fixtures / mocks strategy, anything that constrains the *shape* of test code beyond what topics 1–4 already established. Ask about both kinds of tests where applicable; keep their facts in separate reqs in separate sections.
-   - Author: `:UnitTests:` layout / convention requirements in `***implementation reqs***`; `:ConformanceTests:` layout / convention requirements in `***test reqs***` (only when conformance is enabled). Phrase each one with the predefined concept it shapes so the partition is visible.
-   - Review: each requirement snippet.
-6. **Execution & tooling** — how tests are run (commands, runners, options), coverage targets, CI integration, any environment setup tests rely on beyond `prepare_environment`. Split by concept the same way as topic 5. If the agreed execution command or options differ from what the script generated in topic 1 (or 3, or 4) currently uses, update the affected script(s) now.
-   - Author: `:UnitTests:` execution requirements in `***implementation reqs***`; `:ConformanceTests:` execution requirements in `***test reqs***`. Update any affected scripts under `test_scripts/`.
-   - Review: each requirement snippet and any modified script.
-7. **Other testing constraints** — performance/load expectations, deterministic seeds, network isolation, secrets handling, anything stack-wide that constrains *how* tests are written and that hasn't already been covered.
-   - Author: each constraint as its own requirement at the appropriate scope.
-   - Review: each constraint snippet.
-8. **Anything else** — anything the user wants to add or change that hasn't already been covered.
+When entering a phase, read its reference file and walk its topics **in order** using the core loop and review loop above. Skip a topic only if it genuinely does not apply, and say so explicitly.
 
-When all topics are complete, briefly recap the full testing strategy: which `config.yaml`(s) exist, which scripts each one points at, the framework, test types in scope, the conformance and prepare-environment decisions, and any cross-cutting constraints. Get an explicit overall confirmation before moving to environment verification.
+| Phase | Reference | Finished when |
+|---|---|---|
+| 0 — What is the intent? | `references/phase-0-intent.md` | a concise intent brief covering the problem, primary user and outcome, and initial boundary is explicitly confirmed; nothing is written to disk |
+| 1 — What are we building? | `references/phase-1-product.md` | the new `***definitions***` and `***functional specs***` are on disk and approved |
+| 2 — What tech should it use? | `references/phase-2-tech.md` | the new `***implementation reqs***` are on disk and approved |
+| 3 — How is testing done? | `references/phase-3-testing.md` | the `***test reqs***` (and `***acceptance tests***` if conformance is on) are on disk, the `test_scripts/` and `config.yaml`(s) exist, and `check-plain-env` passed or each gap was acknowledged |
+| 4 — Validate and hand off | `references/phase-4-validate-handoff.md` | the agent ran `codeplain <module>.plain --dry-run` successfully against the render target, and the user has the render command plus every side-channel command |
 
-#### Review the latest additions
+Between phases, summarize and get explicit overall confirmation before continuing — the intent brief
+after Phase 0; the full feature list and module/concept layout after Phase 1; the tech stack and
+architecture after Phase 2; the testing strategy after Phase 3.
 
-Same shape as the Phase 1 and Phase 2 review loops. Ask **one** review question at a time via `AskUserQuestion`, framed around **Missing parts / Possible extensions / Ambiguities**. Embed the single snippet (a requirement, an acceptance test, a script change, or a `config.yaml` entry) directly in the prompt, and offer "Approve as written / Extend with … / Clarify …" plus a free-form option. Never batch.
+Before advancing out of Phases 1–4, spawn a **review agent** to run that phase's block of the
+**Self-check checklist** (`references/checklist.md`) and loop until it returns `APPROVED`. Phase 0
+ends with the user's confirmation and does not use a review agent.
 
-Apply the user's response back to the `.plain` files, the scripts, and the `config.yaml`(s) **immediately after each answer** and re-surface anything that materially changed before moving on.
+## Adding features later
 
-#### Verify the user's environment
-
-Once the review is complete, delegate environment verification to the **`check-plain-env`** skill. Do **not** probe the user's machine inline here — `check-plain-env` is the single source of truth for "can this machine render and test this project?" and it derives the requirement list at runtime from the project's `.plain` files, `test_scripts/`, `config.yaml`(s), and `resources/`.
-
-What `check-plain-env` does on your behalf:
-
-- Detects the host OS.
-- Builds the requirement list at runtime (language toolchains + their package managers, external services, system binaries that language packages wrap, hardware / drivers / accelerators, `codeplain` itself, credentials) — the layers a package manager **cannot** install.
-- Probes each requirement with an actual version / availability command.
-- Never probes individual language packages (`torch`, `numpy`, `FastAPI`, `react`, JARs, gems, ...) — those are installed by the project's own `prepare_environment` / unit-test scripts the moment they run.
-- Emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands for any gaps. Read-only — never installs anything itself.
-
-Invoke `check-plain-env`, then act on its return value:
-
-- **`PASS`** — the machine is ready. Continue to Phase 4.
-- **`WARN`** — everything required is present but at least one soft warning (e.g. service binary present but daemon not running, language version mismatch). Show the warnings to the user; let them decide whether to address each one now or proceed knowing the corresponding scripts will surface the issue later.
-- **`FAIL`** — at least one required item is missing. For every gap, the report already includes **what** is missing, **why** the project needs it, and **how to install it** for the detected OS. Walk the gaps with the user and, for each one, ask whether they want to install it now, swap to an alternative (which would mean revising the Phase 2 / Phase 3 decisions), or proceed knowing the corresponding scripts will fail. Re-invoke `check-plain-env` after the user installs anything so the report reflects the current state of the machine.
-
-Do not move on to Phase 4 until either `check-plain-env` returns `PASS` / `WARN` with the user's explicit acknowledgement of each warning, or the user has explicitly acknowledged each remaining `FAIL`.
-
---- 
-
-### Phase 4 — Validate and hand off
-
-Phase 4 has two halves. First, **you** (the agent) validate every spec end-to-end with a dry-run of the `codeplain` CLI so the user doesn't waste a real render — or any debugging time — on a fixable static error. Only after that passes do you **hand off** the render command (plus any side-channel commands) to the user.
-
-#### 4a. Identify the render target
-
-Find the **last module in the dependency chain** — the module that is not `requires`-ed by any other module. If there is only one module, use it. Call this module `<module>`.
-
-Examples:
-
-- Chain `base.plain → features.plain → integrations.plain` → render target is `integrations.plain`.
-- Single module `my_app.plain` → render target is `my_app.plain`.
-
-#### 4b. Build the final `config.yaml` with `init-config-file`
-
-Before validation, finalize the project's `config.yaml` file(s). Phase 3 may have written provisional entries as scripts were generated; **this** is where they're consolidated into the canonical form the renderer expects.
-
-Invoke the **`init-config-file`** skill. It:
-
-- enumerates every part of the project (one `config.yaml` per part — single-stack → root config; multi-part → one config per part),
-- assembles only the **valid** config keys derived from the `codeplain` CLI parser,
-- emits a clean YAML file per part (script paths first, then template/build folders, then copy/log settings),
-- verifies every `*-script` value resolves to a real file on disk,
-- refuses to write secrets (`api-key`) or per-invocation flags (`dry-run`, `full-plain`, `render-range`, `render-from`, `replay-with`) into the config.
-
-If `init-config-file` stops because a precondition isn't met (e.g. `prepare-environment-script` exists but no conformance script does), resolve the gap with the user before continuing — do **not** hand the project to `plain-healthcheck` with a known-broken config.
-
-#### 4c. Validate the project with `plain-healthcheck`
-
-Before handing off to the user, run the **`plain-healthcheck`** skill. It is the single source of truth for "is this project ready to render?" — it:
-
-- inventories every `.plain` module and identifies every top module,
-- validates every `config.yaml` (existence, parseability, script paths actually point at files in `test_scripts/`, no mixed stacks, etc.), and
-- runs `codeplain <top>.plain --dry-run` for **every** top module with the correct `--config-name` for multi-part projects.
-
-Do **not** run the dry-run inline here. Delegate to `plain-healthcheck`. The skill handles the full detect → fix → re-run loop on its own (syntax errors, undefined concepts, broken `import` / `requires` chains, cyclic definitions, missing templates, complexity violations, conflicting reqs, config drift, missing scripts, …) and only returns once everything passes or a gap genuinely needs the user.
-
-Then:
-
-- **`plain-healthcheck` returns `PASS`** → move on to step 4d.
-- **`plain-healthcheck` returns `FAIL`** → do **not** ask the user to render. Work through the numbered list it produced (each item references a specific `.plain` file, `config.yaml`, or script), resolve each one with the appropriate edit skill, and re-run `plain-healthcheck` until it returns `PASS`. Any item the skill could not auto-resolve will name the concrete question to put to the user.
-- **Environment failure** (e.g. `codeplain` not on PATH, `CODEPLAIN_API_KEY` not set) → `plain-healthcheck` will surface this with a clearly-marked environment failure. Tell the user exactly what's missing and how to fix it before continuing. Do not pretend the healthcheck passed.
-
-For the full list of `codeplain` flags `plain-healthcheck` may use, see the CLI reference at the end of this section.
-
-#### 4d. Present the render command
-
-Only after the dry-run passes, tell the user their specs are ready and present the render command:
-
-```
-codeplain <module>.plain
-```
-
-Examples:
-
-- Chain `base.plain → features.plain → integrations.plain`:
-
-  ```
-  codeplain integrations.plain
-  ```
-
-- Single module with no chain (e.g. `my_app.plain`):
-
-  ```
-  codeplain my_app.plain
-  ```
-
-Also remind the user of any **side-channel commands** they may want to run themselves per the testing strategy locked in during Phase 3 — for example `./test_scripts/run_unittests.sh <module>`, `./test_scripts/prepare_environment.sh <module>`, or `./test_scripts/run_conformance_tests.sh <module> <conformance_tests_folder>`. Only mention the scripts that were actually generated in Phase 3.
-
-### Adding features to an existing project
-
-Once the initial `***plain` specs are written, the user will come back with new features. Use the `add-feature` skill for this — it runs the same interview → implement → review loop but scoped to a single feature against an existing `.plain` file. Always communicate that you are updating the `***plain` specs, not the generated code. This keeps the conversation continuous: the user describes a feature, you ask clarifying questions, write the `***plain` specs, and repeat.
-
----
+Once the initial specs exist, the user will return with new features. Use the `add-feature` skill — the same interview → author → review loop scoped to a single feature on an existing `.plain` file. Keep framing the work as updating the specs, not the generated code.
 
 ## Question style
 
-The questions you put to the user must use simple grammatical structures:
-
 - Prefer short, direct sentences over compound or nested clauses.
 - Use plain words over jargon when both convey the same meaning.
-- One idea per sentence. If a sentence needs a comma-separated list of clauses, split it.
+- One idea per sentence; split a comma-chained list of clauses into separate sentences.
+- Never drop detail to simplify — keep every constraint, edge case, option, and piece of context the user needs to answer accurately, splitting into more sentences instead.
+
+## Error handling
+
+- **A user answer contradicts prior specs** → edit the affected snippet in place immediately, then continue the loop; surface a non-trivial change in the next question.
+- **A phase gate is not met** (a review agent returned unmet boxes) → do not advance; fix each gap through the interview → author → review loop, then spawn a fresh review agent and repeat until `APPROVED`.
+- **A review agent can't be spawned or returns nothing usable** → spawn a fresh one; do not self-certify the gate. Never `SendMessage` a running reviewer — capture its returned result. If spawning genuinely fails in this environment, walk the phase's checklist block inline as a fallback and tell the user the review was self-run.
+- **`check-plain-env` returns `FAIL`** (Phase 3) → walk each gap with the user; install, swap to an alternative, or explicitly acknowledge it before Phase 4. Re-invoke after any install.
+- **`plain-healthcheck` returns `FAIL`** (Phase 4) → do not present the render command; work through its numbered list with the right edit skill and re-run until it passes.
+- **Environment failure** (`codeplain` not on PATH, `CODEPLAIN_API_KEY` unset) → tell the user exactly what is missing and how to fix it; never pretend the check passed.
 
-Simpler grammar must not come at the cost of detail. Keep every constraint, edge case, option, and piece of context the user needs to answer accurately. If simplifying a sentence would drop a detail, split it into more sentences instead.
+## Self-check checklist
 
---- 
+`references/checklist.md` is the **review agent's** one-shot script, not the orchestrator's. At each phase gate the orchestrator spawns a fresh review agent (see *Agent orchestration*) and puts everything it needs in the spawn prompt: that phase's block, the loop-iteration block (Phases 1–3), the touched-file paths, and a **phase evidence record** of what happened in the interview. The reviewer verifies each box by its tag — `[disk]` against the files, `[record]` against the evidence record, `[both]` cross-checked with mismatches flagged — and returns `APPROVED` or a numbered gap list. The orchestrator loops (fix → re-review with a fresh agent) until a review agent approves, and never advances on an unmet box or self-certifies the gate.
 
-### Reference
+## Reference
 
-- Full ``***plain`` language guide: PLAIN_REFERENCE.md
-- Skills for editing specs are in `.claude/skills/`
-- Templates go in `template/`, but import paths omit the `template/` prefix. Resources go in `resources/`
-- Generated code lands in `plain_modules/` (read-only, never edit)
-- Test scripts are in `test_scripts/`
+- Applicable language rules and operational references: `load-plain-reference`.
+- Spec-editing skills live in `.claude/skills/`.
+- Templates go in `template/`, but import paths omit the `template/` prefix. Resources go in `resources/`.
+- Generated code lands in `plain_modules/` (read-only, never edit). Test scripts live in `test_scripts/`.

package/forge/skills/forge-plain/references/checklist.md

@@ -0,0 +1,66 @@
+# Forge Plain Workflow Checklist
+
+This is the **review agent's** script, and the review agent is **one-shot**: it gets everything in its spawn prompt, runs to completion, and returns a single result. It cannot ask the orchestrator or the user anything mid-run — no supported runtime (Claude Code, Codex, OpenCode) lets a subagent converse back. So at each phase gate the orchestrator supplies, in the spawn prompt: this block for the phase being closed, the loop-iteration block (Phases 1–3 only), the paths of the files touched this phase, and a **phase evidence record** — the ordered account of what happened in the interview (each question, its answer, the snippet written or edited, the approval given, and every explicit decision). Load the `***plain` rules with `load-plain-reference` before judging, so boxes like ≤200 LOC, define-before-use, and language-agnostic can be assessed.
+
+Verify each box by its tag:
+
+- **[disk]** — check independently against the files on disk; ignore the record.
+- **[record]** — check against the evidence record; the disk cannot show it.
+- **[both]** — the record claims it and the disk must corroborate; **flag any mismatch** (e.g. the record says conformance was declined but a conformance script exists on disk, or claims a spec was approved that is not on disk).
+
+A box is met only when its source confirms it. Return `APPROVED` only when every box in the relevant blocks passes; otherwise return a numbered list of the unmet boxes, each naming the exact file (and line where relevant) or the record item at fault. The orchestrator loops (fix → re-review with a fresh agent) until a review agent returns `APPROVED`; it never advances on an unmet box.
+
+## Every loop iteration (Phases 1–3)
+
+- [ ] **[record]** Asked exactly one focused question via `AskUserQuestion` each iteration — not two bundled together.
+- [ ] **[both]** Wrote the snippet to disk immediately after the answer, using the dedicated edit skill — never hand-authored a `***plain` section directly.
+- [ ] **[record]** Reviewed only what just changed (missing parts / extensions / ambiguities), applied the response back to disk, and got explicit approval before moving on.
+- [ ] **[both]** Any answer that contradicted an earlier snippet was fixed in place before the next question — no stale spec left on disk.
+- [ ] **[both]** Stayed within the current phase — no drafting of later-phase content on disk, no multi-question detours into later-phase topics.
+
+## Phase 0 — Intent
+
+- [ ] **[record]** Invoked `load-plain-reference` first (unless already loaded this session).
+- [ ] **[record]** Read `references/phase-0-intent.md` and asked its five core questions one at a time.
+- [ ] **[record]** Asked no more than one focused follow-up for an answer too vague to summarize.
+- [ ] **[record]** Kept features, entities, technology, architecture, and testing for later phases.
+- [ ] **[disk]** Wrote no project or specification files during Phase 0.
+- [ ] **[record]** Summarized the problem, primary user, desired outcome, observable success
+  criterion, and initial boundary with explicit exclusions; got explicit confirmation.
+
+## Phase 1 — What are we building?
+
+- [ ] **[record]** Carried the confirmed Phase 0 intent brief into
+  `references/phase-1-product.md`; refined it without restarting intent discovery.
+- [ ] **[record]** Walked Phase 1 topics in order (description, users/product shape, scope, entities,
+  features, flows, constraints, UI if any, anything else).
+- [ ] **[disk]** `.plain` module structure created with YAML frontmatter; template (if any) has no `***functional specs***`.
+- [ ] **[both]** Every concept authored in `***definitions***` via `add-concept`, defined before use.
+- [ ] **[both]** Every feature authored as functional specs via `add-functional-spec(s)`, each ≤200 LOC, in chronological build order.
+- [ ] **[disk]** No `***implementation reqs***`, `***test reqs***`, or `***acceptance tests***` written in this phase.
+- [ ] **[record]** Summarized the full feature list and module/concept layout; got explicit overall confirmation.
+
+## Phase 2 — What tech should it use?
+
+- [ ] **[record]** Read `references/phase-2-tech.md` and walked its topics in order (language, frameworks, storage, external services, structure/architecture, other constraints, anything else).
+- [ ] **[disk]** Every requirement authored into `***implementation reqs***` at the right scope (shared → template, module-specific → module).
+- [ ] **[disk]** No `***test reqs***` or `***acceptance tests***` written in this phase.
+- [ ] **[record]** Summarized the tech stack and architecture; got explicit overall confirmation.
+
+## Phase 3 — How is testing done?
+
+- [ ] **[record]** Read `references/phase-3-testing.md`; stated the planned `config.yaml` split (one per part) and confirmed it before topic 1.
+- [ ] **[disk]** Honored the hard partition — every `:UnitTests:` fact in `***implementation reqs***`, every `:ConformanceTests:` fact in `***test reqs***`; never shared a bullet.
+- [ ] **[record]** Walked topics in order (unit framework, unit types/architecture, conformance decision, prepare-environment decision, layout, execution, other constraints, anything else).
+- [ ] **[disk]** Generated the needed scripts under `test_scripts/` via the `implement-*-script` skills and added each `*-script:` entry to the right `config.yaml`.
+- [ ] **[both]** Conformance decision was asked explicitly; if yes, walked every Phase-1 functional spec one at a time for acceptance tests via `add-acceptance-test` (acceptance tests present on disk when the decision was yes).
+- [ ] **[record]** Prepare-environment decision was asked explicitly and recorded.
+- [ ] **[record]** Recapped the testing strategy; got explicit overall confirmation.
+- [ ] **[record]** Ran `check-plain-env`; it returned `PASS`, or `WARN`/`FAIL` with each remaining item explicitly acknowledged by the user (re-invoked after any install).
+
+## Phase 4 — Validate and hand off
+
+- [ ] **[disk]** Identified the render target — the last module in the dependency chain (or the single module).
+- [ ] **[both]** Ran `init-config-file` to build the final `config.yaml`(s); resolved any precondition gap with the user before validating.
+- [ ] **[record]** Ran `plain-healthcheck`; worked its numbered list to `PASS` — never presented the render command on a `FAIL`.
+- [ ] **[record]** Presented the render command only after the dry-run passed, plus every side-channel script actually generated in Phase 3.

package/forge/skills/forge-plain/references/phase-0-intent.md

@@ -0,0 +1,29 @@
+# Phase 0 — What is the intent?
+
+Extract the user's intent before creating files or decomposing the product into specifications.
+Keep this phase short. Ask exactly five core questions, one at a time, and do not write to disk.
+
+## Questions
+
+1. **Problem** — What problem should this software solve?
+2. **Primary user** — Who is it mainly for?
+3. **Desired outcome** — What should that user be able to accomplish with it?
+4. **Success criterion** — What observable result would make the first version useful?
+5. **Initial boundary** — What should the first version deliberately leave out?
+
+Ask one focused follow-up only when an answer is too vague to summarize. Do not explore features,
+entities, technology, architecture, or testing yet; those belong to later phases.
+
+## Intent brief
+
+Summarize the answers in five short bullets:
+
+- Problem
+- Primary user
+- Desired outcome
+- Observable success criterion
+- Initial boundary and explicit exclusions
+
+Ask the user to confirm or correct the brief. Phase 0 finishes only after explicit confirmation.
+Carry the confirmed brief into Phase 1 so product questions refine it instead of restarting intent
+discovery.