create-agdf 0.6.8 → 0.6.9

package/README.md

@@ -51,8 +51,8 @@ If no language is provided, `create-agdf` derives the preference from the local
 - `codex-repo` writes a repository-local Codex marketplace under `.agents/plugins/` and a local AGDF plugin copy under `plugins/agdf/`
 - `claude` installs the AGDF plugin globally for Claude Code
 - `copilot` writes `AGENTS.md`, Copilot custom instructions under `.github/`, visible repository skills under `.github/skills/`, and AGDF control templates under `.agdf/control/`
-- `opencode` installs the AGDF npm plugin as a user-wide OpenCode hook
-- `opencode-status` reports OpenCode global config, package loadability, session signals and repository surface presence
+- `opencode` installs the AGDF npm plugin and nine native skills as a user-wide OpenCode surface
+- `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, session signals and repository surface presence
 - `opencode-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
 - `both` writes the Codex repository-local marketplace plus the Copilot-facing repository files
 - `config` writes or updates only `.agdf/control/config.json` for an already installed plugin or an existing repository
@@ -75,7 +75,7 @@ Then verify the visible installation state:
 npx --yes @agdf/cli@latest opencode-status --json
 ```
 
-The status command reports global configuration, whether `create-agdf` is loadable from the OpenCode config directory, whether the current process exposes AGDF session signals, and whether the current repository has `.opencode/AGDF.md` plus the `agdf-gate-check` surface. It does not infer an active OpenCode session from config alone.
+The status command reports global configuration, package loadability, global native-skill completeness, session signals and whether the current repository has `.opencode/AGDF.md` plus the `agdf-gate-check` surface. It does not infer an active OpenCode session from config alone.
 In JSON schema version 1, `repository_surface.gate_check_agent` remains a deprecated compatibility alias for the native `gate_check_skill` path so existing status consumers keep working during the agent-to-skill migration.
 
 Use the `opencode-repo` target when AGDF should be available to OpenCode from repository files:
@@ -84,10 +84,10 @@ Use the `opencode-repo` target when AGDF should be available to OpenCode from re
 npm create agdf@latest -- opencode-repo
 ```
 
-OpenCode loads the AGDF npm plugin from global OpenCode config or repository `opencode.json`, AGENTS-style rules from `.opencode/AGDF.md`, explicit `edit`/`bash`/`skill` permissions and the `agdf-` prefixed native skills under `.opencode/skills/`. AGDF for OpenCode has two layers: a global npm plugin hook installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by the `opencode-repo` target.
+OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `edit`/`bash`/`skill` permissions and canonical `agdf-` project skills under `.opencode/skills/`. Global adapters use the collision-safe `agdf-global-` prefix. AGDF for OpenCode has a global discoverability layer installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by `opencode-repo`.
 Those generated skills load on demand through OpenCode's native `skill` tool. Use `agdf-gate-check` first for new build/change intent or unclear approval.
 If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment.
-Using OpenCode's plugin installer or global config for `create-agdf` can add the npm plugin hook, but AGDF still needs the repository instructions and native skills. The `opencode-repo` target writes the repository files together.
+The global layer makes the nine native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has `.opencode/AGDF.md`, `.opencode/skills/agdf-gate-check/SKILL.md` and `.agdf/control/`. Use `opencode-repo` to write that repository surface.
 
 ## Control scaffold
 

package/bin/create-agdf.js

