plain-forge 1.0.18 → 1.0.19

package/forge/skills/add-feature/SKILL.md

@@ -1,136 +1,140 @@
 ---
 name: add-feature
 description: >-
-  End-to-end feature addition: takes a feature request in plain English and
-  incrementally writes ***plain specs (concepts, implementation reqs, functional
-  specs, acceptance tests) one functionality at a time, asking, authoring, and reviewing
-  per functionality. Use when the user wants to add a new feature to an existing project.
+  End-to-end feature addition on an existing ***plain project: runs a short feature-intent
+  interview, then takes the confirmed request and, one question at a time, incrementally writes
+  ***plain specs (concepts, implementation reqs, functional specs, test reqs,
+  acceptance tests) to disk — asking, authoring, and reviewing per
+  functionality — then closes with a plain-healthcheck gate. Use when the user
+  wants to add a feature to an existing project. Not for bootstrapping a new
+  project from scratch (use forge-plain) or for editing generated code (the
+  .plain specs are the source of truth).
 ---
 
 # Add Feature
 
 Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
 
-This skill is the continuous-loop counterpart of the full QA workflow in `forge-plain`. Where that workflow bootstraps an entire project from scratch, `add-feature` adds a single feature to an **existing** set of `.plain` specs.
+`add-feature` is the continuous-loop counterpart of `forge-plain`. Where `forge-plain` bootstraps an entire project from scratch, `add-feature` adds a single feature to an **existing** set of `.plain` specs. It begins with a short intent phase, then runs the authoring loop scoped to one feature.
 
-## Core principle: one question → one answer → write specs
+## Core loop: one question → one answer → write to disk
 
-This skill runs as a tight, granular loop. **Each iteration is a single question to the user, followed by an immediate write to a `.plain` file.** No multi-question batches, no upfront interview, no "I'll gather a few things and then author." The cycle is:
+This loop starts after Phase 0. Each iteration is a single question followed by an immediate write:
 
-1. Ask **one** focused question.
-2. User answers.
-3. **Immediately** write the resulting spec 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.
+1. **Ask** one focused question via `AskUserQuestion` — never bundle two. Shape it so any plausible answer maps directly to one writable snippet: a single behavior, concept, attribute, edge case, or constraint — not an open-ended design question. Bad shape: "How should the feature behave?" Good shape: "When the user submits an empty title, should the request be rejected with HTTP 400, accepted with a default title, or something else?" Offer concrete options plus a free-form catch-all whenever the answer space is predictable.
+2. **Author immediately** — the moment the user answers, write the snippet to disk (see *2b* for which skill to route to). Do not wait for "enough" context; 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. **Refine on the next question**, which often extends or corrects what was just written.
 
-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 and welcome — you'll fix them in place on the next iteration. The questions themselves should be **shaped to produce immediately writable content**: a single attribute, a single behavior, a single edge case, a single constraint — not open-ended design questions that can't be turned into a snippet.
+**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 — another iteration of the loop — 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.
 
-**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 should 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.
+**Fix contradictions in place.** If a later answer refines or contradicts a snippet already on disk, edit that snippet right now. Never leave stale intent on disk; surface a non-trivial change in the next question.
 
 ## Input
 
-A feature request from the user — anything from a one-liner ("add dark mode") to a detailed description. The request may be vague; the functionality loop in Phase 2 will sharpen it as you go.
+A feature request from the user — anything from a one-liner ("add dark mode") to a detailed
+description. Phase 0 turns it into a confirmed feature-intent brief; Phase 2 sharpens the behavior
+as it is authored.
+
+## Phase 0 — Feature intent
+
+Read `references/phase-0-intent.md`. Ask its five core questions one at a time, write nothing to
+disk, summarize the answers as a feature-intent brief, and get explicit confirmation. Ask no more
+than one focused clarification when an answer is too vague to summarize.
+
+Carry the confirmed brief into every later phase. Before advancing, check the Phase 0 block in
+`references/checklist.md` inline.
 
 ## Phase 1 — Scope
 
-Keep this phase short. The goal is to know enough to ask the **very first** writable question — not to design the entire feature on paper.
+Keep this short. The goal is to know enough to ask the **very first** writable question — not to design the whole feature on paper.
 
-1. **Read the request.** Identify what is being asked for at a high level and which existing `.plain` file(s) the feature most likely belongs to.
-2. **Read the target `.plain` file(s).** Follow their `import` and `requires` chains so you understand the existing definitions, implementation reqs, functional specs, test reqs, and acceptance tests. You need this context to recognize impact when it surfaces in Phase 2.
-3. **Pick the target module** with one question — only if it's actually ambiguous which file to modify. Otherwise skip this and start authoring immediately.
+1. **Read the confirmed feature-intent brief.** Identify which existing `.plain` file(s) the feature most likely belongs to.
+2. **Read the target `.plain` file(s)**, following their `import` and `requires` chains, so the existing definitions, implementation reqs, functional specs, test reqs, and acceptance tests are in context. This is what lets Phase 2 recognize impact when it surfaces.
+3. **Pick the target module with one question — only if it is genuinely ambiguous** which file to modify. Otherwise skip it and start authoring immediately.
 
-End Phase 1 the moment you can name the file you'll write into and a single concrete starter question. Do **not** ask framing questions, scope questions, or multi-part design questions here.
+End Phase 1 the moment the target file and a single concrete starter question are clear. Do **not** ask framing, scope, or multi-part design questions here.
 
 ## Phase 2 — One-question loop
 
-This phase is a single, repeating cycle. Each iteration is **exactly one question** to the user followed by **an immediate write** to a `.plain` file. The loop ends when the user says the feature is fully covered.
+A single repeating cycle: exactly one question, then an immediate write. The loop ends when the user says the feature is fully covered.
 
 ### 2a. Ask one question
 
-Use **AskUserQuestion** with **one** question per call. The question must be **writable**: phrase it so that any plausible answer maps directly to a concrete spec snippet you can insert. Bad shape: "How should the feature behave?" Good shape: "When the user submits an empty title, should the request be rejected with HTTP 400, accepted with a default title, or something else?"
-
-Each question targets exactly one of:
+Ask one writable question per `AskUserQuestion` call, targeting exactly one of:
 
 - **Behavior** — a single trigger and its outcome.
-- **A concept** — does this introduce a new concept, or extend an existing one? Which single attribute?
-- **A single edge case** — one invalid input, empty state, boundary value.
+- **A concept** — a new concept, or one single attribute of an existing one.
+- **A single edge case** — one invalid input, empty state, or boundary value.
 - **A single constraint** — one business rule, permission, ordering, or size limit.
-- **Implementation guidance** — only when the functionality requires technology / library / pattern not already in the file or its imports.
+- **Implementation guidance** — only when the functionality needs technology / a library / a pattern not already in the file or its imports.
 - **Verification** — only when the *Conformance gate* below is satisfied: one concrete outcome that proves this functionality works.
 
-Always offer concrete options when the answer space is predictable, plus a free-form catch-all. Never bundle a second question into the prompt; never ask a question whose answer doesn't translate into a writable snippet on its own.
+Never bundle a second question into the prompt; never ask a question whose answer doesn't translate into a writable snippet on its own.
 
 ### 2b. Write 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 will let the user correct them.
+Route each answer to the right edit skill — never hand-author a `***plain` section:
 
-- **New concept** → use `add-concept` to add to `***definitions***`. Define before any reference.
-- **New functional spec** → use `add-functional-spec`. That skill runs `analyze-if-func-spec-too-complex` and `analyze-func-specs` for you; let it. **Never hand-author functional specs.** If the skill reports the spec is too complex, ask the user a follow-up question to split it (the next iteration of the loop) — don't break it down on your own.
-- **New implementation req** → use `add-implementation-requirement`. Only when the answer introduces technology / library / data format / architectural pattern not already present.
-- **New acceptance test** → use `add-acceptance-test` under the relevant functional spec. Only when the *Conformance gate* is satisfied and the answer describes a concrete verification.
-- **New test req** → use `add-test-requirement`. Only when conformance testing is configured and this answer changes how conformance tests are run.
+- **New concept** → `add-concept` (into `***definitions***`; define before any reference).
+- **New functional spec** → `add-functional-spec`. It runs `analyze-if-func-spec-too-complex` and `analyze-func-specs` for you — let it. **Never hand-author functional specs.** If it reports the spec is too complex, ask the user a follow-up question to split it (the next loop iteration) — do not break it down alone.
+- **New implementation req** → `add-implementation-requirement`. Only when the answer introduces technology / a library / a data format / an architectural pattern not already present.
+- **New acceptance test** → `add-acceptance-test`, under the relevant functional spec. Only when the *Conformance gate* is satisfied and the answer describes a concrete verification.
+- **New test req** → `add-test-requirement`. Only when conformance testing is configured and the answer changes how conformance tests are run.
 
