@agdf/cli 0.3.4 → 0.4.0

package/README.md

@@ -13,17 +13,24 @@ GitHub Copilot and OpenCode.
 
 ## Quick Start
 
-Use the primary CLI when command semantics matter:
+Prepare one repository:
+
+```bash
+npx --yes @agdf/cli@latest codex
+npx --yes @agdf/cli@latest codex-repo
+npx --yes @agdf/cli@latest claude
+npx --yes @agdf/cli@latest opencode-repo
+npx --yes @agdf/cli@latest copilot
+```
+
+Install the user-wide OpenCode hook:
 
 ```bash
-npx --yes @agdf/cli@latest init
-npx --yes @agdf/cli@latest doctor
-npx --yes @agdf/cli@latest gate-check --json
 npx --yes @agdf/cli@latest opencode
 ```
 
-Install globally when AGDF should be available as a regular command on your
-machine:
+Install the AGDF CLI globally when `agdf` should be available as a regular
+shell command on your machine:
 
 ```bash
 npm install -g @agdf/cli
@@ -32,9 +39,6 @@ agdf doctor
 agdf gate-check --json
 ```
 
-`npm create agdf@latest -- ...` remains supported through the companion
-`create-agdf` package for scaffold-style setup flows.
-
 ## What This Package Does
 
 `@agdf/cli` is the stable user-facing wrapper. It delegates to `create-agdf`
@@ -46,5 +50,70 @@ Use it to:
 - install AGDF instructions and skills into a target repository
 - initialize durable `.agdf/control` state when a repository should own it
 - run deterministic validators such as `doctor` and `gate-check --json`
-- prepare Codex, Claude Code, GitHub Copilot or OpenCode surfaces from the same
-  source of truth
+- prepare Codex, GitHub Copilot and OpenCode surfaces from the same source of
+  truth while keeping Claude Code installation explicitly separate
+
+## Durable Control State
+
+When a repository owns live AGDF control state,
+`.agdf/control/MASTER_BACKLOG.md` is its human-readable steering view. It links
+active work to the current UR, Brownfield Review, PRD, SD, TP, QA and OR
+artefacts without turning the backlog into a second specification.
+
+- [View the canonical Master Backlog template](https://github.com/ArndtGold/ai-native-governance-delivery-framework/blob/main/plugin/control/templates/MASTER_BACKLOG.md)
+- [Read the durable control-state guide](https://github.com/ArndtGold/ai-native-governance-delivery-framework/blob/main/plugin/control/README.md)
+
+Each repository maintains its own live backlog. The linked template is the
+authoritative reusable format, not AGDF's internal project backlog.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `codex` | Install the AGDF plugin globally for Codex. |
+| `codex-repo` | Add a repository-local Codex marketplace and AGDF plugin copy. |
+| `claude` | Install the AGDF plugin globally for Claude Code. |
+| `opencode` | Install the AGDF npm plugin as a user-wide OpenCode hook. |
+| `opencode-repo` | Add OpenCode repository instructions, subagents, permissions and control templates. |
+| `copilot` | Add `AGENTS.md`, Copilot instructions, skills and control templates. |
+| `both` | Prepare the repository-file and plugin surfaces together. |
+| `init` | Create durable `.agdf/control` files when repository-owned control state is required. |
+| `config --language de\|en` | Persist the project language without creating the full control scaffold. |
+| `doctor [--json]` | Check whether the durable control state is consistent and actionable. |
+| `gate-check [--json]` | Report the current gate, blockers and next permitted action. |
+| `delivery-map [--json]` | Report artefact relationships, evidence, risks and Context Graph effects. |
+
+Examples:
+
+```bash
+npx --yes @agdf/cli@latest opencode
+npx --yes @agdf/cli@latest opencode-repo
+npx --yes @agdf/cli@latest config --language en
+npx --yes @agdf/cli@latest init
+npx --yes @agdf/cli@latest doctor
+npx --yes @agdf/cli@latest gate-check --json
+npx --yes @agdf/cli@latest delivery-map --json
+```
+
+The CLI validators provide deterministic evidence for agents and automation.
+They do not replace AGDF skill judgement or user approvals.
+
+## Surface Notes
+
+- **Codex:** `codex` installs the AGDF plugin globally for Codex, while
+  `codex-repo` prepares a repository-local marketplace for testing AGDF in one
+  repository.
+- **Claude Code:** `claude` installs the AGDF plugin globally for Claude Code.
+- **OpenCode:** `opencode` installs the user-wide npm plugin hook, while
+  `opencode-repo` writes the repository instructions, agents and permissions
+  AGDF needs. Repository instructions, generated agents and control files remain
+  the AGDF source of truth. The generated
+  OpenCode agents are intentional `mode: subagent` workflow controls, not
+  `.opencode/skills/` entries or primary menu agents; use `@agdf-gate-check`
+  as the visible entry point for new build/change intent.
+- **GitHub Copilot:** `copilot` writes repository instructions and skills. If
+  `AGENTS.md` already exists, AGDF preserves it and writes `AGENTS.agdf.md` for
+  manual merging.
+
+`npm create agdf@latest -- ...` remains supported through the companion
+`create-agdf` package for scaffold-style setup flows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agdf/cli",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Primary AGDF CLI for repository-local AI governance, delivery controls and agent setup.",
   "type": "module",
   "files": [
@@ -15,7 +15,7 @@
     "smoke-test": "node ./scripts/smoke-test.js"
   },
   "dependencies": {
-    "create-agdf": "0.3.4"
+    "create-agdf": "0.4.0"
   },
   "keywords": [
     "agdf",