@@ -80,6 +80,10 @@ const gateProgressOrder = [
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
 const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.skillPrefix}${skill.slug}`);
+const globalOpenCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`);
+const globalOpenCodeSkillOwnershipMarker = "<!-- AGDF-GLOBAL-SKILL: ";
+const globalOpenCodeInstructionsOwnershipMarker = "<!-- AGDF-GLOBAL-INSTRUCTIONS -->";
+const globalOpenCodeRuntimeContractOwnershipMarker = "<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->";
 const codexPluginFiles = [
   join(".agents", "plugins", "marketplace.json"),
   join("plugins", "agdf", ".codex-plugin", "plugin.json"),
@@ -476,6 +480,7 @@ function defaultOpenCodeConfigDir() {
 }
 
 function installOpenCodeGlobalPlugin(configDir) {
+  assertGlobalOpenCodeSurfaceWritable(configDir);
   const configPath = join(configDir, "opencode.json");
   let config = {};
 
@@ -503,6 +508,24 @@ function installOpenCodeGlobalPlugin(configDir) {
     plugin: plugins,
   };
 
+  if (nextConfig.instructions !== undefined && !Array.isArray(nextConfig.instructions)) {
+    throw new Error(`Refusing to update OpenCode config with non-array instructions field: ${configPath}`);
+  }
+  nextConfig.instructions = [...(nextConfig.instructions ?? [])];
+  if (!nextConfig.instructions.includes("AGDF.md")) nextConfig.instructions.push("AGDF.md");
+
+  if (nextConfig.permission === undefined) {
+    nextConfig.permission = { skill: { "agdf-*": "allow" } };
+  } else if (nextConfig.permission && typeof nextConfig.permission === "object" && !Array.isArray(nextConfig.permission)) {
+    nextConfig.permission = { ...nextConfig.permission };
+    if (nextConfig.permission.skill === undefined) {
+      nextConfig.permission.skill = { "agdf-*": "allow" };
+    } else if (nextConfig.permission.skill && typeof nextConfig.permission.skill === "object" && !Array.isArray(nextConfig.permission.skill)) {
+      nextConfig.permission.skill = { ...nextConfig.permission.skill };
+      if (nextConfig.permission.skill["agdf-*"] === undefined) nextConfig.permission.skill["agdf-*"] = "allow";
+    }
+  }
+
   mkdirSync(configDir, { recursive: true });
   try {
     execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--prefix", configDir, packageRoot], { stdio: "pipe" });
@@ -517,6 +540,110 @@ function installOpenCodeGlobalPlugin(configDir) {
   };
 }
 
+function globalOpenCodeConfigPaths(configDir) {
+  return {
+    instructions: join(configDir, pluginDefinition.opencode.instructionsFileName),
+    runtimeContract: join(configDir, pluginDefinition.opencode.runtimeContractFileName),
+    skills: join(configDir, "skills"),
+  };
+}
+
+function globalOpenCodeOwnershipMarkerIsValid(content, marker, placement) {
+  const lines = content.split(/\r?\n/);
+  if (placement === "first-line") return lines[0] === marker;
+  const frontmatterEnd = lines.findIndex((line, index) => index > 0 && line === "---");
+  return frontmatterEnd >= 0 && lines[frontmatterEnd + 1] === marker;
+}
+
+function assertGlobalOpenCodeFileWritable(path, marker, placement) {
+  if (!existsSync(path)) return;
+  const existing = readFileSync(path, "utf8");
+  if (!globalOpenCodeOwnershipMarkerIsValid(existing, marker, placement)) {
+    throw new Error(`Refusing to overwrite unowned global OpenCode file: ${path}`);
+  }
+}
+
+function assertGlobalOpenCodeSurfaceWritable(configDir) {
+  const paths = globalOpenCodeConfigPaths(configDir);
+  assertGlobalOpenCodeFileWritable(paths.instructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
+  assertGlobalOpenCodeFileWritable(paths.runtimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+  for (const skillName of globalOpenCodeSkillNames) {
+    assertGlobalOpenCodeFileWritable(
+      join(paths.skills, skillName, "SKILL.md"),
+      `${globalOpenCodeSkillOwnershipMarker}${skillName} -->`,
+      "after-frontmatter",
+    );
+  }
+}
+
+function writeOwnedGlobalOpenCodeFile(path, content, marker, placement) {
+  if (existsSync(path)) {
+    assertGlobalOpenCodeFileWritable(path, marker, placement);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}
+
+function globalOpenCodeBoundary() {
+  return [
+    "## Global OpenCode Surface Boundary",
+    "",
+    "This skill is globally discoverable, but global plugin or skill presence is not repository governance activation.",
+    "Before applying AGDF gates, later artefacts or implementation guidance, inspect the current repository for `.opencode/AGDF.md`, `.opencode/skills/agdf-gate-check/SKILL.md` and `.agdf/control/`.",
+    "If the repository surface is absent, stop and direct the user to `npx --yes @agdf/cli@latest opencode-repo` in this repository.",
+    "When the repository surface exists, its local instructions, native skills and `.agdf/control/` state are authoritative.",
+    "",
+  ].join("\n");
+}
+
+function toGlobalOpenCodeContent(content) {
+  let next = content;
+  for (const skill of pluginDefinition.skillSet) {
+    const localName = `${pluginDefinition.opencode.skillPrefix}${skill.slug}`;
+    const globalName = `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`;
+    next = next.replaceAll(localName, globalName);
+  }
+  return next;
+}
+
+function installOpenCodeGlobalSurface(configDir) {
+  const paths = globalOpenCodeConfigPaths(configDir);
+  const generatedOpenCodeRoot = join(generatedRoot, ".opencode");
+  const generatedInstructions = readFileSync(join(generatedOpenCodeRoot, pluginDefinition.opencode.instructionsFileName), "utf8");
+  const generatedRuntimeContract = readFileSync(join(generatedOpenCodeRoot, pluginDefinition.opencode.runtimeContractFileName), "utf8");
+  const globalInstructions = [
+    globalOpenCodeInstructionsOwnershipMarker,
+    "# AGDF Global OpenCode instructions",
+    "",
+    "AGDF native skills are globally discoverable through OpenCode.",
+    "",
+    globalOpenCodeBoundary(),
+    "The repository-local `.opencode/AGDF.md`, `.opencode/skills/` and `.agdf/control/` files remain the source of truth for active governance.",
+    "",
+    toGlobalOpenCodeContent(generatedInstructions),
+  ].join("\n");
+  const globalRuntimeContract = `${globalOpenCodeRuntimeContractOwnershipMarker}\n${generatedRuntimeContract}`;
+
+  writeOwnedGlobalOpenCodeFile(paths.instructions, globalInstructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
+  writeOwnedGlobalOpenCodeFile(paths.runtimeContract, globalRuntimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+
+  for (let index = 0; index < openCodeSkillNames.length; index += 1) {
+    const sourceName = openCodeSkillNames[index];
+    const skillName = globalOpenCodeSkillNames[index];
+    const sourcePath = join(generatedOpenCodeRoot, "skills", sourceName, "SKILL.md");
+    const sourceContent = readFileSync(sourcePath, "utf8");
+    const marker = `${globalOpenCodeSkillOwnershipMarker}${skillName} -->`;
+    const content = toGlobalOpenCodeContent(sourceContent).replace(/^(---[\s\S]*?\n---\n)/, `$1${marker}\n\n${globalOpenCodeBoundary()}`);
+    writeOwnedGlobalOpenCodeFile(join(paths.skills, skillName, "SKILL.md"), content, marker, "after-frontmatter");
+  }
+
+  return {
+    instructions: paths.instructions,
+    runtimeContract: paths.runtimeContract,
+    skills: paths.skills,
+  };
+}
+
 function readOpenCodeConfig(configPath) {
   if (!existsSync(configPath)) return { exists: false, parseError: "", config: {} };
   try {
@@ -552,12 +679,27 @@ function resolveOpenCodePackage(configDir) {
   }
 }
 
+function evaluateGlobalOpenCodeSurface(configDir) {
+  const paths = globalOpenCodeConfigPaths(configDir);
+  const skillCount = globalOpenCodeSkillNames.filter((skillName) => existsSync(join(paths.skills, skillName, "SKILL.md"))).length;
+  return {
+    path: paths.skills,
+    instructions: paths.instructions,
+    runtime_contract: paths.runtimeContract,
+    expected_skill_count: globalOpenCodeSkillNames.length,
+    skill_count: skillCount,
+    present: existsSync(paths.skills),
+    complete: existsSync(paths.instructions) && existsSync(paths.runtimeContract) && skillCount === openCodeSkillNames.length,
+  };
+}
+
 function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir()) {
   const configPath = join(configDir, "opencode.json");
   const configState = readOpenCodeConfig(configPath);
   const plugins = Array.isArray(configState.config.plugin) ? configState.config.plugin : [];
   const globalConfigured = plugins.includes(pluginDefinition.opencode.npmPackage);
   const packageState = resolveOpenCodePackage(configDir);
+  const globalNativeSurface = evaluateGlobalOpenCodeSurface(configDir);
   const sessionSignals = {
     active: process.env.AGDF_PLUGIN_ACTIVE === "1",
     version: process.env.AGDF_PLUGIN_VERSION || "",
@@ -572,6 +714,7 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
   if (configState.parseError) findings.push(`OpenCode global config is not valid JSON: ${configState.parseError}`);
   if (!globalConfigured) findings.push(`OpenCode global config does not include ${pluginDefinition.opencode.npmPackage}.`);
   if (!packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is not loadable from the OpenCode config directory.`);
+  if (!globalNativeSurface.complete) findings.push(`Global OpenCode native skill surface is incomplete (${globalNativeSurface.skill_count}/${globalNativeSurface.expected_skill_count} skills).`);
   if (!sessionSignals.active) findings.push("No active AGDF OpenCode session signal is visible in this process.");
   if (!repositorySurface) findings.push("Current repository does not contain the AGDF OpenCode surface.");
 
@@ -590,6 +733,7 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
       resolved_path: packageState.path,
       error: packageState.error,
     },
+    global_native_surface: globalNativeSurface,
     session: sessionSignals,
     repository_surface: {
       path: targetDir,
@@ -600,7 +744,9 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
     },
     visible_entrypoint: repositorySurface ? `${pluginDefinition.opencode.skillPrefix}gate-check (native skill)` : "none until opencode-repo is installed for this repository",
     findings,
-    next_step: repositorySurface
+    next_step: !globalNativeSurface.complete
+      ? "Run npx --yes @agdf/cli@latest opencode to install or repair the global native OpenCode skill surface."
+      : repositorySurface
       ? `Restart OpenCode if needed, then load ${pluginDefinition.opencode.skillPrefix}gate-check through the native skill tool for new build/change intent.`
       : "Run npx --yes @agdf/cli@latest opencode-repo in repositories where AGDF governance should be active and reviewable.",
   };
@@ -618,6 +764,8 @@ function printOpenCodeStatus(report, json) {
   if (report.global_config.parse_error) console.log(`Config parse error: ${report.global_config.parse_error}`);
   console.log(`Package loadable: ${report.package.loadable ? "yes" : "no"}`);
   if (report.package.resolved_path) console.log(`Package path: ${report.package.resolved_path}`);
+  console.log(`Global native skills: ${report.global_native_surface.complete ? "complete" : "incomplete"} (${report.global_native_surface.skill_count}/${report.global_native_surface.expected_skill_count})`);
+  console.log(`Global skill path: ${report.global_native_surface.path}`);
   console.log(`Session active signal: ${report.session.active ? "yes" : "no"}`);
   if (report.session.version) console.log(`Session plugin version: ${report.session.version}`);
   if (report.session.control_dir) console.log(`Session control dir: ${report.session.control_dir}`);
@@ -2497,6 +2645,7 @@ async function main() {
     const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
     try {
       const result = installOpenCodeGlobalPlugin(configDir);
+      installOpenCodeGlobalSurface(configDir);
       console.log(`AGDF OpenCode global plugin ${result.added ? "installed" : "already present"}: ${result.configPath}`);
       const report = evaluateOpenCodeStatus(options.dir, configDir);
       printOpenCodeStatus(report, false);

package/generated/.opencode/AGDF.md

@@ -101,13 +101,13 @@ For relevant runs that change durable state, code, artefacts or gate status:
 ## OpenCode Files
 
 - OpenCode loads this file through `opencode.json` `instructions`.
-- AGDF for OpenCode has two layers: an optional global npm plugin hook and this repository-local governance surface.
-- The global plugin hook does not replace this file, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
+- AGDF for OpenCode has a global npm/native-skill discoverability layer and this repository-local governance surface.
+- The global plugin and skills do not replace this file, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
 - Native OpenCode skills live under `.opencode/skills/` and use the `agdf-` prefix.
 - The generated AGDF skills are loaded on demand through OpenCode's native `skill` tool; they are not parallel subagents or primary menu agents.
 - For new build/change intent or unclear approval, load the `agdf-gate-check` skill before later artefacts or implementation.
 - The AGDF OpenCode plugin is loaded from npm through `opencode.json` `plugin: ["create-agdf"]`.
-- Use `npx --yes @agdf/cli@latest opencode-status --json` to verify global config, package loadability, active session signals and repository surface presence separately.
-- OpenCode permissions keep `edit` and `bash` on explicit approval and allow the generated `agdf-*` skills explicitly.
+- Use `npx --yes @agdf/cli@latest opencode-status --json` to verify global config, package loadability, global native-skill completeness, active session signals and repository surface presence separately.
+- OpenCode permissions keep `edit` and `bash` on explicit approval and allow the generated `agdf-*` skills explicitly; global adapters use the `agdf-global-*` namespace.
 - Shared output and gate rules live in `.opencode/agdf-runtime-contract.md`.
 - Do not paste full control files, templates or artefact bodies into chat unless the user explicitly asks for the full content; summarize and link paths instead.

package/generated/.opencode/README.md

@@ -3,12 +3,12 @@
 These files were generated from the AGDF source repository for OpenCode.
 
 - `opencode.json` loads the npm plugin `create-agdf` and `.opencode/AGDF.md` as repository instructions.
-- AGDF for OpenCode has two layers: an optional global npm plugin hook and this repository-local governance surface.
-- The global plugin hook does not replace `.opencode/AGDF.md`, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- `opencode.json` keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills.
+- AGDF for OpenCode has a global npm/native-skill discoverability layer and this repository-local governance surface.
+- The global plugin and skills do not replace `.opencode/AGDF.md`, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
+- `opencode.json` keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills; global adapters use `agdf-global-*` to avoid same-name masking.
 - `.opencode/skills/` contains native OpenCode skills generated from the canonical AGDF skills.
 - For new build/change intent or unclear approval, load `agdf-gate-check` through OpenCode's native `skill` tool.
-- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook configuration, package loadability, session activity and this repository surface.
+- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, session activity and this repository surface.
 - Use `npx --yes @agdf/cli@latest gate-check --status-card` for compact interactive gate state; reserve full `--json` output for automation or audit evidence.
 - `.opencode/agdf-runtime-contract.md` is the shared gate and output contract.
 

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -52,6 +52,7 @@
   },
   "opencode": {
     "skillPrefix": "agdf-",
+    "globalSkillPrefix": "agdf-global-",
     "runtimeContractFileName": "agdf-runtime-contract.md",
     "instructionsFileName": "AGDF.md",
     "npmPackage": "create-agdf",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [