plain-forge 1.0.4 → 1.0.5

package/README.md

@@ -4,18 +4,39 @@
 
 # plain-forge
 
-A conversational spec-writing tool that runs in any AI coding agent (Claude Code, Codex, OpenCode, and more) and is built on the [***plain](https://plainlang.org) specification language. Describe what you want to build in plain English, and plain-forge guides you through a structured interview to produce complete `.plain` spec files — which then generate production-ready code via the [Codeplain](https://codeplain.ai) renderer.
+A toolkit for working with [***plain](https://plainlang.org) projects from inside your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, and any other agent that reads from a standard skills directory. plain-forge ships skills, rules, and docs that turn a conversation into complete `.plain` spec files, then keeps maintaining them across the lifetime of the project. The specs are rendered into production-ready code by the [codeplain](https://codeplain.ai) renderer.
 
-## How It Works
+## What plain-forge does
 
-The main entry point is `forge-plain`. It turns a conversation into ***plain specs through four phases:
+plain-forge is organized around four kinds of work, each with its own entry-point skill (and a long tail of supporting skills behind it).
 
-1. **What are we building?** — Walk through the product: description, users, scope, core entities, key features, user flows, business rules, and (if applicable) UI behavior. Produces the `***definitions***` and `***functional specs***` for each module.
-2. **What technologies should it use?** — Pick the stack and architecture: language, frameworks, data storage, external services, project structure, and any other stack-wide constraints. Produces the `***implementation reqs***`.
-3. **How should testing be done?** — Decide the testing strategy: framework, test types in scope, conformance/acceptance tests, environment-preparation scripts, layout, and execution. Produces the `***test reqs***`, any `***acceptance tests***`, the runnable scripts under `test_scripts/`, and the `config.yaml`(s) wiring them in. plain-forge then probes your machine to confirm everything those scripts need is actually installed.
-4. **Validate and hand off** — plain-forge identifies the final module in the dependency chain and runs `codeplain <module>.plain --dry-run` itself to catch any static errors (syntax, undefined concepts, broken `import`/`requires` chains, complexity violations, conflicts). It fixes the `.plain` files until the dry-run passes, then hands you the exact `codeplain <module>.plain` command (plus any test scripts) so the real render starts from a clean spec.
+### 1. Bootstrap a new project
 
-Each phase is **incremental**, not a single long questionnaire. plain-forge walks one topic at a time, runs an **ask → author → review** loop on every topic — structured questions, immediate edits to the `.plain` files (and `test_scripts/` / `config.yaml` in Phase 3), then snippet-by-snippet confirmation — and only moves on once every flagged snippet is explicitly approved.
+Pick whichever entry point matches how much upfront design you want:
+
+- **`forge-plain`** — full end-to-end interview. One question at a time, immediate writes to disk, covers product → tech stack → testing → validation in four phases. Produces a complete `.plain` project with `config.yaml`, test scripts, and a successful `codeplain --dry-run` before handing off.
+- **`init-plain-project`** — lightweight scaffold. Asks only about the base technology, project kind, and whether conformance testing is on; emits a template module, a stub top-level module, the testing scripts, and a `config.yaml`. No interview, no specs — pair it with `add-feature` to grow the project feature by feature.
+
+### 2. Grow an existing project
+
+- **`add-feature`** — takes a feature request in plain English and runs the same one-question-at-a-time loop that `forge-plain` uses, scoped to a single feature against an existing `.plain` file.
+- **Per-section authoring skills** — `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `add-test-requirement`, `add-concept`, `add-acceptance-test`, `add-resource`, `add-template`. Each enforces the relevant ***plain syntax rules (concept uniqueness, complexity limits, line-length, linked-resource constraints, …) so hand-authoring doesn't drift from the language.
+- **Module-management skills** — `create-import-module`, `create-requires-module`, `refactor-module`, `consolidate-concepts` for restructuring as the project grows.
+
+### 3. Validate and maintain
+
+- **`plain-healthcheck`** — the verification gate. Inventories every `.plain` module, validates every `config.yaml`, and dry-runs every top module with the right config. Returns `PASS` / `FAIL` with a numbered punch-list when something is broken.
+- **`init-config-file`** — assembles the canonical `config.yaml` per part of a project from the decisions made during interviewing.
+- **`check-plain-env`** — probes the host machine for everything the project needs (language toolchains, external services, system binaries, drivers, `codeplain` itself) and emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands.
+- **`analyze-func-specs`** / **`analyze-if-func-spec-too-complex`** / **`break-down-func-spec`** / **`resolve-spec-conflict`** — the spec-quality toolchain that runs behind `add-feature` and `forge-plain` but can also be invoked directly when reviewing or refactoring.
+
+### 4. Debug and render
+
+- **`debug-specs`** — when the rendered app misbehaves, this traces the generated code back to the spec that caused it and fixes the spec (never the generated code).
+- **`run-codeplain`** — experimental supervised render. Launches `codeplain` for you, tails the log, watches generated code appear under `plain_modules/`, and detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures). On approval it stops the renderer, hands off to the right spec-edit skill, and resumes.
+- **`implement-unit-testing-script`** / **`implement-conformance-testing-script`** / **`implement-prepare-environment-script`** — generate the per-language testing scripts that the renderer and you both invoke. New languages can be added by these skills without touching any other part of the project.
+
+Each skill operates on the same one-question-at-a-time, write-immediately, refine-through-follow-ups loop. Specs land on disk after every answer; later answers fix earlier writes in place. There is no batched interview, no "I'll gather context first," and no hand-authored functional specs — every new spec goes through the authoring skills so the complexity and conflict checks actually run.
 
 ## Getting Started
 

package/forge/rules/integration-embedded.md

@@ -38,12 +38,27 @@ Run host discovery **before** the first Phase 1 question. Treat the results as g
 - The renderer is allowed to redefine **only** symbols the host does not provide and the contract schema does not capture
 - Naming the symbol by FQN is not optional decoration — it tells the renderer where the type comes from, which prevents a duplicate definition under `plain_modules/`
 
-## Add host files as linked resources, never restate them
+## Link host files at their original path — never copy them into `resources/`
 
-- Every host file the integration touches (base classes, configuration modules, registries, exception classes, lifecycle hooks) is added under `resources/host/` via the `add-resource` skill and referenced from the relevant spec using `***linked resource***` syntax
+The integration's `.plain` module lives **inside the host codebase** (per the "adopt the host's `.plain` setup verbatim" step). That means host source files are already reachable as linked resources via their host-relative paths. The integration spec references them **in place**; it never duplicates them under `resources/host/`.
+
+- Every host file the integration touches (base classes, configuration modules, registries, exception classes, lifecycle hooks) is referenced from the relevant spec using `***linked resource***` syntax with the **path as it exists in the host codebase** — e.g. `[base.py](host_project/integrations/base.py)` if the `.plain` module sits next to `host_project/`
+- **Do NOT copy host files into `resources/host/`.** A copy creates a second source of truth that drifts the moment the host file is edited; the rendered code will then disagree with whatever the host actually ships
+- **Do NOT add host files via the `add-resource` skill's default copy behavior** when that behavior would duplicate the file — point at the existing host path directly
 - **Never inline a host file's contents** into a spec
-- **Never describe a host symbol's shape from memory** — the renderer reads the linked file's bytes and that is the source of truth
-- This obeys the broader [`linked-resources.md`](linked-resources.md) rules — a directory is not a valid link, a URL is not a valid link, a binary is not a valid link
+- **Never describe a host symbol's shape from memory** — the renderer reads the linked file's bytes at its host path and that is the source of truth
+- This still obeys the broader [`linked-resources.md`](linked-resources.md) rules: a directory is not a valid link, a URL is not a valid link, a binary is not a valid link. Only the *location* changes — host files live where the host put them, not under `resources/`
+
+### What still belongs under `resources/`
+
+This rule applies to **host source code only**. Other artifacts still live under `resources/` exactly like in a non-embedded project:
+
+- **Contract schemas authored by the integration** — `resources/contract/<entry-point>.schema.json`
+- **Configuration schema** — `resources/config.schema.json`
+- **Captured probe responses** (from the live-API cross-check) — `resources/fixtures/<endpoint>.<case>.json`
+- **Static lookup tables** the integration owns — `resources/error-map.yaml`, `resources/retry-policy.yaml`, etc.
+
+The rule of thumb: if the host wrote it and ships it, link it where the host put it. If the integration is authoring it for the first time, it goes under `resources/`.
 
 ## The contract spec declares inheritance, not duplication
 
@@ -125,7 +140,7 @@ Before declaring an embedded integration done, in addition to the shared checkli
 - [ ] `host-codebase` concept records host root path, host language + version, host dependency manager + manifest, target package path, host base class import path, target generated-class FQN, and the host conventions the contract follows
 - [ ] Contract spec carries renderer directives (target language, target file path, target class name, host base class to subclass, host-package pins) and **links** to the contract schema; no class body is inlined
 - [ ] Every host symbol referenced in any spec uses its fully qualified import path and is tagged "imported from the host codebase; do not redefine"
-- [ ] Every host file the integration touches has been added under `resources/host/` as a linked resource — no host file contents are inlined in any spec
+- [ ] Every host file the integration touches is linked at its **original host-relative path** — no host file has been copied into `resources/host/` or anywhere else, and no host file contents are inlined in any spec
 - [ ] `forge-plain` Phase 2's tech-stack decisions are transcribed verbatim from the host (no independent stack choices)
 - [ ] Host-package version pins are copied into `***implementation reqs***`
 - [ ] `prepare_environment` copies the host into `.tmp/<lang>_<arg>/`, overlays `plain_modules/<module>/` at the target package path, installs the merged tree's dependencies, and is the working folder conformance attaches to
@@ -140,7 +155,8 @@ Before declaring an embedded integration done, in addition to the shared checkli
 
 - **Choosing a different language, framework, or dependency manager than the host.** The host stack is inherited; cross-stack `requires` chains are forbidden by [`requires-modules.md`](requires-modules.md)
 - **Redefining a host class under `plain_modules/`.** Reference the host symbol by FQN; let the renderer import it
-- **Inlining a host base class body into the contract spec.** Add the host file as a linked resource under `resources/host/` and reference it
+- **Inlining a host base class body into the contract spec.** Reference the host file as a linked resource **at its original host-relative path** — do not inline its contents and do not copy it into `resources/`
+- **Copying host source files into `resources/host/` (or anywhere under `resources/`).** That creates a second source of truth that silently drifts from the host. Link the host file in place; the integration `.plain` module already lives inside the host codebase, so the path resolves naturally
 - **Hardcoding the host codebase path in any spec or script.** Read it from the env var declared in the configuration concept
 - **Asking the user to design the integration's tech stack.** Read it from the host's manifest files
 - **Authoring an integration spec that contradicts an existing integration in the same host** without first surfacing the conflict and getting explicit user confirmation

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

@@ -44,6 +44,30 @@ Key formatting rules:
 - Each test bullet is indented under the `***acceptance tests***` header.
 - Multiple acceptance tests can be listed under a single functional spec.
 
+### Line syntax (hard rule)
+
+**Every line inside `***acceptance tests***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+  ***acceptance tests***
+  - Processing 250 :Task: items should result in 3 batches with the
+    last batch containing the remaining 50 items.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+  ***acceptance tests***
+  - Processing 250 :Task: items should result in 3 batches.
+    - The first two batches each contain 100 items.
+    - The last batch contains the remaining 50 items.
+```
+
 ## Rules
 
 ### Conformance with the Functional Spec

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

@@ -56,6 +56,29 @@ Attributes and constraints are nested sub-bullets:
   - Due Date - completion deadline (optional)
 ```
 
+## Line syntax (hard rule)
+
+**Every line inside `***definitions***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested attributes are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :Task: describes an activity that needs to be done by :User:.
+  - Name is a short description that the user provides when creating
+    the task and is shown in the task list.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :Task: describes an activity that needs to be done by :User:.
+  - Name is a short description provided when creating the task.
+  - The name is shown in the task list.
+```
+
 ## Validation Checklist
 
 - [ ] Name uses `:CamelCase:` notation

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

@@ -57,6 +57,29 @@ Each functional spec must be unambiguous — the renderer should have only one r
   - All :Participant: members of the :Conversation: can see the new :Message:.
 ```
 
+### Line syntax (hard rule)
+
+**Every line inside `***functional specs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(),
+  which returns a list of :EventEnvelope: dicts conforming to the gateway's
+  contract.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle().
+  - The method returns a list of :EventEnvelope: dicts.
+  - The dicts must conform to the gateway's :EventEnvelope: contract.
+```
+
 ### Deterministic Interface
 
 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.

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

@@ -80,6 +80,30 @@ Each functional spec must be unambiguous — the renderer should have only one r
   - All :Participant: members of the :Conversation: can see the new :Message:.
 ```
 
+### Line syntax (hard rule, per spec)
+
+**Every line inside `***functional specs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject the whole file.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+- This rule applies to **every** spec in the batch — one bad continuation line invalidates the entire insert.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(),
+  which returns a list of :EventEnvelope: dicts conforming to the gateway's
+  contract.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle().
+  - The method returns a list of :EventEnvelope: dicts.
+  - The dicts must conform to the gateway's :EventEnvelope: contract.
+```
+
 ### Deterministic Interface
 
 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.

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {