create-agdf 0.3.5 → 0.4.0

package/README.md

@@ -8,7 +8,9 @@ Preferred long-term CLI shape:
 
 ```bash
 npx --yes @agdf/cli@latest codex
-npx --yes @agdf/cli@latest opencode
+npx --yes @agdf/cli@latest codex-repo
+npx --yes @agdf/cli@latest claude
+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
@@ -19,8 +21,10 @@ 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-repo
 npm create agdf@latest -- both
 npm create agdf@latest -- init
 npm create agdf@latest -- config --language en
@@ -38,27 +42,37 @@ 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-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/`.
+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 +107,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
@@ -119,7 +135,7 @@ The gate check reports `open | blocked`, the current gate, blocking reason, miss
 
 `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,8 @@ 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 allowedTargets = new Set(["codex", "codex-repo", "claude", "copilot", "opencode", "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 +158,21 @@ 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-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-repo
   npm create agdf@latest -- both
   npm create agdf@latest -- init
   npm create agdf@latest -- config --language de
@@ -177,7 +185,7 @@ 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.
@@ -245,6 +253,7 @@ function parseArgs(argv) {
   let force = false;
   let json = false;
   let language;
+  let dirExplicit = false;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -288,6 +297,7 @@ function parseArgs(argv) {
         process.exit(1);
       }
       dir = next;
+      dirExplicit = true;
       i += 1;
       continue;
     }
@@ -313,7 +323,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-repo, both, init, config, doctor, gate-check or delivery-map.");
     printUsage();
     process.exit(1);
   }
@@ -323,10 +333,69 @@ function parseArgs(argv) {
     dir: resolve(process.cwd(), dir),
     force,
     json,
+    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 });
+  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+
+  return {
+    configPath,
+    added: !alreadyInstalled,
+  };
+}
+
+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 +454,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 +494,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 +550,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") {
@@ -1757,6 +1829,42 @@ function main() {
     process.exit(report.status === "block" ? 2 : 0);
   }
 
+  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}`);
+      console.log("Run npx --yes @agdf/cli@latest opencode-repo in each repository where AGDF governance should be active and reviewable.");
+    } 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/.opencode/AGDF.md

@@ -99,7 +99,11 @@ 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"]`.
 - OpenCode permissions keep `edit` and `bash` on explicit approval by default.
 - Shared output and gate rules live in `.opencode/agdf-runtime-contract.md`.

package/generated/.opencode/README.md

@@ -3,8 +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/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.
 - `.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.0",
   "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.0",
   "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,15 +1,19 @@
+import { existsSync } from "node:fs";
+
 export const AGDFPlugin = async ({ directory, client }) => {
   const controlDir = `${directory}/.agdf/control`;
+  const hasRepositorySurface = () => existsSync(`${directory}/.opencode/AGDF.md`) && existsSync(`${directory}/.opencode/agents`);
 
   return {
     event: async ({ event }) => {
       if (event?.type === "session.created") {
+        const repositorySurface = hasRepositorySurface();
         await client.app.log({
           body: {
             service: "agdf",
             level: "info",
-            message: "AGDF OpenCode surface active",
-            extra: { controlDir },
+            message: repositorySurface ? "AGDF OpenCode surface active" : "AGDF OpenCode plugin loaded without repository surface",
+            extra: { controlDir, repositorySurface },
           },
         });
       }
@@ -20,6 +24,16 @@ export const AGDFPlugin = async ({ directory, client }) => {
     },
 
     "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.",

package/package.json

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