create-agdf 0.6.7 → 0.6.9

package/README.md

@@ -51,9 +51,9 @@ 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-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed OpenCode agents under `.opencode/agents/`, explicit edit/bash permissions, and AGDF control templates under `.agdf/control/`
+- `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,8 @@ 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:
 
@@ -83,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` permissions and the `agdf-` prefixed agents under `.opencode/agents/`. 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.
-Those generated agents use `mode: subagent` intentionally: they are internal governance-routing controls, not OpenCode Skills under `.opencode/skills/` and not primary menu agents. Use `@agdf-gate-check` as the visible entry point for new build/change intent or unclear approval.
+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 agents. 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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join, posix, resolve } from "node:path";
@@ -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"),
@@ -173,7 +177,7 @@ const openCodeFiles = [
   join(".opencode", pluginDefinition.opencode.instructionsFileName),
   join(".opencode", "README.md"),
   join(".opencode", pluginDefinition.opencode.runtimeContractFileName),
-  ...openCodeSkillNames.map((skillName) => join(".opencode", "agents", `${skillName}.md`)),
+  ...openCodeSkillNames.map((skillName) => join(".opencode", "skills", skillName, "SKILL.md")),
 ];
 
 function printUsage() {
@@ -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 {
@@ -528,7 +655,7 @@ function readOpenCodeConfig(configPath) {
 
 function isOpenCodeRepositorySurfacePresent(targetDir) {
   return existsSync(join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName))
-    && existsSync(join(targetDir, ".opencode", "agents", `${pluginDefinition.opencode.skillPrefix}gate-check.md`));
+    && existsSync(join(targetDir, ".opencode", "skills", `${pluginDefinition.opencode.skillPrefix}gate-check`, "SKILL.md"));
 }
 
 function resolveOpenCodePackage(configDir) {
@@ -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 || "",
@@ -565,12 +707,14 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
     repository_surface: process.env.AGDF_OPENCODE_REPOSITORY_SURFACE === "1",
   };
   const repositorySurface = isOpenCodeRepositorySurfacePresent(targetDir);
+  const gateCheckSkillPath = join(targetDir, ".opencode", "skills", `${pluginDefinition.opencode.skillPrefix}gate-check`, "SKILL.md");
 
   const findings = [];
   if (!configState.exists) findings.push("OpenCode global config not found.");
   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.");
 
@@ -589,17 +733,21 @@ function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(
       resolved_path: packageState.path,
       error: packageState.error,
     },
+    global_native_surface: globalNativeSurface,
     session: sessionSignals,
     repository_surface: {
       path: targetDir,
       present: repositorySurface,
       instructions: join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName),
-      gate_check_agent: join(targetDir, ".opencode", "agents", `${pluginDefinition.opencode.skillPrefix}gate-check.md`),
+      gate_check_agent: gateCheckSkillPath,
+      gate_check_skill: gateCheckSkillPath,
     },
-    visible_entrypoint: repositorySurface ? `@${pluginDefinition.opencode.skillPrefix}gate-check` : "none until opencode-repo is installed for this repository",
+    visible_entrypoint: repositorySurface ? `${pluginDefinition.opencode.skillPrefix}gate-check (native skill)` : "none until opencode-repo is installed for this repository",
     findings,
-    next_step: repositorySurface
-      ? `Restart OpenCode if needed, then use @${pluginDefinition.opencode.skillPrefix}gate-check for new build/change intent.`
+    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.",
   };
 }
@@ -616,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}`);
@@ -713,6 +863,29 @@ function writeGeneratedFile(targetDir, relativePath, content, force, allowOverwr
   writeFileSync(outputPath, content, "utf8");
 }
 
+function removeOwnedLegacyOpenCodeAgents(targetDir) {
+  const agentsDir = join(targetDir, ".opencode", "agents");
+  if (!existsSync(agentsDir)) return [];
+
+  const removed = [];
+  for (const skill of pluginDefinition.skillSet) {
+    const skillName = `${pluginDefinition.opencode.skillPrefix}${skill.slug}`;
+    const relativePath = join(".opencode", "agents", `${skillName}.md`);
+    const agentPath = join(targetDir, relativePath);
+    if (!existsSync(agentPath)) continue;
+
+    const content = readFileSync(agentPath, "utf8");
+    const ownedHeader = `---\ndescription: ${skill.useFor}\nmode: subagent\n---`;
+    if (!content.startsWith(ownedHeader) || !content.includes(`# ${skill.slug}`)) continue;
+
+    rmSync(agentPath);
+    removed.push(relativePath);
+  }
+
+  if (readdirSync(agentsDir).length === 0) rmSync(agentsDir, { recursive: true });
+  return removed;
+}
+
 function assertGeneratedWritePlan(targetDir, files, force) {
   const blocked = files.find((file) => existsSync(join(targetDir, file.path)) && !force && !file.allowOverwrite);
   if (blocked) {
@@ -873,7 +1046,7 @@ function generatedFilesForTarget(target, targetDir, force, languagePreference) {
   return files;
 }
 
-function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOpenCodeConfigFragment) {
+function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents = []) {
   console.log("");
   console.log(`AGDF bootstrap complete in ${destination}`);
   console.log("");
@@ -883,6 +1056,12 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
     console.log(`- ${action}${file.path}`);
   }
 
+  if (removedOpenCodeAgents.length > 0) {
+    console.log("");
+    console.log("Removed generated legacy OpenCode agents:");
+    for (const relativePath of removedOpenCodeAgents) console.log(`- ${relativePath}`);
+  }
+
   const preservedFiles = [...new Set(files.map((file) => file.preserved).filter(Boolean))];
   if (preservedFiles.length > 0) {
     console.log("");
@@ -924,10 +1103,9 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
     }
     console.log(`- OpenCode will install the ${pluginDefinition.opencode.npmPackage} npm plugin from opencode.json at startup.`);
     console.log("- Optional: also add create-agdf to ~/.config/opencode/opencode.json plugin[] for a user-wide OpenCode hook.");
-    console.log("- The global hook does not replace repository instructions or subagents; this repository's .opencode files remain the AGDF source of truth.");
-    console.log("- Start OpenCode in this repository; it will load opencode.json, .opencode/AGDF.md and the AGDF subagents.");
-    console.log("- AGDF OpenCode agents are mode: subagent workflow controls; they are not .opencode/skills entries or primary menu agents.");
-    console.log("- Use @agdf-gate-check as the visible entry point for new build/change intent or unclear approval before later artefacts or implementation.");
+    console.log("- The global hook does not replace repository instructions or native skills; this repository's .opencode files remain the AGDF source of truth.");
+    console.log("- Start OpenCode in this repository; it will load opencode.json, .opencode/AGDF.md and the native AGDF skills.");
+    console.log("- Load agdf-gate-check through OpenCode's native skill tool for new build/change intent or unclear approval before later artefacts or implementation.");
     console.log("- Run npx --yes @agdf/cli@latest init when the repository needs live AGDF control files.");
   }
   if (target === "copilot" || target === "both") {
@@ -2467,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);
@@ -2481,18 +2660,22 @@ async function main() {
   const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
   const wroteAgentsFragment = files.some(file => file.path === agdfFragmentPath);
   const wroteOpenCodeConfigFragment = files.some(file => file.path === openCodeConfigFragmentPath);
+  let removedOpenCodeAgents = [];
 
   try {
     assertGeneratedWritePlan(options.dir, files, options.force);
     for (const file of files) {
       writeGeneratedFile(options.dir, file.path, file.content, options.force, file.allowOverwrite);
     }
+    if (options.target === "opencode-repo") {
+      removedOpenCodeAgents = removeOwnedLegacyOpenCodeAgents(options.dir);
+    }
   } catch (error) {
     console.error(error.message);
     process.exit(1);
   }
 
-  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment);
+  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents);
 }
 
 await main();

package/generated/.opencode/AGDF.md

@@ -3,13 +3,13 @@
 ## Role
 You are operating in an OpenCode project configured with AGDF.
 
