plain-forge 1.0.15 → 1.0.17

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/examples/integration-embedded-testing/run_conformance_tests_java.sh

@@ -21,7 +21,18 @@ fi
 
 current_dir=$(pwd)
 
-CONFORMANCE_TESTS_FOLDER=".tmp/java_conformance"
+# Resolve the conformance tests folder to an absolute path ($2 may be relative
+# on older renderers; newer renderers pass it as an absolute path).
+case "$2" in
+  /*) CONFORMANCE_TESTS_SOURCE="$2" ;;
+  *)  CONFORMANCE_TESTS_SOURCE="$current_dir/$2" ;;
+esac
+
+# Scratch folder lives in the system temp directory so no build debris is left
+# inside the project. It is removed again when the script exits.
+CONFORMANCE_TESTS_FOLDER="/tmp/java_conformance"
+
+trap 'rm -rf "$CONFORMANCE_TESTS_FOLDER"' EXIT
 
 cd "$current_dir" 2>/dev/null
 
@@ -43,8 +54,8 @@ else
   mkdir -p $CONFORMANCE_TESTS_FOLDER
 fi
 
-printf "Copying all files and folders from $2 to $CONFORMANCE_TESTS_FOLDER...\n"
-cp -R $2/* $CONFORMANCE_TESTS_FOLDER
+printf "Copying all files and folders from $CONFORMANCE_TESTS_SOURCE to $CONFORMANCE_TESTS_FOLDER...\n"
+cp -R "$CONFORMANCE_TESTS_SOURCE"/* $CONFORMANCE_TESTS_FOLDER
 
 # Move to the subfolder
 printf "Moving to $CONFORMANCE_TESTS_FOLDER...\n"

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`