create-agdf 0.1.3 → 0.1.5

package/README.md

@@ -5,6 +5,7 @@ Bootstrap AGDF repository instructions for one repository.
 ## Usage
 
 ```bash
+npm create agdf@latest codex
 npm create agdf@latest copilot
 npm create agdf@latest both
 ```
@@ -16,12 +17,15 @@ Optional flags:
 
 ## Targets and existing AGENTS.md
 
-- `copilot` writes `AGENTS.md`, visible repository skills under `.github/skills/`, and AGDF control templates under `.agdf/control/`
-- `both` writes the same Copilot-facing files and reminds you to install the Claude Code plugin separately
+- `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/`
+- `both` writes the Codex repository-local marketplace plus the Copilot-facing repository files
 
-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. Use `--force` only when you explicitly want to overwrite generated files.
+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.
 
-Codex is supported through the AGDF Codex plugin in `plugin/.codex-plugin/plugin.json`, not through `create-agdf` package output.
+Use the `codex` 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`, restart Codex in that repository, open `/plugins`, select `This repository` and install `agdf`.
 
 ## Control scaffold
 

package/bin/create-agdf.js

@@ -9,8 +9,31 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const generatedRoot = join(packageRoot, "generated");
 const pluginInstallCommand = "claude plugin add arndtgold/ai-native-governance-delivery-framework";
-const allowedTargets = new Set(["copilot", "both"]);
+const allowedTargets = new Set(["codex", "copilot", "both"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
+const codexPluginFiles = [
+  join(".agents", "plugins", "marketplace.json"),
+  join("plugins", "agdf", ".codex-plugin", "plugin.json"),
+  join("plugins", "agdf", "control", "README.md"),
+  join("plugins", "agdf", "control", "templates", "AGDF_RUN.md"),
+  join("plugins", "agdf", "control", "templates", "MASTER_BACKLOG.md"),
+  join("plugins", "agdf", "control", "templates", "SOT_REGISTRY.md"),
+  join("plugins", "agdf", "control", "templates", "CONTEXT_GRAPH.md"),
+  join("plugins", "agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  join("plugins", "agdf", "hooks", "hooks.json"),
+  join("plugins", "agdf", "hooks", "session-start.sh"),
+  join("plugins", "agdf", "meta", "agdf-constitution.md"),
+  join("plugins", "agdf", "meta", "agdf-runtime-contract.md"),
+  join("plugins", "agdf", "meta", "agdf-tenets.md"),
+  join("plugins", "agdf", "skills", "agdf-gate-check", "SKILL.md"),
+  join("plugins", "agdf", "skills", "agdf-brownfield-analysis", "SKILL.md"),
+  join("plugins", "agdf", "skills", "agdf-task-plan-review", "SKILL.md"),
+  join("plugins", "agdf", "skills", "agdf-clean-implementation-review", "SKILL.md"),
+  join("plugins", "agdf", "skills", "agdf-code-review", "SKILL.md"),
+  join("plugins", "agdf", "skills", "agdf-qa-gate", "SKILL.md"),
+  join("plugins", "agdf", "skills", "agdf-release-or", "SKILL.md"),
+  join("plugins", "agdf", "skills", "agdf-delivery-closeout", "SKILL.md"),
+];
 const controlFiles = [
   join(".agdf", "control", "README.md"),
   join(".agdf", "control", "templates", "AGDF_RUN.md"),
@@ -19,6 +42,10 @@ const controlFiles = [
   join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
 ];
+const copilotInstructionFiles = [
+  join(".github", "copilot-instructions.md"),
+  join(".github", "instructions", "agdf-governance.instructions.md"),
+];
 const copilotSkillFiles = [
   join(".github", "skills", "README.md"),
   join(".github", "skills", "agdf-runtime-contract.md"),
@@ -36,6 +63,7 @@ function printUsage() {
   console.log(`create-agdf
 
 Usage:
+  npm create agdf@latest codex
   npm create agdf@latest copilot
   npm create agdf@latest both
 
@@ -98,7 +126,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: copilot or both.");
+    console.error("Please choose one target: codex, copilot or both.");
     printUsage();
     process.exit(1);
   }
