plain-forge 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codeplain Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+<p align="center">
+  <img src="assets/plain-forge.png" alt="plain-forge" width="600" />
+</p>
+
+# 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.
+
+## How It Works
+
+The main entry point is `forge-plain`. It turns a conversation into ***plain specs through four phases:
+
+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.
+
+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.
+
+## Getting Started
+
+plain-forge ships as a set of skills that plug into your AI coding tool of choice. Install it once, then invoke `forge-plain` (or `add-feature` to add a feature to an existing ***plain project) from any project.
+
+### Install with the `skills` CLI (any runtime)
+
+The fastest way to add plain-forge is the `skills` CLI. The `--all` flag installs **every** plain-forge skill at once:
+
+```bash
+npx skills add Codeplain-ai/plain-forge --skill '*'
+```
+
+#### Install into a specific runtime
+
+If you only use one runtime, pass `--agent` to target just that one (you can repeat the flag to pick several):
+
+```bash
+# Just Claude Code
+npx skills add Codeplain-ai/plain-forge --skill '*' --agent claude-code
+
+# Just Codex
+npx skills add Codeplain-ai/plain-forge --skill '*' --agent codex
+
+# Just OpenCode
+npx skills add Codeplain-ai/plain-forge --skill '*' --agent opencode
+
+# Any combination, non-interactive
+npx skills add Codeplain-ai/plain-forge --skill '*' --agent opencode --agent codex --agent claude-code
+```
+
+If you'd rather use the native install flow for a specific runtime, the per-tool instructions below still work.
+
+### Install in Claude Code
+
+Requires the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured. Inside any Claude Code session, run the following **three commands**, one after the other (copy and paste each one separately):
+
+**1.** Register this repository as a plugin marketplace:
+
+```text
+/plugin marketplace add Codeplain-ai/plain-forge
+```
+
+**2.** Install the `plain-forge` plugin from it:
+
+```text
+/plugin install plain-forge@plain-forge
+```
+
+**3.** Reload plugins so Claude Code picks up the newly installed skills:
+
+```text
+/reload-plugins
+```
+
+Without the reload, the plain-forge skills won't be visible in the current session even though the install succeeded. Once all three commands have run, all plain-forge skills become available.
+
+### Install in Codex
+
+Requires the [OpenAI Codex CLI](https://developers.openai.com/codex/cli/reference) installed and signed in. Installation is **two steps**, but only the first one is a shell command:
+
+**1.** From your shell, register this repository as a Codex marketplace:
+
+```bash
+codex plugin marketplace add Codeplain-ai/plain-forge
+```
+
+**2.** Inside Codex, open the plugin directory, pick the `plain-forge` marketplace, and install the plugin from there. (The Codex CLI does not currently expose a `codex plugin install` equivalent — installation has to be triggered from the in-app plugin directory.)
+
+Once the plugin is installed, all plain-forge skills become available in your Codex sessions.
+
+## Usage
+
+### Prerequisites
+
+1. Open your project folder and start a session in your favorite AI coding agent (Claude Code, OpenCode, Codex, …).
+2. Make sure the plain-forge skills are available in that session.
+
+### Starting a new project
+
+1. Invoke `forge-plain` to launch the structured QA workflow.
+2. Answer the questions. plain-forge writes the `.plain` files for you as you go through the four phases.
+3. Render the specs into code (see [Rendering specs](#rendering-specs) below).
+
+### Starting a new project — incremental workflow
+
+If you'd rather skip the full upfront interview and build the specs feature-by-feature, use this lighter loop:
+
+1. Invoke `init-plain-project`. It asks just for the base technology, the project kind, and whether conformance testing is enabled, then scaffolds the project skeleton: `template/base.plain` with the base `***implementation reqs***` and `***test reqs***`, a stub top-level `<project>.plain` (frontmatter only — no functional specs, no concepts), the unit-test script, an optional conformance-test script, an optional prepare-environment script, and a `config.yaml` wired to whichever scripts were generated. No `codeplain --dry-run` is run.
+2. From there, either:
+   - **Converse with the agent.** Just describe the next feature in plain English; the agent will invoke `add-feature` for you and run its one-question-at-a-time loop until the feature is on disk.
+   - **Invoke `add-feature` manually** whenever you want to drive the loop yourself.
+3. Repeat step 2 for each feature you want to add. The specs grow incrementally and `plain-healthcheck` is run as the final automated step of every `add-feature` pass.
+4. Render the specs into code (see [Rendering specs](#rendering-specs) below).
+
+### Adding a feature to an existing project
+
+1. Invoke `add-feature`.
+2. Describe the feature in plain English. plain-forge runs the same **ask → author → review** loop scoped to that feature and updates the relevant `.plain` file(s).
+3. Re-render to regenerate the code (see [Rendering specs](#rendering-specs)).
+
+### Rendering specs
+
+Once your `.plain` files are ready (and `plain-healthcheck` is green), render the specs into code with the [Codeplain](https://codeplain.ai) renderer:
+
+```bash
+codeplain <module>.plain
+```
+
+plain-forge prints the exact command (with the right final module name) at the end of Phase 4.
+
+#### Supervised render (experimental)
+
+If you'd rather have plain-forge babysit the run from your AI coding agent, invoke `run-codeplain`. It launches the renderer for you, tails `codeplain.log`, watches generated code appear under `plain_modules/`, and surfaces what's happening in plain English. If it detects a pathology (stuck conformance loop, complexity error, missing concept, render failure), it asks for approval to stop the renderer, hands off to the right spec-edit skill (`debug-specs`, `resolve-spec-conflict`, `break-down-func-spec`, …), and resumes the render from the last completed functionality via `--render-from`.
+
+This is an **experimental** feature — the default and most reliable way to render is still the manual `codeplain <module>.plain` invocation above.
+
+### Debugging specs
+
+Hit a bug in the rendered app, a failing test, or behavior that doesn't match what you specified?
+
+1. Invoke `debug-specs`. plain-forge reads the generated code in `plain_modules/` (and the failing tests, if any), traces the issue back to the responsible `.plain` spec, and diagnoses the root cause — **ambiguous spec**, **missing spec**, **conflicting specs**, **incorrect spec**, or a **missing implementation req**.
+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.
+
+
+## Repository Structure
+
+plain-forge keeps a single canonical source of truth under `forge/` and uses tiny per-runtime adapters to regenerate the directory layout each AI tool expects. The generated outputs are committed so existing install commands keep working — no build step is needed for end users.
+
+```
+forge/                       # canonical, runtime-neutral content
+  skills/                    # all skills used during spec writing
+  rules/                     # workspace rules for spec validation
+  docs/                      # shared docs (PLAIN_REFERENCE.md, etc.)
+
+runtimes/                    # per-runtime adapters
+  claude/
+    build.ts                 # generates .claude/ + .claude-plugin/ from forge/
+    templates/               # Claude-specific files: settings.json, hook script, plugin manifests
+  codex/
+    build.ts                 # generates .codex-plugin/ and .agents/plugins/ (manifest points at forge/skills/)
+    templates/               # Codex-specific files: plugin.json, marketplace catalog
+  opencode/
+    build.ts                 # generates .opencode/ from forge/
+    templates/               # OpenCode-specific files: package.json, .gitignore
+
+bin/
+  forge-build.ts             # orchestrator: runs every runtimes/*/build.ts
+  lib.ts                     # shared symlink/copy helpers
+
+# Generated outputs (committed, do not edit by hand):
+.claude/                     # Claude Code plugin layout
+.claude-plugin/              # Claude Code plugin manifests
+.codex-plugin/               # Codex plugin manifest (its "skills" field points at forge/skills/)
+.agents/plugins/             # Codex marketplace catalog
+.opencode/                   # OpenCode plugin layout
+```
+
+### Contributing
+
+After editing anything under `forge/` or `runtimes/*/templates/`, regenerate the runtime outputs:
+
+```bash
+npm install        # required after every fresh clone (node_modules/ is gitignored)
+npm run build      # regenerate runtime outputs for Claude, Codex, OpenCode
+npm run clean      # remove generated outputs and rebuild from scratch
+```
+
+If `npm run build` errors with `sh: tsx: command not found`, it means `node_modules/` is missing — run `npm install` first.
+
+The build is idempotent — re-running it produces no `git diff`.
+
+## Available Skills
+
+### Core Workflow
+
+| Skill | Description |
+|-------|-------------|
+| `forge-plain` | End-to-end QA interview that produces complete `.plain` spec files for a new project |
+| `init-plain-project` | Lightweight project initializer — scaffolds `template/base.plain` (base impl + test reqs), a stub top-level module, the testing scripts, and `config.yaml`. No functional specs, no concepts, no dry-run. Pair with `add-feature` to grow the project feature-by-feature. |
+| `add-feature` | Interview the user about a single feature, then write all the specs for it |
+| `run-codeplain` | **Experimental.** Launch a `codeplain` render and supervise it end-to-end — tails `codeplain.log`, watches generated code appear, detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures), and on approval stops the renderer, hands off to the right spec-edit skill, and resumes with `--render-from`. The default render path is still the manual `codeplain <module>.plain` command. |
+
+### Spec Authoring
+
+| Skill | Description |
+|-------|-------------|
+| `add-functional-spec` | Add a single feature spec to `***functional specs***` |
+| `add-functional-specs` | Add multiple feature specs to `***functional specs***` in one pass (same per-spec checks as `add-functional-spec`) |
+| `add-implementation-requirement` | Add a non-functional requirement to `***implementation reqs***` |
+| `add-test-requirement` | Add a testing requirement to `***test reqs***` |
+| `add-concept` | Define a new concept in `***definitions***` |
+| `add-acceptance-test` | Add verification criteria under a functional spec |
+| `add-resource` | Link an external file (schema, API spec) to a spec |
+| `add-template` | Create or include a reusable Liquid template |
+
+### Module Management
+
+| Skill | Description |
+|-------|-------------|
+| `create-import-module` | Create a shared template module (definitions + reqs, no functional specs) |
+| `create-requires-module` | Create a module that depends on a previously built module |
+| `refactor-module` | Split a large module into smaller modules connected via a requires chain |
+| `consolidate-concepts` | Gather scattered concept definitions into a single shared import module |
+
+### Analysis and Quality
+
+| Skill | Description |
+|-------|-------------|
+| `init-config-file` | Build / finalize the project's `config.yaml` file(s) from the decisions made in Phase 3. Knows the full set of valid keys derived from the `codeplain` CLI, refuses to write secrets or per-invocation flags, and produces one config per part of the project. Run at the end of `forge-plain` (just before `plain-healthcheck`) and any time the testing surface changes. |
+| `plain-healthcheck` | Verification gate: validates every `config.yaml`, confirms each `*-script` field points at a real file in `test_scripts/`, and dry-runs every top module. Run whenever anything in the project is finalized — at the end of `forge-plain`, at the end of `add-feature`, after `debug-specs`, and after any single-skill edit that touches the renderable surface. |
+| `check-plain-env` | Read the project's `.plain` files, `test_scripts/`, `config.yaml`(s), and `resources/`, then probe the host for every requirement **the package manager can't install**: language toolchains (`python` + `pip`, `node` + `npm`, JDK + `mvn`, Go, Rust, .NET, etc.), external services (Postgres, Redis, Docker, ...), system binaries that language packages wrap (`ffmpeg`, `tesseract`, `pdftoppm`, browser binaries, ...), hardware / drivers / accelerators (NVIDIA driver → CUDA toolkit → cuDNN → framework-sees-GPU chain), `codeplain` itself, and credential env vars. Does **not** probe individual language packages — `pip install -r requirements.txt` (and equivalents) handle those when the test scripts run. Emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands for any gaps. Read-only — never installs anything. Run on first-time setup, before rendering on a new machine, after adding a new tech to a project, or any time `command not found` shows up in test output. |
+| `analyze-if-func-spec-too-complex` | Check if a spec exceeds the 200-line complexity limit |
+| `analyze-func-specs` | Check a batch of specs (2+) against each other in one call and return every conflicting pair |
+| `analyze-2-func-specs` | Legacy: check exactly two specs for conflicts (prefer `analyze-func-specs`) |
+| `break-down-func-spec` | Split an overly complex spec into smaller specs (each ≤ 200 LOC) |
+| `resolve-spec-conflict` | Resolve a conflict between two functional specs |
+
+### Debugging and Testing
+
+| Skill | Description |
+|-------|-------------|
+| `debug-specs` | Investigate a bug by tracing generated code back to specs and fixing only the `.plain` files |
+| `implement-unit-testing-script` | Generate a per-language unit-test runner (`run_unittests_<lang>.sh` / `.ps1`) |
+| `implement-conformance-testing-script` | Generate a per-language conformance-test runner; picks the install-inline or activate-only variant based on whether `prepare_environment_<lang>` exists |
+| `implement-prepare-environment-script` | Generate a per-language one-time setup script (`prepare_environment_<lang>.sh` / `.ps1`) that stages the build and pre-warms dependencies so conformance tests start cold; reconciles any existing conformance script to remove its now-redundant install step |

package/bin/cli.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const pkgRoot = path.resolve(path.dirname(__filename), "..");
+const forgeDir = path.join(pkgRoot, "forge");
+
+const AGENTS = {
+  claude: ".claude",
+  codex: ".codex",
+  forgecode: ".forgecode",
+  universal: ".agents",
+};
+const SCOPES = ["project", "global"];
+
+function usage() {
+  console.log(`Usage: plain-forge install [options]
+
+Options:
+  --agent <claude|codex|forgecode|universal>   Target agent layout
+  --scope <project|global>                     Install into cwd or $HOME
+  --skill <name>                               Install only the named skill (repeatable; default: all)
+  -h, --help                                   Show this help
+
+Examples:
+  plain-forge install --agent claude --scope project
+  plain-forge install --agent universal --scope global
+  plain-forge install --agent claude --skill add-functional-spec --skill add-concept
+
+Missing flags are prompted interactively.`);
+}
+
+function parseArgs(argv) {
+  const out = { _: [], skills: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--agent") out.agent = argv[++i];
+    else if (a === "--scope") out.scope = argv[++i];
+    else if (a === "--skill") out.skills.push(argv[++i]);
+    else if (a === "-h" || a === "--help") out.help = true;
+    else out._.push(a);
+  }
+  return out;
+}
+
+async function promptChoice(question, choices) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    while (true) {
+      const ans = (await rl.question(`${question} [${choices.join("/")}]: `)).trim().toLowerCase();
+      if (choices.includes(ans)) return ans;
+      console.log(`  please answer one of: ${choices.join(", ")}`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function copyTree(srcDir, destDir, filterNames) {
+  if (!fs.existsSync(srcDir)) return 0;
+  fs.mkdirSync(destDir, { recursive: true });
+  let count = 0;
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    if (filterNames && !filterNames.has(entry.name)) continue;
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      fs.cpSync(src, dest, { recursive: true, force: true, dereference: true });
+    } else {
+      fs.copyFileSync(src, dest);
+    }
+    count++;
+  }
+  return count;
+}
+
+async function cmdInstall(args) {
+  let agent = args.agent;
+  if (!agent) agent = await promptChoice("Which agent?", Object.keys(AGENTS));
+  if (!Object.hasOwn(AGENTS, agent)) {
+    console.error(`unknown agent "${agent}". valid: ${Object.keys(AGENTS).join(", ")}`);
+    process.exit(2);
+  }
+
+  let scope = args.scope;
+  if (!scope) scope = await promptChoice("Scope?", SCOPES);
+  if (!SCOPES.includes(scope)) {
+    console.error(`unknown scope "${scope}". valid: ${SCOPES.join(", ")}`);
+    process.exit(2);
+  }
+
+  const root = scope === "global" ? os.homedir() : process.cwd();
+  const baseDir = path.join(root, AGENTS[agent]);
+
+  const explicit = args.skills.filter((s) => s !== "*");
+  const skillFilter = explicit.length ? new Set(explicit) : null;
+
+  const skillsSrc = path.join(forgeDir, "skills");
+  if (skillFilter) {
+    for (const name of skillFilter) {
+      if (!fs.existsSync(path.join(skillsSrc, name))) {
+        console.error(`skill "${name}" not found under ${skillsSrc}`);
+        process.exit(2);
+      }
+    }
+  }
+
+  const skillsCount = copyTree(skillsSrc, path.join(baseDir, "skills"), skillFilter);
+  const rulesCount = copyTree(path.join(forgeDir, "rules"), path.join(baseDir, "rules"), null);
+  const docsCount = copyTree(path.join(forgeDir, "docs"), path.join(baseDir, "docs"), null);
+
+  console.log(`installed into ${baseDir}`);
+  console.log(`  skills: ${skillsCount}`);
+  console.log(`  rules:  ${rulesCount}`);
+  console.log(`  docs:   ${docsCount}`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || args._.length === 0) {
+    usage();
+    return;
+  }
+  const cmd = args._[0];
+  switch (cmd) {
+    case "install":
+      await cmdInstall(args);
+      break;
+    default:
+      console.error(`unknown command "${cmd}"`);
+      usage();
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.stack ?? err.message : err);
+  process.exit(1);
+});

package/forge/rules/definitions.md

@@ -0,0 +1,57 @@
+---
+description: Rules for writing ***definitions*** sections in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for writing `***definitions***`
+
+When writing or editing a `***definitions***` section in a `.plain` file, always follow these rules:
+
+## Concept syntax
+- Wrap concept names in colons: `:ConceptName:`
+- Use CamelCase starting with an uppercase letter
+- Valid characters: letters, digits, `+`, `-`, `.`, `_`
+
+## Uniqueness
+- Concept names must be globally unique across the spec and all its imports
+- Check for collisions with imported templates, `import` and `requires` modules before adding
+
+## Define before use
+- A concept must be defined before it is referenced in any section (definitions, implementation reqs, functional specs, test reqs)
+- Sources of definitions: the module's own `***definitions***`, an `import`ed module's definitions, or a `require`d module's `exported_concepts`
+
+## No circular references
+- Concept references must not form cycles — if A references B, then B must not reference A (directly or indirectly)
+- Insert each concept after any concepts it references
+
+Bad — circular:
+
+```plain
+- :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
+- :Customer: is a user of the system.
+- :Order: is placed by :Customer: and contains :OrderItem: entries.
+```
+
+## Exported concepts are not transitive
+- If module A exports a concept and module B `requires` A, module C `requires` B does **not** gain access to A's exports
+- Shared concepts belong in a common import module
+
+## Description quality
+- Descriptions must be clear, concise, and language-agnostic
+- Nest attributes and constraints as sub-bullets
+- Do not use programming language constructs (generics, annotations, framework types) in definitions
+
+## Format
+
+```plain
+***definitions***
+- :ConceptName: is a description of what it represents.
+  - Attribute one (required)
+  - Attribute two (optional)
+```

package/forge/rules/exported-concepts.md

@@ -0,0 +1,39 @@
+---
+description: Rules for using exported_concepts in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for `exported_concepts`
+
+When adding or editing `exported_concepts` in a `.plain` file's frontmatter, always follow these rules:
+
+## What exported_concepts does
+- `exported_concepts` declares which concepts from this module are visible to modules that `require` it
+- Concepts not listed in `exported_concepts` are internal to the module and invisible to downstream modules
+- Only modules that use `requires` receive exported concepts — `import` gives access to all definitions, not just exports
+
+## When to use it
+- Use `exported_concepts` on any module that other modules will `require`
+- List only the concepts that downstream modules actually need to reference
+- Keep the exported surface small — expose only what is necessary
+
+## Concepts must be defined
+- Every concept listed in `exported_concepts` must be defined in the module's own `***definitions***` section
+- Do not export concepts that are not defined in the module
+
+## Exports are not transitive
+- If module A exports `:Foo:` and module B `requires` A, module C `requires` B does **not** gain access to `:Foo:`
+- If module C also needs `:Foo:`, it must either `require` A directly or get it through a common import module
+
+## Format
+
+```plain
+---
+import:
+  - airplain
+exported_concepts: [":User:", ":JwtToken:"]
+description: Exports User and JwtToken for downstream modules
+---
+```
+
+List concepts as a YAML array with each concept in `:ConceptName:` notation.

package/forge/rules/func-specs.md

@@ -0,0 +1,72 @@
+---
+description: Rules for writing ***functional specs*** and ***acceptance tests*** in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for writing `***functional specs***`
+
+When writing or editing a `***functional specs***` section in a `.plain` file, always follow these rules:
+
+## 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
+
+## 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 from earlier specs but cannot assume anything about specs that come after it
+- Functional specs from `requires` modules are treated as previous requirements
+
+## No conflicts
+- The new spec must not contradict any existing functional spec
+- Before adding, review all existing specs and verify compatibility
+- If ambiguity exists, add explicit detail to eliminate any conflicting interpretation
+
+## Language agnosticism
+- Write in terms of behavior, concepts, and domain logic
+- Language-specific guidance belongs in `***implementation reqs***`
+
+## Disambiguation
+- Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation
+- If a single line is not enough to fully disambiguate the behavior, use **nested sub-bullets** to add detail
+- Nested lines clarify the parent spec — they do not introduce separate functionality
+- Even with nested detail, the spec must still imply ≤ 200 lines of code
+
+## 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 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
+
+## 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
+- Do not restate the obvious behavior from the functional spec — simple, direct verifications are already auto-generated as conformance tests. Acceptance tests must go beyond that: multi-step workflows, interactions between concepts, edge-case scenarios, or end-to-end sequences that prove the feature works in a realistic context
+- Each acceptance test must be a direct logical consequence of the parent spec — it illustrates, not extends
+- Acceptance tests must describe concrete, verifiable outcomes — not vague qualities
+- Acceptance tests must not contradict, narrow, or extend beyond the parent spec
+
+## Format
+
+```plain
+***functional specs***
+
+- Implement the entry point for :App:.
+
+- :User: should be able to add :Task:. Only valid :Task: items can be added.
+
+- :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:.
+
+  ***acceptance tests***
+  - Sending a :Message: to a :Conversation: with three participants should
+    make the message visible to all three.
+```

package/forge/rules/impl-reqs.md

@@ -0,0 +1,50 @@
+---
+description: Rules for writing ***implementation reqs*** sections in .plain files
+globs: "**/*.plain"
+---
+
+# Rules for writing `***implementation reqs***`
+
+When writing or editing an `***implementation reqs***` section in a `.plain` file, always follow these rules:
+
+## HOW, not WHAT
+- Implementation reqs describe **how** the software should be built, not **what** it should do
+- Observable behavior (endpoints, business rules, user-facing features) belongs in `***functional specs***`
+- Internal structure, technology choices, and coding guidance belong here
+
+## What belongs here
+- 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 → `***functional specs***`
+- Concept definitions → `***definitions***`
+- Conformance test instructions → `***test reqs***`
+
+## Encapsulation warning
+- `requires` modules only receive functional specs from their dependencies — not implementation reqs
+- If downstream modules need certain behavior to be visible, express it in functional specs, not here
+
+## No duplication
+- Do not duplicate guidance already present in the file or its imports
+- Check imported templates before adding a new req
+
+## Concept references
+- Reference defined `:Concepts:` where they add clarity
+- All referenced concepts must already be defined in `***definitions***`
+- Implementation reqs in non-leaf sections apply to all subsections
+
+## Format
+
+```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.
+```