create-agdf 0.1.2 → 0.1.4

package/README.md

@@ -1,10 +1,11 @@
 # create-agdf
 
-Bootstrap AGDF for one repository.
+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,18 +17,36 @@ Optional flags:
 
 ## Targets and existing AGENTS.md
 
-- `copilot` writes `AGENTS.md` and visible repository skills under `.github/skills/`
-- `both` writes the same Copilot-facing files and reminds you to install the Claude 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`, visible repository skills under `.github/skills/`, and AGDF control templates under `.agdf/control/`
+- `both` writes the Codex project 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.
 
+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 the project marketplace and install `agdf`.
+
+## Control scaffold
+
+The generated `.agdf/control/templates/` files are starting points for durable AGDF state:
+
+- `AGDF_RUN.md` for the current run dashboard
+- `MASTER_BACKLOG.md` for active delivery pointers
+- `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
+
+Copy or promote templates into live `.agdf/control/` files only when the target repository is ready to own them as source-of-truth artefacts.
+
 ## Single source of truth
 
 The repository-facing AGDF sources are maintained in:
 
-- `AGENTS.md`
+- `plugin/meta/agdf-copilot-agents.md`
 - `plugin/skills/`
 - `plugin/meta/agdf-runtime-contract.md`
+- `plugin/control/`
 
 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.
 

package/bin/create-agdf.js

@@ -9,8 +9,35 @@ 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", "meta", "agdf-runtime-contract.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"),
+  join(".agdf", "control", "templates", "MASTER_BACKLOG.md"),
+  join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
+  join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
+  join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+];
 const copilotSkillFiles = [
   join(".github", "skills", "README.md"),
   join(".github", "skills", "agdf-runtime-contract.md"),
@@ -28,6 +55,7 @@ function printUsage() {
   console.log(`create-agdf
 
 Usage:
+  npm create agdf@latest codex
   npm create agdf@latest copilot
   npm create agdf@latest both
 
@@ -90,7 +118,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);
   }
@@ -118,15 +146,31 @@ 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"),
-    },
-  ];
+    });
+
+    for (const controlPath of controlFiles) {
+      files.push({
+        path: controlPath,
+        content: loadAsset(controlPath),
+      });
+    }
 
-  if (target === "copilot" || target === "both") {
     for (const skillPath of copilotSkillFiles) {
       files.push({
         path: skillPath,
@@ -152,11 +196,16 @@ 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 the project marketplace 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.");
+    console.log("- Copy the templates under .agdf/control/templates into live control files when the repository needs a durable run state, backlog pointer, SoT registry or context graph.");
   }
   console.log("- Commit the generated files so the repository becomes the source of truth.");
 }

package/generated/.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/.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/.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/.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/.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/.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/.agents/plugins/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "agdf-project",
+  "plugins": [
+    {
+      "name": "agdf",
+      "source": {
+        "source": "local",
+        "path": "./plugins/agdf"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

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

@@ -53,6 +53,18 @@ When a run affects project memory or a Context Graph, use:
 Do not create a new node for a mere version, a general chat summary, or a local observation without a concrete next clean step.
 `sot_drift` must not pass silently as a warning.
 
+## Control Scaffold
+
+When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
+
+- `AGDF_RUN.md` is the current run dashboard.
+- `MASTER_BACKLOG.md` is the living pointer for active delivery work.
+- `SOT_REGISTRY.md` prevents parallel sources of truth.
+- `CONTEXT_GRAPH.md` stores durable Brownfield findings, decisions, risks, evidence and exit criteria.
+- `AGENT_QUALITY_CONTRACTS.json` stores reusable block, revise and warning conditions.
+
+The scaffold is not a second documentation site. Link to authoritative artefacts instead of copying them.
+
 ## Skill Output
 
 Every skill output should be as short as possible and as concrete as needed.

package/generated/AGENTS.md

@@ -57,6 +57,18 @@ the repository-local `agdf-runtime-contract.md` artifact.
 
 Skills may include short runtime reminders, but must not carry a second complete rule or code table.
 
+## Durable Control State
+When this repository uses the AGDF control scaffold, keep live control files under `.agdf/control/`.
+Use the templates as starting points only:
+
+- `.agdf/control/templates/AGDF_RUN.md`
+- `.agdf/control/templates/MASTER_BACKLOG.md`
+- `.agdf/control/templates/SOT_REGISTRY.md`
+- `.agdf/control/templates/CONTEXT_GRAPH.md`
+- `.agdf/control/templates/AGENT_QUALITY_CONTRACTS.json`
+
+Do not let chat history become the source of truth for gate state, approvals, evidence, backlog status or durable Brownfield knowledge.
+
 ## Closeout
 After relevant code, documentation, skill, or governance changes:
 - run relevant checks or state the test gap

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

@@ -0,0 +1,30 @@
+{
+  "name": "agdf",
+  "version": "0.1.4",
+  "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.