plain-forge 1.0.1

package/forge/rules/import-modules.md

@@ -0,0 +1,51 @@
+---
+description: Rules for creating and using import modules in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for import modules
+
+When creating or editing a `.plain` file that uses `import` or is intended to be imported by other modules, always follow these rules:
+
+## What an import module is
+- An import module contains **only** `***definitions***`, `***implementation reqs***`, and/or `***test reqs***`
+- It must **not** contain `***functional specs***`
+- It must **not** use `requires` in its frontmatter
+- It must live in the **`template/`** directory
+- It may optionally `import` other modules or templates for layered reuse
+
+## What import does
+- `import` pulls in `***definitions***`, `***implementation reqs***`, and `***test reqs***` from the target module
+- It does **not** pull in `***functional specs***`
+- The default import directory is `template/` — the `template/` prefix is not needed in import paths
+- Import paths omit the `.plain` extension
+
+## Concept visibility
+- All concepts defined in the imported module become available in the importing module
+- Check for concept name collisions between imports and local definitions before adding
+
+## Format
+
+```plain
+---
+import:
+  - airplain
+description: Module that imports shared definitions and reqs
+---
+```
+
+A module can import multiple modules:
+
+```plain
+---
+import:
+  - airplain
+  - shared_utils
+---
+```
+
+## Combining import with requires
+- A module can use both `import` and `requires` together
+- `import` brings in shared definitions and reqs
+- `requires` brings in the build dependency chain and functional specs
+- An import module itself must **not** use `requires`

package/forge/rules/required-concepts.md

@@ -0,0 +1,45 @@
+---
+description: Rules for using required_concepts in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for `required_concepts`
+
+When adding or editing `required_concepts` in a `.plain` file's frontmatter, always follow these rules:
+
+## What required_concepts does
+- `required_concepts` declares concepts that any module importing this file **must** define
+- It creates a contract: the import module references these concepts but does not define them — the importing module is responsible for providing definitions
+- This is used exclusively on import modules and templates
+
+## When to use it
+- Use `required_concepts` when an import module or template (in `template/`) references concepts that vary per project or per importing module
+- The import module can reference these concepts in its definitions, implementation reqs, or test reqs — but their actual definitions come from whoever imports the file
+
+## Importing module must satisfy the contract
+- Every concept listed in `required_concepts` must be defined in the importing module's own `***definitions***` section
+- If the importing module does not define a required concept, the spec is invalid
+- Check `required_concepts` of all imported modules before finalizing a module
+
+## Do not define required concepts locally
+- The import module that declares `required_concepts` must **not** define those concepts itself
+- The whole point is that the importing module provides the definition
+
+## Format
+
+```plain
+---
+required_concepts: [":AppName:", ":AppConfig:"]
+description: Template that requires AppName and AppConfig to be defined by the importer
+---
+
+***definitions***
+- :MainFile: is the entry point for :AppName:.
+
+***implementation reqs***
+- :MainFile: should load :AppConfig: on startup.
+```
+
+In this example, `:AppName:` and `:AppConfig:` are referenced but not defined — the module that imports this template must define them.
+
+List concepts as a YAML array with each concept in `:ConceptName:` notation.

package/forge/rules/requires-modules.md

@@ -0,0 +1,59 @@
+---
+description: Rules for creating and using requires modules in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for requires modules
+
+When creating or editing a `.plain` file that uses `requires`, always follow these rules:
+
+## What requires does
+- `requires` establishes a **build ordering** — the required module is built before the current one
+- The required module's generated code (`plain_modules/<required_module>`) is copied as the starting point
+- The required module's `***functional specs***` become visible as **previous functional specs**
+- Only `exported_concepts` from the required module are available — not its full definitions
+
+## Build order, not necessarily dependency
+- The current module does not need to extend or depend on the required module's code
+- The two modules may be completely independent
+- `requires` ensures the build order is correct for the project as a whole
+
+## Conflict prevention
+- The current module's functional specs must not conflict with the required module's specs
+- The required module's specs are treated as previous requirements — the renderer sees them as context
+- Review the required module's functional specs before adding new ones
+
+## No access to full definitions
+- Only concepts listed in the required module's `exported_concepts` are available
+- Other concepts from the required module are internal and invisible
+- If you need shared definitions, use `import` for that — not `requires`
+
+## File locations
+- Modules that use `requires` live at the **repository root** — they are functional modules with specs
+- `requires` paths point to other root-level modules (e.g., `auth`, `messaging`)
+- The default import directory is `template/` — the `template/` prefix is not needed in import paths (e.g., `airplain`)
+- Never `require` a template — templates are for `import` only
+
+## Format
+
+```plain
+---
+requires:
+  - auth
+import:
+  - airplain
+description: Module built after auth, importing shared definitions
+---
+```
+
+A module can require multiple modules:
+
+```plain
+---
+requires:
+  - auth
+  - messaging
+import:
+  - airplain
+---
+```

package/forge/rules/test-reqs.md

@@ -0,0 +1,47 @@
+---
+description: Rules for writing ***test reqs*** sections in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for writing `***test reqs***`
+
+When writing or editing a `***test reqs***` section in a `.plain` file, always follow these rules:
+
+## Conformance tests only
+- Test reqs specify how **conformance tests** should be written and run
+- Unit test guidance goes in `***implementation reqs***`, not here
+- Acceptance tests are nested under individual functional specs, not here
+- Behavioral requirements go in `***functional specs***`, not here
+
+## What belongs here
+- Test framework: which framework to use (e.g., pytest, Unittest, xUnit)
+- Execution method: the command to run the tests
+- Testing constraints: what must or must not be done in tests (e.g., no skipping, mock requirements)
+- Test data: how test fixtures or mock data should be structured
+- Environment setup: any prerequisites for running conformance tests
+
+## Test type reference
+
+| Test type | Where to specify | Purpose |
+|-----------|-----------------|---------|
+| Unit tests | `***implementation reqs***` | Test individual functionalities in isolation |
+| Conformance tests | `***test reqs***` | Verify implementation conforms to the full spec |
+| Acceptance tests | `***acceptance tests***` under a functional spec | Verify a specific functional spec |
+
+## No duplication
+- Do not duplicate guidance already present in the file or its imports
+- Check imported templates before adding a new test req
+
+## Concept references
+- Reference predefined concepts like `:ConformanceTests:` where appropriate
+- All other referenced `:Concepts:` must be defined in `***definitions***`
+
+## Format
+
+```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.
+```

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

@@ -0,0 +1,98 @@
+---
+name: add-acceptance-test
+description: >-
+  Add acceptance tests under a functional spec in a ***plain spec file. Use
+  when the user wants to add verification criteria for a specific functional
+  spec, or after adding a functional spec that needs testable success criteria.
+---
+
+# Add Acceptance Test
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## Workflow
+
+1. **Identify the target `.plain` file and the functional spec** to attach the acceptance test to. If ambiguous, ask the user.
+2. **Read the file** to understand the functional spec, existing acceptance tests (if any), and the `***test reqs***` section (acceptance tests are implemented according to test reqs).
+3. **Draft the acceptance test(s)** following the rules below.
+4. **Nest them** under the target functional spec using a `***acceptance tests***` subsection.
+5. **Read the file again** to confirm correct placement, indentation, and syntax.
+
+## When to Add Acceptance Tests
+
+- The functional spec's correct behavior is **non-obvious** or easily misinterpreted.
+- The spec involves **edge cases**, boundary conditions, or specific numeric outcomes.
+- The user explicitly requests verification criteria.
+- The spec was added via the `add-functional-spec` skill and warrants testable success criteria.
+
+## Format
+
+Acceptance tests are nested under the functional spec they verify, using a `***acceptance tests***` subsection:
+
+```plain
+***functional specs***
+
+- The system should process :Task: items in batches of 100.
+
+  ***acceptance tests***
+  - Processing 250 :Task: items should result in 3 batches.
+  - Each batch should contain at most 100 items.
+```
+
+Key formatting rules:
+- The `***acceptance tests***` header is indented under the functional spec it belongs to.
+- Each test bullet is indented under the `***acceptance tests***` header.
+- Multiple acceptance tests can be listed under a single functional spec.
+
+## Rules
+
+### Conformance with the Functional Spec
+
+An acceptance test is essentially an **example that illustrates** the functional spec — it clarifies intent by showing a concrete scenario. It may imply minor code changes, but those should not be substantial. The acceptance test **must be consistent with** the functional spec it is nested under. If the acceptance test asserts behavior that contradicts, narrows, or extends the functional spec in ways not implied by it, the system will reject it as a conflicting acceptance test. Before writing, re-read the parent functional spec and ensure every assertion in the acceptance test is a direct, logical consequence of what the spec states.
+
+```
+Functional spec:
+- The system should return :Resource: items sorted by creation date in descending order.
+
+Good (consistent):
+- The first :Resource: in the response should have the most recent creation date.
+
+Bad (contradicts the spec — the spec says descending, not ascending):
+- The first :Resource: in the response should have the oldest creation date.
+
+Bad (extends beyond the spec — the spec says nothing about limiting results):
+- The response should contain at most 50 :Resource: items.
+```
+
+### Scope
+
+Each acceptance test verifies a specific, observable aspect of the functional spec it's nested under. Do not test behavior from other functional specs.
+
+### Testability
+
+Every acceptance test must describe a concrete, verifiable outcome — not a vague quality. The test should be implementable as an automated conformance test.
+
+```
+Good: - The response should contain exactly 3 items.
+Bad:  - The response should be correct.
+```
+
+### Language Agnosticism
+
+Like functional specs, acceptance tests must be written in terms of behavior and outcomes — not language-specific constructs.
+
+### Relationship to Test Reqs
+
+Acceptance tests extend conformance tests and are implemented according to the `***test reqs***` specification. They do not replace test reqs — they add spec-specific verification on top of the general testing framework defined there.
+
+## Validation Checklist
+
+- [ ] Every assertion is a direct logical consequence of the parent functional spec
+- [ ] No assertion contradicts, narrows, or extends beyond the parent spec
+- [ ] Acceptance test illustrates the spec via example, not introducing substantial new behavior
+- [ ] Nested under the correct functional spec
+- [ ] Indentation is correct (`***acceptance tests***` indented under the spec)
+- [ ] Each test describes a concrete, verifiable outcome
+- [ ] Tests are scoped to the parent functional spec only
+- [ ] Written in language-agnostic terms
+- [ ] No duplication with existing acceptance tests on the same spec

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

@@ -0,0 +1,67 @@
+---
+name: add-concept
+description: >-
+  Add a concept to the ***definitions*** section of a ***plain spec file. Use
+  when the user wants to define a new concept, entity, or domain term in a
+  .plain file.
+---
+
+# Add Concept
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## Workflow
+
+1. **Identify the target `.plain` file.** If ambiguous, ask the user.
+2. **Read the file** to understand existing definitions, imports, and concepts.
+3. **Validate the concept name** against the syntax rules below.
+4. **Check for uniqueness** — the concept name must not already exist in the file or its imports.
+5. **Check referenced concepts** — any `:ConceptName:` used in the definition must already be defined above it (in this file or via `import`/`requires`). Concept references must not form cycles (e.g., A references B and B references A).
+6. **Check for circular references** — if the new concept references `:B:`, then `:B:` must not reference the new concept (directly or indirectly). Example of a circular definition to avoid:
+   ```plain
+   - :Order: is placed by :Customer: and contains :OrderItem: entries.
+   - :Customer: is a user who has placed at least one :Order:.
+   ```
+   Fix by removing the back-reference:
+   ```plain
+   - :Customer: is a user of the system.
+   - :Order: is placed by :Customer: and contains :OrderItem: entries.
+   ```
+7. **Insert the concept** into the `***definitions***` section, after any concepts it references.
+8. **Read the file again** to confirm correct placement and syntax.
+
+## Concept Syntax Rules
+
+- Wrapped in colons: `:ConceptName:`
+- CamelCase, starting with an uppercase letter
+- Valid characters: letters, digits, `+`, `-`, `.`, `_`
+- Must be globally unique across the spec and all its imports
+- Exported concepts from `requires` modules are **not transitive** — if a concept needs to be shared across multiple `requires` modules, define it in a common import module instead
+
+## Definition Format
+
+A concept definition is a bullet in `***definitions***` that starts with the concept name:
+
+```plain
+***definitions***
+- :ConceptName: is a description of what it represents.
+```
+
+Attributes and constraints are nested sub-bullets:
+
+```plain
+- :Task: describes an activity that needs to be done by :User:. :Task: has:
+  - Name - a short description (required)
+  - Notes - additional details (optional)
+  - Due Date - completion deadline (optional)
+```
+
+## Validation Checklist
+
+- [ ] Name uses `:CamelCase:` notation
+- [ ] Name is globally unique (not defined elsewhere in the file or imports)
+- [ ] Definition starts with the concept name
+- [ ] All referenced concepts (`:OtherConcept:`) are already defined above
+- [ ] No circular references between concepts
+- [ ] Description is clear, concise, and language-agnostic
+- [ ] Placed inside a `***definitions***` section

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

