@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/genome/rules/requires-modules.md

@@ -0,0 +1,80 @@
+---
+description: Rules for creating and using requires modules in .plain files
+---
+
+# Rules for requires modules
+
+When creating or editing a `.plain` file that uses `requires`, or one that is referenced in another `.plain` file's `requires` directive, always follow these rules:
+
+## What requires does
+
+- `requires` attaches the current module to the project's **build chain**: the required module is built first, and its generated code is copied as the starting point for the current module
+- The copied code is the required module's **accumulated** output — it already contains the code of all of that module's own ancestors
+- The `***functional specs***` of the required module **and of all its ancestors** become visible as **previous functional specs** — this visibility **is transitive** down the whole chain
+- Of a required module's definitions, only the concepts listed in its `exported_concepts` are visible; the module's other definitions stay internal. Each exported concept arrives with its full definition text
+- Export visibility **is not transitive**: an ancestor's exports are visible only if that ancestor is itself listed in `requires`
+
+## Chain topology
+
+- All modules connected by `requires` form a single **tree** with a common root: code accumulates along each branch, and branches never reconverge
+- **Diamond joins are prohibited.** A module must not require two modules from divergent branches — there is no way to merge two divergent codebases into one starting point
+- When `requires` lists multiple modules, every entry must lie on **one root-to-tip ancestor path**: each listed module must be an ancestor of the deepest one
+- The **deepest entry is the attachment point** — it alone determines the build order and the starting code. The other entries add nothing to ordering; they exist **only** to make those ancestors' `exported_concepts` visible
+- Branching outward is fine: two modules may each require the same parent, creating independent branches (and therefore independent top modules)
+
+## Tech stack must match (hard rule)
+
+- Because the required module's generated code is copied as the starting point and the renderer continues building on top of it with a single toolchain, two modules can only be linked with `requires` when they target the **same language, framework, and runtime**
+- A runtime / network dependency between systems is **not** a reason to use `requires`
+- Example of the mistake: a React frontend that talks to a Python/FastAPI backend over HTTP must **not** `requires: [backend]` — the stacks differ
+- Model that pair as two independent root modules (each with its own test scripts) and express the contract through a shared API schema in `resources/` or shared concepts in an `import`ed module — never through `requires`
+
+## Building upon but not necessarily extension
+
+- The current module does not need to functionally extend the required module — it may address a completely different concern
+- Even so, the two are never independent artifacts: the current module's output physically contains the required module's code, because both are stages of one accumulating codebase
+- Use `requires` to place a module at the right point in that lineage, whether or not it builds on the required module's functionality
+
+## Conflict prevention
+
+- The current module's functional specs must not conflict with the specs of **any module in its ancestor chain** — all of them are previous functional specs
+- The renderer sees the whole chain's specs as prior requirements/context when rendering the current module
+- Review the ancestor chain's functional specs before adding new ones
+
+## Exports are the only visible definitions
+
+- Only concepts listed in a required module's `exported_concepts` are available, and only for modules explicitly listed in `requires`
+- Each exported concept is available with its full definition text
+- Other concepts from required modules are internal and invisible
+- To reference a concept exported by an ancestor deeper in the chain, list that ancestor in `requires` as well
+- If you need shared definitions across branches or stacks, 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`)
+- Never `require` an import module — import modules are for `import` only
+
+## Format
+
+```plain
+---
+requires:
+  - auth
+import:
+  - airplain
+description: Module built on top of auth, importing shared definitions
+---
+```
+
+A module can list multiple required modules **only when they lie on one ancestor path**. Here `messaging` itself requires `auth`, so `auth` is an ancestor of `messaging`; the module attaches after `messaging` and lists `auth` only to see its exports:
+
+```plain
+---
+requires:
+  - auth
+  - messaging
+import:
+  - airplain
+---
+```

package/genome/rules/stdlib.md

@@ -0,0 +1,73 @@
+---
+description: The ***plain standard library - import modules for a backend, a frontend, a command-line tool or a library, on a known stack
+---
+
+# Rules for the standard library
+
+turri ships a standard library of import modules that settle everything about a generic piece
+of software on one stack except what it does: its language and framework, its layout, its
+configuration, how it handles errors, how it logs, how it stops, and how it is tested. A module that
+imports one writes only what is its own - its concepts and its functional specs - and a requirement
+only for what its stack does not settle.
+
+```plain
+---
+import:
+  - stdlib/backend/python-flask
+  - stdlib/backend/conformance/python-flask
+---
+```
+
+## How it is built up
+
+- Each stack imports its language's template - `stdlib/lang/python` - and its kind's `common` -
+  `stdlib/backend/common` - so importing the stack brings all three.
+- Each stack's conformance tests are a template of their own, `stdlib/<kind>/conformance/<stack>`,
+  which imports `stdlib/<kind>/conformance/common`.
+- The `common` of a kind settles what every stack of it shares. For a backend: settings from the
+  environment, checked at start; handler, service and repository layers; domain errors turned into
+  one error body `{"error": {"code", "message"}}` with fixed codes and statuses; JSON logs with a
+  request id; shutdown on a signal. For a command-line tool: `Error: <message>` on standard error,
+  exit codes 0, 1, 2 and 130, logs on standard error with `--verbose` and `--debug`. For a frontend:
+  one API layer with an `ApiError`, errors shown in place or at the root, one logger module. For a
+  library: one public entry point, one base error type, no output of its own.
+
+## When to use it
+
+- When the person wants a backend, a frontend, a command-line tool or a library, import the stack
+  that fits instead of writing its implementation reqs yourself.
+- Pick the stack from what the person said, the project's other modules, and what the module talks
+  to. With nothing to go on: `stdlib/backend/python-fastapi`, `stdlib/frontend/react-vite`,
+  `stdlib/cli/python-typer`, `stdlib/library/python`.
+- Import the conformance template only when the module has conformance tests - the person asked for
+  them, and the project's config does not turn them off (`conformance-tests: false`). Without it
+  the module has no test reqs, and no conformance tests are written or run for it. Turning them on
+  later is adding that one import.
+- Read the templates a module imports before writing its specs - the folder is named below - and
+  write no requirement they already make (see `concise-specs.md`).
+- Write a functional spec's errors in the templates' terms: a backend's failure by its status and
+  `error.code` - `not_found`, `conflict`, `validation_error`, `unauthenticated`, `forbidden`, or a
+  code of the module's own - and a command-line tool's by its exit code and message.
+- Add a requirement on top for what the module needs beyond its stack - storage, an outside
+  service, a library it must use. When the module differs from its stack on something the stack
+  settles - another framework, another layout - write the stack yourself instead: an import cannot
+  be taken back in part. For a language with no stack of the kind wanted, import its
+  `stdlib/lang/<language>` and write the rest.
+- `stdlib/` is a reserved name. An import that starts with it is always the standard library's
+  template, and a project module at such a path - `stdlib/backend/python-fastapi.plain` in the
+  spec's folder, its `template/` folder or `PLAIN_TEMPLATE_DIRS` - is an error. Never write a module
+  under a `stdlib/` folder of the project; a project's own shared template goes in `template/`
+  under a name of its own.
+
+## What it does not do
+
+- It defines no concepts: its requirements are on the predefined `:Implementation:`, `:UnitTests:`
+  and `:ConformanceTests:` only, so it never collides with the module's own definitions.
+- It holds no storage: a module with a database says which, and how it is reached, on top.
+- It holds no testing scripts. The module still needs its unit testing script, and its conformance
+  testing script when it has conformance tests - written with the `implement-unit-testing-script`
+  and `implement-conformance-testing-script` skills for the stack's language and test framework. Each
+  runs the static checks of what it tests - the formatter, linter and type checker its language template
+  names, on the code or on the conformance tests - and they count as the tests do.
+- It names its stack's toolchain - Python 3.12, Node.js 24, Java 21, Go 1.25, Rust - which the agents use from the
+  machine turri runs on; they install none, so `turri doctor` says when the machine lacks it.

package/genome/rules/test-reqs.md

@@ -0,0 +1,57 @@
+---
+description: Rules for writing ***test reqs*** sections in .plain files
+---
+
+# 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
+
+## `:ConformanceTests:` lives here (hard rule)
+- **Everything** about `:ConformanceTests:` goes in `***test reqs***` — paths, approach, packages, framework, execution command, mocking / network policy, fixtures, pass criteria, environment prerequisites
+- `:ConformanceTests:` live outside the generated codebase, in one folder, `plain_modules/<module>/tests/` - the module's whole conformance suite, so requirements that shape them belong in test reqs by definition
+- The conformance-test generator reads **only** `***test reqs***` — anything about `:ConformanceTests:` placed elsewhere (e.g. `***implementation reqs***`) is silently ignored
+- Author each `:ConformanceTests:` requirement via `add-test-requirement` and phrase it in terms of `:ConformanceTests:` so the partition stays visible at a glance
+- Do not link the conformance testing script here (or anywhere in the specs; a link to it is ignored). turri finds it in the project root - `conformance-tests-script:` in `config.turri.yaml`, else the one `run_conformance_tests*.sh` in the root, else the one in `test_scripts/` - and shows it to the agents that write the conformance tests itself. Describe the framework and execution command here in words
+
+## 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 | Generated | Purpose |
+|-----------|-----------------|-----------|---------|
+| Unit tests | `***implementation reqs***` | Automatically | Test individual functionalities in isolation |
+| Conformance tests | `***test reqs***` | Automatically | Verify each functionality's implementation against its functional spec |
+| Acceptance tests | `***acceptance tests***` under a functional spec | Manually | Verify implementation of a functional spec through a specific end-to-end scenario |
+
+## No duplication
+- Do not duplicate guidance already present in the file or its imports
+- Check imported modules before adding a new test req
+
+## Concept references
+- Reference predefined concepts like `:ConformanceTests:` where appropriate
+- All other referenced `:Concepts:` must be defined in `***definitions***`
+
+## Conciseness
+- State each req in the fewest plain words that stay exact — see `concise-specs.md`
+- Do not restate the default behavior of the test framework this section already names
+
+## 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/genome/skills/add-acceptance-test/SKILL.md

@@ -0,0 +1,100 @@
+---
+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.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Acceptance Test
+
+## 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***
+
+- :Task: items are processed 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:
+- :Resource: items are returned 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
+- [ ] Trimmed per `concise-specs.md`: plain words, no obvious steps, no restatement of the parent spec
+- [ ] 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/genome/skills/add-concept/SKILL.md

@@ -0,0 +1,71 @@
+---
+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.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Concept
+
+## 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** — to reference an ancestor's export, list that ancestor in `requires`; if a concept is shared across branches, 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
+***definitions***
+
+- :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
+- [ ] Trimmed per `concise-specs.md`: one plain sentence, no restatement of the name, no rationale
+- [ ] Placed inside a `***definitions***` section

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

@@ -0,0 +1,84 @@
+---
+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. `brood`, `bud`) 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.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Functional Spec
+
+## 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, then run the review pass in `concise-specs.md` over the draft — trim it to the shortest wording that keeps every fact before any other check.
+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
+***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:.
+```
+
+
+### 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
+- [ ] Trimmed per `concise-specs.md`: nothing obvious, no rationale, no uncheckable adjectives or hedges, plain words throughout
+- [ ] No redundancy with existing specs
+- [ ] Placed in correct chronological position (usually at the end)

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

@@ -0,0 +1,118 @@
+---
+name: add-functional-specs
+description: >-
+  Add multiple functional specs to the ***functional specs*** section of a
+  ***plain spec file in a single batch. Use whenever more than one new
+  functional spec is being added — whether the user explicitly asks, or
+  another skill/workflow (e.g. `brood`, `bud`) needs to author
+  several specs in one pass. Bulk-writing or hand-authoring functional
+  specs without invoking this skill is forbidden; for adding a single spec,
+  use add-functional-spec instead.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Functional Specs
+
+## When to Use
+
+- The user asks for several functional specs to be added in one go (e.g. "add these three specs", "spec out this feature in a few bullets").
+- A higher-level skill or workflow (`brood`, `bud`, `debug-specs`) needs to author a tight group of related specs.
+- Anywhere you would otherwise be tempted to write more than one functional spec without running per-spec analysis.
+
+If you only need to add a single spec, use the `add-functional-spec` skill instead. Either way, **never** edit the `***functional specs***` section by hand — every new entry must go through one of these two skills so the complexity and conflict checks actually run.
+
+## Workflow
+
+This skill is `add-functional-spec` applied **one spec at a time, in order**, with no shortcuts. The batch never escapes per-spec rigor.
+
+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 reachable via `import` / `requires`).
+3. **Draft all the specs you intend to add**, in the chronological order they should appear. Keep the drafts in a working list — nothing is inserted yet. Run the review pass in `concise-specs.md` over every draft before continuing; trim each to the shortest wording that keeps every fact.
+4. **For each drafted spec, in order:**
+   1. **Analyze complexity.** Run `analyze-if-func-spec-too-complex` on the spec. If the verdict is `TOO COMPLEX`, run `break-down-func-spec`, replace the entry in the working list with the resulting smaller specs (preserving order), and restart this step on the first of the replacements.
+   2. **Check for conflicts.** Run `analyze-func-specs` **once** with this single input set:
+      - the new spec, plus
+      - every existing functional spec in the file and its `requires` chain, plus
+      - every spec from this batch that has already been inserted.
+
+      The batched analyzer returns every conflicting pair in one call — do **not** loop over pairs invoking a per-pair analyzer. For each conflicting pair it reports, run `resolve-spec-conflict`. Apply the resolution — which may revise the new spec, an existing spec, or both — then re-run `analyze-func-specs` once over the touched set until the verdict is `COMPATIBLE`.
+   3. **Append the spec** to the `***functional specs***` section. Specs are chronological; the new entry goes at the end (unless an earlier existing spec must come *after* it — in that rare case, insert at the correct position).
+5. **Read the file again** to confirm correct placement, ordering, and syntax for the full batch.
+
+Order matters: each new spec is inserted only after its complexity and conflict checks pass, so subsequent specs in the batch are always checked against an already-validated file.
+
+## Rules
+
+All the rules from `add-functional-spec` apply per individual spec. They are restated here so this skill is self-contained.
+
+### Complexity Limit (per spec)
+
+Each functional spec must imply a **maximum of 200 changed lines of code**. If a spec is too large, use `break-down-func-spec` 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.
+- A new spec can reference behavior defined by earlier specs.
+- A new spec **cannot** assume anything about specs that come after it.
+- Order the batch so that each spec only depends on specs that precede it. If two new specs would otherwise reference each other, the dependent one comes second.
+
+### 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 (full coverage via one batched call per spec)
+
+The new specs must not contradict each other **and** must not contradict any existing functional spec. Conflicting specs are the most costly outcome. The conflict check must cover:
+- every (new × existing) pair, and
+- every (new × new) pair within the batch.
+
+That coverage is achieved by running `analyze-func-specs` **once per spec being inserted**, with the new spec plus every existing spec plus every already-inserted spec from this batch passed in as a single set. The batched analyzer lists every conflicting pair in one call — do not invoke a pair-by-pair analyzer. 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 (per spec)
+
+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
+***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:.
+```
+
+
+### 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 any of the newly added functional specs need verification, use the `add-acceptance-test` skill to add acceptance tests after the batch has been inserted. Do this per spec, not as part of the bulk pass.
+
+## Anti-Patterns
+
+- **Don't skip per-spec checks because the batch "feels" small.** Even two specs require two complexity checks and a batched conflict check that includes both new specs.
+- **Don't fall back to pair-by-pair conflict analysis.** Use `analyze-func-specs` with the full relevant set once per inserted spec — not `analyze-2-func-specs` across every pair.
+- **Don't run all complexity checks first and all conflict checks last.** Interleave them per spec, as described in the Workflow — a failed complexity check earlier would otherwise waste later conflict checks.
+- **Don't insert every spec first and then analyze.** A bad spec already in the file pollutes subsequent conflict analyses.
+- **Don't fall back to hand-authoring** because there are "a lot" of specs to add. The right answer is more analyzer calls, not fewer.
+- **Don't use this skill for a single spec.** Use `add-functional-spec` — it's the same checks without the bulk bookkeeping.
+
+## Validation Checklist
+
+- [ ] Every spec in the batch implies ≤ 200 lines of code changes (verified via `analyze-if-func-spec-too-complex`)
+- [ ] No conflict between any new spec and any existing spec (verified via batched `analyze-func-specs` calls)
+- [ ] No conflict between any two new specs in the batch (covered by the same batched `analyze-func-specs` calls)
+- [ ] Every conflicting pair the batched analyzer reported was resolved via `resolve-spec-conflict` before the batch completed
+- [ ] All specs written in language-agnostic terms (no language/framework specifics)
+- [ ] All external interfaces explicit (endpoint paths, methods, CLI args, formats, etc.)
+- [ ] All referenced `:Concepts:` are defined in `***definitions***`
+- [ ] Sentences are short, clear, and unambiguous
+- [ ] Every spec trimmed per `concise-specs.md`: nothing obvious, no rationale, no uncheckable adjectives or hedges, plain words throughout
+- [ ] No redundancy with existing specs or within the batch
+- [ ] Specs placed in correct chronological positions