create-agdf 0.2.9 → 0.3.0

package/README.md

@@ -4,6 +4,19 @@ 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
@@ -136,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

@@ -124,7 +124,14 @@ const openCodeFiles = [
 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
@@ -135,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
@@ -428,13 +439,13 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
   }
   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) {
@@ -454,11 +465,11 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
     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.");
+    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.");
 }
@@ -562,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.",
     );
   }
 
@@ -1177,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.";

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/agents/agdf-gate-check.md

@@ -46,10 +46,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/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "author": {
     "name": "AI-native Governance & Delivery Framework",
@@ -20,6 +20,8 @@
     "category": "Productivity",
     "capabilities": ["Read", "Write"],
     "websiteURL": "https://agdf.iself.eu",
+    "composerIcon": "./assets/agdf-icon.svg",
+    "logo": "./assets/agdf-logo.svg",
     "defaultPrompt": [
       "Run an AGDF gate check for this request.",
       "Create an AGDF control scaffold for this repository.",

package/generated/plugins/agdf/assets/agdf-icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="AGDF">
+  <defs>
+    <linearGradient id="agdf-bg" x1="10" y1="6" x2="54" y2="58" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#0F766E"/>
+      <stop offset="1" stop-color="#2563EB"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="#06131F"/>
+  <rect x="4" y="4" width="56" height="56" rx="12" fill="url(#agdf-bg)"/>
+  <path d="M32 10.5 50 21v22L32 53.5 14 43V21L32 10.5Z" fill="none" stroke="#ECFEFF" stroke-width="5" stroke-linejoin="round"/>
+  <path d="M32 21v13m0 0-10 6m10-6 10 6" fill="none" stroke="#ECFEFF" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="32" cy="21" r="5.3" fill="#ECFEFF"/>
+  <circle cx="32" cy="34" r="5.6" fill="#ECFEFF"/>
+  <circle cx="22" cy="40" r="5.3" fill="#ECFEFF"/>
+  <circle cx="42" cy="40" r="5.3" fill="#ECFEFF"/>
+</svg>

package/generated/plugins/agdf/assets/agdf-logo.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="AGDF">
+  <defs>
+    <linearGradient id="agdf-logo-bg" x1="80" y1="48" x2="432" y2="464" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#0F766E"/>
+      <stop offset="1" stop-color="#2563EB"/>
+    </linearGradient>
+  </defs>
+  <rect width="512" height="512" rx="112" fill="#06131F"/>
+  <rect x="32" y="32" width="448" height="448" rx="96" fill="url(#agdf-logo-bg)"/>
+  <path d="M256 84 400 168v176L256 428 112 344V168L256 84Z" fill="none" stroke="#ECFEFF" stroke-width="40" stroke-linejoin="round"/>
+  <path d="M256 168v104m0 0-80 48m80-48 80 48" fill="none" stroke="#ECFEFF" stroke-width="32" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="256" cy="168" r="42" fill="#ECFEFF"/>
+  <circle cx="256" cy="272" r="45" fill="#ECFEFF"/>
+  <circle cx="176" cy="320" r="42" fill="#ECFEFF"/>
+  <circle cx="336" cy="320" r="42" fill="#ECFEFF"/>
+</svg>

package/generated/plugins/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/plugins/agdf/hooks/session-start.sh

@@ -8,7 +8,7 @@ ROUTER="${META_DIR}/agdf-agent-router.md"
 CONSTITUTION="${META_DIR}/agdf-constitution.md"
 CONFIG_PATH="${PWD}/.agdf/control/config.json"
 
-CONFIG_HINT="Project config: .agdf/control/config.json not found. Use npm create agdf@latest -- config --language de|en to persist the project language."
+CONFIG_HINT="Project config: .agdf/control/config.json not found. Use npx --yes agdf@latest config --language de|en to persist the project language."
 if [[ -f "${CONFIG_PATH}" ]]; then
   CONFIG_HINT="$(CONFIG_PATH="${CONFIG_PATH}" node <<'NODE' 2>/dev/null || true
 const fs = require("node:fs");
@@ -20,7 +20,7 @@ try {
   const runtime = config.runtime_language || "en";
   console.log(`Project config: .agdf/control/config.json (artefacts=${artefacts}, chat=${chat}, runtime=${runtime}).`);
 } catch {
-  console.log("Project config: .agdf/control/config.json exists but is not valid JSON. Run npm create agdf@latest -- doctor.");
+  console.log("Project config: .agdf/control/config.json exists but is not valid JSON. Run npx --yes agdf@latest doctor.");
 }
 NODE
 )"

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
@@ -22,6 +22,8 @@
     "skills": "./skills/",
     "skillPrefix": "",
     "agentRouter": "meta/agdf-agent-router.md",
+    "composerIcon": "./assets/agdf-icon.svg",
+    "logo": "./assets/agdf-logo.svg",
     "capabilities": ["Read", "Write"],
     "defaultPrompt": [
       "Run an AGDF gate check for this request.",

package/generated/plugins/agdf/skills/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. `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/opencode-plugin.js

@@ -24,7 +24,7 @@ export const AGDFPlugin = async ({ directory, client }) => {
         "## AGDF Runtime Reminder",
         "Use `.opencode/AGDF.md`, `.opencode/agents/` and `.agdf/control/` as the AGDF source for this OpenCode session.",
         "For new build/change intent or unclear approval, route first to `agdf-gate-check` before later artefacts or implementation.",
-        "Use `npx --yes create-agdf@latest gate-check --json` only as deterministic proof, not as a replacement for AGDF judgement.",
+        "Use `npx --yes agdf@latest gate-check --json` only as deterministic proof, not as a replacement for AGDF judgement.",
       ].join("\n"));
     },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
@@ -12,6 +12,7 @@
   ],
   "exports": {
     ".": "./opencode-plugin.js",
+    "./cli": "./bin/create-agdf.js",
     "./opencode-plugin": "./opencode-plugin.js"
   },
   "bin": {