-Use the AGDF agents as workflow controls, not as documentation shortcuts.
+Use the native AGDF skills as workflow controls, not as documentation shortcuts.
 Your goal is trustworthy progress: reduce uncertainty, establish evidence, preserve artefacts, verify outcomes and make the next allowed step explicit.
 
 ## Surface Convention
-OpenCode project agents do not have a plugin namespace.
+OpenCode project skills do not have a plugin namespace.
 
-Therefore generated OpenCode agent names use the AGDF prefix:
+Therefore generated OpenCode skill names use the AGDF prefix:
 
 - `agdf-delivery-path-search`
 - `agdf-brownfield-analysis`
@@ -21,7 +21,7 @@ Therefore generated OpenCode agent names use the AGDF prefix:
 - `agdf-release-or`
 - `agdf-task-plan-review`
 
-Do not remove that prefix in OpenCode-facing repository agents.
+Do not remove that prefix in OpenCode-facing repository skills.
 Codex and Claude Code plugin surfaces use unprefixed skill names because their plugin namespace already carries `agdf`.
 ## Mode Selection
 Default entry rule: a new user intent to build, add, change, extend, refactor or otherwise deliver something starts with `agdf-gate-check` unless it is clearly only a question, explanation, local inspection, or explicitly scoped review.
@@ -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/agents/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- OpenCode agents live under `.opencode/agents/` and use the `agdf-` prefix.
-- The generated AGDF agents are `mode: subagent` workflow controls for internal routing. They are not OpenCode Skills under `.opencode/skills/` and are not intended to appear as primary menu agents.
-- The visible user entry point is repository instruction loading plus direct subagent handoff, for example `@agdf-gate-check` for new build/change intent or unclear approval.
+- 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 by default.
+- 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,17 +3,16 @@
 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/agents/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- `opencode.json` keeps `edit` and `bash` on `ask` so execution remains permissioned.
-- `.opencode/agents/` contains AGDF subagents generated from the canonical AGDF skills.
-- These files intentionally do not install OpenCode Skills under `.opencode/skills/`; the AGDF agents are background workflow controls, not primary menu agents.
-- Use `@agdf-gate-check` as the visible entry point for new build/change intent or unclear approval.
-- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook configuration, package loadability, session activity and this repository surface.
+- 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/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.
 
-## Agents
+## Skills
 
 - `agdf-brownfield-analysis`
 - `agdf-clean-implementation-review`

