create-agdf 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# create-agdf
+
+Bootstrap AGDF for one repository.
+
+## Usage
+
+```bash
+npm create agdf@latest copilot
+npm create agdf@latest claude
+npm create agdf@latest both
+```
+
+Optional flags:
+
+- `--dir <path>` write into a specific directory
+- `--force` overwrite existing generated files
+
+## Targets
+
+- `copilot` writes `AGENTS.md` and `.github/copilot-instructions.md`
+- `claude` writes `AGENTS.md` and prints the Claude plugin installation step
+- `both` writes both instruction files and prints both next steps
+
+## Publishing
+
+The repository publishes this package from `create-agdf/` via the GitHub Actions workflow `.github/workflows/publish-create-agdf.yml`.
+
+- 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

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const templatesRoot = join(packageRoot, "templates");
+const pluginInstallCommand = "claude plugin add arndtgold/ai-native-governance-delivery-framework";
+const allowedTargets = new Set(["copilot", "claude", "both"]);
+
+function printUsage() {
+  console.log(`create-agdf
+
+Usage:
+  npm create agdf@latest copilot
+  npm create agdf@latest claude
+  npm create agdf@latest both
+
+Options:
+  --dir <path>   Write files into a specific directory
+  --force        Overwrite existing generated files
+  --help         Show this help
+`);
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  let target;
+  let dir = ".";
+  let force = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg) continue;
+
+    if (arg === "--help" || arg === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+
+    if (arg === "--dir") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error("Missing value for --dir");
+        process.exit(1);
+      }
+      dir = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--target" || arg === "-t") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error("Missing value for --target");
+        process.exit(1);
+      }
+      target = next;
+      i += 1;
+      continue;
+    }
+
+    if (!arg.startsWith("-") && !target) {
+      target = arg;
+      continue;
+    }
+
+    console.error(`Unknown argument: ${arg}`);
+    process.exit(1);
+  }
+
+  if (!target || !allowedTargets.has(target)) {
+    console.error("Please choose one target: copilot, claude, or both.");
+    printUsage();
+    process.exit(1);
+  }
+
+  return {
+    target,
+    dir: resolve(process.cwd(), dir),
+    force,
+  };
+}
+
+function loadTemplate(relativePath) {
+  return readFileSync(join(templatesRoot, relativePath), "utf8");
+}
+
+function writeGeneratedFile(targetDir, relativePath, content, force) {
+  const outputPath = join(targetDir, relativePath);
+  mkdirSync(dirname(outputPath), { recursive: true });
+
+  if (existsSync(outputPath) && !force) {
+    throw new Error(`Refusing to overwrite existing file: ${relativePath}. Re-run with --force if you want to replace it.`);
+  }
+
+  writeFileSync(outputPath, content, "utf8");
+}
+
+function generatedFilesForTarget(target) {
+  const files = [
+    {
+      path: "AGENTS.md",
+      content: loadTemplate("AGENTS.md"),
+    },
+  ];
+
+  if (target === "copilot" || target === "both") {
+    files.push({
+      path: join(".github", "copilot-instructions.md"),
+      content: loadTemplate(join(".github", "copilot-instructions.md")),
+    });
+  }
+
+  return files;
+}
+
+function printNextSteps(target, destination, files) {
+  console.log("");
+  console.log(`AGDF bootstrap complete in ${destination}`);
+  console.log("");
+  console.log("Generated:");
+  for (const file of files) {
+    console.log(`- ${file.path}`);
+  }
+
+  console.log("");
+  console.log("Next steps:");
+  if (target === "claude" || target === "both") {
+    console.log(`- Install the Claude Code plugin: ${pluginInstallCommand}`);
+  }
+  if (target === "copilot" || target === "both") {
+    console.log("- In GitHub Copilot CLI, run /instructions to confirm that the repository instructions are loaded.");
+  }
+  console.log("- Commit the generated files so the repository becomes the source of truth.");
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const files = generatedFilesForTarget(options.target);
+
+  try {
+    for (const file of files) {
+      writeGeneratedFile(options.dir, file.path, file.content, options.force);
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  printNextSteps(options.target, options.dir, files);
+}
+
+main();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "create-agdf",
+  "version": "0.1.0",
+  "description": "Bootstrap AGDF for GitHub Copilot, Claude Code, or both.",
+  "type": "module",
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "bin": {
+    "create-agdf": "./bin/create-agdf.js"
+  },
+  "scripts": {
+    "smoke-test": "node ./scripts/smoke-test.js"
+  },
+  "keywords": [
+    "agdf",
+    "copilot",
+    "claude-code",
+    "scaffold",
+    "bootstrap"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArndtGold/ai-native-governance-delivery-framework.git",
+    "directory": "create-agdf"
+  },
+  "homepage": "https://github.com/ArndtGold/ai-native-governance-delivery-framework/tree/main/create-agdf"
+}

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

@@ -0,0 +1,31 @@
+# AGDF for GitHub Copilot
+
+This repository supports GitHub Copilot CLI and the Copilot Coding Agent through checked-in repository instructions.
+
+## Primary instruction sources
+
+1. Follow `AGENTS.md` as the main operating model.
+2. Use `plugin/meta/agdf-runtime-contract.md` for repeated gate, quality-contract, and closeout output rules when this repository also contains the AGDF runtime files.
+3. Reuse the AGDF skill names as prompt entrypoints: `agdf-gate-check`, `agdf-brownfield-analysis`, `agdf-task-plan-review`, `agdf-clean-implementation-review`, `agdf-qa-gate`, `agdf-release-or`, `agdf-delivery-closeout`.
+
+## Working mode
+
+- Default to **Quick Task Mode** for small questions, reviews, debugging, and local fixes without new product semantics.
+- Escalate to **Structured Delivery Mode** for new capabilities, architecture or policy changes, persistence changes, release-critical work, or formal artefacts.
+
+## Copilot prompt entrypoints
+
+Use natural-language prompts such as:
+
+- `Run an AGDF gate check for this request.`
+- `Perform an AGDF brownfield analysis before implementation.`
+- `Review the completed work against the AGDF task plan expectations.`
+- `Make the AGDF QA gate decision from the available evidence.`
+
+## Rules
+
+- Respect the gate order and exact approval formula from `AGENTS.md`.
+- Do not treat implicit consent as approval.
+- Prefer evidence over assumptions.
+- In brownfield work, reuse before create and avoid silent parallel structures.
+- After relevant work, include exactly one `Next step:` and exactly one `Quality outlook:`.

package/templates/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+## Role
+You are an autonomous agent operating in an AGDF-governed delivery system.
+Your goal is not to produce answers. Your goal is to create trustworthy progress:
+reduce uncertainty, establish evidence, maintain artefacts, verify outcomes, and make the next step explicit.
+
+## Operating Modes
+| Mode | Use When | Required |
+|---|---|---|
+| Quick Task Mode | Questions, short reviews, local debugging, small fixes without new product semantics | Understand the local context, cite evidence, run relevant checks or name the gap, close briefly |
+| Structured Delivery Mode | New user capability, architecture/policy/persistence impact, release-critical work, formal artefacts, or explicit approvals | Respect gates, separate artefacts, make internal reviews visible, do not merge QA and OR |
+
+Quick Task Mode remains the default unless the request creates new product scope or asks for formal gate artefacts.
+
+## Operating Model
+Work in this order:
+
+`Uncertainty Reduction -> Evidence -> Artefacts -> Verification -> Outcome`
+
+Evidence overrides assumptions and memory. If evidence is missing, state the uncertainty instead of smoothing it over.
+
+## Gates
+- User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`.
+- A user approval is valid only in this exact format: `Approval: <GateName>`.
+- Legacy German runs may be interpreted if they use `Freigabe: <GateName>`, but new artefacts must show `Approval: <GateName>`.
+- Implicit consent such as `ok`, `go`, `approved`, or similar wording is not approval.
+- Internal mandatory steps: `Brownfield Analysis -> CD+Tests -> CR -> OR`.
+- `CD+Tests` is not a done, QA, or release signal.
+- `agdf-qa-gate` is the only final QA decision for `pass | revise | block`.
+- `agdf-release-or` is mandatory at the end of relevant runs.
+
+## Brownfield Rules
+- Brownfield is the normal case.
+- Before non-trivial implementation in an existing system, inspect existing artefacts, ownership, behaviour, and tests.
+- Reuse-before-create and minimal clean slice take precedence over new structure.
+- No silent parallel structures, no second SoT, no unjustified fallbacks.
+- SoT/runtime/product-semantics drift must be named explicitly and can trigger an early product gate.
+
+## Skill Routing
+| Skill | Use For | Boundary |
+|---|---|---|
+| `agdf-gate-check` | unclear approval, Structured Delivery, later-gate artefact requested | does not create later artefacts |
+| `agdf-brownfield-analysis` | before non-trivial implementation in existing systems | clarifies reuse, owners, risks |
+| `agdf-task-plan-review` | after implementation and before QA, verify TP coverage | no final QA decision |
+| `agdf-clean-implementation-review` | inspect workarounds, fallbacks, parallel structures, or symptom fixes | not a TP or QA substitute |
+| `agdf-qa-gate` | final QA decision | only instance for `pass | revise | block` |
+| `agdf-release-or` | auditable closeout for every relevant run | not a QA substitute |
+| `agdf-delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
+
+Select exactly one primary skill first. Add more only when they cover a distinct concrete risk dimension.
+
+## Skill Contract
+For repeated output, gate, Quality Contract, and Context Graph rules, use:
+`plugin/meta/agdf-runtime-contract.md`
+
+Skills may include short runtime reminders, but must not carry a second complete rule or code table.
+
+## Closeout
+After relevant code, documentation, skill, or governance changes:
+- run relevant checks or state the test gap
+- never commit, push, or open a PR automatically
+- include exactly one `Next step:`
+- include exactly one `Quality outlook:`