create-agdf

Bootstrap AGDF repository instructions and a machine-checkable control loop for one repository.

Usage

Preferred long-term CLI shape:

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
npx --yes @agdf/cli@latest opencode-status
npx --yes @agdf/cli@latest opencode-repo
npx --yes @agdf/cli@latest init
npx --yes @agdf/cli@latest config --language en
npx --yes @agdf/cli@latest doctor
npx --yes @agdf/cli@latest gate-check --status-card
npx --yes @agdf/cli@latest gate-check --json

Backward-compatible scaffold usage:

npm create agdf@latest -- codex
npm create agdf@latest -- codex-repo
npm create agdf@latest -- claude
npm create agdf@latest -- copilot
npm create agdf@latest -- opencode
npm create agdf@latest -- opencode-status
npm create agdf@latest -- opencode-repo
npm create agdf@latest -- both
npm create agdf@latest -- init
npm create agdf@latest -- config --language en
npm create agdf@latest -- doctor
npm create agdf@latest -- gate-check

Optional flags:

• --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

• codex installs the AGDF plugin globally for Codex
• codex-repo writes a repository-local Codex marketplace under .agents/plugins/ and a local AGDF plugin copy under plugins/agdf/
• claude installs the AGDF plugin globally for Claude Code
• copilot writes AGENTS.md, Copilot custom instructions under .github/, visible repository skills under .github/skills/, and AGDF control templates under .agdf/control/
• opencode installs the AGDF npm plugin as a user-wide OpenCode hook
• opencode-status reports OpenCode global config, package loadability, session signals and repository surface presence
• opencode-repo writes opencode.json, .opencode/AGDF.md, prefixed OpenCode agents under .opencode/agents/, explicit edit/bash permissions, and AGDF control templates under .agdf/control/
• both writes the Codex repository-local marketplace plus the Copilot-facing repository files
• config writes or updates only .agdf/control/config.json for an already installed plugin or an existing repository

If the target repository already has an AGENTS.md, create-agdf preserves it and writes AGENTS.agdf.md instead of replacing your existing instructions. Merge the AGDF fragment into your current AGENTS.md when you want Copilot to load both instruction sets. The generated .github/copilot-instructions.md keeps Copilot pointed at AGENTS.md, .github/skills/ and .agdf/control/ without duplicating the full AGDF rule model. Use --force only when you explicitly want to overwrite generated files.

Use the codex-repo target when AGDF should be available only inside one repository instead of being installed as a personal/global Codex plugin.

After npm create agdf@latest -- codex-repo, restart Codex in that repository, open /plugins, select This repository and install agdf.

Use the opencode target to install the AGDF npm plugin as a user-wide OpenCode hook:

npx --yes @agdf/cli@latest opencode

Then verify the visible installation state:

npx --yes @agdf/cli@latest opencode-status --json

The status command reports global configuration, whether create-agdf is loadable from the OpenCode config directory, whether the current process exposes AGDF session signals, and whether the current repository has .opencode/AGDF.md plus the agdf-gate-check surface. It does not infer an active OpenCode session from config alone.

Use the opencode-repo target when AGDF should be available to OpenCode from repository files:

npm create agdf@latest -- opencode-repo

OpenCode loads the AGDF npm plugin from global OpenCode config or repository opencode.json, AGENTS-style rules from .opencode/AGDF.md, explicit edit/bash permissions and the agdf- prefixed agents under .opencode/agents/. AGDF for OpenCode has two layers: a global npm plugin hook installed with npx --yes @agdf/cli@latest opencode and a repository-local governance surface generated by the opencode-repo target. Those generated agents use mode: subagent intentionally: they are internal governance-routing controls, not OpenCode Skills under .opencode/skills/ and not primary menu agents. Use @agdf-gate-check as the visible entry point for new build/change intent or unclear approval. If opencode.json already exists, AGDF keeps it unchanged and writes opencode.agdf.json as a merge fragment. Using OpenCode's plugin installer or global config for create-agdf can add the npm plugin hook, but AGDF still needs the repository instructions and agents. The opencode-repo target writes the repository files together.

Control scaffold

The generated .agdf/control/templates/ files are reusable starting points for durable AGDF state:

• runs/<run_id>/RUN_STATE.md for each canonical current run dashboard
• MASTER_BACKLOG.md for active delivery pointers
• templates/artefacts/ for durable UR, PRD, SD, TP and QA report artefact templates
• SOT_REGISTRY.md for one source of truth per domain
• 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 when the repository should own durable AGDF control state:

npm create agdf@latest -- init

This writes:

• .agdf/control/runs/<run_id>/RUN_STATE.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
• .agdf/control/templates/artefacts/TP.md
• .agdf/control/templates/artefacts/QA_REPORT.md
• .agdf/control/SOT_REGISTRY.md
• .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.

For a normal fresh request, init is not the required first move. The agent-native path can draft the minimal UR in the response and ask for the exact approval text Approval: UR. Write or initialize .agdf/control only when durable repository-owned control state is explicitly wanted, already in use, or needed for deterministic setup/CI evidence. Before Brownfield Review, later gates or implementation, AGDF still requires the persisted or linked artefacts named by the Runtime Contract.

For an existing repository where the plugin is already installed and only the language preference is missing or wrong, use the lighter config target:

npm create agdf@latest -- config --language en

Use doctor to check whether the live control state is actionable:

npm create agdf@latest -- doctor
npx --yes create-agdf@latest doctor --json

The doctor reports missing live control files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts. It exits non-zero only for blocking control failures.

Use gate-check to derive the next process decision from the selected canonical .agdf/control/runs/<run_id>/RUN_STATE.md. Use --run <run_id> or AGDF_RUN_ID when several runs are active:

npm create agdf@latest -- gate-check
npx --yes create-agdf@latest gate-check --json

The gate check reports open | blocked, the current gate, blocking reason, missing exact approval, allowed outputs, forbidden outputs, next allowed action, evidence references and the embedded doctor report.

Use gate-check --status-card for compact interactive output, especially in OpenCode where shell output is highly visible. Keep gate-check --json for automation, CI, regression evidence and audit trails.

Use delivery-path-search only for high-impact planning decisions with several materially different next steps:

npx --yes @agdf/cli@latest delivery-path-search --surface codex --json

The runtime uses bounded best-first Delivery Path Search, not MCTS. It is read-only and advisory: the result must be checked by canonical gate-check. Codex and Claude Code are executable, tool-enforced evaluator adapters and support opt-in --generate-candidates; generated proposals supplement the deterministic baseline and are deterministically validated before evaluation. Copilot and OpenCode reuse the same skill and contracts as instruction-only surfaces until conforming executable adapters are available.

Requirements and boundaries:

• run it only with selected canonical .agdf/control/runs/<run_id>/RUN_STATE.md state
• the current control state must expose legal next actions
• Codex CLI must be installed and authenticated for --surface codex
• Claude Code CLI must be installed and authenticated for --surface claude
• --model <id> optionally selects the Codex or Claude evaluator model
• --persist writes redacted DELIVERY_PATH_SEARCH.json and .md evidence under the current scope
• --fixture <path> is for deterministic contract tests, not a production evaluator
• Copilot and OpenCode have shared workflow mappings but no executable native evaluator in this release
• cost units are rubric values used for bounded comparison, not measured provider currency

The result is either one recommendation or no_safe_recommendation. In both cases run canonical gate-check afterwards.

gate-check --json and delivery-map --json also expose a status_card object. It is a compact projection of the current control state: current gate, allowed and forbidden actions, blocker, next skill, next permissible step and quality_outlook. next_step is process permission; quality_outlook is the next meaningful quality-improvement focus and does not unlock gates.

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, keep the path 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

The repository-facing AGDF sources are maintained in:

• plugin/meta/agdf-agent-router.md
• plugin/meta/agdf-plugin.definition.json
• plugin/skills/
• plugin/meta/agdf-runtime-contract.md
• plugin/control/

Skill routing is rendered from skillSet.slug, useFor, boundary and the target surface skillPrefix; it is not maintained as separate Codex, Claude Code and Copilot routing tables.

The published package assets are generated from these repository sources only at pack/publish time. The package does not keep a second manually maintained template tree.

npm run sync-package-assets

To verify the rendered routing locally, run:

npm run test:routing

The routing test installs both into a temporary target repository and checks that plugin routing stays unprefixed while Copilot routing receives the configured agdf- prefix.

Publishing

The repository publishes this package and the primary user-facing @agdf/cli wrapper as one coupled AGDF release. See the root RELEASE.md for the sequenced agdf-v<version> workflow and npm token requirements.

Trademark Notice

AGDF(TM) and AI Governance & Delivery Framework(TM) are marks of Arndt Gold. Use of the AGDF name and marks is governed by the project trademark guidelines.