create-agdf 0.2.8 → 0.3.0

package/README.md

@@ -4,9 +4,23 @@ Bootstrap AGDF repository instructions and a machine-checkable control loop for
 
 ## Usage
 
+Preferred long-term CLI shape:
+
+```bash
+npx --yes agdf@latest codex
+npx --yes agdf@latest opencode
+npx --yes agdf@latest init
+npx --yes agdf@latest config --language en
+npx --yes agdf@latest doctor
+npx --yes agdf@latest gate-check --json
+```
+
+Backward-compatible scaffold usage:
+
 ```bash
 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
@@ -26,6 +40,7 @@ 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
 
@@ -35,6 +50,16 @@ Use the `codex` target when AGDF should be available only inside one repository
 
 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
 
 The generated `.agdf/control/templates/` files are reusable starting points for durable AGDF state:
@@ -124,6 +149,8 @@ The routing test installs `both` into a temporary target repository and checks t
 
 The repository publishes this package from `create-agdf/` via the GitHub Actions workflow `.github/workflows/publish-create-agdf.yml`.
 
+The primary user-facing CLI package is published separately from `agdf/` and delegates to this package through the shared `create-agdf/cli` export.
+
 - 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`

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", "config", "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,13 +114,27 @@ 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:
+Preferred AGDF CLI:
+  npx --yes agdf@latest codex
+  npx --yes agdf@latest opencode
+  npx --yes agdf@latest init
+  npx --yes agdf@latest doctor
+  npx --yes agdf@latest gate-check --json
+
+Scaffold-compatible npm create usage:
   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
@@ -126,6 +142,10 @@ Usage:
   npm create agdf@latest -- gate-check
   npm create agdf@latest -- delivery-map
 
+Backward-compatible create-agdf usage:
+  npx --yes create-agdf@latest doctor --json
+  npx --yes create-agdf@latest gate-check --json
+
 Options:
   --dir <path>   Write files into a specific directory
   --force        Overwrite existing generated files
@@ -263,7 +283,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: codex, copilot, both, init, config, 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);
   }
@@ -375,10 +395,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("");
@@ -396,13 +439,13 @@ 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 npx --yes 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.");
+    console.log("- Run npx --yes agdf@latest doctor when this repository also uses durable AGDF control state.");
     return;
   }
   if (wroteAgentsFragment) {
@@ -415,9 +458,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 npx --yes 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 npx --yes 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.");
 }
@@ -521,7 +573,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 npx --yes agdf@latest init only when the repository should own durable AGDF control state or deterministic setup is explicitly needed.",
     );
   }
 
