create-agdf 0.3.5 → 0.4.1

package/README.md

@@ -8,10 +8,15 @@ Preferred long-term CLI shape:
 
 ```bash
 npx --yes @agdf/cli@latest codex
+npx --yes @agdf/cli@latest codex-repo
+npx --yes @agdf/cli@latest claude
 npx --yes @agdf/cli@latest opencode
+npx --yes @agdf/cli@latest opencode-status
+npx --yes @agdf/cli@latest opencode-repo
 npx --yes @agdf/cli@latest init
 npx --yes @agdf/cli@latest config --language en
 npx --yes @agdf/cli@latest doctor
+npx --yes @agdf/cli@latest gate-check --status-card
 npx --yes @agdf/cli@latest gate-check --json
 ```
 
@@ -19,8 +24,12 @@ Backward-compatible scaffold usage:
 
 ```bash
 npm create agdf@latest -- codex
+npm create agdf@latest -- codex-repo
+npm create agdf@latest -- claude
 npm create agdf@latest -- copilot
 npm create agdf@latest -- opencode
+npm create agdf@latest -- opencode-status
+npm create agdf@latest -- opencode-repo
 npm create agdf@latest -- both
 npm create agdf@latest -- init
 npm create agdf@latest -- config --language en
@@ -38,27 +47,46 @@ If no language is provided, `create-agdf` derives the preference from the local
 
 ## Targets and existing AGENTS.md
 
-- `codex` writes a repository-local Codex marketplace under `.agents/plugins/` and a local AGDF plugin copy under `plugins/agdf/`
+- `codex` installs the AGDF plugin globally for Codex
+- `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` 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 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/`
 - `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
 
 If the target repository already has an `AGENTS.md`, `create-agdf` preserves it and writes `AGENTS.agdf.md` instead of replacing your existing instructions. Merge the AGDF fragment into your current `AGENTS.md` when you want Copilot to load both instruction sets. The generated `.github/copilot-instructions.md` keeps Copilot pointed at `AGENTS.md`, `.github/skills/` and `.agdf/control/` without duplicating the full AGDF rule model. Use `--force` only when you explicitly want to overwrite generated files.
 
-Use the `codex` target when AGDF should be available only inside one repository instead of being installed as a personal/global Codex plugin.
+Use the `codex-repo` target when AGDF should be available only inside one repository instead of being installed as a personal/global Codex plugin.
 
-After `npm create agdf@latest -- codex`, restart Codex in that repository, open `/plugins`, select `This repository` and install `agdf`.
+After `npm create agdf@latest -- codex-repo`, restart Codex in that repository, open `/plugins`, select `This repository` and install `agdf`.
 
-Use the `opencode` target when AGDF should be available to OpenCode from repository files:
+Use the `opencode` target to install the AGDF npm plugin as a user-wide OpenCode hook:
 
 ```bash
-npm create agdf@latest -- opencode
+npx --yes @agdf/cli@latest opencode
 ```
 
-OpenCode loads the AGDF npm plugin from `opencode.json`, AGENTS-style rules from `.opencode/AGDF.md`, explicit `edit`/`bash` permissions and the `agdf-` prefixed agents under `.opencode/agents/`.
+Then verify the visible installation state:
+
+```bash
+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.
+
+Use the `opencode-repo` target when AGDF should be available to OpenCode from repository files:
+
+```bash
+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.
 If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment.
-Using OpenCode's plugin installer for `create-agdf` can add the npm plugin entry, but AGDF still needs the repository instructions and agents. The `opencode` target writes the npm plugin entry and the repository files together.
+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.
 
 ## Control scaffold
 
@@ -93,6 +121,8 @@ This writes:
 
 `config.json` stores `artifact_language` and `chat_language` for governed work in the target repository. Runtime rules stay English so all AGDF surfaces share the same control contract.
 
+For a normal fresh request, `init` is not the required first move. The agent-native path can draft the minimal UR in the response and ask for the exact approval text `Approval: UR`. Write or initialize `.agdf/control` only when durable repository-owned control state is explicitly wanted, already in use, or needed for deterministic setup/CI evidence. Before Brownfield Review, later gates or implementation, AGDF still requires the persisted or linked artefacts named by the Runtime Contract.
+
 For an existing repository where the plugin is already installed and only the language preference is missing or wrong, use the lighter config target:
 
 ```bash
