plain-forge 1.0.18 → 1.0.20

package/README.md

@@ -4,7 +4,7 @@
 
 # plain-forge
 
-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.
+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.
 
 ## What plain-forge does
 
@@ -20,7 +20,7 @@ Pick whichever entry point matches how much upfront design you want:
 ### 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.
+- **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, bullet syntax, 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
@@ -62,11 +62,15 @@ npx plain-forge install --agent claude --scope project
 |-----------|---------------|----------|
 | `claude` | `.claude/` · `~/.claude/` | You use Claude Code |
 | `codex` | `.agents/` · `~/.agents/` | You use the OpenAI Codex CLI |
+| `copilot` | `.agents/` · `~/.agents/` | You use GitHub Copilot |
 | `forgecode` | `.forge/` · `~/forge/` | You use ForgeCode |
 | `opencode` | `.opencode/` · `~/.config/opencode/` | You use OpenCode |
 | `universal` | `.agents/` · `~/.agents/` | You want a runtime-neutral layout that any agent reading from `.agents/` can pick up |
 
-> **Why `codex` and `forgecode` don't install into `.codex/` or `.forgecode/`.** Those tools load *skills* from specific directories that are **not** named after the tool. Per the current (2026) docs, Codex reads skills from `.agents/skills` (`~/.agents/skills` globally) — `.codex/` is config-only — and ForgeCode reads them from `.forge/skills` (`~/forge/skills` globally). plain-forge installs where the skills will actually load. As a result `codex` and `universal` share the `.agents/` layout; the install manifest records which agent you chose so `update`/`uninstall` behave correctly.
+> **Why several agents share `.agents/`.** Codex and GitHub Copilot both discover skills from
+> `.agents/skills` (`~/.agents/skills` globally), which is also the runtime-neutral `universal`
+> layout. ForgeCode instead reads `.forge/skills` (`~/forge/skills` globally). The manifest records
+> which agent label you chose so `update` and `uninstall` report it correctly.
 
 **Scope options:**
 
@@ -88,16 +92,19 @@ Each install writes three subfolders under the chosen directory:
 
 #### How the rules get applied per agent
 
-The `skills/` are discovered natively by every supported agent. The `rules/` (the `.plain`-authoring guidance) are applied differently because each agent loads instruction files its own way — so plain-forge does a bit of extra, agent-specific wiring:
+The `skills/` are discovered natively by every supported agent. The `load-plain-reference` skill
+loads only the rules relevant to the current task and skips rules already present in context. Some
+agents additionally support native rules wiring:
 
 | Agent | How rules are applied |
 |-------|-----------------------|
 | **Claude Code** | Native — Claude Code auto-loads `.claude/rules/*.md` at launch. Each rule carries `paths: "**/*.plain"` frontmatter so Claude scopes it to `.plain` files. No extra wiring. |
 | **OpenCode** | OpenCode doesn't auto-load a `rules/` dir; it reads globs from the `instructions` array in `opencode.json`. plain-forge **merges** a rules glob there — `.opencode/rules/*.md` (project, written to `./opencode.json`) or the absolute `~/.config/opencode/rules/*.md` (global, written to `~/.config/opencode/opencode.json`; absolute because OpenCode doesn't expand `~`). |
-| **Codex / ForgeCode** | Neither auto-loads a `rules/` dir; both read custom instructions only from `AGENTS.md`. plain-forge appends a fenced, **managed pointer block** to `AGENTS.md` telling the agent to read the installed rule files. Project → repo-root `./AGENTS.md`; global → `~/.codex/AGENTS.md` (Codex) or `~/forge/AGENTS.md` (ForgeCode). |
-| **Universal** | Verbatim copy only — the rules land in `.agents/rules/`, and it's up to whichever agent reads `.agents/` to consume them. No config is generated. |
+| **ForgeCode** | plain-forge also appends a fenced managed pointer block to `AGENTS.md`: repo-root `./AGENTS.md` for project installs or `~/forge/AGENTS.md` globally. |
+| **Codex / GitHub Copilot / Universal** | No extra instruction file is generated. Their discovered `load-plain-reference` skill loads applicable files from `.agents/rules/` when needed. |
 
-In every case where plain-forge touches a config or `AGENTS.md` file, it **merges** into what's already there — adding only its own glob/block and leaving all your other content intact — and it never writes into a malformed config (it warns instead). `uninstall` reverses the wiring: it removes only plain-forge's glob/block, deleting the file only if it contained nothing else.
+When plain-forge touches `opencode.json` or ForgeCode's `AGENTS.md`, it merges into existing content
+and leaves unrelated configuration intact. `uninstall` removes only plain-forge's glob or block.
 
 `install` refuses to run if plain-forge is already present at the target directory — it prints a message pointing you at `update` and exits non-zero. Use `update` (below) to refresh an existing install.
 
