plain-forge 1.0.23 → 1.0.24-next.2f8299c

package/README.md

@@ -87,23 +87,26 @@ Each install writes three subfolders under the chosen directory:
 
 ```
 <agent-dir>/
-  skills/    # every plain-forge skill
-  rules/     # spec-writing rules (see "How the rules get applied" below)
+  skills/    # every plain-forge skill; the spec-writing rules ship in skills/load-plain-reference/rules/
+  rules/     # plain-forge.md, a short pointer to load-plain-reference (see "How the rules get applied" below)
   docs/      # shared reference docs
 ```
 
 #### How the rules get applied per agent
 
-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:
+The `skills/` are discovered natively by every supported agent. The spec-writing rules ship inside the
+`load-plain-reference` skill, which loads only the rules relevant to the current task and skips rules
+already present in context — so a session pays for the rules its task needs, not for the whole rule
+set. The installed `rules/` dir holds only `plain-forge.md`, a short pointer telling the agent to
+invoke `load-plain-reference` when it works on `.plain` files. Each agent picks that pointer up as
+follows:
 
 | 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. |
+| **Claude Code** | Native — Claude Code auto-loads `.claude/rules/*.md`. The pointer carries `paths: "**/*.plain"` frontmatter, so it loads only once Claude reads or edits a `.plain` file. 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 `~`). |
 | **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. |
+| **Codex / GitHub Copilot / Universal** | No extra instruction file is generated. Their discovered `load-plain-reference` skill loads applicable files from `.agents/skills/load-plain-reference/rules/` when needed. |
 
 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.
@@ -254,7 +257,7 @@ git add vendor/pyro
 git commit -m "Bump pyro to vX.Y.Z"
 ```
 
-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)).
+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 pointer 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

@@ -369,8 +369,8 @@ function opencodeConfigPath(scope) {
 // The instructions glob to add. Project scope uses a cwd-relative glob (opencode
 // resolves relative instruction paths against the launch cwd). Global scope must
 // be absolute: opencode does not expand ~ and would resolve a relative path
-// against the project cwd, not the config dir. Only top-level rules/*.md are
-// wired in — the examples/ subtree holds reference scripts, not instructions.
+// against the project cwd, not the config dir. rules/ holds only the pointer to
+// load-plain-reference; the authoring rules ship inside that skill and load on demand.
 function opencodeRulesGlob(scope) {
   if (scope === "global") {
     return toPosix(
@@ -531,8 +531,9 @@ function agentsMdBlock(glob) {
     "## ***plain authoring rules (plain-forge)",
     "",
     "When creating or editing `.plain` specification files, first read and follow",
-    `every rule file matching \`${glob}\`. Each file covers one section or topic of`,
-    "the ***plain language; they are installed and maintained by plain-forge.",
+    `every rule file matching \`${glob}\`. They route to the \`load-plain-reference\``,
+    "skill, which loads the ***plain authoring rules for the task; they are installed",
+    "and maintained by plain-forge.",
     AGENTS_MD_END,
   ].join("\n");
 }

package/forge/rules/plain-forge.md

@@ -0,0 +1,10 @@
+---
+description: Routes .plain work to the load-plain-reference skill, which loads the ***plain authoring rules
+paths:
+  - "**/*.plain"
+---
+
+# ***plain authoring rules
+
+- Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to.
+- It loads only the ***plain authoring rules that apply to the task; they ship inside that skill under `rules/`.

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

@@ -8,7 +8,7 @@ description: >-
 
 # Add Acceptance Test
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 

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

@@ -8,7 +8,7 @@ description: >-
 
 # Add Concept
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 

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

@@ -13,7 +13,7 @@ description: >-
 
 # Add Feature
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 `add-feature` is the continuous-loop counterpart of `forge-plain`. Where `forge-plain` bootstraps an entire project from scratch, `add-feature` adds a single feature to an **existing** set of `.plain` specs. It begins with a short intent phase, then runs the authoring loop scoped to one feature.
 

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

@@ -13,7 +13,7 @@ description: >-
 
 # Add Functional Spec
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 

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

@@ -12,7 +12,7 @@ description: >-
 
 # Add Functional Specs
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## When to Use
 

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

@@ -10,7 +10,7 @@ description: >-
 
 # Add Implementation Requirement
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 

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

@@ -9,7 +9,7 @@ description: >-
 
 # Add Resource
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 Linked resources are external files referenced from within a `.plain` spec using markdown link syntax. The file contents are passed to the renderer alongside the spec, providing additional context for code generation.
 

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

@@ -8,7 +8,7 @@ description: >-
 
 # Add Template
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 Templates use Liquid syntax (`{% include %}`) to reuse the same spec content across multiple `.plain` files. Each inclusion can pass different parameters, producing tailored output from a single source. This is distinct from `import` and `requires` — templates are about textual reuse with parameterization, not module dependencies.
 

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

@@ -9,7 +9,7 @@ description: >-
 
 # Add Test Requirement
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 

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

@@ -9,7 +9,7 @@ description: >-
 
 # Analyze Two Functional Specs
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Input
 

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

@@ -9,7 +9,7 @@ description: >-
 
 # Analyze Functional Specs
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Input
 

package/forge/skills/analyze-if-func-spec-too-complex/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 
 # Analyze If Functional Spec Is Too Complex
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Why This Matters
 

package/forge/skills/break-down-func-spec/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 
 # Break Down Functional Spec
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## When to Use
 

package/forge/skills/check-plain-env/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 
 # Check Plain Env
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 This skill answers one question: **does the host machine have everything the ***plain project needs to render and test?** It reads the project, derives the requirement list, probes the machine, and returns a report. It never installs anything itself — that decision belongs to the user.
 

package/forge/skills/consolidate-concepts/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Consolidate Concepts
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## When to Use
 

package/forge/skills/create-import-module/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Create Import Module
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## What an Import Module Is
 

package/forge/skills/create-requires-module/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Create Requires Module
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## What Requires Does
 

package/forge/skills/debug-specs/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Debug Specs
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## When to Use
 

package/forge/skills/forge-plain/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 
 # Forge Plain
 
-Always invoke the `load-plain-reference` skill first to load the `***plain` syntax rules — but only if it hasn't been loaded yet this session.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Role
 

package/forge/skills/init-plain-project/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 
 # Init Plain Project
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Scope
 

package/forge/skills/load-plain-reference/SKILL.md

@@ -9,8 +9,9 @@ description: >-
 
 # Load the ***plain reference
 
-Load only the rules and references required for the current task. Files under `../../rules/` are
-the source of truth for `.plain` syntax and authoring constraints. Do not restate or override them.
+Load only the rules and references required for the current task. Files under `rules/`, next to
+this `SKILL.md`, are the source of truth for `.plain` syntax and authoring constraints. Do not
+restate or override them.
 
 **First, confirm the rules about to be loaded are current.** On the first invocation of this skill in
 a session, invoke `check-forge-version` before loading any rule file. A stale plain-forge ships stale
@@ -26,10 +27,7 @@ Skip the check on later invocations in the same session, and skip it when the ne
 
 ## 1. Account for rules already loaded
 
-- In Claude Code, applicable `.claude/rules/*.md` files are loaded natively. Do not read those rule
-  files again.
-- In another agent, do not reread a rule whose full content is already present in the current
-  context.
+- Do not reread a rule whose full content is already present in the current context.
 - Otherwise, read the applicable files from the routing table below before inspecting or changing
   `.plain` content.
 
@@ -39,19 +37,19 @@ All paths are relative to this `SKILL.md`.
 
 | Task or content | Rule files |
 |---|---|
-| New module, file skeleton, section placement, or comments | `../../rules/module-structure.md` |
-| Moving facts between sections (see `resolve-section-ownership`) | `../../rules/module-structure.md`, plus the rule file of each section involved |
-| Definitions or concept usage | `../../rules/definitions.md` |
-| Functional specs or acceptance tests | `../../rules/func-specs.md` |
-| Implementation requirements or unit tests | `../../rules/impl-reqs.md` |
-| Test requirements or conformance tests | `../../rules/test-reqs.md` |
-| `import` modules | `../../rules/import-modules.md` |
-| `requires` modules | `../../rules/requires-modules.md` |
-| `required_concepts` | `../../rules/required-concepts.md` |
-| `exported_concepts` | `../../rules/exported-concepts.md` |
-| Linked files or `resources/` | `../../rules/linked-resources.md` |
-| Any `.plain` text or example | `../../rules/bullet-continuation.md`, `../../rules/concise-specs.md` |
-| Drafting or trimming spec wording, or reviewing a spec for verbosity | `../../rules/concise-specs-examples.md` |
+| New module, file skeleton, section placement, or comments | `rules/module-structure.md` |
+| Moving facts between sections (see `resolve-section-ownership`) | `rules/module-structure.md`, plus the rule file of each section involved |
+| Definitions or concept usage | `rules/definitions.md` |
+| Functional specs or acceptance tests | `rules/func-specs.md` |
+| Implementation requirements or unit tests | `rules/impl-reqs.md` |
+| Test requirements or conformance tests | `rules/test-reqs.md` |
+| `import` modules | `rules/import-modules.md` |
+| `requires` modules | `rules/requires-modules.md` |
+| `required_concepts` | `rules/required-concepts.md` |
+| `exported_concepts` | `rules/exported-concepts.md` |
+| Linked files or `resources/` | `rules/linked-resources.md` |
+| Any `.plain` text or example | `rules/bullet-continuation.md`, `rules/concise-specs.md` |
+| Drafting or trimming spec wording, or reviewing a spec for verbosity | `rules/concise-specs-examples.md` |
 
 For a whole-file review or a task spanning several sections, load the union of the applicable rule
 files. Do not load every rule by default.
@@ -60,16 +58,16 @@ files. Do not load every rule by default.
 
 For an integration spec, always read:
 
-- `../../rules/integrations.md`
+- `rules/integrations.md`
 
 Then read the rule matching the integration shape:
 
-- Embedded integration: `../../rules/integration-embedded.md`
-- Standalone integration: `../../rules/integration-standalone.md`
-- Embedded integration test scripts: `../../rules/integration-embedded-testing.md`
+- Embedded integration: `rules/integration-embedded.md`
+- Standalone integration: `rules/integration-standalone.md`
+- Embedded integration test scripts: `rules/integration-embedded-testing.md`
 
 When drafting or trimming the wording of an integration spec, also read
-`../../rules/concise-specs-integration-examples.md`.
+`rules/concise-specs-integration-examples.md`.
 
 Do not load integration rules for ordinary non-integration specs.
 

package/forge/{rules → skills/load-plain-reference/rules}/integration-embedded-testing.md

@@ -286,4 +286,4 @@ Use them as a template when adding a new embedded integration in Java / Maven
 4. Wire them into the module's `config.yaml` via the `unittests-script`, `conformance-tests-script`, and `prepare-environment-script` keys. Use `init-config-file` to assemble the canonical form
 5. Smoke-test by running each script manually with the renderer's output folder as `$1` (and the conformance-tests folder as `$2` for the conformance runner). Confirm exit codes match what the renderer expects
 
-For non-Java languages, the plain-forge skills [`implement-prepare-environment-script`](../skills/implement-prepare-environment-script/SKILL.md), [`implement-unit-testing-script`](../skills/implement-unit-testing-script/SKILL.md), and [`implement-conformance-testing-script`](../skills/implement-conformance-testing-script/SKILL.md) adapt the contract above to Python, Node.js, Go, Rust, Flutter, and others. Always route script creation through these skills so the cross-cutting rules above are applied uniformly.
+For non-Java languages, the plain-forge skills [`implement-prepare-environment-script`](../../implement-prepare-environment-script/SKILL.md), [`implement-unit-testing-script`](../../implement-unit-testing-script/SKILL.md), and [`implement-conformance-testing-script`](../../implement-conformance-testing-script/SKILL.md) adapt the contract above to Python, Node.js, Go, Rust, Flutter, and others. Always route script creation through these skills so the cross-cutting rules above are applied uniformly.

package/forge/skills/plain-healthcheck/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 
 # Plain Healthcheck
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet. Step 3b checks every module against those rules, and they are needed to fix what `plain-parser` reports in Step 3a.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation. Step 3b checks every module against those rules, and they are needed to fix what `plain-parser` reports in Step 3a.
 
 ## When to run
 

package/forge/skills/refactor-module/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Refactor Module
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## When to Use
 

package/forge/skills/resolve-section-ownership/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 
 # Resolve Section Ownership
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 This is the ownership counterpart to `break-down-func-spec`. That skill splits one functional spec into several because it is **too large**; this one moves facts between sections because they are in the **wrong place**. The two are unrelated: a correctly placed spec can be too large, and a one-line bullet can be misplaced.
 

package/forge/skills/resolve-spec-conflict/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Resolve Spec Conflict
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## When This Applies
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.23",
+  "version": "1.0.24-next.2f8299c",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {