plain-forge 1.0.1

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

@@ -0,0 +1,115 @@
+---
+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. forge-plain, add-feature) 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.
+---
+
+# Add Functional Specs
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## 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 (`forge-plain`, `add-feature`, `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.
+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
+- :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 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
+- [ ] No redundancy with existing specs or within the batch
+- [ ] Specs placed in correct chronological positions

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

@@ -0,0 +1,73 @@
+---
+name: add-implementation-requirement
+description: >-
+  Add an implementation requirement to the ***implementation reqs*** section of
+  a ***plain spec file. Use when the user wants to add non-functional
+  requirements like technology choices, architectural constraints, coding
+  standards, data formats, error handling strategies, or any HOW-to-build
+  guidance to a .plain file.
+---
+
+# Add Implementation Requirement
+
+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 implementation reqs, definitions, and functional specs.
+3. **Determine if this belongs in implementation reqs** — it must describe HOW to build, not WHAT to build (that goes in `***functional specs***`).
+4. **Draft the requirement** following the rules below.
+5. **Insert it** into the `***implementation reqs***` section.
+6. **Read the file again** to confirm correct placement and syntax.
+
+## What Belongs Here
+
+Implementation reqs are free-form instructions that steer code generation. Common contents:
+
+- **Technology choices**: language, framework, runtime version
+- **Architectural constraints**: patterns, layering, dependency rules
+- **Coding standards**: naming conventions, style guidelines
+- **Data formats**: serialization, encoding, transformation rules
+- **Error handling**: strategies, retry logic, exception hierarchies
+- **Algorithm descriptions**: specific approaches when behavior alone is insufficient
+- **Performance guidance**: memory constraints, streaming requirements, batching strategies
+- **Language-specific constructs**: generics, annotations, framework-specific types and idioms
+
+## What Does NOT Belong Here
+
+- **Behavior and features** — those go in `***functional specs***`
+- **Concept definitions** — those go in `***definitions***`
+- **Test instructions** — those go in `***test reqs***`
+
+## Key Principle: HOW vs WHAT
+
+`***implementation reqs***` describe HOW the software should be built.
+`***functional specs***` describe WHAT the software should do.
+
+If the requirement describes observable behavior (endpoints, business rules, user-facing features), it belongs in functional specs. If it describes internal structure, technology, or coding guidance, it belongs here.
+
+## Format
+
+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.
+
+## Encapsulation Warning
+
+`requires` modules only receive functional specs from their dependencies — not implementation reqs. If downstream modules need certain behavior to be visible, that behavior must be expressed in functional specs, not here.
+
+## Validation Checklist
+
+- [ ] Describes HOW to build, not WHAT to build
+- [ ] All referenced `:Concepts:` are defined in `***definitions***`
+- [ ] Does not duplicate guidance already present in the file or its imports
+- [ ] Placed inside a `***implementation reqs***` section
+- [ ] No behavioral requirements that should be in `***functional specs***`

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

@@ -0,0 +1,108 @@
+---
+name: add-resource
+description: >-
+  Add a linked resource (external file reference) to a ***plain spec. Use when
+  the user wants to reference a JSON schema, API spec, data file, or other
+  external file from within a functional spec, definition, or implementation
+  requirement.
+---
+
+# Add Resource
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+Linked resources are external files referenced from within a `.plain` spec using markdown link syntax. The file contents are passed to the renderer alongside the spec, providing additional context for code generation.
+
+## 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.
+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.
+
+## Format
+
+Use standard markdown link syntax inside any spec section:
+
+```plain
+***definitions***
+- :AuthData: is the authentication data structure. Its format is defined
+  in the [auth schema](resources/auth_schema.json).
+
+***implementation reqs***
+- When transforming :BackupData:, use the JOLT transform defined in
+  [backup_transform.jolt](resources/backup_transform.jolt).
+
+***functional specs***
+
+- The system should expose an API conforming to the
+  [API specification](resources/api_spec.yaml).
+```
+
+## Path Rules
+
+- Paths are resolved **relative to the `.plain` file location**.
+- Only files in the same folder or subfolders are supported.
+- No absolute paths.
+- **No external URLs** — only local file references.
+- **No folder paths** — only local file references.
+- Only text-based files are supported.
+
+### A linked resource MUST be a single, text-based file that exists on disk
+
+A linked resource is **always** a single file that exists on disk at the path you reference, **and** that file's content must be text-based. The renderer reads the linked file's bytes and feeds them into the model alongside the spec; a directory, a remote URL, or a binary blob breaks that contract and is one of the most disruptive mistakes you can make when authoring a `.plain` file — the spec looks valid but the renderer either silently ignores the link, fails to read it, or wastes the model's context window on bytes it cannot interpret.
+
+Three things a linked resource **must not** be:
+
+1. **A folder / directory.** `[integrations](src/integrations/)`, `[schemas](resources/schemas/)`, `[host project](../host_project/)` are all invalid — the renderer cannot ingest a directory. If a whole directory's worth of content is relevant, pick the single most representative **file** inside it (a `README.md`, an exemplar source file, a manifest at the directory root) and link **that**.
+2. **A URL / external location.** `[Stripe docs](https://stripe.com/docs/api)`, `[OpenAPI spec](https://example.com/openapi.json)`, any `http://` / `https://` / `ftp://` / `git://` / `s3://` / `gs://` target. Linked resources are local-file only. If a URL's content is essential to the spec, fetch it once, save the response to a text file under `resources/` (e.g. `resources/stripe-docs-snapshot.md`, `resources/example-openapi.yaml`), and link **that file**.
+3. **A binary file.** PNG, JPG, JPEG, GIF, BMP, TIFF, WebP, ICO, PDF, DOCX, XLSX, PPTX, ZIP, TAR, GZ, MP3, MP4, WAV, compiled binaries (`.exe`, `.so`, `.dylib`, `.class`, `.wasm`), and anything else that isn't human-readable text in its raw form. Binary content cannot be meaningfully consumed by the renderer; linking a screenshot, a PDF spec, or a packaged artifact accomplishes nothing except bloating the context. If the information in a binary asset is essential, transcribe it into a text-based form first — a UI screenshot becomes a Markdown description or a structured YAML wireframe under `resources/`; a PDF spec becomes a Markdown extract or the underlying JSON Schema / OpenAPI; an architecture diagram becomes a Mermaid block inside a Markdown file.
+
+If the markdown-link target ends with `/`, contains `://`, points at a path that resolves to a directory, or points at a file with a binary extension (see the list above), **stop** — it cannot be a linked resource. Convert it to a text file under `resources/` first, then link the converted file.
+
+### Do not mention URLs or folder paths in `.plain` content at all
+
+The constraint above is **not** just about markdown link syntax. URLs (any `http://`, `https://`, `ftp://`, `git://`, `s3://`, … string) and folder paths (`src/integrations/`, `../host_project/`, anything ending with `/`, anything that resolves to a directory) **must not appear anywhere in `.plain` content** — not as link targets, not in concept body prose, not in functional-spec text, not in implementation-reqs. Mentioning a URL or a folder in prose is a critical and common mistake because:
+
+- The renderer cannot follow URLs or open folders. A URL or folder reference in prose is a *ghost* dependency: it looks meaningful to a human reader, but it contributes nothing to code generation. Worse, downstream readers (and future you) assume the renderer used the referenced content, so the spec drifts from reality.
+- The fix is always the same: if external content matters, fetch it (or pick one canonical file out of the directory), save it as a text file under `resources/`, and refer to it through a normal linked resource. The concept or spec then names the content through the linked file, not through a URL or folder path string.
+
+The **only** exceptions are URLs and paths that are *values the produced software itself uses at runtime* (e.g. the base URL the integration calls, a database connection path, a CLI argument value). Those are configuration values, not external references, and they belong in the spec because the generated code needs them. A useful litmus test: "Would the renderer benefit from reading the bytes at this URL / folder?" If yes, save it to a text file and link the file. If no (it's a runtime value), it can stay as plain text in the spec.
+
+### 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 **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
+
+| Type | Typical location | Use case |
+|------|-----------------|----------|
+| JSON Schema | `resources/*.json` | Defining data structure contracts |
+| OpenAPI / Swagger spec | `resources/*.yaml` | API endpoint definitions |
+| Data transforms | `resources/*.jolt` | Data transformation rules |
+| Test fixtures | `resources/*.json`, `resources/*.csv` | Sample data for tests |
+| Configuration examples | `resources/*.yaml` | Reference configurations |
+
+## When to Use Resources
+
+- The information is too detailed or structured to express inline in the spec (e.g., a full JSON schema).
+- The same data is referenced by multiple specs or sections.
+- The resource is an industry-standard format (OpenAPI, JSON Schema) that the renderer can interpret directly.
+
+## When NOT to Use Resources
+
+- The information is short enough to include inline in the spec text.
+- The file is generated code (those belong in `plain_modules/`, not `resources/`).
+
+## Validation Checklist
+
+- [ ] Resource file exists at the specified path
+- [ ] **Target is a file on disk, not a directory** (the path does not end in `/` and does not resolve to a folder)
+- [ ] **Target is a local path, not a URL** (no `://` anywhere in the target: no `http://`, `https://`, `ftp://`, `git://`, `s3://`, `gs://`, etc.)
+- [ ] **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)
+- [ ] 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-template/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: add-template
+description: >-
+  Create or include a Liquid template in a ***plain spec file using
+  {% include %} syntax. Use when the same spec content needs to be reused
+  across multiple .plain files with different parameters.
+---
+
+# Add Template
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+Templates use Liquid syntax (`{% include %}`) to reuse the same spec content across multiple `.plain` files. Each inclusion can pass different parameters, producing tailored output from a single source. This is distinct from `import` and `requires` — templates are about textual reuse with parameterization, not module dependencies.
+
+## When to Use Templates
+
+- The **exact same spec structure** is needed in more than one `.plain` file.
+- The reused content differs only in specific values (names, paths, config) that can be parameterized.
+- You want a single source of truth for a pattern that appears in multiple modules.
+
+## Format
+
+### Including a Template
+
+Use `{% include %}` with the template path and parameters:
+
+```plain
+{% include "console_app_template.plain", main_file_name: "app.py", app_name: "MyApp" %}
+```
+
+Parameters are passed as key-value pairs after the template path. Inside the template, parameters are accessed using Liquid variable syntax (`{{ main_file_name }}`).
+
+### Writing a Template
+
+Templates live in the `template/` directory. Only **variables** (`{{ variable_name }}`) are supported — conditionals, loops, and other Liquid features are not available:
+
+```plain
+***definitions***
+- :{{ app_name }}MainFile: is the entry point file for :{{ app_name }}:.
+
+***implementation reqs***
+- :{{ app_name }}MainFile: should be called "{{ main_file_name }}".
+```
+
+## Workflow: Including an Existing Template
+
+1. **Check the `template/` directory** to see what templates are available.
+2. **Read the template** to understand what parameters it expects and what content it produces.
+3. **Add the `{% include %}` statement** to the target `.plain` file with the correct parameters.
+4. **Verify** that the expanded content does not introduce concept name collisions or duplicate sections.
+
+## Workflow: Creating a New Template
+
+1. **Identify the repeated pattern** — find spec content that is duplicated (or will be duplicated) across multiple `.plain` files.
+2. **Extract the common content** into a new `.plain` file in the `template/` directory.
+3. **Parameterize the differences** — replace the varying parts with Liquid variables.
+4. **Update the original files** to use `{% include %}` instead of the duplicated content.
+
+## Validation Checklist
+
+- [ ] Template file is in the `template/` directory
+- [ ] All varying parts are parameterized with Liquid variables
+- [ ] All required parameters are passed at each `{% include %}` call site
+- [ ] Expanded content does not introduce concept name collisions
+- [ ] Template is used by more than one `.plain` file (otherwise, inline the content)

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

@@ -0,0 +1,68 @@
+---
+name: add-test-requirement
+description: >-
+  Add a test requirement to the ***test reqs*** section of a ***plain spec
+  file. Use when the user wants to specify conformance testing instructions
+  like test frameworks, execution methods, or testing constraints in a .plain
+  file.
+---
+
+# Add Test Requirement
+
+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 test reqs and the overall spec structure.
+3. **Confirm this is a conformance test concern** — unit test guidance goes in `***implementation reqs***`, not here.
+4. **Draft the requirement** following the rules below.
+5. **Insert it** into the `***test reqs***` section.
+6. **Read the file again** to confirm correct placement and syntax.
+
+## What Belongs Here
+
+Test reqs specify how **conformance tests** should be written and run. Common contents:
+
+- **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 tests, mock requirements)
+- **Test data**: how test fixtures or mock data should be structured
+- **Environment setup**: any prerequisites for running conformance tests
+
+## What Does NOT Belong Here
+
+- **Unit test guidance** — that goes in `***implementation reqs***`
+- **Acceptance tests** — those are nested under individual functional specs in `***functional specs***`
+- **Behavioral requirements** — those go in `***functional specs***`
+- **Technology choices for the implementation** — those go in `***implementation reqs***`
+
+## Conformance Tests vs Other Tests
+
+| 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 |
+
+## Format
+
+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.
+
+## Validation Checklist
+
+- [ ] Describes conformance testing concerns, not unit tests or behavior
+- [ ] All referenced `:Concepts:` are defined (or are predefined like `:ConformanceTests:`)
+- [ ] Does not duplicate guidance already present in the file or its imports
+- [ ] Placed inside a `***test reqs***` section
+- [ ] No behavioral requirements that should be in `***functional specs***`

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

@@ -0,0 +1,102 @@
+---
+name: analyze-2-func-specs
+description: >-
+  Analyze two functional specs from a ***plain spec file to determine if they
+  conflict. Use when the user wants to check whether two specific functional
+  requirements are compatible, or when debugging a suspected conflict between
+  two specs.
+---
+
+# Analyze Two Functional Specs
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## Input
+
+Two functional specs from a `.plain` file (or across `requires` modules). The user provides them directly or points to them by location in a file.
+
+## Workflow
+
+1. **Read both functional specs** and the `***definitions***` section so all referenced `:Concepts:` are understood.
+2. **Determine chronological order** — which spec comes first? The earlier spec was rendered first and the later spec was rendered with the earlier one in context.
+3. **Run the conflict analysis** using the checklist below.
+4. **Output the verdict and nothing else** — either `COMPATIBLE` or `CONFLICTING`. No reasoning, no category labels, no resolution suggestions.
+
+## Conflict Analysis Checklist
+
+Work through each question. If any answer is "yes", the specs likely conflict.
+
+### 1. Direct Contradiction
+
+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.
+
+Verdict: CONFLICTING — both define the sort order for the same response,
+but specify different fields and directions. A single implementation cannot
+satisfy both unless scoped to different contexts.
+```
+
+### 2. State or Data Conflict
+
+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.
+
+Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
+```
+
+### 3. Behavioral Override
+
+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.
+
+Verdict: CONFLICTING — both define the authentication mechanism but pick
+different approaches. The later spec overrides the earlier one.
+```
+
+### 4. Scope Ambiguity
+
+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.
+
+Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
+Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
+```
+
+### 5. Shared Concept, Different Constraints
+
+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.
+
+Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
+```
+
+## Output Format
+
+The skill emits exactly one of these two strings, with no surrounding text, explanation, category label, or resolution suggestion:
+
+```
+COMPATIBLE
+```
+
+or
+
+```
+CONFLICTING
+```
+
+The internal analysis (checklist, chronological reasoning) informs the verdict but must not appear in the output. The caller decides what to do with the result — typically: act on `COMPATIBLE` by proceeding, or invoke `resolve-spec-conflict` on `CONFLICTING` to produce the actual fix.

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

@@ -0,0 +1,124 @@
+---
+name: analyze-func-specs
+description: >-
+  Analyze a batch of functional specs from a ***plain spec file to determine
+  which pairs conflict. Replaces the pair-by-pair `analyze-2-func-specs` flow
+  when a caller wants to check many specs at once (e.g. a new spec against
+  every existing spec, or a freshly inserted batch against itself).
+---
+
+# Analyze Functional Specs
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## Input
+
+A **set of two or more functional specs** to check against each other. Callers typically supply one of:
+
+- A whole `***functional specs***` section to self-check.
+- A new spec (or batch of new specs) **plus** the existing specs from the same file and any `requires` modules.
+- An explicit list of spec snippets the user wants compared.
+
+Each spec must be identifiable. If the caller didn't label them, assign **stable identifiers** in order of appearance: `S1`, `S2`, `S3`, …. Use those identifiers in the output. If the caller provided their own IDs or quoted snippets, use those instead and keep them verbatim.
+
+The skill also needs the `***definitions***` section (and any imported definitions) so referenced `:Concepts:` can be resolved.
+
+## Workflow
+
+1. **Read all input specs and the relevant `***definitions***`** so every `:Concept:` is understood.
+2. **Establish chronological order** across the batch. Earlier specs are considered to have been rendered first; later specs are evaluated with the earlier ones in context. If the caller already provided an order, preserve it.
+3. **Generate the pair list.** Enumerate every unordered pair `(Sᵢ, Sⱼ)` with `i < j`. Skip pairs where the two specs share no `:Concept:` and no overlapping subject — they are trivially compatible and listing them adds noise.
+4. **Run the conflict analysis below on each remaining pair.** Use the same checklist that the legacy `analyze-2-func-specs` skill used, but apply it pair by pair across the batch in a single pass — do not require the caller to invoke the analyzer once per pair.
+5. **Record every CONFLICTING pair.** Compatible pairs are not listed individually; only the conflicts are emitted.
+6. **Output the verdict** in the format below. No reasoning, no category labels, no resolution suggestions.
+
+## Conflict Analysis Checklist (applied per pair)
+
+Work through each question for the pair under inspection. If any answer is "yes", that pair is CONFLICTING.
+
+### 1. Direct Contradiction
+
+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.
+
+Verdict: CONFLICTING — both define the sort order for the same response,
+but specify different fields and directions. A single implementation cannot
+satisfy both unless scoped to different contexts.
+```
+
+### 2. State or Data Conflict
+
+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.
+
+Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
+```
+
+### 3. Behavioral Override
+
+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.
+
+Verdict: CONFLICTING — both define the authentication mechanism but pick
+different approaches. The later spec overrides the earlier one.
+```
+
+### 4. Scope Ambiguity
+
+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.
+
+Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
+Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
+```
+
+### 5. Shared Concept, Different Constraints
+
+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.
+
+Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
+```
+
+## Output Format
+
+Emit exactly one of the two shapes below, with no surrounding text, explanation, category label, or resolution suggestion.
+
+If **no pair** is conflicting:
+
+```
+COMPATIBLE
+```
+
+If **one or more pairs** are conflicting, emit `CONFLICTING` followed by one line per conflicting pair, in `Sᵢ x Sⱼ` form (using the identifiers from the input, with `i < j`), sorted lexicographically:
+
+```
+CONFLICTING
+S1 x S4
+S2 x S3
+S3 x S5
+```
+
+Rules for the output:
+
+- Do **not** list compatible pairs.
+- Do **not** include reasoning, checklist categories, or fixes — the caller decides what to do with each conflict (typically: invoke `resolve-spec-conflict` on each pair).
+- If the input contained fewer than two specs, emit `COMPATIBLE` (nothing to compare).
+- Identifiers must match exactly what the caller provided (or the `S1`, `S2`, … fallback assigned in step 1).
+
+The internal pairwise analysis informs the verdict but must not appear in the output.