@@ -0,0 +1,136 @@
+---
+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.
+---
+
+# 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.
+
+## Core principle: one question → one answer → write specs
+
+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:
+
+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.
+
+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 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.
+
+## 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.
+
+## 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.
+
+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.
+
+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.
+
+## 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.
+
+### 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:
+
+- **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 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.
+- **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.
+
+### 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.
+
+- **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.
+
+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.
+
+### 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.
+
+Show the exact existing snippet in the question and offer:
+
+- **(a) keep** the existing spec — back out or narrow what you just wrote,
+- **(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.
+
+### 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.
+
+### 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.
+
+## 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`**.
+
+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).
+   - Functional specs are language-agnostic.
+   - All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.).
+   - 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`.
+
+## When the User Comes Back with Another 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 → ...**
+
+## Validation Checklist
+
+- [ ] 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
+
+
+## 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.
+
+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.

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

@@ -0,0 +1,81 @@
+---
+name: add-functional-spec
+description: >-
+  Add a single functional spec to the ***functional specs*** section of a
+  ***plain spec file. Use whenever exactly one new functional spec is being
+  added — whether the user explicitly asks, or another skill/workflow
+  (e.g. forge-plain, add-feature) needs to author a new functional spec.
+  Every new entry under ***functional specs*** must go through either this
+  skill or `add-functional-specs` (the bulk variant for adding multiple specs
+  in one pass); hand-authoring functional specs without invoking one of these
+  skills is forbidden.
+---
+
+# Add Functional Spec
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## Workflow
+
+1. **Identify the target `.plain` file.** If ambiguous, ask the user.
+2. **Read the entire file** to understand existing definitions, implementation reqs, and all current functional specs (including those in `requires` modules).
+3. **Draft the functional spec** following the rules below.
+4. **Analyze complexity** — use the `analyze-if-func-spec-too-complex` skill to verify the drafted spec implies ≤ 200 LOC. If too complex, use the `break-down-func-spec` skill to split it, then repeat from step 3 for each resulting spec.
+5. **Check for conflicts** with every existing functional spec — this is critical. Run `analyze-func-specs` **once** with the new spec plus all existing specs (in the file and in any `requires` chain) as a single batch. The batched analyzer returns every conflicting pair in one call — do **not** invoke a pair-by-pair analyzer. For each conflicting pair it reports, run `resolve-spec-conflict` on that pair; re-run `analyze-func-specs` over the touched set after each resolution until the verdict is `COMPATIBLE`.
+6. **Append the spec** to the end of the `***functional specs***` section (specs are chronological; new ones go last).
+7. **Read the file again** to confirm correct placement and syntax.
+
+## Rules
+
+### Complexity Limit
+
+Each functional spec must imply a **maximum of 200 changed lines of code**. If the requirement is too large, use the `break-down-func-spec` skill to split it into multiple smaller, independent specs. Do not include LOC estimates in the spec text.
+
+### Chronological Ordering
+
+Specs are rendered incrementally, top to bottom. The renderer has **no knowledge of future specs** — only previously rendered specs are in context. This means:
+- A new spec can reference behavior defined by earlier specs.
+- A new spec **cannot** assume anything about specs that come after it.
+- Place the new spec at the correct position if it must come before a future spec; otherwise append at the end.
+
+### Language Agnosticism
+
+Write in terms of behavior, concepts, and domain logic — not implementation constructs. Avoid language-specific types, generics syntax, framework annotations, or other constructs tied to a particular language or framework. General technical terms (null values, JSON types, HTTP status codes) are fine. Language-specific guidance belongs in `***implementation reqs***`.
+
+### No Conflicts
+
+The new spec must not contradict any existing functional spec. Conflicting specs are the most costly outcome. Before adding, review all existing specs and verify the new one is compatible. Use `analyze-func-specs` to check the new spec against every existing spec in **one batched call** — it lists every conflicting pair, so a pair-by-pair analyzer is not needed. If ambiguity exists, add explicit detail to eliminate any conflicting interpretation. For each conflicting pair the batched analyzer reports, use the `resolve-spec-conflict` skill to diagnose and fix it before proceeding.
+
+### Disambiguation
+
+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:.
+  - 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:.
+```
+
+### Deterministic Interface
+
+Specs must be detailed enough that a developer can use the built software without reading the generated code. All external interfaces must be explicit — REST endpoint paths and HTTP methods, CLI command names and arguments, file formats, message schemas, etc. Never leave interface details up to the renderer's discretion.
+
+### Encapsulation
+
+Functionality must be self-contained in the spec text. `requires` modules only import functional specs, so do not rely on implementation reqs to convey behavior — they won't be visible in downstream modules.
+
+## Acceptance Tests
+
+If the functional spec needs verification, use the `add-acceptance-test` skill to add acceptance tests after inserting the spec.
+
+## Validation Checklist
+
+- [ ] Spec implies ≤ 200 lines of code changes
+- [ ] No conflict with any existing functional spec
+- [ ] Written in language-agnostic terms (no language/framework specifics)
+- [ ] All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.)
+- [ ] All referenced `:Concepts:` are defined in `***definitions***`
+- [ ] Sentences are short, clear, and unambiguous
+- [ ] No redundancy with existing specs
+- [ ] Placed in correct chronological position (usually at the end)