create-agdf 0.9.1 → 0.9.5

package/lib/scaffold/plan.js

@@ -0,0 +1,278 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { generatedRoot, languageConfigContent, pluginDefinition } from "../cli/runtime-context.js";
+
+export const agdfFragmentPath = "AGENTS.agdf.md";
+export const openCodeConfigFragmentPath = "opencode.agdf.json";
+const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
+const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
+const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.skillPrefix}${skill.slug}`);
+const globalOpenCodeSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`);
+const contractModules = [
+  "gate-transition.md",
+  "interaction.md",
+  "modes.md",
+  "quality.md",
+  "context-graph.md",
+  "control-scaffold.md",
+  "closeout.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", "RUN_STATE.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", "control", "templates", "artefacts", "UR.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "PRD.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "SD.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "TP.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "OR.md"),
+  join("plugins", "agdf", "hooks", "hooks.json"),
+  join("plugins", "agdf", "hooks", "session-start.sh"),
+  join("plugins", "agdf", "meta", "agdf-agent-router.md"),
+  join("plugins", "agdf", "meta", "agdf-constitution.md"),
+  join("plugins", "agdf", "meta", "agdf-plugin.definition.json"),
+  join("plugins", "agdf", "meta", "agdf-runtime-contract.md"),
+  join("plugins", "agdf", "meta", "agdf-tenets.md"),
+  ...contractModules.map((moduleName) => join("plugins", "agdf", "meta", "contracts", moduleName)),
+  ...codexSkillNames.map((skillName) => join("plugins", "agdf", "skills", skillName, "SKILL.md")),
+];
+const controlFiles = [
+  join(".agdf", "control", "README.md"),
+  join(".agdf", "control", "templates", "AGDF_RUN.md"),
+  join(".agdf", "control", "templates", "RUN_STATE.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"),
+  join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
+  join(".agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
+  join(".agdf", "control", "templates", "artefacts", "PRD.md"),
+  join(".agdf", "control", "templates", "artefacts", "SD.md"),
+  join(".agdf", "control", "templates", "artefacts", "TP.md"),
+  join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
+  join(".agdf", "control", "templates", "artefacts", "OR.md"),
+];
+const liveControlFiles = [
+  {
+    path: join(".agdf", "control", "AGDF_RUN.md"),
+    source: join(".agdf", "control", "templates", "AGDF_RUN.md"),
+  },
+  {
+    path: join(".agdf", "control", "MASTER_BACKLOG.md"),
+    source: join(".agdf", "control", "templates", "MASTER_BACKLOG.md"),
+  },
+  {
+    path: join(".agdf", "control", "SOT_REGISTRY.md"),
+    source: join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
+  },
+  {
+    path: join(".agdf", "control", "CONTEXT_GRAPH.md"),
+    source: join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
+  },
+  {
+    path: join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json"),
+    source: join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  },
+];
+const artefactTemplateFiles = [
+  join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
+  join(".agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
+  join(".agdf", "control", "templates", "artefacts", "PRD.md"),
+  join(".agdf", "control", "templates", "artefacts", "SD.md"),
+  join(".agdf", "control", "templates", "artefacts", "TP.md"),
+  join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
+  join(".agdf", "control", "templates", "artefacts", "OR.md"),
+];
+export const doctorRequiredFiles = [
+  join(".agdf", "control", "AGDF_RUN.md"),
+  join(".agdf", "control", "MASTER_BACKLOG.md"),
+  join(".agdf", "control", "SOT_REGISTRY.md"),
+  join(".agdf", "control", "CONTEXT_GRAPH.md"),
+  join(".agdf", "control", "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", pluginDefinition.copilot.runtimeContractFileName),
+  ...contractModules.map((moduleName) => join(".github", "skills", "contracts", moduleName)),
+  ...copilotSkillNames.map((skillName) => join(".github", "skills", skillName, "SKILL.md")),
+];
+const openCodeFiles = [
+  join(".opencode", pluginDefinition.opencode.instructionsFileName),
+  join(".opencode", "README.md"),
+  join(".opencode", pluginDefinition.opencode.runtimeContractFileName),
+  ...contractModules.map((moduleName) => join(".opencode", "contracts", moduleName)),
+  ...openCodeSkillNames.map((skillName) => join(".opencode", "skills", skillName, "SKILL.md")),
+];
+
+function loadAsset(relativePath) {
+  return readFileSync(join(generatedRoot, relativePath), "utf8");
+}
+
+function isAgdfOwnedAgentsFile(content) {
+  return content.includes("## Surface Convention")
+    && content.includes("GitHub Copilot repository skills do not have a plugin namespace")
+    && content.includes("AGDF is agent-native first and CLI-verifiable by design");
+}
+
+function addCopilotAgentsFile(files, targetDir, force) {
+  const agentsPath = join(targetDir, "AGENTS.md");
+  if (!existsSync(agentsPath) || force) {
+    files.push({
+      path: "AGENTS.md",
+      content: loadAsset("AGENTS.md"),
+    });
+    return;
+  }
+
+  const existingAgents = readFileSync(agentsPath, "utf8");
+  if (isAgdfOwnedAgentsFile(existingAgents)) {
+    files.push({
+      path: "AGENTS.md",
+      content: loadAsset("AGENTS.md"),
+      allowOverwrite: true,
+      action: "refreshed",
+    });
+    return;
+  }
+
+  files.push({
+    path: agdfFragmentPath,
+    content: loadAsset("AGENTS.md"),
+    allowOverwrite: true,
+    action: "refreshed",
+    preserved: "AGENTS.md",
+  });
+}
+
+function shouldWriteLanguageConfig(target, targetDir, force) {
+  if (force) return true;
+  if ((target === "copilot" || target === "both") && existsSync(join(targetDir, ".agdf", "control", "config.json"))) return false;
+  return true;
+}
+
+function addLanguageConfig(files, languagePreference) {
+  files.push({
+    path: join(".agdf", "control", "config.json"),
+    content: languageConfigContent(languagePreference),
+  });
+}
+
+export function generatedFilesForTarget(target, targetDir, force, languagePreference) {
+  const files = [];
+
+  if (target === "config") {
+    files.push({
+      path: join(".agdf", "control", "config.json"),
+      content: languageConfigContent(languagePreference),
+      allowOverwrite: true,
+    });
+    return files;
+  }
+
+  if (target === "init") {
+    addLanguageConfig(files, languagePreference);
+    files.push({
+      path: join(".agdf", "control", "README.md"),
+      content: loadAsset(join(".agdf", "control", "README.md")),
+    });
+
+    for (const controlPath of liveControlFiles) {
+      files.push({
+        path: controlPath.path,
+        content: loadAsset(controlPath.source),
+      });
+    }
+
+    for (const templatePath of artefactTemplateFiles) {
+      files.push({
+        path: templatePath,
+        content: loadAsset(templatePath),
+      });
+    }
+
+    return files;
+  }
+
+  if (target === "codex-repo" || target === "both") {
+    if (shouldWriteLanguageConfig(target, targetDir, force)) addLanguageConfig(files, languagePreference);
+    for (const codexPath of codexPluginFiles) {
+      files.push({
+        path: codexPath,
+        content: loadAsset(codexPath),
+      });
+    }
+  }
+
+  if (target === "copilot" || target === "both") {
+    if (target !== "both" && shouldWriteLanguageConfig(target, targetDir, force)) addLanguageConfig(files, languagePreference);
+    addCopilotAgentsFile(files, targetDir, force);
+
+    for (const controlPath of controlFiles) {
+      files.push({
+        path: controlPath,
+        content: loadAsset(controlPath),
+        allowOverwrite: true,
+        action: "refreshed",
+      });
+    }
+
+    for (const instructionPath of copilotInstructionFiles) {
+      files.push({
+        path: instructionPath,
+        content: loadAsset(instructionPath),
+        allowOverwrite: true,
+        action: "refreshed",
+      });
+    }
+
+    for (const skillPath of copilotSkillFiles) {
+      files.push({
+        path: skillPath,
+        content: loadAsset(skillPath),
+        allowOverwrite: true,
+        action: "refreshed",
+      });
+    }
+  }
+
+  if (target === "opencode-repo") {
+    addLanguageConfig(files, languagePreference);
+    const openCodeConfigTargetPath = existsSync(join(targetDir, "opencode.json")) && !force ? openCodeConfigFragmentPath : "opencode.json";
+    files.push({
+      path: openCodeConfigTargetPath,
+      content: loadAsset("opencode.json"),
+    });
+
+    for (const openCodePath of openCodeFiles) {
+      files.push({
+        path: openCodePath,
+        content: loadAsset(openCodePath),
+      });
+    }
+
+    for (const controlPath of controlFiles) {
+      files.push({
+        path: controlPath,
+        content: loadAsset(controlPath),
+      });
+    }
+  }
+
+  return files;
+}
+

package/lib/scaffold/presentation.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pluginDefinition } from "../cli/runtime-context.js";
+import { printLifecycleResult } from "../lifecycle/presentation.js";
+import { createLifecycleResult } from "../lifecycle/result.js";
+import { agdfFragmentPath, openCodeConfigFragmentPath } from "./plan.js";
+
+const pluginInstallCommand = "npx --yes @agdf/cli@latest claude";
+
+export function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOpenCodeConfigFragment, removedOpenCodeAgents = [], io = console) {
+  io.log("");
+  io.log(`AGDF bootstrap complete in ${destination}`);
+  io.log("");
+  io.log("Generated:");
+  for (const file of files) {
+    const action = file.action ? `${file.action}: ` : "";
+    io.log(`- ${action}${file.path}`);
+  }
+
+  if (removedOpenCodeAgents.length > 0) {
+    io.log("");
+    io.log("Removed generated legacy OpenCode agents:");
+    for (const relativePath of removedOpenCodeAgents) io.log(`- ${relativePath}`);
+  }
+
+  const preservedFiles = [...new Set(files.map((file) => file.preserved).filter(Boolean))];
+  if (preservedFiles.length > 0) {
+    io.log("");
+    io.log("Preserved:");
+    for (const preserved of preservedFiles) io.log(`- ${preserved}`);
+  }
+
+  if (target === "codex-repo") {
+    const verified = files.every((file) => {
+      const path = join(destination, file.path);
+      return existsSync(path) && readFileSync(path, "utf8") === file.content;
+    });
+    printLifecycleResult(createLifecycleResult({
+      operation: "repository_setup",
+      result: verified ? "success" : "partial",
+      surface: "codex",
+      scope: "repository",
+      version: { expected: pluginDefinition.version, status: "expected" },
+      verification: { status: verified ? "healthy" : "degraded", evidence: files.map((file) => file.path) },
+      restart: { required: true, reason: "host_reload_and_repository_plugin_activation" },
+      next_action: {
+        kind: "host_action",
+        text: "Restart Codex, open /plugins, select This repository and install agdf; then start a new task with: Run an AGDF gate check for this request.",
+      },
+    }), { locale: JSON.parse(files.find((file) => file.path === join(".agdf", "control", "config.json"))?.content ?? "{}").chat_language, io });
+    return;
+  }
+
+  io.log("");
+  io.log("Next steps:");
+  const languageConfig = files.find((file) => file.path === join(".agdf", "control", "config.json"));
+  if (languageConfig) {
+    const language = JSON.parse(languageConfig.content);
+    io.log(`- AGDF language preference: artefacts=${language.artifact_language}, chat=${language.chat_language}, runtime=${language.runtime_language}.`);
+  }
+  if (target === "init") {
+    io.log("- Create or migrate a canonical run, then fill its RUN_STATE.md with the current gate, evidence and next allowed action.");
+    io.log("- Run npx --yes @agdf/cli@latest doctor to check the control state before the next agent run.");
+    io.log("- Commit the live control files once they represent the repository's current delivery state.");
+    return;
+  }
+  if (target === "config") {
+    io.log("- Restart or start a new agent session so the AGDF SessionStart hook reads the updated project language config.");
+    io.log("- Run npx --yes @agdf/cli@latest doctor when this repository also uses durable AGDF control state.");
+    return;
+  }
+  if (wroteAgentsFragment) {
+    io.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
+  }
+  if (target === "both") {
+    io.log("- Restart Codex in this repository, open /plugins, select This repository and install agdf.");
+    io.log("- Start a new Codex thread in this repository and ask: Run an AGDF gate check for this request.");
+  }
+  if (target === "both") {
+    io.log(`- Optional global Claude Code install: ${pluginInstallCommand}`);
+  }
+  if (target === "opencode-repo") {
+    if (wroteOpenCodeConfigFragment) {
+      io.log(`- Existing opencode.json detected. Review ${openCodeConfigFragmentPath} and merge its owned entries so OpenCode loads .opencode/AGDF.md; preserve an explicit permission.question decision.`);
+    }
+    io.log(`- OpenCode will install the ${pluginDefinition.opencode.npmPackage} npm plugin from opencode.json at startup.`);
+    io.log("- Optional: also add create-agdf to ~/.config/opencode/opencode.json plugin[] for a user-wide OpenCode hook.");
+    io.log("- The global hook does not replace repository instructions or native skills; this repository's .opencode files remain the AGDF source of truth.");
+    io.log("- Start OpenCode in this repository; it will load opencode.json, .opencode/AGDF.md and the native AGDF skills.");
+    io.log("- Load agdf-gate-check through OpenCode's native skill tool for new build/change intent or unclear approval before later artefacts or implementation.");
+    io.log("- Run npx --yes @agdf/cli@latest init when the repository needs live AGDF control files.");
+  }
+  if (target === "copilot" || target === "both") {
+    io.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.");
+    io.log("- Run npx --yes @agdf/cli@latest init when the repository needs live AGDF control files.");
+  }
+  io.log("- Commit the generated files so the repository becomes the source of truth.");
+}

package/lib/scaffold/write.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pluginDefinition } from "../cli/runtime-context.js";
+
+export function writeGeneratedFile(targetDir, relativePath, content, force, allowOverwrite = false) {
+  const outputPath = join(targetDir, relativePath);
+  mkdirSync(dirname(outputPath), { recursive: true });
+
+  if (existsSync(outputPath) && !force && !allowOverwrite) {
+    throw new Error(`Refusing to overwrite existing file: ${relativePath}. Re-run with --force if you want to replace it.`);
+  }
+
+  writeFileSync(outputPath, content, "utf8");
+}
+
+export function removeOwnedLegacyOpenCodeAgents(targetDir) {
+  const agentsDir = join(targetDir, ".opencode", "agents");
+  if (!existsSync(agentsDir)) return [];
+
+  const removed = [];
+  for (const skill of pluginDefinition.skillSet) {
+    const skillName = `${pluginDefinition.opencode.skillPrefix}${skill.slug}`;
+    const relativePath = join(".opencode", "agents", `${skillName}.md`);
+    const agentPath = join(targetDir, relativePath);
+    if (!existsSync(agentPath)) continue;
+
+    const content = readFileSync(agentPath, "utf8");
+    const ownedHeader = `---\ndescription: ${skill.useFor}\nmode: subagent\n---`;
+    if (!content.startsWith(ownedHeader) || !content.includes(`# ${skill.slug}`)) continue;
+
+    rmSync(agentPath);
+    removed.push(relativePath);
+  }
+
+  if (readdirSync(agentsDir).length === 0) rmSync(agentsDir, { recursive: true });
+  return removed;
+}
+
+export function assertGeneratedWritePlan(targetDir, files, force) {
+  const blocked = files.find((file) => existsSync(join(targetDir, file.path)) && !force && !file.allowOverwrite);
+  if (blocked) {
+    throw new Error(`Refusing to overwrite existing file: ${blocked.path}. Re-run with --force if you want to replace it.`);
+  }
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.9.1",
+  "version": "0.9.5",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
@@ -24,6 +24,8 @@
     "test:delivery-path-search": "node ./scripts/delivery-path-search-test.js",
     "test:delivery-path-search-unit": "node ./scripts/delivery-path-search-unit-test.js",
     "test:delivery-path-search-generator": "node ./scripts/delivery-path-search-generator-test.js",
+    "test:cli-modularization": "node ./scripts/cli-modularization-test.js",
+    "test:lifecycle": "node ./scripts/lifecycle-test.js",
     "test:control-state": "node ./scripts/control-state-test.js",
     "test:interaction-presentation": "node ./scripts/interaction-presentation-test.js",
     "test:verified-change": "node ./scripts/verified-change-test.js",
@@ -34,7 +36,7 @@
     "eval:skills:record": "node ./scripts/record-skill-evals.js",
     "test:release-bootstrap": "node ./scripts/release-bootstrap-smoke-test.js",
     "test:routing": "npm run sync-package-assets && node ./scripts/test-routing.js",
-    "smoke-test": "npm run sync-package-assets && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:skill-evals && npm run eval:skills && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
+    "smoke-test": "npm run sync-package-assets && npm run test:cli-modularization && npm run test:lifecycle && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:skill-evals && npm run eval:skills && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
     "prepack": "npm run sync-package-assets"
   },
   "keywords": [