@@ -1136,7 +1188,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 npx --yes 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.";
@@ -1301,6 +1353,7 @@ 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) {
@@ -1311,7 +1364,7 @@ function main() {
     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,21 +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
+npx --yes 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
+npx --yes agdf@latest config --language en
 ```
 
 Then check whether the live state is actionable:
 
 ```bash
-npm create agdf@latest -- doctor
-npx --yes create-agdf@latest doctor --json
-npx --yes create-agdf@latest gate-check --json
+npx --yes agdf@latest doctor
+npx --yes agdf@latest doctor --json
+npx --yes 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
-npx --yes create-agdf@latest doctor --json
-npx --yes create-agdf@latest gate-check --json
-npx --yes create-agdf@latest delivery-map --json
+npx --yes agdf@latest init
+npx --yes agdf@latest doctor --json
+npx --yes agdf@latest gate-check --json
+npx --yes 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`

package/generated/.opencode/agdf-runtime-contract.md

@@ -0,0 +1,219 @@
+# AGDF Runtime Contract
+
+This contract centralizes recurring runtime rules for AGDF skills.
+It is the operational reference for skill outputs, but it is not a second copy of the framework documentation.
+
+## Mode Selection
+
+| Mode | Default | Escalate When |
+|---|---|---|
+| Quick Task Mode | small questions, reviews, debugging, local fixes without new product semantics | a new user capability, architecture/policy/persistence impact, formal artefacts, or approvals are involved |
+| Structured Delivery Mode | formal delivery runs, gate-relevant work, release-critical changes | always use gate discipline, internal reviews, and OR |
+
+Quick Task Mode must not become ritual gate overhead.
+Structured Delivery must not bypass missing approvals.
+New product semantics, functional change, user-visible behaviour, policy, persistence, architecture or release-critical work requires a durable UR in `.agdf/control/` or a linked authoritative repository SoT before later artefacts or implementation.
+UR, PRD, SD, TP and QA report approvals require durable artefacts or linked authoritative repository SoT entries before the next gate can open.
+
+## Quick Task Output
+
+Quick Tasks are intentionally lightweight, but they must not become invisible.
+Use this compact output shape when no formal gate artefact is required:
+
+- `result`: what changed or was concluded
+- `evidence`: files, commands, observations, or reasoning that support the result
+- `risk`: remaining risk or `none`
+- `next_step`: the single next useful action or `none`
+
+Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
+
+## Chat Output Discipline
+
+Durable artefacts are for the repository, not for flooding the chat.
+When a skill creates or updates `.agdf/control/` files, gate artefacts, reviews, QA reports or OR reports, the chat response must stay compact:
+
+- name the artefact path and status
+- summarize the decision or content in a few lines
+- state the current gate, forbidden work and next permissible step
+- mention validation evidence when available
+
+Do not paste full control files, full artefact bodies, full templates or full generated reports into the chat unless the user explicitly asks to see the full content.
+For larger or more formal work, create or update the durable artefacts fully, then reference them by path and summarize what changed.
+
+## Relevant Run
+
+A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
+
+OR is not mandatory for a pure explanation, read-only inspection, small review, or local debugging step that produces no durable state change and no gate consequence.
+When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
+
+## Gate Rules
+
+- User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
+- Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Brownfield Analysis -> CD+Tests -> CR -> OR`
+- Exact approval formula: `Approval: <GateName>`
+- Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
+- Implicit consent is not approval. Phrases such as "ok", "go ahead", "do it", "approved", "continue", "leg los" or "looks good" are work intent, not gate approval.
+- The earliest blocking gate wins.
+- For UR, PRD, SD, TP and QA, approval and durable artefact presence are separate requirements. A gate is not satisfied by approval text alone when its artefact is missing from `.agdf/control/` or not linked to the authoritative repository SoT.
+- Approval of one user gate permits work on the next allowed gate artefact or required internal step only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
+- Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
+- Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
+- `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
+- PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
+- The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in `AGDF_RUN.md` or an equivalent linked control artefact.
+- `Approval: PRD` permits Solution Design drafting, not implementation.
+- `Approval: SD` permits Task/Test Plan drafting, not implementation.
+- `Approval: TP` permits implementation-preparation Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
+- `CD+Tests` is implementation and test status only, not a delivery signal.
+- `agdf-code-review` standardizes the mandatory `CR` step, but does not replace QA.
+- `agdf-qa-gate` decides final `pass | revise | block`.
+- `agdf-release-or` reports the run, but does not replace QA or produce the operative commit/PR handoff.
+- `agdf-delivery-closeout` owns the operative Git handoff text when QA/OR/UAT state allows it.
+
+## Brownfield Review After G-00
+
+After an approved and durable UR, perform a lightweight `Brownfield Review` before PRD when Brownfield, UI, UX, admin, runtime, policy, persistence, architecture, ownership or source-of-truth impact is possible.
+
+This review is not a new user approval gate, not PRD, not SD, not TP and not implementation permission.
+It is the sizing and routing step that decides how much later gate discipline is actually needed.
+
+Its output is limited to:
+
+- workstream or follow-up-slice classification
+- `Mode/Slice Decision`: `quick_task | structured_slice | structured_delivery | block`
+- affected existing owners, source-of-truth artefacts, contracts, policies, runtime paths or tests
+- reuse-before-create risks and parallel-structure risks
+- open questions that PRD or SD must resolve
+- whether implementation-preparation Brownfield Analysis will also be needed after TP
+
+Mode/Slice Decision rules:
+
+- `quick_task`: use only when Brownfield Review shows a narrow local change, no new product semantics beyond the approved UR, no architecture/policy/persistence/contract expansion, and evidence is sufficient to proceed with a small implementation plus relevant checks.
+- `structured_slice`: use when some formal artefacts are needed, but they can stay intentionally small and scoped to the approved slice.
+- `structured_delivery`: use when the change has broad product, architecture, runtime, policy, persistence, release or cross-owner impact.
+- `block`: use when ownership, SoT, impact, evidence or product direction is not clear enough to choose a safe path.
+
+A Mode/Slice Decision without scope reason and evidence is not recorded. Treat it as missing and keep the next step at `Mode/Slice Decision`.
+
+## Gate Transition Model
+
+This table is the canonical transition model. Skills may reference it, but must not carry a second complete copy.
+
+| State | Current gate or step | Allowed | Forbidden | Missing approval |
+|---|---|---|---|---|
+| No approved UR | `UR` | clarify user need, formulate and persist UR, request `Approval: UR` | PRD, SD, TP, Brownfield Analysis, implementation, QA, release | `Approval: UR` |
+| `UR` approved and UR artefact persisted or linked, Brownfield Review missing | `Brownfield Review` | classify workstream, existing owners, SoT, reuse risks, change size and PRD/SD open questions; mark review done or not_applicable | PRD, SD, TP, implementation, QA, release | none |
+| Brownfield Review done or not_applicable, Mode/Slice Decision missing or incomplete | `Mode/Slice Decision` | decide `quick_task`, `structured_slice`, `structured_delivery` or `block`; record scope reason, evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
+| Mode/Slice Decision is `quick_task` | `Quick Task Execution` | implement only the narrow approved UR scope, run relevant checks, record evidence and OR-lite when the run is relevant | broad PRD/SD/TP by ritual, scope expansion, QA or release claims without evidence | none |
+| Mode/Slice Decision is `structured_slice` or `structured_delivery`, PRD missing or draft | `PRD` | draft/refine PRD at the smallest justified depth, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, implementation-preparation Brownfield Analysis, implementation, QA, release | `Approval: PRD` |
+| `PRD` approved and PRD artefact persisted or linked, SD missing or draft | `SD` | draft/refine Solution Design, ownership and architecture, persist/link SD, request `Approval: SD` | TP, implementation, QA, release | `Approval: SD` |
+| `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |
+| `TP` approved and TP artefact persisted or linked, Brownfield Analysis missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
+| Brownfield Analysis passed for approved TP | `CD+Tests` | implement approved TP tasks and run tests | QA pass, UAT, release | none |
+| `QA` approved but QA report missing or not pass | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
+
+## Brownfield Modes
+
+The `agdf-brownfield-analysis` skill has two explicit modes:
+
+- `post_ur_review`: lightweight sizing and routing after approved durable UR; decides Mode/Slice Decision before PRD depth or implementation is chosen.
+- `pre_implementation_analysis`: implementation-preparation analysis after approved durable TP; verifies reuse path, owners, regression risk and fit before `CD+Tests`.
+
+Do not mix the modes silently. Name the active mode in Brownfield output.
+
+## Quality Contract Output
+
+Structured Delivery skills use this shape when relevant:
+
+- `decision`: `pass | revise | block | not_applicable`
+- `evidence`: concrete artefacts, files, tests, logs, diffs, or observations
+- `missing_evidence`: missing proof needed for a stronger claim
+- `risks`: remaining risks, assumptions, fallbacks, drift, or blockers
+- `required_next_step`: exactly the next clean step
+- `impact_codes`: affected Quality Contract codes, if the target repo has a registry
+
+A skill may briefly remind this shape, but must not duplicate a complete code or rule matrix.
+
+## Context Graph Output
+
+When a run affects project memory or a Context Graph, use:
+
+- `Situation:` short plain-language summary when the impact is non-trivial
+- `context_graph_impact`: `none | link_only | update_existing_node | new_node_required | sot_drift`
+- `context_graph_refs`
+- `context_graph_required_action`: `none | link | update | create | resolve_drift`
+- `context_graph_gate_effect`: `none | warning | revise | block`
+- `context_graph_evidence`
+
+Do not create a new node for a mere version, a general chat summary, or a local observation without a concrete next clean step.
+`sot_drift` must not pass silently as a warning.
+
+## Control Scaffold
+
+When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
+
+- `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
+- `AGDF_RUN.md` is the current run dashboard.
+- `MASTER_BACKLOG.md` is the living pointer for active delivery work.
+- `BROWNFIELD_REVIEW.md` records the post-UR existing-system view and Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
+- `SOT_REGISTRY.md` prevents parallel sources of truth.
+- `CONTEXT_GRAPH.md` stores durable Brownfield findings, decisions, risks, evidence and exit criteria.
+- `AGENT_QUALITY_CONTRACTS.json` stores reusable block, revise and warning conditions.
+- OR reports live under `.agdf/control/artefacts/<key>/OR.md` when a run closeout is steering-relevant or should be auditable beyond the chat.
+
+The scaffold is not a second documentation site. Link to authoritative artefacts instead of copying them.
+
+## Agent-Native Runtime And CLI Verification
+
+AGDF is agent-native first and CLI-verifiable by design.
+
+The primary operating path is the active skill plus the live `.agdf/control/` artefacts.
+Agents should read the repository state, apply this Runtime Contract, create or update only the currently allowed artefact, and make the next permissible step explicit.
+When control state is missing for a fresh request, keep the first step lightweight: draft the minimal UR in the response and request `Approval: UR`.
+Initialize a control scaffold only when durable AGDF control state is explicitly requested, already used by the repository, or required by a deterministic CLI/CI setup path.
+
+Helper commands are deterministic proof and automation interfaces, not the normal-work ritual:
+
+- `init` creates the machine-readable control scaffold.
+- `doctor --json` checks whether `.agdf/control/` is consistent and actionable; it is not the reviewer.
+- `gate-check --json` reports reproducible gate state; it does not replace the gate-check skill judgement.
+- `delivery-map --json` reports the delivery picture for CI, PRs, regression checks and audit trails.
+
+Machine-readable outputs should stay agent-friendly: stable decisions, blocking gate or current gate, missing approval, allowed outputs, forbidden outputs, next step, evidence and findings.
+They make the repository state checkable, but they do not replace the native skill workflow or the durable control artefacts.
+
+## Delivery Map
+
+`delivery-map --json` is the machine-readable delivery picture for the active control state.
+It derives, but does not replace, the live `.agdf/control/AGDF_RUN.md` and `MASTER_BACKLOG.md` state.
+
+It must expose:
+
+- approved or active artefacts and approvals
+- `UR -> PRD -> SD -> TP -> QA_REPORT` relationships
+- evidence refs, missing evidence and declared risks
+- Context Graph impact and gate effect
+- findings that explain why the delivery picture is `pass | warn | revise | block`
+
+Missing relationship evidence in the Artefact Chain is at least `revise` once the related gate artefact is approved or passed.
+Declared missing evidence, declared risk or Context Graph gate effect may escalate the delivery map to `warn`, `revise` or `block`.
+
+## Skill Output
+
+Every skill output should be as short as possible and as concrete as needed.
+It must distinguish:
+
+- facts
+- evidence
+- assumptions
+- interpretations
+- missing evidence
+- the next permissible step
+
+## Do Not Duplicate
+
+The explanatory framework lives in `docs/`.
+The operating philosophy lives in `plugin/meta/agdf-constitution.md`.
+The principles live in `plugin/meta/agdf-tenets.md`.
+This contract is only the compact runtime interface for skills.