create-agdf 0.4.0 → 0.4.1

package/README.md

@@ -10,10 +10,13 @@ Preferred long-term CLI shape:
 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
 ```
 
@@ -24,6 +27,8 @@ 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
@@ -47,6 +52,7 @@ If no language is provided, `create-agdf` derives the preference from the local
 - `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/`
 - `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
@@ -63,6 +69,14 @@ Use the `opencode` target to install the AGDF npm plugin as a user-wide OpenCode
 npx --yes @agdf/cli@latest opencode
 ```
 
+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
@@ -133,6 +147,8 @@ 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, 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.

package/bin/create-agdf.js

@@ -13,7 +13,9 @@ 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 = "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 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"];
@@ -161,6 +163,7 @@ Preferred AGDF CLI:
   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
@@ -172,6 +175,7 @@ Scaffold-compatible npm create usage:
   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
@@ -191,6 +195,7 @@ Options:
                  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
 `);
 }
@@ -252,6 +257,7 @@ function parseArgs(argv) {
   let dir = ".";
   let force = false;
   let json = false;
+  let statusCard = false;
   let language;
   let dirExplicit = false;
 
@@ -274,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) {
@@ -323,7 +334,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, codex-repo, claude, copilot, opencode, opencode-repo, 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);
   }
@@ -333,6 +344,7 @@ function parseArgs(argv) {
     dir: resolve(process.cwd(), dir),
     force,
     json,
+    statusCard,
     dirExplicit,
     language: resolveLanguagePreference(language),
   };
@@ -371,6 +383,11 @@ function installOpenCodeGlobalPlugin(configDir) {
   };
 
   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 {
@@ -379,6 +396,119 @@ function installOpenCodeGlobalPlugin(configDir) {
   };
 }
 
+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" });
@@ -1703,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}`);
@@ -1819,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);
   }
 
@@ -1829,6 +1977,13 @@ 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();
@@ -1857,7 +2012,9 @@ function main() {
     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.");
+      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);

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

@@ -105,6 +105,7 @@ For relevant runs that change durable state, code, artefacts or gate status:
 - 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

@@ -9,6 +9,8 @@ These files were generated from the AGDF source repository for OpenCode.
 - `.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/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.4.0",
+  "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.4.0",
+  "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,26 +1,38 @@
-import { existsSync } from "node:fs";
+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 repositorySurface = hasRepositorySurface();
+        const currentStatus = status();
         await client.app.log({
           body: {
             service: "agdf",
             level: "info",
-            message: repositorySurface ? "AGDF OpenCode surface active" : "AGDF OpenCode plugin loaded without repository surface",
-            extra: { controlDir, repositorySurface },
+            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) => {
@@ -38,7 +50,7 @@ export const AGDFPlugin = async ({ directory, client }) => {
         "## 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.4.0",
+  "version": "0.4.1",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [