plain-forge 1.0.14 → 1.0.16

package/README.md

@@ -58,29 +58,47 @@ npx plain-forge install --agent claude --scope project
 
 **Agent options:**
 
-| `--agent` | Installs into | Use when |
+| `--agent` | Installs into (project · global) | Use when |
 |-----------|---------------|----------|
-| `claude` | `.claude/` | You use Claude Code |
-| `codex` | `.codex/` | You use the OpenAI Codex CLI |
-| `forgecode` | `.forgecode/` | You use ForgeCode |
-| `universal` | `.agents/` | You want a runtime-neutral layout that any agent reading from `.agents/` can pick up |
+| `claude` | `.claude/` · `~/.claude/` | You use Claude Code |
+| `codex` | `.agents/` · `~/.agents/` | You use the OpenAI Codex CLI |
+| `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.
 
 **Scope options:**
 
 | `--scope` | Installs into | Use when |
 |-----------|---------------|----------|
-| `project` | `./<agent-dir>/` in the current working directory | You want plain-forge in just this project |
-| `global` | `~/<agent-dir>/` in your home directory | You want plain-forge available in every project on the machine |
+| `project` | the agent's project dir in the current working directory | You want plain-forge in just this project |
+| `global` | the agent's user-level dir in your home directory | You want plain-forge available in every project on the machine |
+
+(See the per-agent table above for the exact project/global directory each agent uses — a few diverge from the plain `~/<dir>` pattern, e.g. OpenCode global is `~/.config/opencode/` and ForgeCode global is `~/forge/`.)
 
 Each install writes three subfolders under the chosen directory:
 
 ```
 <agent-dir>/
   skills/    # every plain-forge skill
-  rules/     # spec-writing rules (loaded as workspace instructions)
+  rules/     # spec-writing rules (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 `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:
+
+| 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. |
+
+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.
+
 `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.
 
 #### Updating an existing install
@@ -101,7 +119,7 @@ Installs that predate the manifest (anyone who installed before this feature exi
 npx plain-forge uninstall
 ```
 
-`uninstall` reads the install manifest (`<agent-dir>/.plain-forge/manifest.json`) and deletes **exactly** the files plain-forge wrote, then the manifest itself, then any directory left empty (including the agent directory). Your own skills and third-party content are never in the manifest, so they are never touched.
+`uninstall` reads the install manifest (`<agent-dir>/.plain-forge/manifest.json`) and deletes **exactly** the files plain-forge wrote, then the manifest itself, then removes its rules wiring (the `opencode.json` glob or the `AGENTS.md` pointer block, for the relevant agents), then any directory left empty (including the agent directory). Your own skills and third-party content are never in the manifest, so they are never touched.
 
 By default it removes **every** agent layout in the **project** scope (the current folder). Narrow it with flags:
 
@@ -111,7 +129,7 @@ npx plain-forge uninstall --agent claude --scope global
 
 | Flag | Default | Values |
 |------|---------|--------|
-| `--agent` | `*` (all agents) | `claude`, `codex`, `forgecode`, `universal`, or `*` |
+| `--agent` | `*` (all agents) | `claude`, `codex`, `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`.
@@ -191,7 +209,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/`, `.codex/`, `.forgecode/`, or `.agents/`), recording every file it wrote in `<agent-dir>/.plain-forge/manifest.json` so `update` can later refresh and prune precisely.
+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)).
 
 ## Available Skills
 

package/bin/cli.mjs

@@ -9,10 +9,22 @@ const __filename = fileURLToPath(import.meta.url);
 const pkgRoot = path.resolve(path.dirname(__filename), "..");
 const forgeDir = path.join(pkgRoot, "forge");
 
+// Agent name → the project-scope content directory plain-forge writes into.
+// 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`.
+//   - 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
+//     — see resolveBaseDir.
+// Some scopes/agents diverge from `path.join(root, dir)`; resolveBaseDir owns
+// those exceptions.
 const AGENTS = {
   claude: ".claude",
-  codex: ".codex",
-  forgecode: ".forgecode",
+  codex: ".agents",
+  forgecode: ".forge",
+  opencode: ".opencode",
   universal: ".agents",
 };
 const SCOPES = ["project", "global"];
@@ -83,7 +95,8 @@ Commands:
   uninstall   Remove a plain-forge install using its manifest
 
 Install options:
-  --agent <claude|codex|forgecode|universal>   Target agent layout
+  --agent <claude|codex|forgecode|opencode|universal>
+                                               Target agent layout
   --scope <project|global>                     Install into cwd or $HOME
   -h, --help                                   Show this help
 
@@ -92,7 +105,8 @@ Update options:
                                                confirming each one
 
 Uninstall options:
-  --agent <claude|codex|forgecode|universal|*> Which install to remove
+  --agent <claude|codex|forgecode|opencode|universal|*>
+                                               Which install to remove
                                                (default: * — every agent)
   --scope <project|global>                     Where to look (default: project)
 
@@ -292,6 +306,337 @@ function writeContent(baseDir) {
   return { counts, files };
 }
 
+// Absolute install directory for an agent in a given scope. Global scope roots
+// at $HOME, project scope at the cwd. OpenCode is the one exception: its global
+// config lives under XDG at ~/.config/opencode — it does NOT read ~/.opencode —
+// while its project layout is ./.opencode like every other agent.
+function resolveBaseDir(agent, scope) {
+  const root = scope === "global" ? os.homedir() : process.cwd();
+  if (agent === "opencode" && scope === "global") {
+    return path.join(root, ".config", "opencode");
+  }
+  if (agent === "forgecode" && scope === "global") {
+    // ForgeCode's global content dir is ~/forge, not ~/.forge.
+    return path.join(root, "forge");
+  }
+  return path.join(root, AGENTS[agent]);
+}
+
+// --- OpenCode instructions wiring -------------------------------------------
+// OpenCode does not auto-read a rules/ directory the way it does skills/; it
+// loads extra instruction files from the `instructions` glob array in
+// opencode.json. So for opencode we merge a glob pointing at our rules dir into
+// that file (creating it if needed, never disturbing the user's own keys) so
+// the ***plain rules actually apply. This is opencode-specific — every other
+// agent just gets the verbatim file copy.
+
+const OPENCODE_SCHEMA = "https://opencode.ai/config.json";
+
+// Location of opencode.json for a scope. Project config lives at the project
+// root (cwd), global config under ~/.config/opencode.
+function opencodeConfigPath(scope) {
+  if (scope === "global") {
+    return path.join(os.homedir(), ".config", "opencode", "opencode.json");
+  }
+  return path.join(process.cwd(), "opencode.json");
+}
+
+// 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.
+function opencodeRulesGlob(scope) {
+  if (scope === "global") {
+    return toPosix(
+      path.join(os.homedir(), ".config", "opencode", "rules", "*.md"),
+    );
+  }
+  return ".opencode/rules/*.md";
+}
+
+// Add our rules glob to opencode.json's `instructions`, creating or merging the
+// file. Returns a status: "created" | "merged" | "present" | "skipped".
+function mergeOpencodeInstructions(scope) {
+  const configPath = opencodeConfigPath(scope);
+  const glob = opencodeRulesGlob(scope);
+  const existed = fs.existsSync(configPath);
+
+  let config = {};
+  if (existed) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    } catch {
+      return { status: "skipped", reason: "malformed", configPath, glob };
+    }
+    if (config === null || typeof config !== "object" || Array.isArray(config)) {
+      return { status: "skipped", reason: "not-an-object", configPath, glob };
+    }
+  }
+
+  const list = Array.isArray(config.instructions) ? config.instructions : [];
+  if (list.includes(glob)) return { status: "present", configPath, glob };
+
+  // Only stamp $schema onto a file we are creating; never touch an existing one.
+  if (!existed && config.$schema === undefined) config.$schema = OPENCODE_SCHEMA;
+  config.instructions = list.concat(glob);
+
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return { status: existed ? "merged" : "created", configPath, glob };
+}
+
+// Reverse of the merge: drop our glob from opencode.json's `instructions`. If
+// that leaves a file containing only our scaffold ($schema + now-empty
+// instructions), delete it; otherwise write back the trimmed config, leaving
+// every user-authored key intact. Returns "removed" | "updated" | "absent" |
+// "skipped".
+function unmergeOpencodeInstructions(scope) {
+  const configPath = opencodeConfigPath(scope);
+  const glob = opencodeRulesGlob(scope);
+  if (!fs.existsSync(configPath)) return { status: "absent", configPath, glob };
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return { status: "skipped", reason: "malformed", configPath, glob };
+  }
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    return { status: "skipped", reason: "not-an-object", configPath, glob };
+  }
+  if (!Array.isArray(config.instructions) || !config.instructions.includes(glob)) {
+    return { status: "absent", configPath, glob };
+  }
+
+  config.instructions = config.instructions.filter((g) => g !== glob);
+
+  const onlyScaffold =
+    config.instructions.length === 0 &&
+    Object.keys(config).every((k) => k === "$schema" || k === "instructions");
+  if (onlyScaffold) {
+    fs.rmSync(configPath, { force: true });
+    return { status: "removed", configPath, glob };
+  }
+
+  if (config.instructions.length === 0) delete config.instructions;
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return { status: "updated", configPath, glob };
+}
+
+// Human-readable line for a merge result, printed under the install/update
+// summary. A skip is a warning the user should see (their config is untouched).
+function reportOpencodeMerge(result) {
+  switch (result.status) {
+    case "created":
+      console.log(`  opencode.json: created, wired rules via "${result.glob}"`);
+      break;
+    case "merged":
+      console.log(`  opencode.json: added rules glob "${result.glob}"`);
+      break;
+    case "present":
+      console.log(`  opencode.json: rules glob already present`);
+      break;
+    case "skipped":
+      console.log(
+        `  opencode.json: left untouched (${result.reason}) — add "${result.glob}" to its "instructions" manually`,
+      );
+      break;
+  }
+}
+
+// Human-readable line for an unmerge result during uninstall.
+function reportOpencodeUnmerge(result) {
+  switch (result.status) {
+    case "removed":
+      console.log(`  opencode.json: removed (was only plain-forge's rules wiring)`);
+      break;
+    case "updated":
+      console.log(`  opencode.json: removed rules glob, kept your other config`);
+      break;
+    case "skipped":
+      console.log(
+        `  opencode.json: left untouched (${result.reason}) — remove "${result.glob}" from "instructions" manually`,
+      );
+      break;
+  }
+}
+
+// --- 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,
+// 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.
+
+const AGENTS_MD_BEGIN = "<!-- BEGIN plain-forge (managed) -->";
+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";
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Where the tool reads AGENTS.md from for a scope. Project scope is the repo
+// 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
+}
+
+// Glob the pointer block references — the installed rules dir. Project scope is
+// written relative to the repo root; global scope must be absolute (these files
+// are consulted from arbitrary working directories).
+function agentsMdRulesGlob(agent, scope) {
+  const rulesDir = path.join(resolveBaseDir(agent, scope), "rules");
+  if (scope === "global") return toPosix(path.join(rulesDir, "*.md"));
+  return toPosix(path.join(path.relative(process.cwd(), rulesDir), "*.md"));
+}
+
+function agentsMdBlock(glob) {
+  return [
+    AGENTS_MD_BEGIN,
+    "## ***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.",
+    AGENTS_MD_END,
+  ].join("\n");
+}
+
+// Add or refresh the managed pointer block in AGENTS.md, creating the file if
+// needed and preserving all user content. Returns a status:
+// "created" | "merged" | "refreshed" | "present".
+function mergeAgentsMd(agent, scope) {
+  const filePath = agentsMdPath(agent, scope);
+  const glob = agentsMdRulesGlob(agent, scope);
+  const block = agentsMdBlock(glob);
+  const existed = fs.existsSync(filePath);
+  let content = existed ? fs.readFileSync(filePath, "utf8") : "";
+
+  const hadBlock = content.includes(AGENTS_MD_BEGIN);
+  if (hadBlock) {
+    const re = new RegExp(
+      `${escapeRe(AGENTS_MD_BEGIN)}[\\s\\S]*?${escapeRe(AGENTS_MD_END)}`,
+    );
+    const replaced = content.replace(re, block);
+    if (replaced === content) return { status: "present", filePath, glob };
+    content = replaced;
+  } else {
+    if (content && !content.endsWith("\n")) content += "\n";
+    if (content) content += "\n";
+    content += block + "\n";
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  const status = !existed ? "created" : hadBlock ? "refreshed" : "merged";
+  return { status, filePath, glob };
+}
+
+// Remove the managed pointer block. Deletes the file if nothing but the block
+// (and whitespace) remains; otherwise writes back the user's content.
+// Returns "removed" | "updated" | "absent".
+function unmergeAgentsMd(agent, scope) {
+  const filePath = agentsMdPath(agent, scope);
+  if (!fs.existsSync(filePath)) return { status: "absent", filePath };
+  let content = fs.readFileSync(filePath, "utf8");
+  if (!content.includes(AGENTS_MD_BEGIN)) return { status: "absent", filePath };
+
+  const re = new RegExp(
+    `\\n*${escapeRe(AGENTS_MD_BEGIN)}[\\s\\S]*?${escapeRe(AGENTS_MD_END)}\\n*`,
+  );
+  content = content.replace(re, "\n");
+
+  if (content.trim() === "") {
+    fs.rmSync(filePath, { force: true });
+    return { status: "removed", filePath };
+  }
+  content = content.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+  if (!content.endsWith("\n")) content += "\n";
+  fs.writeFileSync(filePath, content);
+  return { status: "updated", filePath };
+}
+
+function reportAgentsMdMerge(result) {
+  const rel = result.filePath;
+  switch (result.status) {
+    case "created":
+      console.log(`  AGENTS.md: created at ${rel}, wired rules via "${result.glob}"`);
+      break;
+    case "merged":
+      console.log(`  AGENTS.md: added rules block to ${rel}`);
+      break;
+    case "refreshed":
+      console.log(`  AGENTS.md: refreshed rules block in ${rel}`);
+      break;
+    case "present":
+      console.log(`  AGENTS.md: rules block already up to date`);
+      break;
+  }
+}
+
+function reportAgentsMdUnmerge(result) {
+  switch (result.status) {
+    case "removed":
+      console.log(`  AGENTS.md: removed (was only plain-forge's rules block)`);
+      break;
+    case "updated":
+      console.log(`  AGENTS.md: removed rules block, kept your other content`);
+      break;
+  }
+}
+
+// Wire rules for an agent whose mechanism needs it, during install/update.
+// The skills/rules/docs and manifest are already on disk by the time this runs,
+// so a failure here (e.g. an unwritable opencode.json/AGENTS.md) must not fail
+// the whole install — it degrades to a warning and the install still succeeds.
+function wireRules(agent, scope) {
+  try {
+    if (agent === "opencode") {
+      reportOpencodeMerge(mergeOpencodeInstructions(scope));
+    } else if (usesAgentsMd(agent)) {
+      reportAgentsMdMerge(mergeAgentsMd(agent, scope));
+    }
+  } catch (err) {
+    warnRulesWiring("wire", agent, err);
+  }
+}
+
+// Reverse of wireRules, during uninstall. Also non-fatal: the manifest files
+// are already gone, so a failure to tidy up the rules wiring is a warning, not
+// an uninstall failure.
+function unwireRules(agent, scope) {
+  try {
+    if (agent === "opencode") {
+      reportOpencodeUnmerge(unmergeOpencodeInstructions(scope));
+    } else if (usesAgentsMd(agent)) {
+      reportAgentsMdUnmerge(unmergeAgentsMd(agent, scope));
+    }
+  } catch (err) {
+    warnRulesWiring("unwire", agent, err);
+  }
+}
+
+function warnRulesWiring(action, agent, err) {
+  const target = agent === "opencode" ? "opencode.json" : "AGENTS.md";
+  const verb = action === "wire" ? "wire up" : "clean up";
+  const msg = err instanceof Error ? err.message : String(err);
+  console.warn(
+    `  warning: could not ${verb} the ${agent} rules in ${target} (${msg}).`,
+  );
+  console.warn(
+    `  the skills and rule files were installed successfully; see the README`,
+  );
+  console.warn(`  section "How the rules get applied per agent" to finish by hand.`);
+}
+
 function manifestPathFor(baseDir) {
   return path.join(baseDir, MANIFEST_REL);
 }
@@ -306,12 +651,16 @@ function readManifest(baseDir) {
   return null;
 }
 
-function writeManifest(baseDir, files) {
+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.
   const manifest = {
     name: "plain-forge",
     version: readPkgVersion(),
+    ...(agent ? { agent } : {}),
     files: files.map(toPosix).sort(),
   };
   fs.writeFileSync(target, JSON.stringify(manifest, null, 2) + "\n");
@@ -361,15 +710,22 @@ function deleteForgeFile(baseDir, rel) {
 // the flagship skill.
 function detectInstalls() {
   const installs = [];
+  const seen = new Set();
   for (const scope of SCOPES) {
-    const root = scope === "global" ? os.homedir() : process.cwd();
-    for (const [agent, dirName] of Object.entries(AGENTS)) {
-      const baseDir = path.join(root, dirName);
+    for (const agent of Object.keys(AGENTS)) {
+      const baseDir = resolveBaseDir(agent, scope);
+      // Some agents share a directory (codex and universal both use .agents).
+      // Only inspect each physical dir once so a single install isn't detected
+      // — and later updated/pruned — twice.
+      if (seen.has(baseDir)) continue;
+      seen.add(baseDir);
       if (!fs.existsSync(baseDir)) continue;
       const manifest = readManifest(baseDir);
       const isLegacy = !manifest && hasForgeSignature(baseDir);
       if (manifest || isLegacy) {
-        installs.push({ agent, scope, baseDir, manifest });
+        // Prefer the agent recorded at install time; fall back to the dir's
+        // first-mapped agent for legacy/manifest-less installs.
+        installs.push({ agent: manifest?.agent ?? agent, scope, baseDir, manifest });
       }
     }
   }
@@ -395,8 +751,7 @@ async function cmdInstall(args) {
     process.exit(2);
   }
 
-  const root = scope === "global" ? os.homedir() : process.cwd();
-  const baseDir = path.join(root, AGENTS[agent]);
+  const baseDir = resolveBaseDir(agent, scope);
 
   const alreadyInstalled =
     readManifest(baseDir) !== null || hasForgeSignature(baseDir);
@@ -407,12 +762,13 @@ async function cmdInstall(args) {
   }
 
   const { counts, files } = writeContent(baseDir);
-  writeManifest(baseDir, files);
+  writeManifest(baseDir, files, agent);
 
   console.log(`installed into ${baseDir}`);
   console.log(`  skills: ${counts.skills}`);
   console.log(`  rules:  ${counts.rules}`);
   console.log(`  docs:   ${counts.docs}`);
+  wireRules(agent, scope);
   console.log();
   printNextSteps(agent);
 }
@@ -453,6 +809,10 @@ async function cmdUpdate(args) {
     console.log(
       `  skills: ${counts.skills}  rules: ${counts.rules}  docs: ${counts.docs}`,
     );
+    // Re-assert rules wiring (opencode.json / AGENTS.md) — installs from before
+    // this feature lack it; the merge is idempotent for those that already have
+    // it, and refreshes the glob if the layout changed.
+    wireRules(inst.agent, inst.scope);
 
     // Pruning only applies to manifest-tracked installs. Each deprecated file
     // is confirmed individually before removal; denied files stay on disk and
@@ -484,7 +844,7 @@ async function cmdUpdate(args) {
 
     // Manifest reflects what's actually on disk: the fresh files plus any
     // deprecated files the user chose to keep.
-    writeManifest(inst.baseDir, files.concat(kept));
+    writeManifest(inst.baseDir, files.concat(kept), inst.agent);
     console.log();
     updated++;
   }
@@ -528,7 +888,7 @@ async function cmdUninstall(args) {
   let hadError = false;
 
   for (const agent of agents) {
-    const baseDir = path.join(root, AGENTS[agent]);
+    const baseDir = resolveBaseDir(agent, scope);
     if (!fs.existsSync(baseDir)) continue;
 
     const manifest = readManifest(baseDir);
@@ -560,19 +920,31 @@ async function cmdUninstall(args) {
       if (deleteForgeFile(baseDir, rel)) deleted++;
       else failed++;
     }
-    // Finally remove the manifest itself, then prune the now-empty .plain-forge
-    // directory and the agent directory if nothing else remains in it.
+    // Remove the manifest itself.
     fs.rmSync(manifestPathFor(baseDir), { force: true });
-    removeEmptyDirsUpward(
-      path.join(baseDir, path.dirname(MANIFEST_REL)),
-      baseDir,
-    );
-    removeEmptyDirsUpward(baseDir, root);
 
     console.log(`uninstalled ${agent} (${scope}) from ${baseDir}`);
     console.log(
       `  removed ${deleted} file(s)${failed ? `, ${failed} could not be removed` : ""} + manifest`,
     );
+
+    // 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
+    // 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.
+    unwireRules(manifest.agent ?? agent, scope);
+
+    // Prune the now-empty .plain-forge directory and the agent directory if
+    // nothing else remains in it.
+    removeEmptyDirsUpward(
+      path.join(baseDir, path.dirname(MANIFEST_REL)),
+      baseDir,
+    );
+    // Stop at the agent dir's parent so only the agent dir itself is pruned
+    // (e.g. for opencode-global we remove ~/.config/opencode, never ~/.config).
+    removeEmptyDirsUpward(baseDir, path.dirname(baseDir));
     console.log();
     removed++;
   }
@@ -626,6 +998,8 @@ function agentLabel(agent) {
       return "Codex";
     case "forgecode":
       return "ForgeCode";
+    case "opencode":
+      return "OpenCode";
     case "universal":
       return "AI coding agent";
     default:
@@ -698,6 +1072,16 @@ export {
   isUpToDate,
   copyTreeTracked,
   writeContent,
+  resolveBaseDir,
+  opencodeConfigPath,
+  opencodeRulesGlob,
+  mergeOpencodeInstructions,
+  unmergeOpencodeInstructions,
+  usesAgentsMd,
+  agentsMdPath,
+  agentsMdRulesGlob,
+  mergeAgentsMd,
+  unmergeAgentsMd,
   manifestPathFor,
   readManifest,
   writeManifest,

package/forge/rules/definitions.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for writing ***definitions*** sections in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for writing `***definitions***`

package/forge/rules/exported-concepts.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for using exported_concepts in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for `exported_concepts`

package/forge/rules/func-specs.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for writing ***functional specs*** and ***acceptance tests*** in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for writing `***functional specs***`
@@ -74,6 +75,5 @@ When writing or editing a `***functional specs***` section in a `.plain` file, a
   - 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.
+  - Sending a :Message: to a :Conversation: with three participants should make the message visible to all three.
 ```

package/forge/rules/impl-reqs.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for writing ***implementation reqs*** sections in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for writing `***implementation reqs***`

package/forge/rules/import-modules.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for creating and using import modules in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for import modules

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

@@ -1,6 +1,7 @@
 ---
 description: Rules for authoring the three test scripts that an embedded ***plain integration ships
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for embedded-integration test scripts

package/forge/rules/integration-embedded.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for authoring ***plain specs for REST API integrations embedded into an existing host codebase
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for **embedded** integration specs

package/forge/rules/integration-standalone.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for authoring ***plain specs for REST API integrations deployed standalone
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for **standalone** integration specs

package/forge/rules/integrations.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for authoring ***plain specs for REST API integrations
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for writing integration specs in `***plain`

package/forge/rules/line-length.md

@@ -1,6 +1,7 @@
 ---
 description: Line-length and bullet-continuation rules for every section in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for line length in `.plain` files

package/forge/rules/linked-resources.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for linking external resources from .plain specs
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for linked resources in `.plain` files
@@ -14,8 +15,8 @@ A linked resource **must not** be any of the following:
 1. **A folder / directory.** `[integrations](src/integrations/)`, `[host project](../host_project/)` are invalid — the renderer cannot ingest a directory. Pick the single most representative file inside (a `README.md`, an exemplar source file, a manifest) and link **that**.
 2. **A URL / external location.** `[Stripe docs](https://stripe.com/docs/api)`, any `http://` / `https://` / `ftp://` / `git://` / `s3://` / `gs://` target. Linked resources are local-file only. If a URL's content is essential, fetch it once, save the response to a text file under `resources/`, and link the saved file.
 3. **A binary file.** PNG, JPG, GIF, PDF, DOCX, XLSX, ZIP, MP3, MP4, compiled binaries (`.exe`, `.so`, `.class`, `.wasm`), and anything else that isn't human-readable text in its raw form. Binary content cannot be meaningfully consumed by the renderer — transcribe it into a text-based form first (a UI screenshot becomes a Markdown description, a PDF spec becomes a Markdown extract or the underlying JSON Schema / OpenAPI, an architecture diagram becomes a Mermaid block).
+4. **Another `.plain` file.** `[Auth Module](auth.plain)` is invalid. To reference another module, use the `require` or `import` frontmatter directives. Do not link it as a markdown resource; the `plain-dry-run` will flag this as a syntax error.
 
-If the markdown-link target ends with `/`, contains `://`, resolves to a directory, or has a binary extension, **stop** — it cannot be a linked resource. Convert it first.
 
 ## URLs and folder paths must not appear *anywhere* in `.plain` content
 - The constraint is not only about markdown links — URLs and folder paths must not appear **anywhere** in `.plain` content (concept body prose, functional-spec text, implementation reqs, test reqs)
@@ -31,15 +32,15 @@ If the markdown-link target ends with `/`, contains `://`, resolves to a directo
 ```plain
 ***definitions***
 
-- :TaskCreateRequest: is the JSON payload for creating a task, defined by
-  [resources/task_create_request.schema.json](resources/task_create_request.schema.json).
-- :TasksAPI: is the public HTTP surface for tasks, defined by
-  [resources/tasks_openapi.yaml](resources/tasks_openapi.yaml).
+- :TaskCreateRequest: is the JSON payload for creating a task.
+  - It is defined by [resources/task_create_request.schema.json](resources/task_create_request.schema.json).
+- :TasksAPI: is the public HTTP surface for tasks.
+  - It is defined by [resources/tasks_openapi.yaml](resources/tasks_openapi.yaml).
 
 ***functional specs***
 
-- :User: should be able to add :Task: by POSTing :TaskCreateRequest: to the
-  `POST /tasks` endpoint of :TasksAPI:. The endpoint responds per :TasksAPI:.
+- :User: should be able to add :Task: by POSTing :TaskCreateRequest: to the `POST /tasks` endpoint of :TasksAPI:.
+  - The endpoint responds per :TasksAPI:.
 ```
 
 ## Each linked resource is referenced from exactly one place
@@ -50,8 +51,8 @@ If the markdown-link target ends with `/`, contains `://`, resolves to a directo
 ```plain
 ***definitions***
 
-- :TaskModalSpec: is the user-interface contract for the task modal,
-  fully described in [task_modal_specification.yaml](task_modal_specification.yaml).
+- :TaskModalSpec: is the user-interface contract for the task modal.
+  - It is fully described in [task_modal_specification.yaml](task_modal_specification.yaml).
 
 ***functional specs***
 

package/forge/rules/required-concepts.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for using required_concepts in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for `required_concepts`

package/forge/rules/requires-modules.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for creating and using requires modules in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for requires modules

package/forge/rules/test-reqs.md

@@ -1,6 +1,7 @@
 ---
 description: Rules for writing ***test reqs*** sections in .plain files
-globs: "**/*.plain"
+paths:
+  - "**/*.plain"
 ---
 
 # Rules for writing `***test reqs***`

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

@@ -26,17 +26,16 @@ Use standard markdown link syntax inside any spec section:
 
 ```plain
 ***definitions***
-- :AuthData: is the authentication data structure. Its format is defined
-  in the [auth schema](resources/auth_schema.json).
+- :AuthData: is the authentication data structure.
+  - Its format is defined in the [auth schema](resources/auth_schema.json).
 
 ***implementation reqs***
-- When transforming :BackupData:, use the JOLT transform defined in
-  [backup_transform.jolt](resources/backup_transform.jolt).
+- When transforming :BackupData:, use the JOLT transform.
+  - The transform is defined in [backup_transform.jolt](resources/backup_transform.jolt).
 
 ***functional specs***
 
-- The system should expose an API conforming to the
-  [API specification](resources/api_spec.yaml).
+- The system should expose an API conforming to the [API specification](resources/api_spec.yaml).
 ```
 
 ## Path Rules

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

@@ -69,10 +69,9 @@ Too complex:
 
 Acceptable (separate the modes):
 - The system should process standard :Order: by validating and storing it.
-- The system should process express :Order: by queuing it for immediate dispatch
-  without validation.
-- The system should process bulk :Order: by splitting it into sub-orders of 100
-  items each and processing them individually.
+- The system should process express :Order: by queuing it for immediate dispatch without validation.
+- The system should process bulk :Order: by splitting it into sub-orders of 100 items each.
+  - Each sub-order is processed individually.
 ```
 
 ### 4. Cross-Cutting Concerns
@@ -88,8 +87,7 @@ Too complex:
 Acceptable (separate concerns):
 - The system should fetch :Resource: items from the external API.
 - The system should paginate when fetching :Resource: items from the external API.
-- The system should retry fetching :Resource: on transient errors using
-  exponential backoff.
+- The system should retry fetching :Resource: on transient errors using exponential backoff.
 ```
 
 ### 5. UI Complexity

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

@@ -111,10 +111,10 @@ If the spec describes different modes or branches, give each its own spec.
 **After:**
 ```plain
 - The system should generate a standard :MealPlan: using round-robin :Recipe: assignment.
-- The system should generate a restrictive :MealPlan: by filtering out excluded
-  :Ingredient: items before applying round-robin assignment.
-- The system should allow :User: to manually assign :Recipe: items to individual
-  :Slot: items for a custom :MealPlan:.
+- The system should generate a restrictive :MealPlan:.
+  - Excluded :Ingredient: items are filtered out first.
+  - Round-robin :Recipe: assignment is then applied.
+- The system should allow :User: to manually assign :Recipe: items to :Slot: items for a custom :MealPlan:.
 ```
 
 ### Strategy 5: Build UI Incrementally

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

@@ -184,8 +184,8 @@ The frontmatter is enclosed between `---` markers and supports:
 Specifications can reference external files using markdown link syntax. The linked resource is passed along with the spec to the renderer. File paths are resolved relative to the `.plain` file location. Only files in the same folder (and subfolders) are supported.
 
 ```plain
-- :User: should be able to add :Task:. The details of the user interface
-  are provided in the file [task_modal_specification.yaml](task_modal_specification.yaml).
+- :User: should be able to add :Task:.
+  - The user-interface details are in [task_modal_specification.yaml](task_modal_specification.yaml).
 ```
 
 #### Hard constraint: a linked resource is always a single, text-based file on disk
@@ -220,15 +220,15 @@ The accompanying spec line should describe the *role* of the artifact ("the requ
 ```plain
 ***definitions***
 
-- :TaskCreateRequest: is the JSON payload for creating a task, defined by
-  [resources/task_create_request.schema.json](resources/task_create_request.schema.json).
-- :TasksAPI: is the public HTTP surface for tasks, defined by
-  [resources/tasks_openapi.yaml](resources/tasks_openapi.yaml).
+- :TaskCreateRequest: is the JSON payload for creating a task.
+  - It is defined by [resources/task_create_request.schema.json](resources/task_create_request.schema.json).
+- :TasksAPI: is the public HTTP surface for tasks.
+  - It is defined by [resources/tasks_openapi.yaml](resources/tasks_openapi.yaml).
 
 ***functional specs***
 
-- :User: should be able to add :Task: by POSTing :TaskCreateRequest: to the
-  `POST /tasks` endpoint of :TasksAPI:. The endpoint responds per :TasksAPI:.
+- :User: should be able to add :Task: by POSTing :TaskCreateRequest: to the `POST /tasks` endpoint of :TasksAPI:.
+  - The endpoint responds per :TasksAPI:.
 ```
 
 **Each linked resource must be referenced from exactly one place** in the project — a single functional spec, implementation requirement, or `***definitions***` entry. Linking the same file from two functional specs (or from a functional spec *and* a requirement, etc.) creates two independent sources of truth: any later edit to one site silently diverges from the other, and the renderer has no way to know which one is canonical.
@@ -243,8 +243,8 @@ For example, instead of linking `task_modal_specification.yaml` from two differe
 ```plain
 ***definitions***
 
-- :TaskModalSpec: is the user-interface contract for the task modal,
-  fully described in [task_modal_specification.yaml](task_modal_specification.yaml).
+- :TaskModalSpec: is the user-interface contract for the task modal.
+  - It is fully described in [task_modal_specification.yaml](task_modal_specification.yaml).
 
 ***functional specs***
 

package/package.json

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