@@ -129,7 +136,7 @@ npx plain-forge uninstall --agent claude --scope global
 
 | Flag | Default | Values |
 |------|---------|--------|
-| `--agent` | `*` (all agents) | `claude`, `codex`, `forgecode`, `opencode`, `universal`, or `*` |
+| `--agent` | `*` (all agents) | `claude`, `codex`, `copilot`, `forgecode`, `opencode`, `universal`, or `*` |
 | `--scope` | `project` | `project` (cwd) or `global` (home directory) |
 
 If an install has **no manifest** (e.g. one that predates manifests), `uninstall` cannot tell which files are plain-forge's, so it refuses to delete anything: it prints an error, lists the directories to clean up by hand, and exits non-zero. Refresh such an install with `update` first (which writes a manifest going forward), then `uninstall`.
@@ -188,7 +195,7 @@ Hit a bug in the rendered app, a failing test, or behavior that doesn't match wh
 2. plain-forge applies the fix in the `.plain` file(s) only and summarizes what changed.
 3. Re-render to regenerate the code (see [Rendering specs](#rendering-specs)).
 
-> **Important:** Never edit generated code under `plain_modules/` or `conformance_tests/` directly — your changes will be overwritten on the next render. Always fix the spec and re-render.
+> **Important:** Never edit generated output under `plain_modules/` directly — neither the code in `plain_modules/<module>/code/` nor the conformance tests in `plain_modules/<module>/tests/`. Your changes will be overwritten on the next render. Always fix the spec and re-render.
 
 
 ## Repository Structure
@@ -209,7 +216,7 @@ test/
 package.json                 # ships only `bin/cli.mjs` and `forge/` to npm
 ```
 
-On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them into the chosen agent directory (`.claude/`, `.agents/` for Codex/universal, `.forge/`, or `.opencode/` — see the per-agent table above for global-scope paths), recording every file it wrote in `<agent-dir>/.plain-forge/manifest.json` so `update` can later refresh and prune precisely. For agents that need it, it also wires the rules into `opencode.json` or `AGENTS.md` (see [How the rules get applied per agent](#how-the-rules-get-applied-per-agent)).
+On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them into the chosen agent directory (`.claude/`, `.agents/` for Codex/Copilot/universal, `.forge/`, or `.opencode/` — see the per-agent table above for global-scope paths), recording every file it wrote in `<agent-dir>/.plain-forge/manifest.json` so `update` can later refresh and prune precisely. For agents that need it, it also wires the rules into `opencode.json` or ForgeCode's `AGENTS.md` (see [How the rules get applied per agent](#how-the-rules-get-applied-per-agent)).
 
 ## Available Skills
 

package/bin/cli.mjs

@@ -13,7 +13,8 @@ const forgeDir = path.join(pkgRoot, "forge");
 // These are the directories each tool actually loads skills from (verified
 // against the 2026 docs), NOT necessarily a dir named after the tool:
 //   - Codex reads skills from .agents/skills (never .codex/skills); .codex is
-//     config-only. So codex shares the .agents layout with `universal`.
+//     config-only. So codex shares the .agents layout with `copilot` and
+//     `universal`.
 //   - ForgeCode reads skills from .forge/skills (never .forgecode/skills); its
 //     global dir is ~/forge (no dot) — see resolveBaseDir.
 //   - OpenCode reads project skills from .opencode; global is ~/.config/opencode
@@ -23,6 +24,7 @@ const forgeDir = path.join(pkgRoot, "forge");
 const AGENTS = {
   claude: ".claude",
   codex: ".agents",
+  copilot: ".agents",
   forgecode: ".forge",
   opencode: ".opencode",
   universal: ".agents",
@@ -53,16 +55,32 @@ function hasForgeSignature(baseDir) {
   );
 }
 
-const BANNER = `\x1b[38;2;224;255;110m██████╗ ██╗      █████╗ ██╗███╗   ██╗      ███████╗ ██████╗ ██████╗  ██████╗ ███████╗
+const BANNER = `██████╗ ██╗      █████╗ ██╗███╗   ██╗      ███████╗ ██████╗ ██████╗  ██████╗ ███████╗
 ██╔══██╗██║     ██╔══██╗██║████╗  ██║      ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
 ██████╔╝██║     ███████║██║██╔██╗ ██║█████╗█████╗  ██║   ██║██████╔╝██║  ███╗█████╗
 ██╔═══╝ ██║     ██╔══██║██║██║╚██╗██║╚════╝██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝
 ██║     ███████╗██║  ██║██║██║ ╚████║      ██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
-╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝      ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝\x1b[0m
+╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝      ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝
 `;
 
 const TAGLINE = "turn ideas into ***plain specs.";
 
+function terminalHasLightBackground(env = process.env) {
+  const parts = String(env.COLORFGBG ?? "").split(";");
+  const background = Number(parts.at(-1));
+  if (!Number.isInteger(background)) return false;
+  return background === 7 || background >= 9;
+}
+
+function terminalPalette(env = process.env) {
+  return terminalHasLightBackground(env)
+    ? { brand: "76;92;0", plain: "0;105;55", link: "0;85;170" }
+    : { brand: "224;255;110", plain: "121;252;150", link: "95;175;255" };
+}
+
+const color = (rgb, text, extra = "") =>
+  `\x1b[${extra}38;2;${rgb}m${text}\x1b[0m`;
+
 function stripAnsi(s) {
   return s.replace(/\x1b\[[0-9;]*m/g, "");
 }
@@ -75,13 +93,14 @@ function bannerWidth() {
 
 function printBanner() {
   if (!process.stdout.isTTY) return;
-  process.stdout.write("\n" + BANNER + "\n");
+  const palette = terminalPalette();
+  process.stdout.write("\n" + color(palette.brand, BANNER) + "\n");
 
   const width = bannerWidth();
   const pad = Math.max(0, Math.floor((width - TAGLINE.length) / 2));
   const tag = TAGLINE.replace(
     "***plain",
-    "\x1b[38;2;121;252;150m***plain\x1b[0m",
+    color(palette.plain, "***plain"),
   );
   process.stdout.write(" ".repeat(pad) + tag + "\n\n");
 }
@@ -95,7 +114,7 @@ Commands:
   uninstall   Remove a plain-forge install using its manifest
 
 Install options:
-  --agent <claude|codex|forgecode|opencode|universal>
+  --agent <claude|codex|copilot|forgecode|opencode|universal>
                                                Target agent layout
   --scope <project|global>                     Install into cwd or $HOME
   -h, --help                                   Show this help
@@ -105,7 +124,7 @@ Update options:
                                                confirming each one
 
 Uninstall options:
-  --agent <claude|codex|forgecode|opencode|universal|*>
+  --agent <claude|codex|copilot|forgecode|opencode|universal|*>
                                                Which install to remove
                                                (default: * — every agent)
   --scope <project|global>                     Where to look (default: project)
@@ -462,10 +481,10 @@ function reportOpencodeUnmerge(result) {
   }
 }
 
-// --- Codex / ForgeCode instructions wiring ----------------------------------
-// Neither tool auto-reads a rules/ directory; both load custom instructions
-// only from AGENTS.md (Codex: repo AGENTS.md or ~/.codex/AGENTS.md; ForgeCode:
-// repo AGENTS.md or ~/forge/AGENTS.md). AGENTS.md has no include/glob mechanism,
+// --- ForgeCode instructions wiring ------------------------------------------
+// ForgeCode does not auto-read a rules/ directory; it loads custom instructions
+// from AGENTS.md (repo AGENTS.md or ~/forge/AGENTS.md). AGENTS.md has no
+// include/glob mechanism,
 // so we append a managed pointer block that tells the agent to read our rules
 // dir when touching .plain files. The block is fenced by markers so it can be
 // refreshed or removed idempotently without disturbing the user's own content.
@@ -476,7 +495,7 @@ const AGENTS_MD_END = "<!-- END plain-forge (managed) -->";
 // Agents whose rules are delivered through AGENTS.md rather than a natively
 // auto-loaded rules/ dir (claude) or a config glob (opencode).
 function usesAgentsMd(agent) {
-  return agent === "codex" || agent === "forgecode";
+  return agent === "forgecode";
 }
 
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -485,8 +504,10 @@ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 // root (cwd) for both tools; global scope differs per tool.
 function agentsMdPath(agent, scope) {
   if (scope === "project") return path.join(process.cwd(), "AGENTS.md");
-  if (agent === "forgecode") return path.join(os.homedir(), "forge", "AGENTS.md");
-  return path.join(os.homedir(), ".codex", "AGENTS.md"); // codex global
+  // Retained only so update/uninstall can remove blocks created by older Codex
+  // installs. New Codex installs do not create this file.
+  if (agent === "codex") return path.join(os.homedir(), ".codex", "AGENTS.md");
+  return path.join(os.homedir(), "forge", "AGENTS.md");
 }
 
 // Glob the pointer block references — the installed rules dir. Project scope is
@@ -603,6 +624,10 @@ function wireRules(agent, scope) {
       reportOpencodeMerge(mergeOpencodeInstructions(scope));
     } else if (usesAgentsMd(agent)) {
       reportAgentsMdMerge(mergeAgentsMd(agent, scope));
+    } else if (agent === "codex") {
+      // Migrate installs from the former Codex AGENTS.md wiring. Rules are now
+      // loaded by load-plain-reference itself.
+      reportAgentsMdUnmerge(unmergeAgentsMd(agent, scope));
     }
   } catch (err) {
     warnRulesWiring("wire", agent, err);
@@ -616,7 +641,7 @@ function unwireRules(agent, scope) {
   try {
     if (agent === "opencode") {
       reportOpencodeUnmerge(unmergeOpencodeInstructions(scope));
-    } else if (usesAgentsMd(agent)) {
+    } else if (usesAgentsMd(agent) || agent === "codex") {
       reportAgentsMdUnmerge(unmergeAgentsMd(agent, scope));
     }
   } catch (err) {
@@ -655,8 +680,8 @@ function writeManifest(baseDir, files, agent) {
   const target = manifestPathFor(baseDir);
   fs.mkdirSync(path.dirname(target), { recursive: true });
   // `agent` records which agent layout produced this install. It matters when
-  // two agents resolve to the same dir (codex and universal both use .agents):
-  // it lets detect/update/uninstall know whether AGENTS.md rule-wiring applies.
+  // Multiple agents resolve to the same .agents dir, so the manifest preserves
+  // the selected label for detection, updates, and uninstall output.
   const manifest = {
     name: "plain-forge",
     version: readPkgVersion(),
@@ -714,7 +739,7 @@ function detectInstalls() {
   for (const scope of SCOPES) {
     for (const agent of Object.keys(AGENTS)) {
       const baseDir = resolveBaseDir(agent, scope);
-      // Some agents share a directory (codex and universal both use .agents).
+      // Some agents share the .agents directory.
       // Only inspect each physical dir once so a single install isn't detected
       // — and later updated/pruned — twice.
       if (seen.has(baseDir)) continue;
@@ -929,8 +954,7 @@ async function cmdUninstall(args) {
     );
 
     // Undo the rules wiring (opencode.json / AGENTS.md). Keyed off the agent
-    // recorded at install time, not the requested name — codex and universal
-    // share the .agents dir, and only the codex install wired AGENTS.md. Done
+    // recorded at install time, not the requested name. Done
     // before the dir cleanup so a now-orphaned config file living inside baseDir
     // (e.g. forgecode-global ~/forge/AGENTS.md) can be removed and let baseDir
     // itself be pruned.
@@ -960,11 +984,12 @@ async function cmdUninstall(args) {
 }
 
 function printNextSteps(agent) {
-  const bold = (s) => `\x1b[1;97m${s}\x1b[0m`;
+  const palette = terminalPalette();
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`;
   const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-  const plain = (s) => `\x1b[38;2;121;252;150m${s}\x1b[0m`;
-  const codeplain = (s) => `\x1b[38;2;224;255;110m${s}\x1b[0m`;
-  const link = (s) => `\x1b[4;38;2;95;175;255m${s}\x1b[0m`;
+  const plain = (s) => color(palette.plain, s);
+  const codeplain = (s) => color(palette.brand, s);
+  const link = (s) => color(palette.link, s, "4;");
 
   console.log(`\x1b[1mnext steps:\x1b[0m`);
   console.log(
@@ -996,6 +1021,8 @@ function agentLabel(agent) {
       return "Claude Code";
     case "codex":
       return "Codex";
+    case "copilot":
+      return "GitHub Copilot";
     case "forgecode":
       return "ForgeCode";
     case "opencode":
@@ -1090,4 +1117,6 @@ export {
   deleteForgeFile,
   detectInstalls,
   promptConfirm,
+  terminalHasLightBackground,
+  terminalPalette,
 };

package/forge/rules/bullet-continuation.md

@@ -0,0 +1,59 @@
+---
+description: Bullet and continuation syntax for every section in .plain files
+---
+
+# Rules for bullets and continuations in `.plain` files
+
+These rules apply to every section and to concept explanations.
+
+## No line-length limit
+
+- `.plain` does not impose a maximum number of characters per line
+- Do not split a valid line merely to satisfy an arbitrary formatting width
+- Prefer clear, precise wording; concision must never remove required detail
+
+## Never use bare continuation lines
+
+- Every line inside a section must be a list item beginning with `- `
+- An indented continuation without `- ` is invalid syntax
+- If content is intentionally separated across lines, express the additional lines as nested
+  bullet items so each line remains syntactically valid
+
+WRONG — bare continuation lines:
+
+```plain
+***functional specs***
+
+- :GatewayWebhook: hands off :StripeRequest: to :StripeIntegration:.handle(),
+  which returns a list of :EventEnvelope: dicts conforming to the gateway contract.
+```
+
+GOOD — one valid list item:
+
+```plain
+***functional specs***
+
+- :GatewayWebhook: hands off :StripeRequest: to :StripeIntegration:.handle(), which returns a list of :EventEnvelope: dicts conforming to the gateway contract.
+```
+
+BEST — separate clarifications expressed as nested bullets:
+
+```plain
+***functional specs***
+
+- :GatewayWebhook: hands off :StripeRequest: to :StripeIntegration:.handle().
+  - The method returns a list of :EventEnvelope: dicts.
+  - The dicts conform to the gateway's :EventEnvelope: contract.
+```
+
+## Presenting `.plain` examples
+
+- Show every example under its owning section header
+- Separate top-level list items with one blank line
+- Keep nested clarifications directly under their parent without a blank line
+- BAD, WRONG, `Before:`, and `Too complex:` examples may intentionally demonstrate invalid syntax
+
+## Content that belongs in resources
+
+Long URLs, schema fragments, and example payloads belong in `resources/` because they are external
+artifacts, not because of their character count. Follow `linked-resources.md`.

package/forge/rules/definitions.md

@@ -42,14 +42,20 @@ When writing or editing a `***definitions***` section in a `.plain` file, always
 Bad — circular:
 
 ```plain
+***definitions***
+
 - :Customer: is a user who has placed at least one :Order:.
+
 - :Order: is placed by :Customer: and contains :OrderItem: entries.
 ```
 
 `:Order:` references `:Customer:`, and `:Customer:` references `:Order:`. Fix by removing the back-reference:
 
 ```plain
+***definitions***
+
 - :Customer: is a user of the system.
+
 - :Order: is placed by :Customer: and contains :OrderItem: entries.
 ```
 
@@ -69,13 +75,21 @@ Bad — circular:
 Example of defining technical components alongside their behavior:
 
 ```plain
+***definitions***
+
 - :CsvToJsonConverter: bidirectionally converts csv and json strings.
+
 - :CsvToJson: of :CsvToJsonConverter: converts a list of csv strings (e.g., "value1,value2,value3") to a list of json strings (e.g., "{\"key1\":\"value1\"}").
+
 - :JsonToCsv: of :CsvToJsonConverter: converts a list of json strings (e.g., "{\"key1\":\"value1\"}") to a list of csv strings (e.g., "value1,value2").
 
 - :StorageService: is an abstraction for a remote blob storage backend.
+
 - :CsvFileWriter: writes CSV rows to local files, automatically rotates to new files when size limits are reached, and flushes completed files to :StorageService:.
+
 - :CsvFileReader: reads CSV rows in a batched manner.
+
+
 - :CsvJoiner: joins csvs and uses :CsvFileWriter: to create the merged CSV.
 ```
 
@@ -83,6 +97,7 @@ Example of defining technical components alongside their behavior:
 
 ```plain
 ***definitions***
+
 - :ConceptName: is a description of what it represents.
   - Attribute one (required)
   - Attribute two (optional)

package/forge/rules/func-specs.md

@@ -6,12 +6,53 @@ description: Rules for writing ***functional specs*** and ***acceptance tests***
 
 When writing or editing a `***functional specs***` section in a `.plain` file, always follow these rules:
 
+## Voice
+- Write each functional spec as a **statement of fact** — present tense, indicative mood — describing what the software *is* or *does* once built, not as a command telling a developer what to build
+- **Name a concrete subject**: an actor (`A :User: can …`), a named component or concept (`:PdfRenderer: lays out …`, `:Order: processing depends on …`), or the affected data in passive voice (`All :Resource: items are returned`)
+- **Avoid the vague subject "The system …"** — it says nothing about *which* part does the work. Prefer the concrete component/concept, or passive voice with the affected concept as the subject
+- **Never open a spec with an imperative** like "Implement …", "Add …", "Create …", "Show …", "Display …", "Build …" — those read as instructions, not specifications
+- Do **not** use "should" / "should be able to" in a functional spec — that is requirement-modal voice; state the fact directly
+
+BAD — imperative commands, or the vague "The system":
+
+```plain
+***functional specs***
+
+- Implement the entry point for :App:.
+
+- The system shows :TaskList:.
+
+- Add :Task:.
+```
+
+GOOD — statements of fact with concrete subjects:
+
+```plain
+***functional specs***
+
+- :App: has an entry point.
+
+- The :TaskList: is displayed.
+
+- A :User: can add a :Task:. Only valid :Task: items are added.
+```
+
 ## Complexity limit
 - 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
 - Use `analyze-if-func-spec-too-complex` to verify before inserting
 - Use `analyze-func-specs` to check a spec (or a batch of specs) against all relevant existing specs in a single batched call; use `resolve-spec-conflict` for each conflicting pair it reports
 
+## First-spec bootstrap cost
+- The first functional spec in a new root module carries implicit implementation cost even when its text describes little behavior
+- The renderer may need to create the project structure, package metadata, framework configuration, entry point, initial source files, and unit-test infrastructure before implementing the behavior
+- Count that bootstrap work toward the 200-changed-line limit; it is not free setup outside the spec
+- Make the first spec the module's simplest useful, independently observable capability
+- The first spec must still imply a testable outcome; setup alone is not a functional spec
+- Prefer one minimal entry point or public operation with a deterministic result that can be invoked and verified
+- Defer persistence, integrations, multiple interfaces, branching workflows, and cross-cutting behavior until later specs can build on the generated baseline
+- This extra bootstrap cost applies when no previous implementation baseline exists; a module that continues from a `requires` module may already inherit the necessary scaffold
+
 ## Chronological ordering
 - Specs are rendered incrementally, top to bottom
 - The renderer has **no knowledge of future specs** — only previously rendered specs are in context
@@ -36,6 +77,14 @@ When writing or editing a `***functional specs***` section in a `.plain` file, a
 - Nested lines clarify the parent spec — they do not introduce separate functionality
 - Even with nested detail, the spec must still imply ≤ 200 lines of code
 
+## Testability
+- Every functional spec must describe behavior that can be verified through an observable interface
+- State the triggering input or action and the deterministic outcome a test can observe
+- Include relevant outputs, state changes, errors, or externally visible side effects
+- Do not rely on generated implementation details as the only way to verify the behavior
+- If a black-box conformance test cannot be derived from the spec, make the behavior more explicit
+- Testability does not require an acceptance test; acceptance tests are reserved for full workflows
+
 ## 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.
@@ -46,10 +95,6 @@ When writing or editing a `***functional specs***` section in a `.plain` file, a
 - `requires` modules only receive functional specs — do not rely on implementation reqs to convey behavior
 - Behavior that downstream modules need must be expressed in functional specs, not elsewhere
 
-## Line length
-- See [`line-length.md`](line-length.md) — applies to every section, but bites hardest here because functional specs trend long
-- Hard limit: 120 characters. When a line gets too long, split at a natural clause boundary into nested `- ` bullets — **never** use bare indented continuation lines (invalid ***plain syntax)
-
 ## Acceptance tests
 - Nest `***acceptance tests***` under a functional spec when verification criteria are needed
 - Each acceptance test must be a **full workflow test** — a specific scenario that exercises the functional spec end-to-end, not a unit-level check of a single field or condition
@@ -63,11 +108,11 @@ When writing or editing a `***functional specs***` section in a `.plain` file, a
 ```plain
 ***functional specs***
 
-- Implement the entry point for :App:.
+- :App: has an entry point.
 
-- :User: should be able to add :Task:. Only valid :Task: items can be added.
+- A :User: can add a :Task:. Only valid :Task: items are added.
 
-- :User: should be able to send a :Message: to a :Conversation:.
+- 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:.

package/forge/rules/impl-reqs.md

@@ -13,7 +13,7 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 
 ## `:UnitTests:` lives here (hard rule)
 - **Everything** about `:UnitTests:` goes in `***implementation reqs***` — paths, approach, packages, framework, conventions, fixtures, mocking policy, file layout, naming, lint / static-analysis gates
-- `:UnitTests:` are part of the generated codebase (they sit inside `plain_modules/<module>/` alongside the implementation), so requirements that shape them are implementation reqs by definition
+- `:UnitTests:` are part of the generated codebase (they sit inside `plain_modules/<module>/code/` alongside the implementation), so requirements that shape them are implementation reqs by definition
 - The unit-test generator reads **only** `***implementation reqs***` — anything about `:UnitTests:` placed elsewhere (e.g. `***test reqs***`) is silently ignored
 - Author each `:UnitTests:` requirement via `add-implementation-requirement` and phrase it in terms of `:UnitTests:` so the partition stays visible at a glance
 

package/forge/rules/integration-embedded-testing.md

@@ -4,7 +4,10 @@ description: Rules for authoring the three test scripts that an embedded ***plai
 
 # Rules for embedded-integration test scripts
 
-When an embedded integration ships its three `test_scripts/` (prepare-environment, unit, conformance) — whether you author them by hand or via the `implement-*-testing-script` skills — these rules apply on top of the shared testing-script rules in PLAIN_REFERENCE.md (exit-code conventions, the activate-only vs install-inline conformance distinction, `VERBOSE=1`, etc.).
+When an embedded integration ships its three `test_scripts/` (prepare-environment, unit,
+conformance), these rules apply on top of the contracts in the corresponding
+`implement-*-testing-script` skills. Use `load-plain-reference` for the rendering and testing
+workflow overview when needed.
 
 ## Staging model (read this first)
 
@@ -72,7 +75,7 @@ mvn test -Dtest='<:UnitTests: package>.**.*Test' checkstyle:check
 
 These reqs feed `run_conformance_tests_<lang>`. At minimum, declare:
 
-1. **`:ConformanceTests:` source location** — where the conformance suite lives in the project (typically a sibling folder, e.g. `conformance_tests/<module>/`); the renderer passes the resolved path as `$2`
+1. **`:ConformanceTests:` source location** — the generated suite lives under `plain_modules/<module>/tests/`, one folder per functional spec; the renderer passes the resolved path of the folder under test as `$2`
 2. **`:ConformanceTests:` framework and execution command** — `mvn test --no-transfer-progress`, `pytest`, `npm test`, `go test ./...`, etc., with any flags / profiles the project requires
 3. **Fully qualified `:ConformanceTests:` package** (or path / pattern) used to scope discovery, if the runner needs one
 4. **`:ConformanceTests:` network and secrets policy** — by default the suite runs against the **live provider** (see [`integrations.md`](integrations.md) → *`:ConformanceTests:` always run against the live integration*). Declare the env-var names the script reads (e.g. `<PROVIDER>_API_KEY`), whether the script loads a `.env` file before running, and any specific endpoints that are mocked because they can't be exercised live safely (429, forced 5xx)
@@ -82,7 +85,7 @@ These reqs feed `run_conformance_tests_<lang>`. At minimum, declare:
 Author the conformance facts as one or more entries, phrased in terms of `:ConformanceTests:`:
 
 ```plain
-- :ConformanceTests: of :Implementation: live in `conformance_tests/foo/` and are implemented with JUnit 5 + Maven.
+- :ConformanceTests: of :Implementation: live in `plain_modules/foo/tests/` and are implemented with JUnit 5 + Maven.
   - The fully qualified package used for :ConformanceTests: discovery is `com.example.integrations.foo.conformance`.
   - :ConformanceTests: are run via `mvn test --no-transfer-progress`; the host's Surefire plugin must be installed.
   - :ConformanceTests: run against the live :ProviderName: sandbox — no mocking of provider calls.
@@ -136,7 +139,7 @@ All three scripts are invoked by the `codeplain` renderer with positional argume
 
 ## 1. `prepare_environment_<lang>` — copy into the host, then compile
 
-Receives one positional argument: the renderer's build output folder (e.g. `plain_modules/<module>/`).
+Receives one positional argument: the renderer's build output folder (e.g. `plain_modules/<module>/code/`).
 
 Purpose: stage the generated code **into the host codebase at the module's package path**, then run the host's install / build so that downstream test projects (specifically the conformance suite) can depend on it from the local dependency cache.
 

package/forge/rules/integration-embedded.md

@@ -30,6 +30,9 @@ The embedded integration's `.plain` specs (and the rest of the ***plain project
 │   ├── resources/
 │   ├── test_scripts/
 │   ├── plain_modules/     # generated; gitignored
+│   │   └── <module>/
+│   │       ├── code/      #   implementation + unit tests
+│   │       └── tests/     #   conformance tests, per functional spec
 │   └── config.yaml
 └── src/            # host source tree (Java, Python, etc.)
 ```
@@ -117,7 +120,7 @@ The renderer reads the directives from the spec and the shapes from the linked s
 
 ## Test-script wiring — copy into the host, run tests there
 
-Embedded integrations are tested **inside the host codebase itself**. The prepare and unit-test scripts copy the renderer's output (`$1`, i.e. `plain_modules/<module>/`) into the host's source tree at the module's package path, then compile / test the host project in place. Only the conformance script uses a scratch folder in the system temp directory (`/tmp/<lang>_conformance/`), because the conformance suite is a separate project that consumes the host build as a dependency.
+Embedded integrations are tested **inside the host codebase itself**. The prepare and unit-test scripts copy the renderer's output (`$1`, i.e. `plain_modules/<module>/code/`) into the host's source tree at the module's package path, then compile / test the host project in place. Only the conformance script uses a scratch folder in the system temp directory (`/tmp/<lang>_conformance/`), because the conformance suite is a separate project that consumes the host build as a dependency.
 
 This matters because the integration's generated code references host symbols by their full import path (e.g. `from host_project.integrations.base import IntegrationContract`). Those imports only resolve cleanly when the test process is rooted in the host's package layout — anything else creates path edge cases that bite later in conformance failures.
 

package/forge/rules/linked-resources.md

@@ -23,7 +23,7 @@ A linked resource **must not** be any of the following:
 - Litmus test: "Would the renderer benefit from reading the bytes at this URL / folder?" If yes, save it to a file and link the file. If no (it's a runtime value the code carries forward), it can stay as plain text
 
 ## Structured protocol artifacts must be linked, never transcribed
-- JSON Schema, OpenAPI / Swagger, GraphQL SDL, Protobuf `.proto`, Avro / Thrift schemas, XML XSDs, AsyncAPI specs, JSON-RPC method definitions, wire-protocol descriptions, payload examples — anything with a formal machine-readable shape — belongs in a file under `resources/` (or a subfolder of the `.plain` file's directory)
+- JSON Schema, OpenAPI / Swagger, GraphQL SDL, Protobuf `.proto`, Avro / Thrift schemas, XML XSDs, AsyncAPI specs, JSON-RPC method definitions, wire-protocol descriptions, payload examples — anything with a formal machine-readable shape — belongs in a file under `resources/` (or another directory within the project)
 - The spec line should describe the *role* of the artifact ("the request body conforms to ...", "the public API surface is defined in ...") rather than its contents
 - Reasons: one source of truth (no drift between prose and schema); the renderer and the generated code can both consume the file directly; schema changes show up cleanly as diffs
 
@@ -37,7 +37,7 @@ A linked resource **must not** be any of the following:
 
 ***functional specs***
 
-- :User: should be able to add :Task: by POSTing :TaskCreateRequest: to the `POST /tasks` endpoint of :TasksAPI:.
+- A :User: can add a :Task: by POSTing :TaskCreateRequest: to the `POST /tasks` endpoint of :TasksAPI:.
   - The endpoint responds per :TasksAPI:.
 ```
 
@@ -54,11 +54,12 @@ A linked resource **must not** be any of the following:
 
 ***functional specs***
 
-- :User: should be able to add :Task: using :TaskModalSpec:.
+- A :User: can add a :Task: using :TaskModalSpec:.
 
-- :User: should be able to edit :Task: using :TaskModalSpec:.
+- A :User: can edit a :Task: using :TaskModalSpec:.
 ```
 
 ## File location and path resolution
-- Paths are resolved relative to the `.plain` file's directory
-- The conventional location is `resources/` under the `.plain` file's directory
+- Paths are resolved relative to the directory where `codeplain` is run (the current working directory)
+- Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk
+- The conventional location is a `resources/` directory; keep the resource inside the project so the path stays stable from wherever `codeplain` is run

package/forge/rules/requires-modules.md

@@ -8,7 +8,7 @@ When creating or editing a `.plain` file that uses `requires`, always follow the
 
 ## What requires does
 - `requires` establishes a **build ordering** — the required module is built before the current one
-- The required module's generated code (`plain_modules/<required_module>`) is copied as the starting point
+- The required module's generated code (`plain_modules/<required_module>/code`) is copied as the starting point
 - The required module's `***functional specs***` become visible as **previous functional specs** — this property **is transitive**
 - Only `exported_concepts` from the required module are available — not its full definitions — and this property **is not transitive**
 

package/forge/rules/test-reqs.md

@@ -14,7 +14,7 @@ When writing or editing a `***test reqs***` section in a `.plain` file, always f
 
 ## `: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 (typically in a separate project under `conformance_tests/<module>/`), so requirements that shape them belong in test reqs by definition
+- `:ConformanceTests:` live outside the generated codebase, in their own tree under `plain_modules/<module>/tests/` (one folder per functional spec), 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
 - Conformance testing run scripts should be linked here as a linked resource