@@ -126,15 +154,24 @@ function writeGeneratedFile(targetDir, relativePath, content, force) {
 }
 
 function generatedFilesForTarget(target, targetDir, force) {
-  const agentsTargetPath = existsSync(join(targetDir, "AGENTS.md")) && !force ? agdfFragmentPath : "AGENTS.md";
-  const files = [
-    {
+  const files = [];
+
+  if (target === "codex" || target === "both") {
+    for (const codexPath of codexPluginFiles) {
+      files.push({
+        path: codexPath,
+        content: loadAsset(codexPath),
+      });
+    }
+  }
+
+  if (target === "copilot" || target === "both") {
+    const agentsTargetPath = existsSync(join(targetDir, "AGENTS.md")) && !force ? agdfFragmentPath : "AGENTS.md";
+    files.push({
       path: agentsTargetPath,
       content: loadAsset("AGENTS.md"),
-    },
-  ];
+    });
 
-  if (target === "copilot" || target === "both") {
     for (const controlPath of controlFiles) {
       files.push({
         path: controlPath,
@@ -142,6 +179,13 @@ function generatedFilesForTarget(target, targetDir, force) {
       });
     }
 
+    for (const instructionPath of copilotInstructionFiles) {
+      files.push({
+        path: instructionPath,
+        content: loadAsset(instructionPath),
+      });
+    }
+
     for (const skillPath of copilotSkillFiles) {
       files.push({
         path: skillPath,
@@ -167,8 +211,12 @@ function printNextSteps(target, destination, files, wroteAgentsFragment) {
   if (wroteAgentsFragment) {
     console.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
   }
+  if (target === "codex" || target === "both") {
+    console.log("- Restart Codex in this repository, open /plugins, select This repository and install agdf.");
+    console.log("- Start a new Codex thread in this repository and ask: Run an AGDF gate check for this request.");
+  }
   if (target === "both") {
-    console.log(`- Install the Claude Code plugin: ${pluginInstallCommand}`);
+    console.log(`- Optional global Claude Code install: ${pluginInstallCommand}`);
   }
   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.");

package/generated/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "agdf-repo",
+  "interface": {
+    "displayName": "This repository"
+  },
+  "plugins": [
+    {
+      "name": "agdf",
+      "source": {
+        "source": "local",
+        "path": "./plugins/agdf"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+# AGDF Copilot instructions
+
+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.
+- 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.
+- Do not treat chat history as the source of truth for gate state, approvals, evidence or delivery status.

package/generated/.github/instructions/agdf-governance.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "AGENTS.md,AGENTS.agdf.md,.agdf/**,.github/skills/**,.github/copilot-instructions.md,.github/instructions/**"
+---
+
+# AGDF governance artefacts
+
+These files are control artefacts, not general documentation.
+
+- Keep AGDF rules sourced from `AGENTS.md`, `.github/skills/` and `.github/skills/agdf-runtime-contract.md`.
+- Do not duplicate the full gate model, Quality Contract table or Context Graph relationship language in new files.
+- Keep generated AGDF files small, reviewable and linked to the owning source of truth.
+- Preserve the rule that missing approval, missing evidence or unclear ownership blocks later delivery steps.
+- If changing AGDF bootstrap behaviour, update the generated files, smoke test and affected setup documentation together.

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

@@ -0,0 +1,30 @@
+{
+  "name": "agdf",
+  "version": "0.1.5",
+  "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
+  "author": {
+    "name": "AI-native Governance & Delivery Framework",
+    "url": "https://agdf.iself.eu"
+  },
+  "homepage": "https://agdf.iself.eu",
+  "repository": "https://github.com/arndtgold/ai-native-governance-delivery-framework",
+  "license": "Apache-2.0",
+  "keywords": ["agentic", "governance", "delivery", "ai-native", "brownfield"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "AI Governance & Delivery Framework",
+    "shortDescription": "Codex-first workflow skills for gated, auditable AI-assisted delivery.",
+    "longDescription": "AI Governance & Delivery Framework (AGDF) packages reusable Codex-first skills and control templates for gate checks, Brownfield analysis, task-plan review, solution-integrity review, QA decisions, durable run state and auditable delivery closeout.",
+    "developerName": "AI-native Governance & Delivery Framework",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://agdf.iself.eu",
+    "defaultPrompt": [
+      "Run an AGDF gate check for this request.",
+      "Create an AGDF control scaffold for this repository.",
+      "Use AGDF Brownfield analysis before implementation.",
+      "Close this run with an AGDF orchestration report."
+    ],
+    "brandColor": "#14B8A6"
+  }
+}

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

@@ -0,0 +1,39 @@
+# AGDF Control Scaffold
+
+AGDF is primarily a control system for AI-assisted delivery. The skills guide the agent during a run; these files make the run state durable in a repository.
+
+Use this scaffold when a target repository should keep AGDF state outside chat history and tool memory.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `templates/AGDF_RUN.md` | Current run state: mode, gate, approvals, evidence, risks, next allowed action |
+| `templates/MASTER_BACKLOG.md` | Living backlog pointer: active initiatives and current UR/PRD/SD/TP artefacts |
+| `templates/SOT_REGISTRY.md` | Source-of-truth registry: one primary owner per domain |
+| `templates/CONTEXT_GRAPH.md` | Project memory: durable decisions, Brownfield findings, risks, evidence and exit criteria |
+| `templates/AGENT_QUALITY_CONTRACTS.json` | Machine-readable warning, revise and block contracts for review and QA |
+
+## Recommended Target Layout
+
+```text
+.agdf/
+  control/
+    AGDF_RUN.md
+    MASTER_BACKLOG.md
+    SOT_REGISTRY.md
+    CONTEXT_GRAPH.md
+    AGENT_QUALITY_CONTRACTS.json
+```
+
+Keep these files small and reviewable. They are control artefacts, not a second documentation site.
+
+## Operating Rules
+
+- `AGDF_RUN.md` is the current run dashboard.
+- `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
+- `SOT_REGISTRY.md` decides which document owns which domain.
+- `CONTEXT_GRAPH.md` records durable project knowledge only when it has evidence and an exit criterion.
+- `AGENT_QUALITY_CONTRACTS.json` names reusable block, revise and warning conditions.
+
+Do not duplicate full product documentation in this scaffold. Link to the authoritative artefact instead.

package/generated/plugins/agdf/control/templates/AGDF_RUN.md

@@ -0,0 +1,84 @@
+# AGDF Run State
+
+## Run Meta
+
+- run_id:
+- started_at:
+- mode: `quick_task | structured_delivery`
+- current_gate: `none | UR | PRD | SD | TP | CD+Tests | CR | QA | UAT | OR`
+- decision: `pass | revise | block | in_progress`
+- owner:
+
+## Objective
+
+What outcome is this run trying to make trustworthy?
+
+## Current Control State
+
+| Question | Answer |
+|---|---|
+| What is known? |  |
+| What is approved? |  |
+| What is missing? |  |
+| What is the next allowed action? |  |
+| What is explicitly forbidden right now? |  |
+
+## Approvals
+
+Valid approval format for new runs: `Approval: <GateName>`.
+
+| Gate | Status | Evidence |
+|---|---|---|
+| UR | `missing | approved | not_applicable` |  |
+| PRD | `missing | approved | not_applicable` |  |
+| SD | `missing | approved | not_applicable` |  |
+| TP | `missing | approved | not_applicable` |  |
+| QA | `missing | approved | not_applicable` |  |
+| UAT | `missing | approved | not_applicable` |  |
+
+## Artefacts
+
+| Type | Path | Status | Notes |
+|---|---|---|---|
+| UR |  | `draft | approved | superseded | not_applicable` |  |
+| PRD |  | `draft | approved | superseded | not_applicable` |  |
+| SD |  | `draft | approved | superseded | not_applicable` |  |
+| TP |  | `draft | approved | superseded | not_applicable` |  |
+| Review |  | `missing | done | not_applicable` |  |
+| QA |  | `missing | pass | revise | block | not_applicable` |  |
+| OR |  | `missing | done | not_applicable` |  |
+
+## Evidence
+
+| Evidence | Source | Covers | Strength |
+|---|---|---|---|
+|  |  |  | `direct | indirect | weak` |
+
+## Missing Evidence
+
+| Missing evidence | Impact | Required next step |
+|---|---|---|
+|  | `warn | revise | block` |  |
+
+## Risks
+
+| Risk | Impact | Mitigation or owner |
+|---|---|---|
+|  | `warn | revise | block` |  |
+
+## Context Graph Impact
+
+- 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:
+
+## Closeout
+
+- delivered:
+- not_delivered:
+- verification_performed:
+- unverified:
+- next_allowed_action:
+- quality_outlook:

package/generated/plugins/agdf/control/templates/AGENT_QUALITY_CONTRACTS.json

@@ -0,0 +1,78 @@
+{
+  "schema_version": "1",
+  "updated_at": "",
+  "contracts": [
+    {
+      "code": "AGDF_GATE_BYPASS",
+      "category": "agent_process",
+      "impact": "block",
+      "title": "Gate bypass",
+      "description": "A later artefact or implementation was produced without the required exact approval.",
+      "applies_to_modes": ["structured_delivery"],
+      "gate_effect": ["prd", "sd", "tp", "qa", "uat"],
+      "required_evidence": ["approval_log", "artifact_status"],
+      "evaluation": "review",
+      "owner": "governance"
+    },
+    {
+      "code": "AGDF_QA_WITHOUT_TASK_PLAN_REVIEW",
+      "category": "agent_process",
+      "impact": "block",
+      "title": "QA without task-plan review",
+      "description": "QA is evaluated for Structured Delivery without prior task-plan coverage evidence.",
+      "applies_to_modes": ["structured_delivery"],
+      "gate_effect": ["qa"],
+      "required_evidence": ["task_plan_review"],
+      "evaluation": "review",
+      "owner": "governance"
+    },
+    {
+      "code": "AGDF_PARALLEL_SOT",
+      "category": "architecture_integrity",
+      "impact": "block",
+      "title": "Parallel source of truth",
+      "description": "A second source of truth was introduced for product intent, runtime behavior, visible state, policy or persistent domain data.",
+      "applies_to_modes": ["structured_delivery", "quick_task"],
+      "gate_effect": ["prd", "sd", "tp", "qa"],
+      "required_evidence": ["brownfield_analysis", "source_of_truth_reference"],
+      "evaluation": "review",
+      "owner": "governance"
+    },
+    {
+      "code": "AGDF_DOC_IMPACT_UNCHECKED",
+      "category": "doc_spec_drift",
+      "impact": "revise",
+      "title": "Documentation or SoT impact unchecked",
+      "description": "A behavior, architecture, API, UX, policy or runtime change was completed without checking the affected source-of-truth artefacts.",
+      "applies_to_modes": ["structured_delivery", "quick_task"],
+      "gate_effect": ["qa"],
+      "required_evidence": ["sot_impact_review"],
+      "evaluation": "review",
+      "owner": "docs"
+    },
+    {
+      "code": "AGDF_TEST_SCOPE_UNCLEAR",
+      "category": "tp_coverage",
+      "impact": "revise",
+      "title": "Test scope unclear",
+      "description": "Tests were cited but are not traceable to affected acceptance criteria, tasks or risk paths.",
+      "applies_to_modes": ["structured_delivery", "quick_task"],
+      "gate_effect": ["qa"],
+      "required_evidence": ["test_result", "acceptance_mapping"],
+      "evaluation": "review",
+      "owner": "test"
+    },
+    {
+      "code": "AGDF_QUICK_TASK_EVIDENCE_LIGHT",
+      "category": "agent_process",
+      "impact": "warn",
+      "title": "Quick task evidence light",
+      "description": "A Quick Task has minimal evidence that may be acceptable for scope and risk but must remain visible.",
+      "applies_to_modes": ["quick_task"],
+      "gate_effect": ["none"],
+      "required_evidence": ["closeout_note"],
+      "evaluation": "review",
+      "owner": "governance"
+    }
+  ]
+}

package/generated/plugins/agdf/control/templates/CONTEXT_GRAPH.md

@@ -0,0 +1,51 @@
+# AGDF Context Graph
+
+This file keeps durable delivery knowledge discoverable. It is not a second PRD, SD or task plan.
+
+## Admission Rules
+
+A node belongs here only when it has:
+
+- concrete evidence
+- affected artefacts or paths
+- a visible risk, decision, invariant or reusable Brownfield finding
+- a next clean step
+- an exit criterion
+
+Do not add nodes for general opinions, one-off chat summaries or local observations without future decision value.
+
+## Node Index
+
+| ID | Type | Status | Title | Evidence | Next Step |
+|---|---|---|---|---|---|
+| CG-001 | `decision | brownfield_finding | quality_node | sot_invariant | cleanup_obligation | integration_surface` | `draft | active | resolved | superseded | rejected` |  |  |  |
+
+## Relationship Language
+
+| Relationship | Meaning |
+|---|---|
+| `derived_from` | An artefact was derived from another artefact |
+| `satisfies` | A task or implementation satisfies a requirement or acceptance criterion |
+| `tests` | A test checks a criterion or risk |
+| `mitigates` | Evidence reduces a risk |
+| `depends_on` | A decision or artefact depends on another |
+| `changes` | A requirement changes a component, artefact or behavior |
+| `supersedes` | A newer artefact replaces an older basis |
+| `blocks` | A defect or risk blocks a gate |
+| `approved_by` | An artefact was approved by a gate |
+| `evidenced_by` | A claim is backed by evidence |
+
+## Nodes
+
+### CG-001 Example
+
+- type:
+- status:
+- title:
+- introduced_by:
+- affects:
+- evidence:
+- risk_or_value:
+- next_clean_step:
+- exit_criterion:
+- links:

package/generated/plugins/agdf/control/templates/MASTER_BACKLOG.md

@@ -0,0 +1,29 @@
+# AGDF Master Backlog
+
+This file is the living control pointer for active AGDF delivery work. Detailed UR, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
+
+## Rules
+
+1. Keep only steering-relevant work in `Active Backlog`.
+2. Every active item has exactly one current spec pointer.
+3. Historical artefacts remain linkable but do not override the current pointer.
+4. If an item is superseded, mark the replacement.
+5. If active work grows beyond roughly ten items, triage the backlog.
+
+## Active Backlog
+
+| Prio | Key | Title | Status | Current Spec | Notes |
+|---:|---|---|---|---|---|
+| P1 |  |  | `in_progress | blocked` |  |  |
+
+## Planned / Parking Lot
+
+| Prio | Key | Title | Status | Current Spec | Notes |
+|---:|---|---|---|---|---|
+| P2 |  |  | `planned | review_needed` |  |  |
+
+## Completed / Superseded Pointers
+
+| Key | Title | Final Status | Current or Historical Link | Notes |
+|---|---|---|---|---|
+|  |  | `done | superseded | abandoned` |  |  |

package/generated/plugins/agdf/control/templates/SOT_REGISTRY.md

@@ -0,0 +1,25 @@
+# AGDF Source-of-Truth Registry
+
+Use this file to prevent parallel sources of truth. Each domain should have one primary owner.
+
+## Primary Sources of Truth
+
+| Domain | SoT Document | Status | Owner | Last Verified |
+|---|---|---|---|---|
+| Product intent |  | `active | draft | superseded` |  |  |
+| Architecture |  | `active | draft | superseded` |  |  |
+| Runtime contracts |  | `active | draft | superseded` |  |  |
+| UX / user flows |  | `active | draft | superseded` |  |  |
+| Operations / release |  | `active | draft | superseded` |  |  |
+
+## Secondary References
+
+Secondary references may support decisions, but they do not override the primary SoT.
+
+| Reference | Purpose | Limit |
+|---|---|---|
+|  |  |  |
+
+## Conflict Rule
+
+When a secondary document, generated output, old snapshot or chat summary conflicts with the primary SoT, the primary SoT wins until a new approved artefact changes it.

package/generated/plugins/agdf/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+    "hooks": {
+        "SessionStart": [
+            {
+                "hooks": [
+                    {
+                        "type":         "command",
+                        "command":      "bash -lc 'for hook in \"${CODEX_HOME:-$HOME/.codex}\"/plugins/cache/*/agdf/*/hooks/session-start.sh \"$PWD/plugins/agdf/hooks/session-start.sh\" \"$(dirname \"$0\")/session-start.sh\"; do [ -f \"$hook\" ] && exec bash \"$hook\"; done; exit 0'",
+                        "statusMessage": "Loading AGDF..."
+                    }
+                ]
+            }
+        ]
+    }
+}

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

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# AGDF Session Start Hook
+# Loads the AGDF constitution into the agent session.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONSTITUTION="${SCRIPT_DIR}/../meta/agdf-constitution.md"
+
+if [ -f "$CONSTITUTION" ]; then
+    cat "$CONSTITUTION"
+fi