create-agdf 0.2.5 → 0.2.7

package/README.md

@@ -17,6 +17,9 @@ Optional flags:
 
 - `--dir <path>` write into a specific directory
 - `--force` overwrite existing generated files
+- `--language <de|en>` or `--lang <de|en>` persist the preferred AGDF artefact and chat language
+
+If no language is provided, `create-agdf` derives the preference from the local system locale (`LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE` or the Node.js runtime locale) and falls back to `en`.
 
 ## Targets and existing AGENTS.md
 
@@ -41,7 +44,7 @@ The generated `.agdf/control/templates/` files are reusable starting points for
 - `CONTEXT_GRAPH.md` for durable Brownfield findings, decisions, risks, evidence and exit criteria
 - `AGENT_QUALITY_CONTRACTS.json` for reusable block, revise and warning conditions
 
-Use `init` to promote those templates into live control files:
+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
@@ -51,6 +54,7 @@ This writes:
 
 - `.agdf/control/AGDF_RUN.md`
 - `.agdf/control/MASTER_BACKLOG.md`
+- `.agdf/control/config.json`
 - `.agdf/control/templates/artefacts/UR.md`
 - `.agdf/control/templates/artefacts/PRD.md`
 - `.agdf/control/templates/artefacts/SD.md`
@@ -60,6 +64,8 @@ This writes:
 - `.agdf/control/CONTEXT_GRAPH.md`
 - `.agdf/control/AGENT_QUALITY_CONTRACTS.json`
 
+`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.
+
 Use `doctor` to check whether the live control state is actionable:
 
 ```bash
@@ -78,7 +84,7 @@ npm 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.
 
-Together, `init`, `doctor` and `gate-check --json` turn AGDF from an instruction layer into a repository control system: the agent can be guided by rules, and the repository state can be checked before the next governed step.
+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.
 
 ## Single source of truth
 

package/bin/create-agdf.js

@@ -128,17 +128,72 @@ Usage:
 Options:
   --dir <path>   Write files into a specific directory
   --force        Overwrite existing generated files
+  --language <de|en>
+                 Set AGDF chat and artefact language. Defaults to detected system locale.
+  --lang <de|en> Alias for --language
   --json         Print doctor, gate-check or delivery-map output as JSON
   --help         Show this help
 `);
 }
 
+function normalizeLanguage(value) {
+  const normalized = String(value ?? "").trim().toLowerCase().replace("_", "-");
+  if (!normalized) return "";
+  if (normalized.startsWith("de")) return "de";
+  if (normalized.startsWith("en")) return "en";
+  return "";
+}
+
+function detectSystemLocale() {
+  const envLocale = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || process.env.LANGUAGE || "";
+  if (envLocale) return envLocale;
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale || "";
+  } catch {
+    return "";
+  }
+}
+
+function resolveLanguagePreference(explicitLanguage) {
+  const explicit = normalizeLanguage(explicitLanguage);
+  if (explicit) {
+    return {
+      artifact_language: explicit,
+      chat_language: explicit,
+      runtime_language: "en",
+      source: "parameter",
+      detected_locale: detectSystemLocale() || "unknown",
+    };
+  }
+
+  const detectedLocale = detectSystemLocale();
+  const detected = normalizeLanguage(detectedLocale) || "en";
+  return {
+    artifact_language: detected,
+    chat_language: detected,
+    runtime_language: "en",
+    source: detectedLocale ? "system_locale" : "default",
+    detected_locale: detectedLocale || "unknown",
+  };
+}
+
+function languageConfigContent(languagePreference) {
+  return `${JSON.stringify({
+    artifact_language: languagePreference.artifact_language,
+    chat_language: languagePreference.chat_language,
+    runtime_language: languagePreference.runtime_language,
+    source: languagePreference.source,
+    detected_locale: languagePreference.detected_locale,
+  }, null, 2)}\n`;
+}
+
 function parseArgs(argv) {
   const args = [...argv];
   let target;
   let dir = ".";
   let force = false;
   let json = false;
+  let language;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -159,6 +214,22 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--language" || arg === "--lang") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error(`Missing value for ${arg}`);
+        process.exit(1);
+      }
+      const normalized = normalizeLanguage(next);
+      if (!normalized) {
+        console.error("Unsupported language. Use --language de or --language en.");
+        process.exit(1);
+      }
+      language = normalized;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--dir") {
       const next = args[i + 1];
       if (!next) {
@@ -201,6 +272,7 @@ function parseArgs(argv) {
     dir: resolve(process.cwd(), dir),
     force,
     json,
+    language: resolveLanguagePreference(language),
   };
 }
 
@@ -219,10 +291,18 @@ function writeGeneratedFile(targetDir, relativePath, content, force) {
   writeFileSync(outputPath, content, "utf8");
 }
 
-function generatedFilesForTarget(target, targetDir, force) {
+function addLanguageConfig(files, languagePreference) {
+  files.push({
+    path: join(".agdf", "control", "config.json"),
+    content: languageConfigContent(languagePreference),
+  });
+}
+
+function generatedFilesForTarget(target, targetDir, force, languagePreference) {
   const files = [];
 
   if (target === "init") {
+    addLanguageConfig(files, languagePreference);
     files.push({
       path: join(".agdf", "control", "README.md"),
       content: loadAsset(join(".agdf", "control", "README.md")),
@@ -246,6 +326,7 @@ function generatedFilesForTarget(target, targetDir, force) {
   }
 
   if (target === "codex" || target === "both") {
+    addLanguageConfig(files, languagePreference);
     for (const codexPath of codexPluginFiles) {
       files.push({
         path: codexPath,
@@ -255,6 +336,7 @@ function generatedFilesForTarget(target, targetDir, force) {
   }
 
   if (target === "copilot" || target === "both") {
+    if (target !== "both") addLanguageConfig(files, languagePreference);
     const agentsTargetPath = existsSync(join(targetDir, "AGENTS.md")) && !force ? agdfFragmentPath : "AGENTS.md";
     files.push({
       path: agentsTargetPath,
@@ -297,6 +379,11 @@ function printNextSteps(target, destination, files, wroteAgentsFragment) {
 
   console.log("");
   console.log("Next steps:");
+  const languageConfig = files.find((file) => file.path === join(".agdf", "control", "config.json"));
+  if (languageConfig) {
+    const language = JSON.parse(languageConfig.content);
+    console.log(`- AGDF language preference: artefacts=${language.artifact_language}, chat=${language.chat_language}, runtime=${language.runtime_language}.`);
+  }
   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.");
@@ -419,7 +506,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, then fill the live control files with the current repository state.",
+      "Run npm create agdf@latest init only when the repository should own durable AGDF control state or deterministic setup is explicitly needed.",
     );
   }
 
@@ -1026,18 +1113,32 @@ function evaluateGateCheck(targetDir) {
     ? transitionDecision.next_allowed_action
     : runState.next_allowed_action;
 
-  if (doctorBlocker) {
+  if (doctorBlocker?.code === "AGDF_CONTROL_FILE_MISSING") {
+    status = "blocked";
+    blockingReason = doctorBlocker.code;
+    currentGate = "UR";
+    missingApproval = "Approval: UR";
+    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",
+    ];
+    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.";
+  } else if (doctorBlocker) {
     status = "blocked";
     blockingReason = doctorBlocker.code;
-    allowed = ["repair the AGDF control scaffold", "run doctor again"];
-    forbidden = ["continue governed delivery", "create later-gate artefacts", "implement gated work"];
+    allowed = ["repair the AGDF control scaffold", ...transitionDecision.allowed, "run doctor again"];
+    forbidden = ["create later-gate artefacts beyond the current allowed gate", "implement gated work", "claim QA or release readiness"];
     nextAllowedAction = doctorBlocker.next_step;
   } else if (doctorRevise) {
     status = "blocked";
     blockingReason = doctorRevise.code;
-    allowed = [...new Set(["repair the incomplete control state", ...transitionDecision.allowed, "run doctor again"])];
-    forbidden = ["continue governed delivery", "create later-gate artefacts", "implement gated work"];
-    nextAllowedAction = doctorRevise.next_step;
+    allowed = [...new Set(["complete the current control-state fields", ...transitionDecision.allowed, "run doctor again"])];
+    forbidden = ["create later-gate artefacts beyond the current allowed gate", "implement gated work before the gate allows it", "claim QA or release readiness"];
+    nextAllowedAction = transitionDecision.current_gate === "UR"
+      ? "Fill the current UR control state, persist the UR draft, and request exact approval: Approval: UR."
+      : doctorRevise.next_step;
   }
 
   return {
@@ -1183,7 +1284,7 @@ function main() {
     process.exit(report.status === "block" ? 2 : 0);
   }
 
-  const files = generatedFilesForTarget(options.target, options.dir, options.force);
+  const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
   const wroteAgentsFragment = files.some(file => file.path === agdfFragmentPath);
 
   try {

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

@@ -8,6 +8,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 | File | Purpose |
 |---|---|
+| `config.json` | Project language preference for generated AGDF artefacts and user-facing chat |
 | `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
 | `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
@@ -26,6 +27,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 ```text
 .agdf/
   control/
+    config.json
     AGDF_RUN.md
     MASTER_BACKLOG.md
     artefacts/
@@ -64,6 +66,7 @@ npm create agdf@latest gate-check --json
 ## Operating Rules
 
 - `AGDF_RUN.md` is the current run dashboard.
+- `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
 - Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.

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

@@ -5,9 +5,11 @@ AGDF is active in this repository.
 - Treat `AGENTS.md` as the primary repository instruction source.
 - Use `.github/skills/` for AGDF task workflows instead of inventing parallel process rules.
 - Use `.agdf/control/` for durable run state, backlog pointers, source-of-truth ownership, Context Graph knowledge and quality contracts.
+- AGDF is agent-native first and CLI-verifiable by design.
 - Apply AGDF natively from `AGENTS.md`, repository skills and live `.agdf/control/` state before reaching for helper commands.
 - Before non-trivial implementation or formal delivery work, determine whether the request is a Quick Task or Structured Delivery.
 - If approval, evidence, ownership or the next allowed action is unclear, run the AGDF gate-check workflow before creating later artefacts or code.
-- Use machine-readable checks such as `doctor --json`, `gate-check --json` or `delivery-map --json` as validators, not as the primary workflow.
+- Use `doctor --json`, `gate-check --json` or `delivery-map --json` as deterministic validators for CI, PR evidence, regression checks and audit trails, not as the primary workflow.
 - 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.

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

@@ -21,9 +21,10 @@ This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or U
 Use `../agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
 The canonical gate order and transition model live only in the Runtime Contract. This skill evaluates the current state against that model; it must not maintain a second complete gate table.
 
-## Native Control Path
+## Agent-Native Control Path
 
-AGDF is applied natively through this skill, the agent router, and live `.agdf/control/` state.
+AGDF is agent-native first and CLI-verifiable by design.
+This skill is the primary operating path for gate judgement.
 
 First inspect the durable control state directly:
 
@@ -33,18 +34,23 @@ First inspect the durable control state directly:
 - `.agdf/control/CONTEXT_GRAPH.md`
 - `.agdf/control/AGENT_QUALITY_CONTRACTS.json`
 
-Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, or when a repository-local automation needs JSON evidence:
+If required control files are missing, do not automatically create a full `.agdf/control/` scaffold for a fresh small request.
+The default first action is to draft the minimal UR in the response and request `Approval: UR`.
+Use `init` 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.
+
+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
 ```
 
-`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.
+`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.
 `delivery-map` reports the durable delivery picture: active artefacts, approvals, Artefact Chain relationships, evidence refs, missing evidence, risks, Context Graph gate effect and machine-readable findings.
 
-The CLI reports are validators and JSON evidence, not the primary user experience and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
+The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
@@ -61,6 +67,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 12. Approval text and durable artefact presence are separate requirements for UR, PRD, SD, TP and QA report decisions. Approval text without the corresponding persisted or linked artefact keeps the current gate at that gate.
 13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | structured_slice | structured_delivery | block`.
 14. The Mode/Slice Decision must be visible and evidenced before any Quick Task execution, PRD shortcut or implementation. A decision value without scope reason and evidence is still missing.
+15. Missing or incomplete control state must not push setup work back to the user. For a fresh request, draft the current minimal artefact in the response and request the exact approval. Initialize or write `.agdf/control/` only when durable control state is explicitly requested, already live for the repository, or required for a deterministic CLI/CI setup path. Implementation remains forbidden.
 
 ## Gate Evaluation
 
@@ -107,6 +114,7 @@ If a status is not explicit, do not assume it is satisfied.
 8. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
 9. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
 10. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
+11. When `.agdf/control/` is missing or incomplete, make the next allowed artefact action explicit. For a fresh request, that means draft the minimal UR in the response, then request `Approval: UR`. Do not write a full control scaffold unless durable control state was explicitly requested or is already the repository's live AGDF working state.
 
 ## Output
 Keep the result short and operational:
@@ -118,6 +126,9 @@ Keep the result short and operational:
 - **Missing approval:** `Approval: <GateName> | none`
 - **Next step:** `<single permissible next step>`
 
+If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
+List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.
+
 ## Forbidden
 This skill must not:
 
@@ -133,5 +144,6 @@ This skill must not:
 - treat "ok", "leg los", "go ahead", "approved" or similar wording as gate approval
 - perform full Brownfield Analysis unless explicitly requested
 - provide implementation snippets while implementation is gated
+- paste full `.agdf/control/` files, templates or artefact bodies into the chat unless the user explicitly asks for the full content
 - present QA or UAT as passed without evidence
 - present release as allowed without QA pass and UAT approval where required

package/generated/.github/skills/agdf-runtime-contract.md

@@ -25,6 +25,21 @@ Use this compact output shape when no formal gate artefact is required:
 - `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.
@@ -43,6 +58,7 @@ When in doubt, use a short OR-lite only if it clarifies gate state, evidence, ri
 - 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.
@@ -137,6 +153,7 @@ Do not create a new node for a mere version, a general chat summary, or a local
 
 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.
@@ -147,12 +164,23 @@ When a repository needs durable AGDF state, use the plugin-local `control/` scaf
 
 The scaffold is not a second documentation site. Link to authoritative artefacts instead of copying them.
 
-## Native Runtime
+## 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:
 
-AGDF must work natively through the plugin router, skills and live `.agdf/control/` artefacts.
-Agents should read the live control state and apply the gate model directly before reaching for helper commands.
+- `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 commands such as `doctor --json`, `gate-check --json` and `delivery-map --json` are validators and automation interfaces.
+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

package/generated/AGENTS.md

@@ -72,11 +72,19 @@ 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 a native agent workflow first: read the live control state, apply the active skill and make the next allowed step explicit.
-Use `doctor`, `gate-check --json` or `delivery-map --json` as validators when a machine-readable proof is useful, not as a substitute for the router or skills.
+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
-After relevant code, documentation, skill or governance changes:
+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

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

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

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

@@ -8,6 +8,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 
 | File | Purpose |
 |---|---|
+| `config.json` | Project language preference for generated AGDF artefacts and user-facing chat |
 | `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
 | `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
@@ -26,6 +27,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 ```text
 .agdf/
   control/
+    config.json
     AGDF_RUN.md
     MASTER_BACKLOG.md
     artefacts/
@@ -64,6 +66,7 @@ npm create agdf@latest gate-check --json
 ## Operating Rules
 
 - `AGDF_RUN.md` is the current run dashboard.
+- `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
 - Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.

package/generated/plugins/agdf/hooks/session-start.sh

@@ -1,16 +1,20 @@
 #!/usr/bin/env bash
 # AGDF Session Start Hook
-# Loads the AGDF plugin router and constitution into the agent session.
+# Activates a compact AGDF runtime reminder for the agent session.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROUTER="${SCRIPT_DIR}/../meta/agdf-agent-router.md"
-CONSTITUTION="${SCRIPT_DIR}/../meta/agdf-constitution.md"
+META_DIR="$(cd "${SCRIPT_DIR}/../meta" && pwd)"
+ROUTER="${META_DIR}/agdf-agent-router.md"
+CONSTITUTION="${META_DIR}/agdf-constitution.md"
 
-if [ -f "$ROUTER" ]; then
-    cat "$ROUTER"
-    printf "\n\n"
-fi
+cat <<EOF
+AGDF active.
 
-if [ -f "$CONSTITUTION" ]; then
-    cat "$CONSTITUTION"
-fi
+Use the installed AGDF skills as workflow controls.
+For a new build, change, extension, refactor, CLI, app, fix with product semantics, unclear approval, or unclear next step, use gate-check before implementation or later-gate artefacts.
+
+Do not print the full router or constitution unless the user asks for them.
+Source of truth:
+- ${ROUTER}
+- ${CONSTITUTION}
+EOF

package/generated/plugins/agdf/meta/agdf-agent-router.md

@@ -73,11 +73,19 @@ 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 a native agent workflow first: read the live control state, apply the active skill and make the next allowed step explicit.
-Use `doctor`, `gate-check --json` or `delivery-map --json` as validators when a machine-readable proof is useful, not as a substitute for the router or skills.
+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
-After relevant code, documentation, skill or governance changes:
+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

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

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

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -25,6 +25,21 @@ Use this compact output shape when no formal gate artefact is required:
 - `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.
@@ -43,6 +58,7 @@ When in doubt, use a short OR-lite only if it clarifies gate state, evidence, ri
 - 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.
@@ -137,6 +153,7 @@ Do not create a new node for a mere version, a general chat summary, or a local
 
 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.
@@ -147,12 +164,23 @@ When a repository needs durable AGDF state, use the plugin-local `control/` scaf
 
 The scaffold is not a second documentation site. Link to authoritative artefacts instead of copying them.
 
-## Native Runtime
+## 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:
 
-AGDF must work natively through the plugin router, skills and live `.agdf/control/` artefacts.
-Agents should read the live control state and apply the gate model directly before reaching for helper commands.
+- `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 commands such as `doctor --json`, `gate-check --json` and `delivery-map --json` are validators and automation interfaces.
+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

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

@@ -21,9 +21,10 @@ This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or U
 Use `../../meta/agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
 The canonical gate order and transition model live only in the Runtime Contract. This skill evaluates the current state against that model; it must not maintain a second complete gate table.
 
-## Native Control Path
+## Agent-Native Control Path
 
-AGDF is applied natively through this skill, the agent router, and live `.agdf/control/` state.
+AGDF is agent-native first and CLI-verifiable by design.
+This skill is the primary operating path for gate judgement.
 
 First inspect the durable control state directly:
 
@@ -33,18 +34,23 @@ First inspect the durable control state directly:
 - `.agdf/control/CONTEXT_GRAPH.md`
 - `.agdf/control/AGENT_QUALITY_CONTRACTS.json`
 
-Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, or when a repository-local automation needs JSON evidence:
+If required control files are missing, do not automatically create a full `.agdf/control/` scaffold for a fresh small request.
+The default first action is to draft the minimal UR in the response and request `Approval: UR`.
+Use `init` 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.
+
+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
 ```
 
-`doctor` checks whether `.agdf/control/` is actionable. `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.
+`init` creates the control scaffold. `doctor` checks whether `.agdf/control/` is actionable. `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.
 `delivery-map` reports the durable delivery picture: active artefacts, approvals, Artefact Chain relationships, evidence refs, missing evidence, risks, Context Graph gate effect and machine-readable findings.
 
-The CLI reports are validators and JSON evidence, not the primary user experience and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
+The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
@@ -61,6 +67,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 12. Approval text and durable artefact presence are separate requirements for UR, PRD, SD, TP and QA report decisions. Approval text without the corresponding persisted or linked artefact keeps the current gate at that gate.
 13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | structured_slice | structured_delivery | block`.
 14. The Mode/Slice Decision must be visible and evidenced before any Quick Task execution, PRD shortcut or implementation. A decision value without scope reason and evidence is still missing.
+15. Missing or incomplete control state must not push setup work back to the user. For a fresh request, draft the current minimal artefact in the response and request the exact approval. Initialize or write `.agdf/control/` only when durable control state is explicitly requested, already live for the repository, or required for a deterministic CLI/CI setup path. Implementation remains forbidden.
 
 ## Gate Evaluation
 
@@ -107,6 +114,7 @@ If a status is not explicit, do not assume it is satisfied.
 8. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
 9. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
 10. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
+11. When `.agdf/control/` is missing or incomplete, make the next allowed artefact action explicit. For a fresh request, that means draft the minimal UR in the response, then request `Approval: UR`. Do not write a full control scaffold unless durable control state was explicitly requested or is already the repository's live AGDF working state.
 
 ## Output
 Keep the result short and operational:
@@ -118,6 +126,9 @@ Keep the result short and operational:
 - **Missing approval:** `Approval: <GateName> | none`
 - **Next step:** `<single permissible next step>`
 
+If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
+List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.
+
 ## Forbidden
 This skill must not:
 
@@ -133,5 +144,6 @@ This skill must not:
 - treat "ok", "leg los", "go ahead", "approved" or similar wording as gate approval
 - perform full Brownfield Analysis unless explicitly requested
 - provide implementation snippets while implementation is gated
+- paste full `.agdf/control/` files, templates or artefact bodies into the chat unless the user explicitly asks for the full content
 - present QA or UAT as passed without evidence
 - present release as allowed without QA pass and UAT approval where required

package/package.json

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