-If the user's answer **contradicts or refines** something you wrote in a previous iteration, fix the existing snippet in place right now — edit the spec, the concept, or the requirement directly. This is the explicit "correct on the next pass" behavior. Surface the change in the next question if it's non-trivial.
+If the answer contradicts or refines an earlier snippet, fix that snippet in place now (per *Fix contradictions in place* above).
 
 ### 2c. Handle conflicts just-in-time
 
-If `add-functional-spec` (via the analyzers it calls) reports a conflict with an existing spec, or if the snippet you just wrote would **break** (contradict, invalidate) or **augment** (change the meaning of, add behavior to) an existing concept / functional spec / implementation req / test req / acceptance test, your **next question** to the user must be about that conflict.
+If `add-functional-spec` (via its analyzers) reports a conflict, or the snippet just written would **break** (contradict, invalidate) or **augment** (change the meaning of, add behavior to) an existing concept / functional spec / implementation req / test req / acceptance test, the **next question** must be about that conflict. Show the exact existing snippet in the question and offer:
 
-Show the exact existing snippet in the question and offer:
-
-- **(a) keep** the existing spec — back out or narrow what you just wrote,
+- **(a) keep** the existing spec — back out or narrow what was just written,
 - **(b) augment** the existing spec — embed the proposed new wording in the question,
 - **(c) replace** the existing spec.
 
-Apply the user's choice the instant they answer. If they augmented a concept, walk every spec that references it and update each in place; limit changes to the approved scope. Never silently rewrite prior intent.
+Apply the choice the instant the user answers. If they augmented a concept, walk every spec that references it and update each in place, limited to the approved scope. Never silently rewrite prior intent.
 
 ### 2d. Decide what's next
 
-Ask the user whether the feature is fully covered. If yes, go to Phase 3. If no, return to 2a with the next single question — which often refines what you just wrote, or starts the next behavior, concept, edge case, or constraint.
+Ask the user whether the feature is fully covered. Yes → Phase 3. No → return to 2a with the next single question.
 
 ### Conformance gate
 
-Steps 2a–2d above only generate `***test reqs***` and `***acceptance tests***` when the project has a `config.yaml` with a valid `conformance-tests-script` entry pointing at an existing conformance-test script in `test_scripts/`. Check the relevant `config.yaml` (the one that covers this module — there may be more than one in multi-part projects) and confirm the referenced script file exists. If conformance testing is not configured, skip those authoring paths entirely; functional specs, concepts, and implementation reqs still get authored normally.
+Author `***test reqs***` and `***acceptance tests***` **only** when the project has a `config.yaml` with a valid `conformance-tests-script` entry pointing at an existing script in `test_scripts/`. Check the `config.yaml` that covers this module (multi-part projects may have several) and confirm the referenced script exists. If conformance testing is not configured, skip those two authoring paths entirely — concepts, functional specs, and implementation reqs are still authored normally.
 
 ## Phase 3 — Final review
 
-Most checks have already happened in the one-question loop. Phase 3 is a slim consistency pass, and its **final automated step is always `plain-healthcheck`**.
+Most checks already happened in the loop; this is a slim consistency pass whose final automated step is always `plain-healthcheck`.
 
 1. Read the modified `.plain` file(s) in full.
 2. Verify:
-   - All new concepts are defined before use and have no circular references.
-   - Chronological ordering is correct end-to-end (no new spec depends on something that comes after it).
+   - Every new concept is defined before use, with no circular references.
+   - Chronological ordering is correct end-to-end — no spec depends on something that comes after it.
    - Functional specs are language-agnostic.
-   - All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.).
+   - Every external interface is explicit (endpoint paths, methods, CLI args, formats).
    - Acceptance tests (if any) are consistent with their parent specs.
-3. Present the final diff for the modified file(s) to the user for approval.
-4. If the user requests changes, drop **straight back into the one-question loop** to fix them — one question, one write, one fix at a time. Do not restart the whole loop from scratch.
-5. **Final automated step — run `plain-healthcheck`.** This is the last thing the skill does before handing control back to the user. After the user approves the final diff, invoke the `plain-healthcheck` skill. It validates every `config.yaml` and dry-runs every top module, so a feature is never considered finished while the project would fail to render. If `plain-healthcheck` returns `FAIL`, work through the numbered list it produced (fix only `.plain` files / `config.yaml` / scripts — never generated code) by dropping back into the one-question loop, and then re-run `plain-healthcheck`. Repeat until it returns `PASS`. The skill is not done until `plain-healthcheck` has returned `PASS` — only then tell the user the feature is ready and remind them to re-render with `codeplain <module>.plain`.
+3. Present the final diff for the modified file(s) and get the user's approval.
+4. If the user requests changes, drop **straight back into the one-question loop** — one question, one write, one fix at a time. Do not restart the loop from scratch.
+5. **Run `plain-healthcheck`** — the last thing this skill does. It validates every `config.yaml` and dry-runs every top module, so a feature is never finished while the project would fail to render. If it returns `FAIL`, work through its numbered list (fixing only `.plain` files / `config.yaml` / scripts — never generated code) by dropping back into the loop, then re-run. Repeat until `PASS`. Only then tell the user the feature is ready and remind them to re-render with `codeplain <module>.plain`.
 
-## When the User Comes Back with Another Feature
+## Next feature
 
-After completing one feature, the user may immediately describe the next. Start again from Phase 1. This creates a continuous loop: **scope → functionality loop → final review → scope → ...**
+After one feature is done, the user may describe the next. Start again from Phase 0 — a continuous
+loop: **intent → scope → one-question loop → final review → intent → …**
 
-## Validation Checklist
+## Error handling
 
-- [ ] Target `.plain` file(s) and their `import`/`requires` chain were read before authoring
-- [ ] Every iteration asked exactly one question and wrote to disk immediately after the answer
-- [ ] Every functional spec was authored via `add-functional-spec` (never hand-written)
-- [ ] New concepts defined before they are referenced
-- [ ] No circular concept references
-- [ ] Every conflict / break / augment surfaced by the analyzers was put to the user as the next question and resolved before continuing
-- [ ] Functional specs are language-agnostic
-- [ ] All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.)
-- [ ] Acceptance tests are consistent with their parent functional specs
-- [ ] User approved the final diff
-- [ ] `plain-healthcheck` returned `PASS` after the final diff was approved
+- **A user answer contradicts prior specs** → edit the affected snippet in place immediately; surface a non-trivial change in the next question.
+- **`add-functional-spec` reports "too complex"** → ask the user a follow-up question to split the spec (next loop iteration); never split it alone.
+- **A conflict / break / augment surfaces** → make it the next question (2c) and resolve it before continuing.
+- **`plain-healthcheck` returns `FAIL`** → do not declare the feature done; fix the listed `.plain` / `config.yaml` / script items via the loop and re-run until `PASS`.
 
+## Validation checklist
 
-## Question style
+Run the loop block in `references/checklist.md` on each iteration, and walk the whole list during Phase 3 before declaring the feature done. It is a self-audit of this workflow — never a substitute for it. A box only counts as met when the spec is on disk and explicitly approved; complete any unmet step before finishing.
 
-The questions you put to the user must use simple grammatical structures:
+## Question style
 
 - 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.
-
-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.
+- One idea per sentence; split a comma-chained list of clauses into separate sentences.
+- Never drop detail to simplify — keep every constraint, edge case, and option the user needs, splitting into more sentences instead.

package/forge/skills/add-feature/references/checklist.md

@@ -0,0 +1,38 @@
+# Add Feature Workflow Checklist
+
+Use this to verify the workflow was followed — never as a substitute for it. Run the loop block on each iteration, and run the whole list once more during Phase 3 before declaring the feature done. A box only counts as met when the spec is on disk and explicitly approved, not merely discussed. If a box is unmet, go back and complete the step.
+
+## Phase 0 — Feature intent
+
+- [ ] Invoked `load-plain-reference` first (unless already loaded this session).
+- [ ] Read `references/phase-0-intent.md` and asked its five core questions one at a time.
+- [ ] Asked no more than one focused clarification for an answer too vague to summarize.
+- [ ] Wrote no project or specification files during Phase 0.
+- [ ] Kept concepts, spec wording, implementation technology, and tests for later phases.
+- [ ] Summarized motivation, affected user, desired outcome, observable success criterion, and
+  boundary with explicit exclusions; got explicit confirmation.
+
+## Phase 1 — Scope
+
+- [ ] Carried the confirmed feature-intent brief into scope and identified the likely target
+  `.plain` file(s) without restarting intent discovery.
+- [ ] Read the target `.plain` file(s) and followed their `import`/`requires` chain before authoring.
+- [ ] Picked the target module with a question only when genuinely ambiguous — otherwise started authoring immediately (no framing/scope/multi-part design questions here).
+
+## Every loop iteration (Phase 2)
+
+- [ ] Asked exactly one focused question via `AskUserQuestion` — not two bundled together — targeting one writable snippet (behavior, one concept/attribute, one edge case, one constraint, implementation guidance, or verification).
+- [ ] Wrote the snippet to disk immediately after the answer via the dedicated edit skill — never hand-authored a `***plain` section.
+- [ ] Every functional spec was authored via `add-functional-spec` (never hand-written); if it reported "too complex", split it via a follow-up question rather than alone.
+- [ ] New concepts defined before they are referenced, with no circular references.
+- [ ] Any answer that contradicted an earlier snippet was fixed in place before the next question — no stale intent left on disk.
+- [ ] Every conflict / break / augment surfaced by the analyzers was put to the user as the *next* question (keep / augment / replace) and resolved before continuing.
+- [ ] `***test reqs***` / `***acceptance tests***` authored only when the Conformance gate holds (a `config.yaml` with a valid `conformance-tests-script` pointing at an existing script).
+- [ ] Asked the user whether the feature is fully covered before leaving the loop.
+
+## Phase 3 — Final review
+
+- [ ] Read the modified `.plain` file(s) in full.
+- [ ] Verified: concepts defined before use, no cycles, chronological ordering correct end-to-end, functional specs language-agnostic, every external interface explicit (endpoints, methods, CLI args, formats), acceptance tests consistent with their parent specs.
+- [ ] Presented the final diff and got the user's approval (change requests dropped back into the one-question loop, not a restart).
+- [ ] Ran `plain-healthcheck`; worked its numbered list to `PASS` (fixing only `.plain`/`config.yaml`/scripts — never generated code) before declaring the feature ready and reminding the user to re-render with `codeplain <module>.plain`.

package/forge/skills/add-feature/references/phase-0-intent.md

@@ -0,0 +1,29 @@
+# Phase 0 — What is the feature intent?
+
+Extract the intent of this feature before choosing files or authoring specifications. Ask exactly
+five core questions, one at a time, and do not write to disk.
+
+## Questions
+
+1. **Motivation** — What problem or limitation should this feature address?
+2. **Affected user** — Who should benefit from or interact with this feature?
+3. **Desired outcome** — What should that user be able to accomplish after the feature exists?
+4. **Success criterion** — What observable result would prove the feature is useful and working?
+5. **Boundary** — What should this feature deliberately leave unchanged or out of scope?
+
+Ask one focused follow-up only when an answer is too vague to summarize. Do not choose concepts,
+spec wording, implementation technology, or tests yet.
+
+## Feature-intent brief
+
+Summarize the answers in five short bullets:
+
+- Motivation
+- Affected user
+- Desired outcome
+- Observable success criterion
+- Boundary and explicit exclusions
+
+Ask the user to confirm or correct the brief. Phase 0 finishes only after explicit confirmation.
+Carry the brief into Phase 1 so scope discovery maps the intent onto existing modules instead of
+restarting the feature discussion.

package/forge/skills/add-functional-spec/SKILL.md

@@ -51,34 +51,14 @@ The new spec must not contradict any existing functional spec. Conflicting specs
 Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation. If a single line is not enough to fully disambiguate the behavior, use **nested sub-bullets** to add detail. Nested lines clarify the parent spec; they do not introduce separate functionality. Even with nested detail, the spec must still imply ≤ 200 LOC.
 
 ```plain
-- :User: should be able to send a :Message: to a :Conversation:.
+***functional specs***
+
+- A :User: can send a :Message: to a :Conversation:.
   - A :Message: must have non-empty content.
   - The :Message: is appended to the end of the :Conversation:.
   - All :Participant: members of the :Conversation: can see the new :Message:.
 ```
 
-### Line syntax (hard rule)
-
-**Every line inside `***functional specs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
-
-- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
-- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
-
-BAD — bare continuation lines (invalid ***plain syntax, will not render):
-
-```plain
-- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(),
-  which returns a list of :EventEnvelope: dicts conforming to the gateway's
-  contract.
-```
-
-GOOD — every line starts with `- `:
-
-```plain
-- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle().
-  - The method returns a list of :EventEnvelope: dicts.
-  - The dicts must conform to the gateway's :EventEnvelope: contract.
-```
 
 ### Deterministic Interface
 

package/forge/skills/add-functional-specs/SKILL.md

@@ -74,35 +74,14 @@ That coverage is achieved by running `analyze-func-specs` **once per spec being
 Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation. If a single line is not enough to fully disambiguate the behavior, use **nested sub-bullets** to add detail. Nested lines clarify the parent spec; they do not introduce separate functionality. Even with nested detail, the spec must still imply ≤ 200 LOC.
 
 ```plain
-- :User: should be able to send a :Message: to a :Conversation:.
+***functional specs***
+
+- A :User: can send a :Message: to a :Conversation:.
   - A :Message: must have non-empty content.
   - The :Message: is appended to the end of the :Conversation:.
   - All :Participant: members of the :Conversation: can see the new :Message:.
 ```
 
-### Line syntax (hard rule, per spec)
-
-**Every line inside `***functional specs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject the whole file.
-
-- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
-- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
-- This rule applies to **every** spec in the batch — one bad continuation line invalidates the entire insert.
-
-BAD — bare continuation lines (invalid ***plain syntax, will not render):
-
-```plain
-- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(),
-  which returns a list of :EventEnvelope: dicts conforming to the gateway's
-  contract.
-```
-
-GOOD — every line starts with `- `:
-
-```plain
-- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle().
-  - The method returns a list of :EventEnvelope: dicts.
-  - The dicts must conform to the gateway's :EventEnvelope: contract.
-```
 
 ### Deterministic Interface
 

package/forge/skills/add-implementation-requirement/SKILL.md

@@ -61,36 +61,17 @@ Implementation reqs are bullet points in the `***implementation reqs***` section
 
 ```plain
 ***implementation reqs***
-- :Implementation: should be in Python 3.12.
-- :Implementation: should use pip for dependency management.
-- When writing CSV files, :Implementation: should use streaming writes to avoid holding large datasets in memory.
-```
-
-Reference defined `:Concepts:` where they add clarity. Implementation reqs in non-leaf sections apply to all subsections.
-
-## Line syntax (hard rule)
 
-**Every line inside a section must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+- :Implementation: should be in Python 3.12.
 
-- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
-- Nested detail is also a `- ` item, indented under its parent. The indentation alone is not enough; the leading `- ` is required.
+- :Implementation: should use pip for dependency management.
 
-BAD — bare continuation lines (invalid ***plain syntax, will not render):
+- When writing CSV files, :Implementation: should use streaming writes to avoid holding large datasets in memory.
 
-```plain
-- :Implementation: tech stack will be finalized in Phase 2.
-  - Until then, treat this section as a placeholder so the renderer accepts
-    the file. Phase 2 will replace this with language, framework, HTTP
-    client, packaging, and architecture decisions.
 ```
 
-GOOD — every line starts with `- `:
+Reference defined `:Concepts:` where they add clarity. Implementation reqs in non-leaf sections apply to all subsections.
 
-```plain
-- :Implementation: tech stack will be finalized in Phase 2.
-  - Until then, treat this section as a placeholder so the renderer accepts the file.
-  - Phase 2 will replace it with language, framework, HTTP client, packaging, and architecture decisions.
-```
 
 ## Encapsulation Warning
 

package/forge/skills/add-resource/SKILL.md

@@ -15,7 +15,7 @@ Linked resources are external files referenced from within a `.plain` spec using
 
 ## Workflow
 
-1. **Identify or create the resource file.** It should be in the `resources/` directory or in the same folder (or a subfolder) as the `.plain` file.
+1. **Identify or create the resource file.** Keep it inside the project — the `resources/` directory is the conventional home; it does not have to sit next to the `.plain` file.
 2. **Add the markdown link** at the appropriate place in the spec.
 3. **Verify the file path** is relative to the `.plain` file location.
 4. **Read the file back** to confirm correct link syntax and path.
@@ -35,16 +35,15 @@ Use standard markdown link syntax inside any spec section:
 
 ***functional specs***
 
-- The system should expose an API conforming to the [API specification](resources/api_spec.yaml).
+- An API conforming to the [API specification](resources/api_spec.yaml) is exposed.
 ```
 
 ## Path Rules
 
-- Paths are resolved **relative to the `.plain` file location**.
-- Only files in the same folder or subfolders are supported.
-- No absolute paths.
+- Paths are resolved **relative to the directory where `codeplain` is run** (the current working directory).
+- Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk.
 - **No external URLs** — only local file references.
-- **No folder paths** — only local file references.
+- **No folder paths** — the target must be a file, not a directory.
 - Only text-based files are supported.
 
 ### A linked resource MUST be a single, text-based file that exists on disk
@@ -70,7 +69,7 @@ The **only** exceptions are URLs and paths that are *values the produced softwar
 
 ### What a linked resource CAN be
 
-- A single file in the same folder as the `.plain` file, or in any subfolder of it (`resources/` is the conventional home).
+- A single file inside the project, reachable by a path relative to where `codeplain` is run — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
 - A **text-based** file the renderer can read end-to-end: JSON, YAML, XML, HTML, Markdown, plain text, CSV, TSV, source code in any language (`.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.rs`, `.kt`, `.swift`, `.c`, `.cpp`, `.cs`, …), shell scripts, SQL, JSON Schema, OpenAPI, AsyncAPI, Protobuf `.proto`, GraphQL SDL, `.jolt`, `.env.example`, `.toml`, `.ini`, `.proto`, `Dockerfile`, etc.
 
 ## Common Resource Types
@@ -102,6 +101,6 @@ The **only** exceptions are URLs and paths that are *values the produced softwar
 - [ ] **Target is a text-based file** (no binary extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.ico`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.zip`, `.tar`, `.gz`, `.mp3`, `.mp4`, `.wav`, `.exe`, `.so`, `.dylib`, `.class`, `.wasm`, …)
 - [ ] **No URLs or folder paths anywhere in the surrounding `.plain` content** (not as link targets, not in body prose), with the sole exception of URLs / paths that are runtime values the generated software itself uses
 - [ ] Path is relative to the `.plain` file, not absolute
-- [ ] File is in the same folder or a subfolder (no `../` references)
+- [ ] Path resolves to a real text file on disk from where `codeplain` is run (`../` traversal is allowed)
 - [ ] Markdown link syntax is correct: `[display text](relative/path)`
 - [ ] Resource content is relevant and adds value beyond what the spec text says

package/forge/skills/add-test-requirement/SKILL.md

@@ -51,35 +51,18 @@ Test reqs are bullet points in the `***test reqs***` section:
 
 ```plain
 ***test reqs***
+
 - :ConformanceTests: should be implemented using pytest framework.
+
 - :ConformanceTests: will be run using "pytest" command.
+
 - :ConformanceTests: must be implemented and executed - do not skip tests.
+
 - :ConformanceTests: should mock all external HTTP calls.
 ```
 
 Reference predefined concepts like `:ConformanceTests:` and any defined `:Concepts:` where they add clarity.
 
-## Line syntax (hard rule)
-
-**Every line inside `***test reqs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
-
-- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
-- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
-
-BAD — bare continuation lines (invalid ***plain syntax, will not render):
-
-```plain
-- :ConformanceTests: must mock all external HTTP calls so that the
-  test suite remains hermetic and does not depend on network access.
-```
-
-GOOD — every line starts with `- `:
-
-```plain
-- :ConformanceTests: must mock all external HTTP calls.
-  - The test suite must remain hermetic.
-  - Tests must not depend on network access.
-```
 
 ## Validation Checklist
 

package/forge/skills/analyze-2-func-specs/SKILL.md

@@ -31,8 +31,8 @@ Work through each question. If any answer is "yes", the specs likely conflict.
 Do the two specs make mutually exclusive assertions about the same behavior?
 
 ```
-Spec A: The system should return :Resource: items sorted by name in ascending order.
-Spec B: The system should return :Resource: items sorted by creation date in descending order.
+Spec A: :Resource: items are returned sorted by name in ascending order.
+Spec B: :Resource: items are returned sorted by creation date in descending order.
 
 Verdict: CONFLICTING — both define the sort order for the same response,
 but specify different fields and directions. A single implementation cannot
@@ -44,8 +44,8 @@ satisfy both unless scoped to different contexts.
 Does one spec set a state or value that the other spec assumes is different?
 
 ```
-Spec A: :TaskList: should initially be empty.
-Spec B: :TaskList: should contain a default "Welcome" :Task: on first load.
+Spec A: :TaskList: is initially empty.
+Spec B: :TaskList: contains a default "Welcome" :Task: on first load.
 
 Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
 ```
@@ -55,8 +55,8 @@ Verdict: CONFLICTING — both define the initial state of :TaskList: differently
 Does the later spec silently replace behavior established by the earlier spec without acknowledging it?
 
 ```
-Spec A: The system should validate :User: credentials using an API key.
-Spec B: The system should validate :User: credentials using OAuth 2.0.
+Spec A: :User: credentials are validated using an API key.
+Spec B: :User: credentials are validated using OAuth 2.0.
 
 Verdict: CONFLICTING — both define the authentication mechanism but pick
 different approaches. The later spec overrides the earlier one.
@@ -67,8 +67,8 @@ different approaches. The later spec overrides the earlier one.
 Are the two specs ambiguous enough that a renderer could interpret them as conflicting, even if the user intends them to be complementary?
 
 ```
-Spec A: The system should return all :Resource: items.
-Spec B: The system should return only active :Resource: items.
+Spec A: All :Resource: items are returned.
+Spec B: Only active :Resource: items are returned.
 
 Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
 Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
@@ -79,8 +79,8 @@ Could be resolved by scoping each to different conditions (e.g., filtered vs unf
 Do both specs impose constraints on the same `:Concept:` that cannot coexist?
 
 ```
-Spec A: :BatchSize: should be 100 items.
-Spec B: :BatchSize: should be 50 items for :Resource: types with attachments.
+Spec A: :BatchSize: is 100 items.
+Spec B: :BatchSize: is 50 items for :Resource: types with attachments.
 
 Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
 ```

package/forge/skills/analyze-func-specs/SKILL.md

@@ -41,8 +41,8 @@ Work through each question for the pair under inspection. If any answer is "yes"
 Do the two specs make mutually exclusive assertions about the same behavior?
 
 ```
-Spec A: The system should return :Resource: items sorted by name in ascending order.
-Spec B: The system should return :Resource: items sorted by creation date in descending order.
+Spec A: :Resource: items are returned sorted by name in ascending order.
+Spec B: :Resource: items are returned sorted by creation date in descending order.
 
 Verdict: CONFLICTING — both define the sort order for the same response,
 but specify different fields and directions. A single implementation cannot
@@ -54,8 +54,8 @@ satisfy both unless scoped to different contexts.
 Does one spec set a state or value that the other spec assumes is different?
 
 ```
-Spec A: :TaskList: should initially be empty.
-Spec B: :TaskList: should contain a default "Welcome" :Task: on first load.
+Spec A: :TaskList: is initially empty.
+Spec B: :TaskList: contains a default "Welcome" :Task: on first load.
 
 Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
 ```
@@ -65,8 +65,8 @@ Verdict: CONFLICTING — both define the initial state of :TaskList: differently
 Does the later spec silently replace behavior established by the earlier spec without acknowledging it?
 
 ```
-Spec A: The system should validate :User: credentials using an API key.
-Spec B: The system should validate :User: credentials using OAuth 2.0.
+Spec A: :User: credentials are validated using an API key.
+Spec B: :User: credentials are validated using OAuth 2.0.
 
 Verdict: CONFLICTING — both define the authentication mechanism but pick
 different approaches. The later spec overrides the earlier one.
@@ -77,8 +77,8 @@ different approaches. The later spec overrides the earlier one.
 Are the two specs ambiguous enough that a renderer could interpret them as conflicting, even if the user intends them to be complementary?
 
 ```
-Spec A: The system should return all :Resource: items.
-Spec B: The system should return only active :Resource: items.
+Spec A: All :Resource: items are returned.
+Spec B: Only active :Resource: items are returned.
 
 Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
 Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
@@ -89,8 +89,8 @@ Could be resolved by scoping each to different conditions (e.g., filtered vs unf
 Do both specs impose constraints on the same `:Concept:` that cannot coexist?
 
 ```
-Spec A: :BatchSize: should be 100 items.
-Spec B: :BatchSize: should be 50 items for :Resource: types with attachments.
+Spec A: :BatchSize: is 100 items.
+Spec B: :BatchSize: is 50 items for :Resource: types with attachments.
 
 Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
 ```