@@ -117,9 +147,11 @@ npx --yes create-agdf@latest gate-check --json
 
 The gate check reports `open | blocked`, the current gate, blocking reason, missing exact approval, allowed outputs, forbidden outputs, next allowed action, evidence references and the embedded doctor report.
 
+Use `gate-check --status-card` for compact interactive output, especially in OpenCode where shell output is highly visible. Keep `gate-check --json` for automation, CI, regression evidence and audit trails.
+
 `gate-check --json` and `delivery-map --json` also expose a `status_card` object. It is a compact projection of the current control state: current gate, allowed and forbidden actions, blocker, next skill, next permissible step and `quality_outlook`. `next_step` is process permission; `quality_outlook` is the next meaningful quality-improvement focus and does not unlock gates.
 
-Together, `init`, `doctor` and `gate-check --json` turn AGDF from an instruction layer into a repository control system when durable control state is needed. For normal fresh requests, the agent-native path can stay lighter: draft the minimal UR in the response, request `Approval: UR`, and use CLI validators only when machine-readable proof is useful.
+Together, `init`, `doctor` and `gate-check --json` turn AGDF from an instruction layer into a repository control system when durable control state is needed. For normal fresh requests, keep the path lighter: draft the minimal UR in the response, request `Approval: UR`, and use CLI validators only when machine-readable proof is useful.
 
 ## Single source of truth
 

package/bin/create-agdf.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
 import { dirname, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
@@ -10,8 +12,10 @@ const packageRoot = resolve(__dirname, "..");
 const generatedRoot = join(packageRoot, "generated");
 const pluginDefinitionPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-plugin.definition.json");
 const pluginDefinition = JSON.parse(readFileSync(pluginDefinitionPath, "utf8"));
-const pluginInstallCommand = "claude plugin add arndtgold/ai-native-governance-delivery-framework";
-const allowedTargets = new Set(["codex", "copilot", "opencode", "both", "init", "config", "doctor", "gate-check", "delivery-map"]);
+const pluginInstallCommand = "npx --yes @agdf/cli@latest claude";
+const npmCommand = process.platform === "win32" ? process.execPath : "npm";
+const npmPrefixArgs = process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
+const allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "opencode-status", "opencode-repo", "both", "init", "config", "doctor", "gate-check", "delivery-map"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
 const openCodeConfigFragmentPath = "opencode.agdf.json";
 const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
@@ -156,15 +160,23 @@ function printUsage() {
 
 Preferred AGDF CLI:
   npx --yes @agdf/cli@latest codex
+  npx --yes @agdf/cli@latest codex-repo
+  npx --yes @agdf/cli@latest claude
   npx --yes @agdf/cli@latest opencode
+  npx --yes @agdf/cli@latest opencode-status
+  npx --yes @agdf/cli@latest opencode-repo
   npx --yes @agdf/cli@latest init
   npx --yes @agdf/cli@latest doctor
   npx --yes @agdf/cli@latest gate-check --json
 
 Scaffold-compatible npm create usage:
   npm create agdf@latest -- codex
+  npm create agdf@latest -- codex-repo
+  npm create agdf@latest -- claude
   npm create agdf@latest -- copilot
   npm create agdf@latest -- opencode
+  npm create agdf@latest -- opencode-status
+  npm create agdf@latest -- opencode-repo
   npm create agdf@latest -- both
   npm create agdf@latest -- init
   npm create agdf@latest -- config --language de
@@ -177,12 +189,13 @@ Backward-compatible create-agdf usage:
   npx --yes create-agdf@latest gate-check --json
 
 Options:
-  --dir <path>   Write files into a specific directory
+  --dir <path>   Write files into a specific directory. With opencode, use this as the OpenCode config directory.
   --force        Overwrite existing generated files
   --language <de|en>
                  Set AGDF chat and artefact language. Defaults to detected system locale.
   --lang <de|en> Alias for --language
   --json         Print doctor, gate-check or delivery-map output as JSON
+  --status-card  Print compact gate-check status-card output for interactive use
   --help         Show this help
 `);
 }
@@ -244,7 +257,9 @@ function parseArgs(argv) {
   let dir = ".";
   let force = false;
   let json = false;
+  let statusCard = false;
   let language;
+  let dirExplicit = false;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -265,6 +280,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--status-card") {
+      statusCard = true;
+      continue;
+    }
+
     if (arg === "--language" || arg === "--lang") {
       const next = args[i + 1];
       if (!next) {
@@ -288,6 +308,7 @@ function parseArgs(argv) {
         process.exit(1);
       }
       dir = next;
+      dirExplicit = true;
       i += 1;
       continue;
     }
@@ -313,7 +334,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, copilot, opencode, both, init, config, doctor, gate-check or delivery-map.");
+    console.error("Please choose one target: codex, codex-repo, claude, copilot, opencode, opencode-status, opencode-repo, both, init, config, doctor, gate-check or delivery-map.");
     printUsage();
     process.exit(1);
   }
@@ -323,10 +344,188 @@ function parseArgs(argv) {
     dir: resolve(process.cwd(), dir),
     force,
     json,
+    statusCard,
+    dirExplicit,
     language: resolveLanguagePreference(language),
   };
 }
 
+function defaultOpenCodeConfigDir() {
+  return process.env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode");
+}
+
+function installOpenCodeGlobalPlugin(configDir) {
+  const configPath = join(configDir, "opencode.json");
+  let config = {};
+
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(`Refusing to update unreadable OpenCode config: ${configPath}`);
+    }
+  }
+
+  if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
+    throw new Error(`Refusing to update OpenCode config with non-array plugin field: ${configPath}`);
+  }
+
+  const plugins = [...(config.plugin ?? [])];
+  const alreadyInstalled = plugins.includes(pluginDefinition.opencode.npmPackage);
+  if (!alreadyInstalled) {
+    plugins.push(pluginDefinition.opencode.npmPackage);
+  }
+
+  const nextConfig = {
+    "$schema": config.$schema ?? "https://opencode.ai/config.json",
+    ...config,
+    plugin: plugins,
+  };
+
+  mkdirSync(configDir, { recursive: true });
+  try {
+    execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--prefix", configDir, packageRoot], { stdio: "pipe" });
+  } catch (error) {
+    throw new Error(`Failed to install ${pluginDefinition.opencode.npmPackage} into the OpenCode config directory: ${(error.stderr || error.message).toString().trim()}`);
+  }
+  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+
+  return {
+    configPath,
+    added: !alreadyInstalled,
+  };
+}
+
+function readOpenCodeConfig(configPath) {
+  if (!existsSync(configPath)) return { exists: false, parseError: "", config: {} };
+  try {
+    return { exists: true, parseError: "", config: JSON.parse(readFileSync(configPath, "utf8")) };
+  } catch (error) {
+    return { exists: true, parseError: error.message, config: {} };
+  }
+}
+
+function isOpenCodeRepositorySurfacePresent(targetDir) {
+  return existsSync(join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName))
+    && existsSync(join(targetDir, ".opencode", "agents", `${pluginDefinition.opencode.skillPrefix}gate-check.md`));
+}
+
+function resolveOpenCodePackage(configDir) {
+  const packageName = pluginDefinition.opencode.npmPackage;
+  try {
+    return {
+      loadable: true,
+      path: execFileSync(process.execPath, ["-e", `process.stdout.write(require.resolve(${JSON.stringify(packageName)}))`], {
+        cwd: configDir,
+        encoding: "utf8",
+        stdio: "pipe",
+      }),
+      error: "",
+    };
+  } catch (error) {
+    return {
+      loadable: false,
+      path: "",
+      error: (error.stderr || error.message || "package not resolvable").toString().trim(),
+    };
+  }
+}
+
+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 sessionSignals = {
+    active: process.env.AGDF_PLUGIN_ACTIVE === "1",
+    version: process.env.AGDF_PLUGIN_VERSION || "",
+    control_dir: process.env.AGDF_CONTROL_DIR || "",
+    repository_surface: process.env.AGDF_OPENCODE_REPOSITORY_SURFACE === "1",
+  };
+  const repositorySurface = isOpenCodeRepositorySurfacePresent(targetDir);
+
+  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 (!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.");
+
+  return {
+    schema_version: "1",
+    status: globalConfigured && packageState.loadable ? "configured" : "not_configured",
+    global_config: {
+      path: configPath,
+      exists: configState.exists,
+      parse_error: configState.parseError,
+      plugin_configured: globalConfigured,
+    },
+    package: {
+      name: pluginDefinition.opencode.npmPackage,
+      loadable: packageState.loadable,
+      resolved_path: packageState.path,
+      error: packageState.error,
+    },
+    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`),
+    },
+    visible_entrypoint: repositorySurface ? `@${pluginDefinition.opencode.skillPrefix}gate-check` : "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.`
+      : "Run npx --yes @agdf/cli@latest opencode-repo in repositories where AGDF governance should be active and reviewable.",
+  };
+}
+
+function printOpenCodeStatus(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log("AGDF OpenCode status");
+  console.log(`Status: ${report.status}`);
+  console.log(`Global config: ${report.global_config.plugin_configured ? "configured" : "missing"} (${report.global_config.path})`);
+  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(`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}`);
+  console.log(`Repository surface: ${report.repository_surface.present ? "present" : "missing"}`);
+  console.log(`Visible entrypoint: ${report.visible_entrypoint}`);
+  console.log(`Next step: ${report.next_step}`);
+
+  if (report.findings.length > 0) {
+    console.log("");
+    console.log("Findings:");
+    for (const finding of report.findings) console.log(`- ${finding}`);
+  }
+}
+
+function installCodexGlobalPlugin() {
+  try {
+    execFileSync("codex", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], { stdio: "inherit" });
+    execFileSync("codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], { stdio: "inherit" });
+  } catch (error) {
+    throw new Error("Failed to install the AGDF Codex plugin. Make sure the Codex CLI is installed and available on PATH, then rerun this command.");
+  }
+}
+
+function installClaudeGlobalPlugin() {
+  try {
+    execFileSync("claude", ["plugin", "add", "arndtgold/ai-native-governance-delivery-framework"], { stdio: "inherit" });
+  } catch {
+    throw new Error("Failed to install the AGDF Claude Code plugin. Make sure the Claude Code CLI is installed and available on PATH, then rerun this command.");
+  }
+}
+
 function loadAsset(relativePath) {
   return readFileSync(join(generatedRoot, relativePath), "utf8");
 }
@@ -385,7 +584,7 @@ function generatedFilesForTarget(target, targetDir, force, languagePreference) {
     return files;
   }
 
-  if (target === "codex" || target === "both") {
+  if (target === "codex-repo" || target === "both") {
     addLanguageConfig(files, languagePreference);
     for (const codexPath of codexPluginFiles) {
       files.push({
@@ -425,7 +624,7 @@ function generatedFilesForTarget(target, targetDir, force, languagePreference) {
     }
   }
 
-  if (target === "opencode") {
+  if (target === "opencode-repo") {
     addLanguageConfig(files, languagePreference);
     const openCodeConfigTargetPath = existsSync(join(targetDir, "opencode.json")) && !force ? openCodeConfigFragmentPath : "opencode.json";
     files.push({
@@ -481,20 +680,23 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
   if (wroteAgentsFragment) {
     console.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
   }
-  if (target === "codex" || target === "both") {
+  if (target === "codex-repo" || target === "both") {
     console.log("- Restart Codex in this repository, open /plugins, select This repository and install agdf.");
     console.log("- Start a new Codex thread in this repository and ask: Run an AGDF gate check for this request.");
   }
   if (target === "both") {
     console.log(`- Optional global Claude Code install: ${pluginInstallCommand}`);
   }
-  if (target === "opencode") {
+  if (target === "opencode-repo") {
     if (wroteOpenCodeConfigFragment) {
       console.log(`- Existing opencode.json detected. Merge ${openCodeConfigFragmentPath} into your current opencode.json so OpenCode loads .opencode/AGDF.md.`);
     }
     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("- Use @agdf-gate-check for new build/change intent or unclear approval before later artefacts or implementation.");
+    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("- Run npx --yes @agdf/cli@latest init when the repository needs live AGDF control files.");
   }
   if (target === "copilot" || target === "both") {
@@ -1631,12 +1833,30 @@ function evaluateGateCheck(targetDir) {
   };
 }
 
-function printGateCheckReport(report, json) {
+function printGateCheckStatusCard(report) {
+  const card = report.status_card;
+  console.log(`AGDF status-card: ${card.status}`);
+  console.log(`Current gate: ${card.current_gate}`);
+  console.log(`Blocked by: ${card.blocking_condition}`);
+  console.log(`Missing approval: ${card.missing_approval}`);
+  console.log(`Next skill: ${card.next_skill}`);
+  console.log(`Next step: ${card.next_step}`);
+  console.log(`Quality outlook: ${card.quality_outlook}`);
+  if (card.allowed_now.length > 0) console.log(`Allowed now: ${card.allowed_now.join("; ")}`);
+  if (card.forbidden_now.length > 0) console.log(`Forbidden now: ${card.forbidden_now.join("; ")}`);
+}
+
+function printGateCheckReport(report, json, statusCard = false) {
   if (json) {
     console.log(JSON.stringify(report, null, 2));
     return;
   }
 
+  if (statusCard) {
+    printGateCheckStatusCard(report);
+    return;
+  }
+
   console.log(`AGDF gate-check: ${report.status}`);
   console.log(`Current gate: ${report.current_gate}`);
   console.log(`Blocking reason: ${report.blocking_reason}`);
@@ -1747,7 +1967,7 @@ function main() {
 
   if (options.target === "gate-check") {
     const report = evaluateGateCheck(options.dir);
-    printGateCheckReport(report, options.json);
+    printGateCheckReport(report, options.json, options.statusCard);
     process.exit(report.status === "blocked" ? 2 : 0);
   }
 
@@ -1757,6 +1977,51 @@ function main() {
     process.exit(report.status === "block" ? 2 : 0);
   }
 
+  if (options.target === "opencode-status") {
+    const configDir = process.env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir();
+    const report = evaluateOpenCodeStatus(options.dir, configDir);
+    printOpenCodeStatus(report, options.json);
+    process.exit(report.status === "configured" ? 0 : 1);
+  }
+
+  if (options.target === "codex") {
+    try {
+      installCodexGlobalPlugin();
+      console.log("AGDF Codex plugin installed globally.");
+      console.log("Run npx --yes @agdf/cli@latest codex-repo in a repository when you want to test AGDF from repository-local plugin files.");
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (options.target === "claude") {
+    try {
+      installClaudeGlobalPlugin();
+      console.log("AGDF Claude Code plugin installed globally.");
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (options.target === "opencode") {
+    const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
+    try {
+      const result = installOpenCodeGlobalPlugin(configDir);
+      console.log(`AGDF OpenCode global plugin ${result.added ? "installed" : "already present"}: ${result.configPath}`);
+      const report = evaluateOpenCodeStatus(options.dir, configDir);
+      printOpenCodeStatus(report, false);
+      console.log("Restart OpenCode so it loads the updated global plugin config.");
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
   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);

package/generated/.github/copilot-instructions.md

@@ -13,3 +13,4 @@ AGDF is active in this repository.
 - Do not infer gate approval from generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved".
 - Do not treat chat history as the source of truth for gate state, approvals, evidence or delivery status.
 - 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.
+- For interactive checks, prefer `npx --yes @agdf/cli@latest gate-check --status-card`. Use `gate-check --json` for automation or audit evidence and summarize the status card instead of mirroring full JSON into chat.

package/generated/.opencode/AGDF.md

@@ -99,8 +99,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.
 - 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.
 - 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,8 +3,14 @@
 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.
+- 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

package/generated/.opencode/agents/agdf-brownfield-analysis.md

@@ -3,11 +3,6 @@ description: after gate-check permits Brownfield Review or implementation prepar
 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
 
 ## Purpose

package/generated/.opencode/agents/agdf-clean-implementation-review.md

@@ -3,11 +3,6 @@ description: inspect workarounds, fallbacks, parallel structures or symptom fixe
 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
 
 ## Purpose

package/generated/.opencode/agents/agdf-code-review.md

@@ -3,11 +3,6 @@ description: mandatory CR step after code changes, focused on defects, regressio
 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
 
 ## Purpose

package/generated/.opencode/agents/agdf-delivery-closeout.md

@@ -3,11 +3,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
 
 ## Purpose

package/generated/.opencode/agents/agdf-gate-check.md

@@ -3,11 +3,6 @@ description: new build/change intent, unclear approval, Structured Delivery, lat
 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
 
 ## Purpose

package/generated/.opencode/agents/agdf-qa-gate.md

@@ -3,11 +3,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
 
 ## Purpose

package/generated/.opencode/agents/agdf-release-or.md

@@ -3,11 +3,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
 
 ## Purpose

package/generated/.opencode/agents/agdf-task-plan-review.md

@@ -3,11 +3,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
 
 ## Purpose

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

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "author": {
     "name": "AI-native Governance & Delivery Framework",

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",

package/opencode-plugin.js

@@ -1,30 +1,56 @@
+import { existsSync, readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+
 export const AGDFPlugin = async ({ directory, client }) => {
   const controlDir = `${directory}/.agdf/control`;
+  const hasRepositorySurface = () => existsSync(`${directory}/.opencode/AGDF.md`) && existsSync(`${directory}/.opencode/agents`);
+  const status = () => ({
+    active: true,
+    version: packageJson.version,
+    controlDir,
+    repositorySurface: hasRepositorySurface(),
+  });
 
   return {
     event: async ({ event }) => {
       if (event?.type === "session.created") {
+        const currentStatus = status();
         await client.app.log({
           body: {
             service: "agdf",
             level: "info",
-            message: "AGDF OpenCode surface active",
-            extra: { controlDir },
+            message: currentStatus.repositorySurface ? "AGDF OpenCode active" : "AGDF OpenCode global hook active without repository surface",
+            extra: currentStatus,
           },
         });
       }
     },
 
     "shell.env": async (_input, output) => {
+      const currentStatus = status();
+      output.env.AGDF_PLUGIN_ACTIVE = "1";
+      output.env.AGDF_PLUGIN_VERSION = currentStatus.version;
       output.env.AGDF_CONTROL_DIR = controlDir;
+      output.env.AGDF_OPENCODE_REPOSITORY_SURFACE = currentStatus.repositorySurface ? "1" : "0";
     },
 
     "experimental.session.compacting": async (_input, output) => {
+      if (!hasRepositorySurface()) {
+        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.",
+          "Run `npx --yes @agdf/cli@latest opencode-repo` in this repository when AGDF governance should be active here.",
+        ].join("\n"));
+        return;
+      }
+
       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 `npx --yes @agdf/cli@latest gate-check --json` only as deterministic proof, not as a replacement for AGDF judgement.",
+        "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.3.5",
+  "version": "0.4.1",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [