qfai 1.4.7 → 1.4.9

package/README.md

@@ -207,7 +207,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.4.7)
+## Minimal tutorial (v1.4.9)
 
 1. `npx qfai init`
 2. Run `/qfai-discuss` to structure scope and open questions.
@@ -233,7 +233,9 @@ Release gate behavior:
 
 ## Continuous integration
 
-QFAI v1.4.7 no longer generates `.github/**` assets.
+QFAI v1.4.9 generates `.github/**` only for Copilot integration wrappers
+(`.github/prompts`, `.github/agents`).
+It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:
 
 ```bash
@@ -348,10 +350,17 @@ Typical customizations.
 └── qfai.config.yaml
 ```
 
+Integration wrappers are also generated for immediate use:
+
+- Claude Code: `.claude/commands/**`, `.claude/agents/**`
+- GitHub Copilot: `.github/prompts/**`, `.github/agents/**`
+- Codex: `.codex/skills/**`
+
 ## Agent integrations
 
-`npx qfai init` installs only canonical skills under `.qfai/assistant/skills/**`.
-If your toolchain needs wrapper files, manage them in your own repository convention and keep `.qfai/assistant/skills/**` as SSOT.
+`npx qfai init` installs canonical skills under `.qfai/assistant/skills/**` (SSOT)
+and generates thin wrapper assets for Copilot / Claude Code / Codex.
+If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
 
 ## Contributing (for QFAI maintainers)
 

package/dist/cli/index.cjs

@@ -1218,8 +1218,8 @@ var import_promises7 = require("fs/promises");
 var import_node_path8 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 async function resolveToolVersion() {
-  if ("1.4.7".length > 0) {
-    return "1.4.7";
+  if ("1.4.9".length > 0) {
+    return "1.4.9";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -2400,11 +2400,12 @@ async function runInit(options) {
   const assetsRoot = getInitAssetsDir();
   const rootAssets = import_node_path14.default.join(assetsRoot, "root");
   const qfaiAssets = import_node_path14.default.join(assetsRoot, ".qfai");
+  const assistantAssets = import_node_path14.default.join(qfaiAssets, "assistant");
   const destRoot = import_node_path14.default.resolve(options.dir);
   const destQfai = import_node_path14.default.join(destRoot, ".qfai");
   if (options.force) {
     info(
-      "NOTE: --force \u306F .qfai/assistant/skills/** \u3092\u4E0A\u66F8\u304D\u3057\u3001legacy 10_workflow.md \u3092\u524A\u9664\u3057\u307E\u3059\uFF08skills.local \u306F\u4FDD\u8B77\u3055\u308C\u3001specs/contracts \u7B49\u306F\u4E0A\u66F8\u304D\u3057\u307E\u305B\u3093\uFF09\u3002"
+      "NOTE: --force \u306F .qfai/assistant/skills/** \u3068 wrapper assets\uFF08.claude/.github/.codex\uFF09\u3092\u4E0A\u66F8\u304D\u3057\u3001legacy 10_workflow.md \u3092\u524A\u9664\u3057\u307E\u3059\uFF08skills.local \u306F\u4FDD\u8B77\u3055\u308C\u3001specs/contracts \u7B49\u306F\u4E0A\u66F8\u304D\u3057\u307E\u305B\u3093\uFF09\u3002"
     );
   }
   const rootResult = await copyTemplateTree(rootAssets, destRoot, {
@@ -2430,11 +2431,30 @@ async function runInit(options) {
       protect: ["assistant/skills.local"]
     }
   );
+  const wrappersResult = await syncIntegrationWrappers(
+    assistantAssets,
+    destRoot,
+    {
+      force: options.force,
+      dryRun: options.dryRun
+    }
+  );
   const removedLegacySkills = options.force ? await pruneLegacySkillFiles(destRoot, options.dryRun) : [];
+  const removed = [...removedLegacySkills, ...wrappersResult.removed];
   report(
-    [...rootResult.copied, ...qfaiResult.copied, ...skillsResult.copied],
-    [...rootResult.skipped, ...qfaiResult.skipped, ...skillsResult.skipped],
-    removedLegacySkills,
+    [
+      ...rootResult.copied,
+      ...qfaiResult.copied,
+      ...skillsResult.copied,
+      ...wrappersResult.copied
+    ],
+    [
+      ...rootResult.skipped,
+      ...qfaiResult.skipped,
+      ...skillsResult.skipped,
+      ...wrappersResult.skipped
+    ],
+    removed,
     options.dryRun,
     "init",
     destRoot
@@ -2505,6 +2525,366 @@ async function exists7(target) {
     return false;
   }
 }
+async function syncIntegrationWrappers(assistantAssetsDir, destRoot, options) {
+  const skills = await collectCanonicalSkillIds(assistantAssetsDir);
+  const agents = await collectCanonicalAgentNames(assistantAssetsDir);
+  const entries = buildWrapperEntries(skills, agents);
+  const copied = [];
+  const skipped = [];
+  const removed = options.force ? await pruneStaleQfaiWrappers(destRoot, skills, options.dryRun) : [];
+  for (const entry of entries) {
+    const destination = import_node_path14.default.join(destRoot, ...entry.relativePath.split("/"));
+    const alreadyExists = await exists7(destination);
+    if (alreadyExists && !options.force) {
+      skipped.push(destination);
+      continue;
+    }
+    copied.push(destination);
+    if (options.dryRun) {
+      continue;
+    }
+    await (0, import_promises12.mkdir)(import_node_path14.default.dirname(destination), { recursive: true });
+    await (0, import_promises12.writeFile)(destination, entry.body, "utf-8");
+  }
+  return { copied, skipped, removed };
+}
+async function collectCanonicalSkillIds(assistantAssetsDir) {
+  const skillsDir = import_node_path14.default.join(assistantAssetsDir, "skills");
+  if (!await exists7(skillsDir)) {
+    return [];
+  }
+  const entries = await (0, import_promises12.readdir)(skillsDir, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const skillDoc = import_node_path14.default.join(skillsDir, entry.name, "SKILL.md");
+    if (await exists7(skillDoc)) {
+      skills.push(entry.name);
+    }
+  }
+  return skills.sort();
+}
+async function collectCanonicalAgentNames(assistantAssetsDir) {
+  const agentsDir = import_node_path14.default.join(assistantAssetsDir, "agents");
+  if (!await exists7(agentsDir)) {
+    return [];
+  }
+  const entries = await (0, import_promises12.readdir)(agentsDir, { withFileTypes: true });
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (!entry.name.endsWith(".md") || entry.name === "README.md") {
+      continue;
+    }
+    names.push(entry.name.slice(0, -".md".length));
+  }
+  return names.sort();
+}
+function buildWrapperEntries(skills, agents) {
+  const entries = [
+    {
+      relativePath: ".codex/README.md",
+      body: buildCodexReadme()
+    },
+    {
+      relativePath: ".claude/agents/README.md",
+      body: buildClaudeAgentsReadme()
+    },
+    {
+      relativePath: ".github/agents/README.md",
+      body: buildGithubAgentsReadme()
+    },
+    {
+      relativePath: ".github/copilot-instructions.md",
+      body: buildCopilotInstructions()
+    }
+  ];
+  for (const skillId of skills) {
+    entries.push({
+      relativePath: `.claude/commands/${skillId}.md`,
+      body: buildClaudeCommandWrapper(skillId)
+    });
+    entries.push({
+      relativePath: `.github/prompts/${skillId}.prompt.md`,
+      body: buildGithubPromptWrapper(skillId)
+    });
+    entries.push({
+      relativePath: `.codex/skills/${skillId}/SKILL.md`,
+      body: buildCodexSkillWrapper(skillId)
+    });
+  }
+  for (const agentName of agents) {
+    entries.push({
+      relativePath: `.claude/agents/${agentName}.md`,
+      body: buildClaudeAgentWrapper(agentName)
+    });
+    entries.push({
+      relativePath: `.github/agents/${agentName}.agent.md`,
+      body: buildGithubAgentWrapper(agentName)
+    });
+  }
+  return entries;
+}
+async function pruneStaleQfaiWrappers(destRoot, canonicalSkills, dryRun) {
+  const canonical = new Set(canonicalSkills);
+  const removed = [];
+  const claudeCommandsDir = import_node_path14.default.join(destRoot, ".claude", "commands");
+  if (await exists7(claudeCommandsDir)) {
+    const entries = await (0, import_promises12.readdir)(claudeCommandsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!entry.name.startsWith("qfai-") || !entry.name.endsWith(".md")) {
+        continue;
+      }
+      const skillId = entry.name.slice(0, -".md".length);
+      if (canonical.has(skillId)) {
+        continue;
+      }
+      const target = import_node_path14.default.join(claudeCommandsDir, entry.name);
+      removed.push(target);
+      if (!dryRun) {
+        await (0, import_promises12.rm)(target, { force: true });
+      }
+    }
+  }
+  const githubPromptsDir = import_node_path14.default.join(destRoot, ".github", "prompts");
+  if (await exists7(githubPromptsDir)) {
+    const entries = await (0, import_promises12.readdir)(githubPromptsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!entry.name.startsWith("qfai-") || !entry.name.endsWith(".prompt.md")) {
+        continue;
+      }
+      const skillId = entry.name.slice(0, -".prompt.md".length);
+      if (canonical.has(skillId)) {
+        continue;
+      }
+      const target = import_node_path14.default.join(githubPromptsDir, entry.name);
+      removed.push(target);
+      if (!dryRun) {
+        await (0, import_promises12.rm)(target, { force: true });
+      }
+    }
+  }
+  const codexSkillsDir = import_node_path14.default.join(destRoot, ".codex", "skills");
+  if (await exists7(codexSkillsDir)) {
+    const entries = await (0, import_promises12.readdir)(codexSkillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (!entry.name.startsWith("qfai-")) {
+        continue;
+      }
+      if (canonical.has(entry.name)) {
+        continue;
+      }
+      const target = import_node_path14.default.join(codexSkillsDir, entry.name);
+      removed.push(target);
+      if (!dryRun) {
+        await (0, import_promises12.rm)(target, { recursive: true, force: true });
+      }
+    }
+  }
+  return removed;
+}
+function buildCodexReadme() {
+  return [
+    "# QFAI Codex skills",
+    "",
+    "This directory provides thin Codex skill wrappers for QFAI.",
+    "",
+    "## Canonical entrypoint",
+    "",
+    "Codex skill wrappers must point to QFAI's canonical skill documents under:",
+    "",
+    "- .qfai/assistant/skills/",
+    "",
+    "These canonical skill documents are the SSOT.",
+    "Tool integrations must reference `.qfai/assistant/skills/`.",
+    "",
+    "## Usage",
+    "",
+    "In Codex CLI, select a skill by name (e.g., `qfai-configure`) and provide your request.",
+    "All outputs must match the user's language.",
+    ""
+  ].join("\n");
+}
+function buildClaudeAgentsReadme() {
+  return [
+    "# QFAI Claude agents",
+    "",
+    "This directory provides thin Claude Code agent wrappers for QFAI.",
+    "",
+    "## Canonical entrypoint",
+    "",
+    "All wrappers must point to:",
+    "",
+    "- .qfai/assistant/agents/",
+    "",
+    "Use these wrappers as entrypoints and keep canonical behavior in `.qfai/assistant/agents/**`.",
+    ""
+  ].join("\n");
+}
+function buildGithubAgentsReadme() {
+  return [
+    "# QFAI GitHub agents",
+    "",
+    "This directory provides thin GitHub Copilot custom agent wrappers for QFAI.",
+    "",
+    "## Canonical entrypoint",
+    "",
+    "All wrappers must point to:",
+    "",
+    "- .qfai/assistant/agents/",
+    "",
+    "Use these wrappers as entrypoints and keep canonical behavior in `.qfai/assistant/agents/**`.",
+    ""
+  ].join("\n");
+}
+function buildCopilotInstructions() {
+  return [
+    "# QFAI repository instructions (Copilot)",
+    "",
+    "This repository uses QFAI (Quality-First AI) to improve the quality and consistency of AI-assisted development.",
+    "",
+    "## Golden rules",
+    "",
+    "- Always match the user\u2019s language in your outputs.",
+    "- Treat `.qfai/` as the canonical source of truth for the QFAI workflow:",
+    "  - Skills (SSOT): `.qfai/assistant/skills/`",
+    "  - Instructions: `.qfai/assistant/instructions/`",
+    "  - Project steering: `.qfai/assistant/steering/`",
+    "- When asked to perform QFAI workflow tasks, prefer using the QFAI prompt wrappers in `.github/prompts/`.",
+    "  - These wrappers forward to `.qfai/assistant/skills/<skill-name>/SKILL.md`.",
+    "- Do not invent repository structure, tools, or frameworks. Inspect the repo first and align with what is already used.",
+    "- Keep changes minimal and targeted. Update tests and docs when behavior changes.",
+    ""
+  ].join("\n");
+}
+function buildClaudeCommandWrapper(skillId) {
+  return [
+    "---",
+    `description: "QFAI: ${skillId}"`,
+    'argument-hint: "[optional notes]"',
+    "---",
+    "",
+    "Follow the canonical QFAI skill document exactly:",
+    `@.qfai/assistant/skills/${skillId}/SKILL.md`,
+    "",
+    "Follow the DoD/Checkpoints in the skill document.",
+    "Use the repository as the source of truth.",
+    "",
+    "Additional user notes: $ARGUMENTS",
+    "",
+    "Critical: output must match the user's language.",
+    ""
+  ].join("\n");
+}
+function buildGithubPromptWrapper(skillId) {
+  return [
+    "---",
+    'agent: "agent"',
+    `description: "QFAI: ${skillId}"`,
+    "---",
+    "",
+    "You are operating in a repository that uses QFAI.",
+    "",
+    "1. Open and follow the canonical QFAI skill:",
+    "",
+    `- .qfai/assistant/skills/${skillId}/SKILL.md`,
+    "",
+    "2. Use the repository as the source of truth (tools, frameworks, directory structure).",
+    "3. Ask the user for missing inputs only when necessary.",
+    "4. Do not modify files not required by the canonical skill.",
+    "5. All outputs must match the user's language.",
+    "",
+    "User notes: ${input:notes:Optional}",
+    ""
+  ].join("\n");
+}
+function buildCodexSkillWrapper(skillId) {
+  return [
+    "---",
+    `name: "${skillId}"`,
+    `description: "QFAI: ${skillId} (Codex skill wrapper)"`,
+    "---",
+    "",
+    `# ${skillId}`,
+    "",
+    "This skill is a thin wrapper that forwards to the canonical QFAI skill in this repository:",
+    "",
+    `- .qfai/assistant/skills/${skillId}/SKILL.md`,
+    "",
+    "How to invoke (Codex CLI):",
+    "",
+    `- Select the \`${skillId}\` skill, or reference it by name and provide your request.`,
+    "",
+    "Instructions:",
+    "",
+    "1. Read the skill document above and follow it precisely.",
+    "2. Use the repository as the source of truth (tools, frameworks, directory structure).",
+    "3. Ensure all outputs match the user's language.",
+    ""
+  ].join("\n");
+}
+function buildClaudeAgentWrapper(agentName) {
+  const title = formatDisplayName(agentName);
+  return [
+    `# ${title} (Claude Code wrapper)`,
+    "",
+    "## Purpose",
+    "",
+    `This is a thin wrapper for Claude Code agents. The canonical role card lives in .qfai/assistant/agents/${agentName}.md.`,
+    "",
+    "## Rules",
+    "",
+    "- Always follow the .qfai role card and instructions first.",
+    "- If this file conflicts with .qfai, the .qfai content wins.",
+    "- Do not proceed without reading the role card.",
+    "",
+    "## Minimal steps",
+    "",
+    `1. Read .qfai/assistant/agents/${agentName}.md and follow its output format.`,
+    "2. Use .qfai/assistant/steering/ and .qfai/assistant/instructions/ as required context.",
+    "3. List unknowns as Open Questions; do not mix them with decisions.",
+    ""
+  ].join("\n");
+}
+function buildGithubAgentWrapper(agentName) {
+  const title = formatDisplayName(agentName);
+  return [
+    `# ${title} (GitHub Copilot Custom wrapper)`,
+    "",
+    "## Purpose",
+    "",
+    `This is a thin wrapper for GitHub Copilot Custom agents. The canonical role card lives in .qfai/assistant/agents/${agentName}.md.`,
+    "",
+    "## Rules",
+    "",
+    "- Always follow the .qfai role card and instructions first.",
+    "- If this file conflicts with .qfai, the .qfai content wins.",
+    "- Do not proceed without reading the role card.",
+    "",
+    "## Minimal steps",
+    "",
+    `1. Read .qfai/assistant/agents/${agentName}.md and follow its output format.`,
+    "2. Use .qfai/assistant/steering/ and .qfai/assistant/instructions/ as required context.",
+    "3. List unknowns as Open Questions; do not mix them with decisions.",
+    ""
+  ].join("\n");
+}
+function formatDisplayName(raw) {
+  return raw.split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
 
 // src/cli/commands/report.ts
 var import_promises22 = require("fs/promises");