package/generated/.opencode/{agents/agdf-brownfield-analysis.md → skills/agdf-brownfield-analysis/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: after gate-check permits Brownfield Review or implementation preparation, before non-trivial changes in existing systems
-mode: subagent
+name: agdf-brownfield-analysis
+description: "Use this skill after gate-check or live AGDF control state confirms that Brownfield Review or implementation preparation is allowed. Use it after Approval: UR as the lightweight Brownfield Review after G-00 before PRD when existing systems may be affected, and again before non-trivial implementation after TP. Do not use it as the first AGDF skill for a fresh \"I want to build/change X\" prompt when approval, scope, or next allowed action is unclear."
 ---
 
 # brownfield-analysis
@@ -19,7 +19,7 @@ The skill answers:
 - whether Context Graph impact exists without automatically creating a node
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 Brownfield-specific output must make evidence, missing existing-system view, parallel-structure risk, reuse strategy, and the minimal next step visible.
 When `.agdf/control/` is present, persist or link `post_ur_review` output under `.agdf/control/artefacts/<key>/BROWNFIELD_REVIEW.md`.
@@ -96,7 +96,7 @@ When used as Brownfield Review after `Approval: UR`, do not recommend PRD, SD, T
 7. Check SoT/runtime/product-semantics drift.
 8. Check primary visible ownership for UI/status/recovery paths.
 9. Check UI monolith risk for large surfaces or central hooks.
-10. Check Context Graph impact according to `../agdf-runtime-contract.md`.
+10. Check Context Graph impact according to `../../agdf-runtime-contract.md`.
 11. Recommend the minimal clean implementation path.
 
 ## Output
@@ -134,4 +134,3 @@ This skill must not:
 - create Context Graph nodes automatically
 - treat archive links as active current specification signals
 - recommend broad PRD/SD/TP or implementation by reflex before Mode/Slice Decision is recorded
-

package/generated/.opencode/{agents/agdf-clean-implementation-review.md → skills/agdf-clean-implementation-review/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: inspect workarounds, fallbacks, parallel structures or symptom fixes
-mode: subagent
+name: agdf-clean-implementation-review
+description: Use this skill to determine whether an implementation is a clean primary solution or whether fallbacks, workarounds, guards, defaults, shims, or parallel structures have made it unnecessarily complex. Use it after code changes, before QA, or whenever symptom treatment is suspected.
 ---
 
 # clean-implementation-review
@@ -18,7 +18,7 @@ This skill answers:
 - is it maintainable or workaround-heavy
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 Clean-review-specific output must make the primary solution, fallbacks, workarounds, parallel structures, exit criteria, and next cleanup/review step visible.
 
@@ -98,4 +98,3 @@ This skill must not:
 - hide unjustified workarounds
 - treat green tests as proof of solution integrity
 - decide final QA
-

package/generated/.opencode/{agents/agdf-code-review.md → skills/agdf-code-review/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: mandatory CR step after code changes, focused on defects, regression and security findings
-mode: subagent
+name: agdf-code-review
+description: Use this skill after code changes and before QA to produce the mandatory Code Review Report for correctness, regression, security, and maintainability findings in the actual diff. It standardizes the CR step without replacing TP review, clean review, or QA.
 ---
 
 # code-review
@@ -17,7 +17,7 @@ It answers:
 - whether Brownfield, TP, or clean-review follow-up remains open
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 Code-review-specific output must make actual findings, missing review scope, evidence strength, and the next required step visible.
 
@@ -92,4 +92,3 @@ This skill must not:
 - hide missing review scope
 - generate style-only findings
 - duplicate TP Review or QA as if they were the same step
-

package/generated/.opencode/{agents/agdf-delivery-closeout.md → skills/agdf-delivery-closeout/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: commit/PR-near handoff after QA/OR/UAT
-mode: subagent
+name: agdf-delivery-closeout
+description: Use this skill for the final delivery handoff after QA, OR, or UAT when a run should move toward commit, push, or PR. It standardizes commit-ready summaries, UAT-gated commit offers, and the next delivery step without replacing QA or OR decisions.
 ---
 
 # delivery-closeout
@@ -20,7 +20,7 @@ It answers:
 This skill does not replace `agdf-qa-gate`, `agdf-release-or`, user approvals, or gate decisions.
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for closeout discipline, gate terms, Context Graph fields, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for closeout discipline, gate terms, Context Graph fields, and non-duplication rules.
 
 ## Rules
 1. Delivery follows gate clarity.
@@ -112,4 +112,3 @@ This skill must not:
 - execute commit, push, or PR
 - invent a commit handoff for non-code runs
 - imply new gate approvals
-

package/generated/.opencode/{agents/agdf-delivery-path-search.md → skills/agdf-delivery-path-search/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: high-impact planning decisions with several plausible next delivery steps before implementation
-mode: subagent
+name: agdf-delivery-path-search
+description: Use this skill for high-impact planning decisions when several materially different next delivery steps are plausible and comparing scope, risk, evidence, tests, cost and gate readiness would reduce expensive rework. Do not use for routine tasks, during implementation, or as gate permission.
 ---
 
 # Delivery Path Search
@@ -13,7 +13,7 @@ The search is advisory and read-only. Canonical AGDF `agdf-gate-check` remains t
 
 ## Runtime Contract
 
-Use `../agdf-runtime-contract.md` for canonical gate state, output discipline and Delivery Path Search boundaries. This skill must not maintain a second gate or scoring model.
+Use `../../agdf-runtime-contract.md` for canonical gate state, output discipline and Delivery Path Search boundaries. This skill must not maintain a second gate or scoring model.
 
 ## Trigger
 
@@ -87,4 +87,3 @@ Persist only the redacted decision summary when durable evidence is required. Do
 - Do not replace deterministic candidates with generated proposals.
 - Do not send secrets, full artefacts, source snapshots, raw prompts or hidden reasoning to a generator.
 - Do not claim executable generation for instruction-only surfaces.
-

package/generated/.opencode/{agents/agdf-gate-check.md → skills/agdf-gate-check/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: new build/change intent, unclear approval, Structured Delivery, later-gate artefact requested
-mode: subagent
+name: agdf-gate-check
+description: Use this skill as the default first AGDF skill for any new build, change, extension, refactor, feature, CLI, app, fix with product semantics, Structured Delivery request, unclear approval, later-gate artefact request, or unclear next permissible step. Use it before brownfield-analysis, implementation, formal artefacts, QA, or release when approval/evidence/next action is not already explicit.
 ---
 
 # gate-check
@@ -18,7 +18,7 @@ Determine the earliest blocking user approval gate and derive:
 This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or UAT when the gate does not allow them.
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
 The canonical gate order and transition model live only in the Runtime Contract. This skill evaluates the current state against that model; it must not maintain a second complete gate table.
 
 ## Agent-Native Control Path
@@ -159,4 +159,3 @@ This skill must not:
 - paste full `.agdf/control/` files, templates or artefact bodies into the chat unless the user explicitly asks for the full content
 - present QA or UAT as passed without evidence
 - present release as allowed without QA pass and UAT approval where required
-

package/generated/.opencode/{agents/agdf-qa-gate.md → skills/agdf-qa-gate/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: final QA decision
-mode: subagent
+name: agdf-qa-gate
+description: Use this skill before any QA decision to determine whether implementation can be classified as pass, revise, or block based on TP coverage, Brownfield fit, solution integrity, evidence, and open blockers. Use it after CD+Tests, after reviews, and before UAT or release decisions.
 ---
 
 # qa-gate
@@ -22,7 +22,7 @@ It answers:
 - whether blockers, critical risks, or missing evidence remain
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 QA-specific `decision` is exactly `pass | revise | block`.
 `pass` is allowed only when TP coverage, Brownfield fit, solution integrity, and relevant documentation/Context Graph impact are sufficiently evidenced.
@@ -93,7 +93,7 @@ Use this shape:
 - impact_codes:
 ```
 
-If Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
+If Context Graph impact is relevant, include the fields from `../../agdf-runtime-contract.md`.
 
 ## Decision Guidance
 - `pass`: required TP tasks are done, evidence is strong, no blocking Brownfield or solution-integrity risk remains.
@@ -108,4 +108,3 @@ This skill must not:
 - replace UAT
 - treat missing reviews as completed
 - downgrade SoT drift to harmless warning
-

package/generated/.opencode/{agents/agdf-release-or.md → skills/agdf-release-or/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: auditable closeout for every relevant run
-mode: subagent
+name: agdf-release-or
+description: Use this skill at the end of every relevant run to produce a compact, auditable Orchestration Report. It summarizes gate status, delivered and intentionally not delivered work, TP coverage, Brownfield fit, solution integrity, open risks, and the next permissible step.
 ---
 
 # release-or
@@ -25,7 +25,7 @@ It reports:
 - whether further quality follow-up or a separate delivery closeout is useful
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 OR-specific output must make gate status, delivered and intentionally not delivered content, missing approvals, missing evidence, risks, retained fallbacks, and the next permissible step visible.
 When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from the selected canonical `RUN_STATE.md` or `MASTER_BACKLOG.md` when it is steering-relevant.
@@ -117,7 +117,7 @@ Use a compact structure:
 - quality_outlook:
 ```
 
-When Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
+When Context Graph impact is relevant, include the fields from `../../agdf-runtime-contract.md`.
 Include `context_graph_reconciliation` whenever Context Graph impact is present. If the value is `open_gap`, required next step must resolve or explicitly retain that gap before commit-ready or release-ready handoff.
 
 ## Forbidden
@@ -129,4 +129,3 @@ This skill must not:
 - provide later-gate content while an earlier gate blocks
 - produce the operative commit/PR handoff owned by `agdf-delivery-closeout`
 - execute commit, push, or PR actions
-

package/generated/.opencode/{agents/agdf-task-plan-review.md → skills/agdf-task-plan-review/SKILL.md}

@@ -1,6 +1,6 @@
 ---
-description: after implementation and before QA, verify TP coverage
-mode: subagent
+name: agdf-task-plan-review
+description: Use this skill after code changes and before QA to verify whether the approved Task Plan was actually fulfilled. It checks each task_id against implementation, acceptance criteria, tests, visible evidence, and deviations, and provides TP coverage for QA.
 ---
 
 # task-plan-review
@@ -19,7 +19,7 @@ For each relevant task, this skill determines:
 This skill provides TP coverage. It is not the final QA decision.
 
 ## Runtime Contract
-Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use `../../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 TP-specific output must evaluate every relevant `task_id` with completion status, AC coverage, evidence, missing evidence, and QA-relevant gaps.
 If `context_graph_required_action` is not `none`, the affected task is complete only if follow-up, evidence, or an intentionally open gap is visible.
@@ -113,4 +113,3 @@ This skill must not:
 - hide partial work
 - upgrade missing evidence into confidence
 - reinterpret the TP scope
-

package/generated/opencode.json

@@ -8,6 +8,9 @@
   ],
   "permission": {
     "edit": "ask",
-    "bash": "ask"
+    "bash": "ask",
+    "skill": {
+      "agdf-*": "allow"
+    }
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.6.7",
+  "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.7",
+  "version": "0.6.9",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -52,12 +52,16 @@
   },
   "opencode": {
     "skillPrefix": "agdf-",
+    "globalSkillPrefix": "agdf-global-",
     "runtimeContractFileName": "agdf-runtime-contract.md",
     "instructionsFileName": "AGDF.md",
     "npmPackage": "create-agdf",
     "permissions": {
       "edit": "ask",
-      "bash": "ask"
+      "bash": "ask",
+      "skill": {
+        "agdf-*": "allow"
+      }
     }
   },
   "skillSet": [

package/opencode-plugin.js

@@ -4,7 +4,7 @@ const packageJson = JSON.parse(readFileSync(new URL("./package.json", import.met
 
 export const AGDFPlugin = async ({ directory, client }) => {
   const controlDir = `${directory}/.agdf/control`;
-  const hasRepositorySurface = () => existsSync(`${directory}/.opencode/AGDF.md`) && existsSync(`${directory}/.opencode/agents`);
+  const hasRepositorySurface = () => existsSync(`${directory}/.opencode/AGDF.md`) && existsSync(`${directory}/.opencode/skills/agdf-gate-check/SKILL.md`);
   const status = () => ({
     active: true,
     version: packageJson.version,
@@ -40,7 +40,7 @@ export const AGDFPlugin = async ({ directory, client }) => {
         output.context.push([
           "## AGDF Plugin Notice",
           "The AGDF OpenCode npm plugin is loaded, but this repository does not contain the AGDF OpenCode surface.",
-          "Do not apply AGDF gates from the global plugin alone; repository instructions, subagents and control files are the source of truth.",
+          "Do not apply AGDF gates from the global plugin alone; repository instructions, native skills and control files are the source of truth.",
           "Run `npx --yes @agdf/cli@latest opencode-repo` in this repository when AGDF governance should be active here.",
         ].join("\n"));
         return;
@@ -48,8 +48,8 @@ export const AGDFPlugin = async ({ directory, client }) => {
 
       output.context.push([
         "## AGDF Runtime Reminder",
-        "Use `.opencode/AGDF.md`, `.opencode/agents/` and `.agdf/control/` as the AGDF source for this OpenCode session.",
-        "For new build/change intent or unclear approval, route first to `agdf-gate-check` before later artefacts or implementation.",
+        "Use `.opencode/AGDF.md`, `.opencode/skills/` and `.agdf/control/` as the AGDF source for this OpenCode session.",
+        "For new build/change intent or unclear approval, load the native `agdf-gate-check` skill before later artefacts or implementation.",
         "Use `npx --yes @agdf/cli@latest gate-check --status-card` for compact interactive status. Use `--json` only as deterministic proof for automation or audit evidence, and summarize it instead of mirroring full JSON into chat.",
       ].join("\n"));
     },

package/package.json

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