create-agdf 0.2.7 → 0.2.9

package/NOTICE

@@ -0,0 +1,10 @@
+AI Governance & Delivery Framework (AGDF)
+
+Copyright 2024-2026 Arndt Gold.
+
+The create-agdf package is licensed under the Apache License, Version 2.0.
+
+AGDF(TM) and AI Governance & Delivery Framework(TM) are marks of Arndt Gold.
+The package license does not grant permission to use project names, trademarks,
+service marks or logos except as required for reasonable and customary
+description of the origin of the project.

package/README.md

@@ -5,12 +5,14 @@ Bootstrap AGDF repository instructions and a machine-checkable control loop for
 ## Usage
 
 ```bash
-npm create agdf@latest codex
-npm create agdf@latest copilot
-npm create agdf@latest both
-npm create agdf@latest init
-npm create agdf@latest doctor
-npm create agdf@latest gate-check
+npm create agdf@latest -- codex
+npm create agdf@latest -- copilot
+npm create agdf@latest -- opencode
+npm create agdf@latest -- both
+npm create agdf@latest -- init
+npm create agdf@latest -- config --language en
+npm create agdf@latest -- doctor
+npm create agdf@latest -- gate-check
 ```
 
 Optional flags:
@@ -25,13 +27,25 @@ If no language is provided, `create-agdf` derives the preference from the local
 
 - `codex` writes a repository-local Codex marketplace under `.agents/plugins/` and a local AGDF plugin copy under `plugins/agdf/`
 - `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/`
 - `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.
 
-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`, 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:
+
+```bash
+npm create agdf@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/`.
+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.
 
 ## Control scaffold
 
@@ -47,7 +61,7 @@ The generated `.agdf/control/templates/` files are reusable starting points for
 Use `init` to promote those templates into live control files when the repository should own durable AGDF control state:
 
 ```bash
-npm create agdf@latest init
+npm create agdf@latest -- init
 ```
 
 This writes:
@@ -66,11 +80,17 @@ 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 an existing repository where the plugin is already installed and only the language preference is missing or wrong, use the lighter config target:
+
+```bash
+npm create agdf@latest -- config --language en
+```
+
 Use `doctor` to check whether the live control state is actionable:
 
 ```bash
-npm create agdf@latest doctor
-npm create agdf@latest doctor --json
+npm create agdf@latest -- doctor
+npx --yes create-agdf@latest doctor --json
 ```
 
 The doctor reports missing live control files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts. It exits non-zero only for blocking control failures.
@@ -78,8 +98,8 @@ The doctor reports missing live control files, missing current gate, missing nex
 Use `gate-check` to derive the next process decision from the doctor result and `AGDF_RUN.md`:
 
 ```bash
-npm create agdf@latest gate-check
-npm create agdf@latest gate-check --json
+npm create agdf@latest -- gate-check
+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.
@@ -119,3 +139,8 @@ The repository publishes this package from `create-agdf/` via the GitHub Actions
 - Create or update the version in `create-agdf/package.json`
 - Push a matching git tag in the form `create-agdf-v<version>`
 - Ensure the repository secret `NPM_TOKEN` exists with publish rights for `create-agdf`
+
+## Trademark Notice
+
+AGDF(TM) and AI Governance & Delivery Framework(TM) are marks of Arndt Gold.
+Use of the AGDF name and marks is governed by the project trademark guidelines.

package/bin/create-agdf.js

@@ -11,8 +11,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 = "claude plugin add arndtgold/ai-native-governance-delivery-framework";
-const allowedTargets = new Set(["codex", "copilot", "both", "init", "doctor", "gate-check", "delivery-map"]);
+const allowedTargets = new Set(["codex", "copilot", "opencode", "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"];
 const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
 const internalStepArtefacts = new Set(["Brownfield Review"]);
@@ -25,6 +26,7 @@ const deliveryRelationships = [
 ];
 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 codexPluginFiles = [
   join(".agents", "plugins", "marketplace.json"),
   join("plugins", "agdf", ".codex-plugin", "plugin.json"),
@@ -112,18 +114,26 @@ const copilotSkillFiles = [
   join(".github", "skills", pluginDefinition.copilot.runtimeContractFileName),
   ...copilotSkillNames.map((skillName) => join(".github", "skills", skillName, "SKILL.md")),
 ];
+const openCodeFiles = [
+  join(".opencode", pluginDefinition.opencode.instructionsFileName),
+  join(".opencode", "README.md"),
+  join(".opencode", pluginDefinition.opencode.runtimeContractFileName),
+  ...openCodeSkillNames.map((skillName) => join(".opencode", "agents", `${skillName}.md`)),
+];
 
 function printUsage() {
   console.log(`create-agdf
 
 Usage:
-  npm create agdf@latest codex
-  npm create agdf@latest copilot
-  npm create agdf@latest both
-  npm create agdf@latest init
-  npm create agdf@latest doctor
-  npm create agdf@latest gate-check
-  npm create agdf@latest delivery-map
+  npm create agdf@latest -- codex
+  npm create agdf@latest -- copilot
+  npm create agdf@latest -- opencode
+  npm create agdf@latest -- both
+  npm create agdf@latest -- init
+  npm create agdf@latest -- config --language de
+  npm create agdf@latest -- doctor
+  npm create agdf@latest -- gate-check
+  npm create agdf@latest -- delivery-map
 
 Options:
   --dir <path>   Write files into a specific directory
@@ -262,7 +272,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, copilot, both, init, doctor, gate-check or delivery-map.");
+    console.error("Please choose one target: codex, copilot, opencode, both, init, config, doctor, gate-check or delivery-map.");
     printUsage();
     process.exit(1);
   }
@@ -280,11 +290,11 @@ function loadAsset(relativePath) {
   return readFileSync(join(generatedRoot, relativePath), "utf8");
 }
 
-function writeGeneratedFile(targetDir, relativePath, content, force) {
+function writeGeneratedFile(targetDir, relativePath, content, force, allowOverwrite = false) {
   const outputPath = join(targetDir, relativePath);
   mkdirSync(dirname(outputPath), { recursive: true });
 
-  if (existsSync(outputPath) && !force) {
+  if (existsSync(outputPath) && !force && !allowOverwrite) {
     throw new Error(`Refusing to overwrite existing file: ${relativePath}. Re-run with --force if you want to replace it.`);
   }
 
@@ -301,6 +311,15 @@ function addLanguageConfig(files, languagePreference) {
 function generatedFilesForTarget(target, targetDir, force, languagePreference) {
   const files = [];
 
+  if (target === "config") {
+    files.push({
+      path: join(".agdf", "control", "config.json"),
+      content: languageConfigContent(languagePreference),
+      allowOverwrite: true,
+    });
+    return files;
+  }
+
   if (target === "init") {
     addLanguageConfig(files, languagePreference);
     files.push({
@@ -365,10 +384,33 @@ function generatedFilesForTarget(target, targetDir, force, languagePreference) {
     }
   }
 
+  if (target === "opencode") {
+    addLanguageConfig(files, languagePreference);
+    const openCodeConfigTargetPath = existsSync(join(targetDir, "opencode.json")) && !force ? openCodeConfigFragmentPath : "opencode.json";
+    files.push({
+      path: openCodeConfigTargetPath,
+      content: loadAsset("opencode.json"),
+    });
+
+    for (const openCodePath of openCodeFiles) {
+      files.push({
+        path: openCodePath,
+        content: loadAsset(openCodePath),
+      });
+    }
+
+    for (const controlPath of controlFiles) {
+      files.push({
+        path: controlPath,
+        content: loadAsset(controlPath),
+      });
+    }
+  }
+
   return files;
 }
 
-function printNextSteps(target, destination, files, wroteAgentsFragment) {
+function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOpenCodeConfigFragment) {
   console.log("");
   console.log(`AGDF bootstrap complete in ${destination}`);
   console.log("");
@@ -386,10 +428,15 @@ function printNextSteps(target, destination, files, wroteAgentsFragment) {
   }
   if (target === "init") {
     console.log("- Fill .agdf/control/AGDF_RUN.md with the current gate, evidence and next allowed action.");
-    console.log("- Run npm create agdf@latest doctor to check the control state before the next agent run.");
+    console.log("- Run npm create agdf@latest -- doctor to check the control state before the next agent run.");
     console.log("- Commit the live control files once they represent the repository's current delivery state.");
     return;
   }
+  if (target === "config") {
+    console.log("- Restart or start a new agent session so the AGDF SessionStart hook reads the updated project language config.");
+    console.log("- Run npm create agdf@latest -- doctor when this repository also uses durable AGDF control state.");
+    return;
+  }
   if (wroteAgentsFragment) {
     console.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
   }
@@ -400,9 +447,18 @@ function printNextSteps(target, destination, files, wroteAgentsFragment) {
   if (target === "both") {
     console.log(`- Optional global Claude Code install: ${pluginInstallCommand}`);
   }
+  if (target === "opencode") {
+    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("- 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("- Run npm create agdf@latest -- init when the repository needs live AGDF control files.");
+  }
   if (target === "copilot" || target === "both") {
     console.log("- In GitHub Copilot CLI, run /instructions after the AGENTS.md step is complete to confirm that AGDF instructions and the repository skills are visible.");
-    console.log("- Run npm create agdf@latest init when the repository needs live AGDF control files.");
+    console.log("- Run npm create agdf@latest -- init when the repository needs live AGDF control files.");
   }
   console.log("- Commit the generated files so the repository becomes the source of truth.");
 }
@@ -506,7 +562,7 @@ function evaluateDoctor(targetDir) {
         ? "Live control file is missing; only the template exists."
         : "Required live control file is missing.",
       relativePath,
-      "Run npm create agdf@latest init only when the repository should own durable AGDF control state or deterministic setup is explicitly needed.",
+      "Run npm create agdf@latest -- init only when the repository should own durable AGDF control state or deterministic setup is explicitly needed.",
     );
   }
 
@@ -1121,7 +1177,7 @@ function evaluateGateCheck(targetDir) {
     allowed = [
       "draft the minimal UR for the requested change in the response",
       "request exact approval: Approval: UR",
-      "run npm create agdf@latest init only when durable control state or deterministic setup is explicitly needed",
+      "run npm create agdf@latest -- init only when durable control state or deterministic setup is explicitly needed",
     ];
     forbidden = ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"];
     nextAllowedAction = "Draft the minimal UR for the request in the response, then ask for exact approval: Approval: UR. Do not write a full .agdf/control scaffold unless durable control state or deterministic setup is explicitly needed.";
@@ -1286,17 +1342,18 @@ 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);
 
   try {
     for (const file of files) {
-      writeGeneratedFile(options.dir, file.path, file.content, options.force);
+      writeGeneratedFile(options.dir, file.path, file.content, options.force, file.allowOverwrite);
     }
   } catch (error) {
     console.error(error.message);
     process.exit(1);
   }
 
-  printNextSteps(options.target, options.dir, files, wroteAgentsFragment);
+  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, wroteOpenCodeConfigFragment);
 }
 
 main();

package/generated/.agdf/control/README.md

@@ -49,15 +49,21 @@ Keep these files small and reviewable. They are control artefacts, not a second
 Create the live files with:
 
 ```bash
-npm create agdf@latest init
+npm create agdf@latest -- init
+```
+
+If only the project language preference is missing or should change after plugin installation, write just the config file:
+
+```bash
+npm create agdf@latest -- config --language en
 ```
 
 Then check whether the live state is actionable:
 
 ```bash
-npm create agdf@latest doctor
-npm create agdf@latest doctor --json
-npm create agdf@latest gate-check --json
+npm create agdf@latest -- doctor
+npx --yes create-agdf@latest doctor --json
+npx --yes create-agdf@latest gate-check --json
 ```
 
 `doctor` does not replace agent judgment. It catches basic control failures: missing live files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts.

package/generated/.github/skills/agdf-gate-check/SKILL.md

@@ -41,10 +41,10 @@ Use `init` only when the user explicitly asks for durable AGDF control state, th
 Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, when CI or PR evidence is needed, or when a repository-local automation needs JSON output:
 
 ```bash
-npm create agdf@latest init
-npm create agdf@latest doctor --json
-npm create agdf@latest gate-check --json
-npm create agdf@latest delivery-map --json
+npm create agdf@latest -- init
+npx --yes create-agdf@latest doctor --json
+npx --yes create-agdf@latest gate-check --json
+npx --yes create-agdf@latest delivery-map --json
 ```
 
 `init` creates the control scaffold. `doctor` checks whether `.agdf/control/` is actionable. `agdf-gate-check` consumes that result and `AGDF_RUN.md` to report the operative process decision: `open | blocked`, current gate, blocking reason, missing approval, allowed outputs, forbidden outputs, next allowed action and evidence references.

package/generated/.opencode/AGDF.md

@@ -0,0 +1,102 @@
+# AGDF OpenCode instructions
+
+## Role
+You are operating in an OpenCode project configured with AGDF.
+
+Use the AGDF agents 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.
+
+Therefore generated OpenCode agent names use the AGDF prefix:
+
+- `agdf-brownfield-analysis`
+- `agdf-clean-implementation-review`
+- `agdf-code-review`
+- `agdf-delivery-closeout`
+- `agdf-gate-check`
+- `agdf-qa-gate`
+- `agdf-release-or`
+- `agdf-task-plan-review`
+
+Do not remove that prefix in OpenCode-facing repository agents.
+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.
+
+Use Quick Task Mode for questions, small reviews, local debugging and narrow fixes without new product semantics.
+
+Use Structured Delivery Mode for new capabilities, architecture, policy, persistence, release-critical work, formal artefacts or explicit approvals.
+
+Any new product semantics, functional change or user-visible behaviour change requires a durable UR first.
+Persist it in `.agdf/control/` or link it from there to the target repository's authoritative source of truth before PRD, SD, TP, Brownfield Analysis or implementation.
+Treat approval text and durable artefact presence as separate checks for UR, PRD, SD, TP and QA report decisions.
+Do not infer approval from "ok", "go ahead", "do it", "approved", "continue", "leg los" or similar wording.
+Those phrases may express intent to proceed, but they do not unlock a gate unless the exact gate formula is present.
+After `Approval: UR`, run lightweight Brownfield Review before PRD when Brownfield, ownership, runtime, policy, persistence, architecture, UI or UX impact is possible.
+Brownfield Review must produce a Mode/Slice Decision: `quick_task`, `structured_slice`, `structured_delivery` or `block`.
+Make that decision visible before coding or drafting later artefacts: state the selected path, scope reason, evidence and next required gate in the live control state or linked artefact.
+Do not assume the full PRD/SD/TP chain before that decision; use only as much gate depth as the reviewed change size justifies.
+
+Quick Task Mode must still use the Runtime Contract mini-output: `result`, `evidence`, `risk`, `next_step`.
+Structured Delivery Mode must respect gates, reviews and closeout discipline.
+
+## Skill Routing
+| Skill | Use For | Boundary |
+|---|---|---|
+| `agdf-brownfield-analysis` | after gate-check permits Brownfield Review or implementation preparation, before non-trivial changes in existing systems | clarifies reuse, owners, risks and Mode/Slice Decision; never bypasses gate-check; Brownfield Review is not implementation permission |
+| `agdf-clean-implementation-review` | inspect workarounds, fallbacks, parallel structures or symptom fixes | not a TP or QA substitute |
+| `agdf-code-review` | mandatory CR step after code changes, focused on defects, regression and security findings | does not replace TP review, clean review or QA |
+| `agdf-delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
+| `agdf-gate-check` | new build/change intent, unclear approval, Structured Delivery, later-gate artefact requested | does not create later artefacts or skip Mode/Slice Decision after Brownfield Review |
+| `agdf-qa-gate` | final QA decision | only instance for `pass | revise | block` |
+| `agdf-release-or` | auditable closeout for every relevant run | not a QA substitute |
+| `agdf-task-plan-review` | after implementation and before QA, verify TP coverage | no final QA decision |
+
+Select exactly one primary skill first.
+Add more only when they cover a distinct concrete risk dimension.
+Do not choose `agdf-brownfield-analysis` as the first primary skill for a fresh "I want to build/change X" prompt unless `agdf-gate-check` or existing live AGDF control state already makes implementation preparation the next allowed action.
+Never jump directly from `Approval: UR`, implicit consent, or a generic "start" request to implementation. Route to Brownfield Review, then a visible Mode/Slice Decision with evidence, then the smallest safe next gate or Quick Task execution.
+
+## Runtime Contract
+For repeated output, gate, Quality Contract and Context Graph rules, use:
+
+`agdf-runtime-contract.md`
+
+Skills may include short reminders, but they must not carry a second complete rule or code table.
+
+## Durable Control State
+When the target repository uses the AGDF control scaffold, keep live control files under `.agdf/control/`.
+Use templates as starting points only.
+
+Do not let chat history become the source of truth for gate state, approvals, evidence, backlog status or durable Brownfield knowledge.
+
+AGDF is agent-native first and CLI-verifiable by design: read the live control state, apply the active skill and make the next allowed step explicit.
+Use `init` only when durable control state is explicitly requested, the repository already uses `.agdf/control/` as its live AGDF working state, or a deterministic CLI/CI setup path is being executed.
+Use `doctor --json`, `gate-check --json` or `delivery-map --json` as deterministic validators for CI, PR evidence, regression checks or audit trails, not as a substitute for the router or skills.
+
+## Closeout
+For Quick Task Mode, close with the Runtime Contract mini-output only:
+
+- `result`
+- `evidence`
+- `risk`
+- `next_step`
+
+For relevant runs that change durable state, code, artefacts or gate status:
+
+- run relevant checks or state the test gap
+- never commit, push or open a PR automatically
+- include exactly one `Next step:`
+- include exactly one `Quality outlook:`
+
+
+## OpenCode Files
+
+- OpenCode loads this file through `opencode.json` `instructions`.
+- OpenCode agents live under `.opencode/agents/` and use the `agdf-` prefix.
+- 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`.
+- 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

@@ -0,0 +1,19 @@
+# AGDF OpenCode surface
+
+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.
+- `opencode.json` keeps `edit` and `bash` on `ask` so execution remains permissioned.
+- `.opencode/agents/` contains AGDF subagents generated from the canonical AGDF skills.
+- `.opencode/agdf-runtime-contract.md` is the shared gate and output contract.
+
+## Agents
+
+- `agdf-brownfield-analysis`
+- `agdf-clean-implementation-review`
+- `agdf-code-review`
+- `agdf-delivery-closeout`
+- `agdf-gate-check`
+- `agdf-qa-gate`
+- `agdf-release-or`
+- `agdf-task-plan-review`