@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/templates/.geminiignore.template

@@ -0,0 +1,8 @@
+.ai-workflow/
+.ai-workflow-backups/
+node_modules/
+.git/
+EVIDENCE.json
+*.tgz
+*.zip
+*.tar

package/dist-assets/templates/CLAUDE.md.template

@@ -0,0 +1,20 @@
+# Claude Instructions — AI Workflow Kit
+
+Use AGENTS.md and the relevant contracts.
+
+```txt
+readonly → Inspect → Report → Recommendation
+quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
+standard → Mini spec → Mini review → Mini plan → Scoped PR plan → Implement → Document → Test/Validate → Evidence
+full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
+```
+
+Provide evidence for completed work.
+
+
+## Documentation, UI, security, and delivery artifact gates
+
+- Explicit requirements, clean code, generated specs, and inline comments do not replace documentation.
+- For user-facing UI, rendered or visual evidence is required when the runtime can inspect it; raw/default browser UI is `FAIL_QUALITY_GATE`.
+- High/Critical security findings must be classified in evidence.
+- Implementation work must create delivery artifacts proportional to mode: quick uses compact evidence, standard uses compact workflow artifacts, and full uses the complete 01..07 set.

package/dist-assets/templates/CODEX.md.template

@@ -0,0 +1,20 @@
+# Codex Instructions — AI Workflow Kit
+
+Use AGENTS.md and the relevant contracts.
+
+```txt
+readonly → Inspect → Report → Recommendation
+quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
+standard → Mini spec → Mini review → Mini plan → Scoped PR plan → Implement → Document → Test/Validate → Evidence
+full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
+```
+
+Never publish, tag, release, deploy, merge, push, force-push, or change package version without explicit approval.
+
+
+## Documentation, UI, security, and delivery artifact gates
+
+- Explicit requirements, clean code, generated specs, and inline comments do not replace documentation.
+- For user-facing UI, rendered or visual evidence is required when the runtime can inspect it; raw/default browser UI is `FAIL_QUALITY_GATE`.
+- High/Critical security findings must be classified in evidence.
+- Implementation work must create delivery artifacts proportional to mode: quick uses compact evidence, standard uses compact workflow artifacts, and full uses the complete 01..07 set.

package/dist-assets/templates/GEMINI.md.template

@@ -0,0 +1,20 @@
+# Gemini Instructions — AI Workflow Kit
+
+Use AGENTS.md and the relevant contracts.
+
+```txt
+readonly → Inspect → Report → Recommendation
+quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
+standard → Mini spec → Mini review → Mini plan → Scoped PR plan → Implement → Document → Test/Validate → Evidence
+full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
+```
+
+Use professional taxonomy: Primary Agents, Skill-backed Specialist Roles, Skills, Commands.
+
+
+## Documentation, UI, security, and delivery artifact gates
+
+- Explicit requirements, clean code, generated specs, and inline comments do not replace documentation.
+- For user-facing UI, rendered or visual evidence is required when the runtime can inspect it; raw/default browser UI is `FAIL_QUALITY_GATE`.
+- High/Critical security findings must be classified in evidence.
+- Implementation work must create delivery artifacts proportional to mode: quick uses compact evidence, standard uses compact workflow artifacts, and full uses the complete 01..07 set.

package/dist-assets/templates/HANDOFF.template.md

@@ -0,0 +1,45 @@
+#  AI Workflow Handoff Packet
+
+##  Metadata
+
+- **ID:** ${TASK_ID}
+- **Timestamp:** ${TIMESTAMP}
+- **Author:** ${AUTHOR}
+- **Status:** ${STATUS}
+
+---
+
+##  Requirements & Specifications
+
+${SPECS_CONTENT}
+
+---
+
+## Implementation Evidence
+
+### EVIDENCE.json Summary
+
+${EVIDENCE_SUMMARY}
+
+### Structured Evidence
+
+\`\`\`json
+${EVIDENCE_JSON}
+\`\`\`
+
+---
+
+##  Git Changes (Diff)
+
+\`\`\`diff
+${GIT_DIFF}
+\`\`\`
+
+---
+
+##  Required Next Actions
+
+${NEXT_ACTIONS}
+
+---
+Generated by AI Workflow Kit - Automated Handoff Engine

package/dist-assets/templates/SPEC.template.md

@@ -0,0 +1,38 @@
+# [STANDARD] Specification: ${TITLE}
+
+## Metadata
+
+- **ID:** SPEC-${ID}
+- **Author:** Spec-Engineer
+- **Status:** DRAFT | REVIEW | APPROVED
+- **Reviewer:** Atlas | Orion | Sage
+- **Date:** ${DATE}
+
+##  Functional Requirements
+
+- ${REQ_1}
+- ${REQ_2}
+
+##  Technical Implementation Plan
+
+### Files to Create/Modify
+
+- `${FILE_1}`
+- `${FILE_2}`
+
+### Logic & Workflow
+
+${IMPLEMENTATION_DETAILS}
+
+##  Acceptance Criteria
+
+- [ ] ${AC_1}
+- [ ] ${AC_2}
+
+##  Testing Strategy
+
+- [ ] Unit Tests: ${TEST_PLAN}
+- [ ] Integration Tests: ${INTEGRATION_PLAN}
+
+---
+Generated by AI Workflow Kit - Spec-Driven Development Engine

package/dist-assets/templates/change-proposal.template.md

@@ -0,0 +1,14 @@
+# Change Proposal: [Title]
+
+## 1. Context
+[Briefly describe why this change is needed]
+
+## 2. Proposed Change
+[Describe the technical change]
+
+## 3. Impact & Risks
+[What could break? What is the scope?]
+
+## 4. Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] EVIDENCE.json generated

package/dist-assets/templates/owner-evidence/astra-implementation.json

@@ -0,0 +1,10 @@
+{
+  "taskSlug": "<task-slug>",
+  "owner": "Astra",
+  "phase": "implementation",
+  "status": "PASS",
+  "skillsLoaded": ["frontend-development"],
+  "referencesLoaded": [],
+  "outputPaths": ["src/"],
+  "changedFiles": []
+}

package/dist-assets/templates/owner-evidence/phoenix-remediation.json

@@ -0,0 +1,8 @@
+{
+  "taskSlug": "<task-slug>",
+  "owner": "Phoenix",
+  "phase": "remediation",
+  "status": "PASS",
+  "outputPaths": ["<fixed-path>"],
+  "resolvedFindings": []
+}

package/dist-assets/templates/owner-evidence/sage-revalidation.json

@@ -0,0 +1,8 @@
+{
+  "taskSlug": "<task-slug>",
+  "owner": "Sage",
+  "phase": "revalidation",
+  "status": "PASS",
+  "outputPaths": ["docs/workflows/<task-slug>/delivery-report.md"],
+  "findings": []
+}

package/dist-assets/templates/owner-evidence/sage-validation.json

@@ -0,0 +1,8 @@
+{
+  "taskSlug": "<task-slug>",
+  "owner": "Sage",
+  "phase": "validation",
+  "status": "PASS",
+  "outputPaths": ["docs/workflows/<task-slug>/delivery-report.md"],
+  "findings": []
+}

package/dist-assets/templates/specs/deep.md

@@ -0,0 +1,48 @@
+# [DEEP] Specification: ${TITLE}
+
+## Metadata
+
+- **ID:** SPEC-DEEP-${ID}
+- **Author:** ${AUTHOR}
+- **Status:** DRAFT | REVIEW | APPROVED
+- **Reviewer:** Atlas | Orion
+- **Date:** ${DATE}
+
+## Architectural Intent
+
+${DETAILED_ARCHITECTURAL_DESCRIPTION}
+
+##  Strategic Goals
+
+- ${GOAL_1}
+- ${GOAL_2}
+
+## System Design & Patterns
+
+### Components Impacted
+
+- ${COMPONENT_1}
+- ${COMPONENT_2}
+
+### Data Structures & Flow
+
+${DATA_FLOW_DESCRIPTION}
+
+### Security & Integrity
+
+${SECURITY_CONSIDERATIONS}
+
+##  Acceptance Criteria (Audit Gate)
+
+- [ ] ${AC_1}
+- [ ] ${AC_2}
+- [ ] ${AC_3}
+
+## Risk Assessment
+
+| Risk | Impact | Mitigation |
+| :--- | :--- | :--- |
+| ${RISK} | ${IMPACT} | ${MITIGATION} |
+
+---
+Generated by AI Workflow Kit - Spec-Driven Development Engine

package/dist-assets/templates/specs/standard.md

@@ -0,0 +1,38 @@
+# [STANDARD] Specification: ${TITLE}
+
+## Metadata
+
+- **ID:** SPEC-${ID}
+- **Author:** Spec-Engineer
+- **Status:** DRAFT | REVIEW | APPROVED
+- **Reviewer:** Atlas | Orion | Sage
+- **Date:** ${DATE}
+
+##  Functional Requirements
+
+- ${REQ_1}
+- ${REQ_2}
+
+##  Technical Implementation Plan
+
+### Files to Create/Modify
+
+- `${FILE_1}`
+- `${FILE_2}`
+
+### Logic & Workflow
+
+${IMPLEMENTATION_DETAILS}
+
+##  Acceptance Criteria
+
+- [ ] ${AC_1}
+- [ ] ${AC_2}
+
+##  Testing Strategy
+
+- [ ] Unit Tests: ${TEST_PLAN}
+- [ ] Integration Tests: ${INTEGRATION_PLAN}
+
+---
+Generated by AI Workflow Kit - Spec-Driven Development Engine

package/dist-assets/templates/specs/tiny.md

@@ -0,0 +1,19 @@
+# [TINY] Spec: ${TITLE}
+
+## Metadata
+
+- **ID:** SPEC-TINY-${ID}
+- **Status:** DRAFT | APPROVED
+- **Reviewer:** Sage | Kai
+- **Date:** ${DATE}
+
+##  Task Description
+
+${BRIEF_DESCRIPTION}
+
+##  Acceptance Criteria
+
+- [ ] ${AC_1}
+
+---
+Generated by AI Workflow Kit - Spec-Driven Development Engine

package/package.json

@@ -1,12 +1,16 @@
 {
-  "version": "1.19.1",
   "name": "@williambeto/ai-workflow",
-  "description": "AI Workflow Kit repository for designing and validating AI-assisted software delivery workflows with Codex and OpenCode",
+  "version": "2.2.0",
+  "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
+  "author": "José Willams",
+  "type": "module",
   "private": false,
+  "engines": {
+    "node": ">=20.11"
+  },
   "keywords": [
     "ai-workflow",
-    "codex",
     "opencode",
     "prompts",
     "agent-workflows",
@@ -16,58 +20,49 @@
     "type": "git",
     "url": "git+https://github.com/williambeto/ai-workflow.git"
   },
-  "files": [
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "packages/ai-workflow/bin/",
-    "packages/ai-workflow/src/",
-    ".codex/prompts/",
-    ".agents/skills/",
-    ".agents/napkin.md",
-    "opencode/agents/",
-    "opencode/commands/",
-    "opencode/README.md",
-    "opencode.jsonc",
-    "prompts/",
-    "templates/",
-    "checklists/",
-    "runbooks/",
-    "schemas/",
-    "harness/",
-    "docs/architecture-policy.md",
-    "docs/design-patterns-policy.md",
-    "docs/full-documentation.md",
-    "docs/setup-codex-opencode.md",
-    "docs/npm-consumer-quickstart.md"
-  ],
   "homepage": "https://github.com/williambeto/ai-workflow#readme",
   "bugs": {
     "url": "https://github.com/williambeto/ai-workflow/issues"
   },
   "bin": {
-    "ai-workflow": "packages/ai-workflow/bin/ai-workflow.js"
+    "ai-workflow": "bin/ai-workflow.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "dist-assets",
+    "PUBLISH_MANIFEST.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "scripts": {
-    "setup:dev": "node scripts/setup-dev.mjs",
-    "metrics:feedback": "node scripts/collect-feedback-metrics.mjs",
+    "build": "node internal/validate/build-publish.mjs",
+    "validate": "node internal/validate/validate-all.mjs",
+    "validate:json": "node internal/validate/validate-json.mjs",
+    "validate:structure": "node internal/validate/validate-structure.mjs",
+    "validate:refs": "node internal/validate/validate-refs.mjs",
+    "validate:artifact-safety": "node internal/validate/validate-artifact-safety.mjs",
+    "validate:links": "node internal/validate/validate-links.mjs",
+    "validate:docs-consistency": "node internal/validate/validate-doc-consistency.mjs",
+    "validate:workflow": "node internal/validate/validate-workflow.mjs",
+    "validate:schemas": "node internal/validate/validate-schemas.mjs",
+    "validate:skills": "node internal/validate/validate-skills.mjs",
+    "validate:policy-refs": "node internal/validate/validate-policy-refs.mjs",
+    "validate:privacy-gate": "node internal/validate/validate-privacy-gate.mjs",
+    "validate:ui-evidence": "node internal/validate/validate-ui-evidence-gate.mjs",
+    "validate:delegation": "node internal/validate/validate-delegation.mjs",
+    "validate:cli-smoke": "node internal/validate/validate-cli-smoke.mjs",
+    "validate:cli-docs": "node internal/validate/validate-cli-docs.mjs",
     "lint:md": "markdownlint \"**/*.md\"",
-    "submodule:init": "node scripts/init.mjs",
-    "validate:md": "npm run lint:md",
-    "validate:json": "node scripts/validate-json.mjs",
-    "validate:structure": "node scripts/validate-structure.mjs",
-    "validate:refs": "node scripts/validate-refs.mjs",
-    "validate:artifact-safety": "node scripts/validate-artifact-safety.mjs",
-    "validate:links": "node scripts/validate-links.mjs",
-    "validate:docs-consistency": "node scripts/validate-doc-consistency.mjs",
-    "validate:workflow": "node scripts/validate-workflow.mjs",
-    "validate:schemas": "node scripts/validate-schemas.mjs",
-    "validate:skills": "node scripts/validate-skills.mjs",
-    "validate:delegation": "node scripts/validate-delegation.mjs",
-    "validate:cli-smoke": "node scripts/validate-cli-smoke.mjs",
+    "validate:registry": "node internal/validate/validate-registry-integrity.mjs",
+    "test": "npm run test:unit",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
     "test:e2e": "node tests/validate-e2e.mjs",
-    "validate": "node scripts/validate-all.mjs",
-    "release:ship": "node scripts/release-ship.mjs"
+    "pack:safe": "node internal/validate/pack-safe.mjs",
+    "validate:behavioral-contracts": "node internal/validate/validate-behavioral-contracts.mjs",
+    "validate:release-readiness": "node internal/validate/validate-release-readiness.mjs"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
@@ -77,6 +72,7 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "markdownlint-cli": "^0.48.0",
-    "semantic-release": "^25.0.3"
+    "semantic-release": "^25.0.3",
+    "vitest": "^4.1.7"
   }
 }

package/src/adapters/index.js

@@ -0,0 +1,3 @@
+export { GeminiAdapter } from "./platforms/gemini.js";
+export { ClaudeAdapter } from "./platforms/claude.js";
+export { CodexAdapter } from "./platforms/codex.js";

package/src/adapters/platforms/claude.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { COMPLETION_STATUS_TEXT } from "../../core/statuses.js";
+
+/**
+ * Claude Adapter - Transforms OpenCode agents and skills into CLAUDE.md and .claude/rules/.
+ */
+export class ClaudeAdapter {
+  constructor({ cwd }) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Transforms an OpenCode agent or skill into a Claude rule with completion contract.
+   */
+  async transformToRule(filePath, type = "agent") {
+    const content = await fs.readFile(filePath, "utf8");
+    const fileName = path.basename(filePath, ".md") === "SKILL" 
+      ? path.basename(path.dirname(filePath)) 
+      : path.basename(filePath, ".md");
+    
+    const ruleName = `${type}-${fileName.toLowerCase()}`;
+    
+    const hardenedContent = `---
+name: ${ruleName}
+description: ${type === "agent" ? "Persona" : "Skill"} rule for ${fileName}
+---
+# ${fileName} ${type === "agent" ? "Persona" : "Skill"}
+
+${content}
+
+##  Completion Contract (Mandatory)
+Every task completion MUST provide the following payload:
+1. **Status**: ${COMPLETION_STATUS_TEXT}
+2. **Scope reviewed**: Brief summary of what was analyzed.
+3. **Findings**: Evidence-based discoveries.
+4. **Files affected**: List of all concrete paths modified or created.
+5. **Validation/evidence**: Commands run and their results.
+6. **Risks/notes**: Any caveats or technical debt introduced.
+7. **Required manager action**: Clear next step for the orchestrator.
+8. **Can manager continue**: [yes/no]
+`;
+
+    return {
+      content: hardenedContent,
+      name: ruleName
+    };
+  }
+
+  /**
+   * Deploys agents, skills, and root CLAUDE.md.
+   */
+  async deploy(installRoot = ".ai-workflow") {
+    const rulesDir = path.join(this.cwd, ".claude/rules");
+    await fs.mkdir(rulesDir, { recursive: true });
+
+    const sourceAgentsDir = path.join(this.cwd, installRoot, "opencode/agents");
+    const sourceSkillsDir = path.join(this.cwd, installRoot, "opencode/skills");
+    const sourceCommandsDir = path.join(this.cwd, installRoot, "opencode/commands");
+
+    // 1. Deploy Agents to .claude/rules/agent-*.md
+    const agentFiles = await fs.readdir(sourceAgentsDir).catch(() => []);
+    for (const file of agentFiles) {
+      if (!file.endsWith(".md")) continue;
+      const transformed = await this.transformToRule(path.join(sourceAgentsDir, file), "agent");
+      await fs.writeFile(path.join(rulesDir, `${transformed.name}.md`), transformed.content);
+    }
+
+    // 2. Deploy Skills to .claude/rules/skill-*.md
+    const skillFolders = await fs.readdir(sourceSkillsDir).catch(() => []);
+    for (const folder of skillFolders) {
+      const skillSource = path.join(sourceSkillsDir, folder, "SKILL.md");
+      if (await this.exists(skillSource)) {
+        const transformed = await this.transformToRule(skillSource, "skill");
+        await fs.writeFile(path.join(rulesDir, `${transformed.name}.md`), transformed.content);
+      }
+    }
+
+    // 3. Create root CLAUDE.md
+    await this.deployRootClaudeMd(sourceCommandsDir);
+  }
+
+  async deployRootClaudeMd(sourceCommandsDir) {
+    const targetPath = path.join(this.cwd, "CLAUDE.md");
+    
+    // Collect commands to document them in CLAUDE.md
+    const commandFiles = await fs.readdir(sourceCommandsDir).catch(() => []);
+    let commandsDoc = "";
+    for (const file of commandFiles) {
+      if (!file.endsWith(".md")) continue;
+      const name = path.basename(file, ".md");
+      commandsDoc += `- \`ai-workflow run --spec-path=...\` (Target: ${name})\n`;
+    }
+
+    const instructions = `# CLAUDE.md - AI Workflow Kit Governance
+
+This project uses the **AI Workflow Kit** (OpenCode-first) workflow.
+
+##  Mandate: Atlas Authority Protocol
+All architectural changes must align with the specifications issued by the **Specification Authority** (./specs).
+
+##  Common Commands
+${commandsDoc}
+- \`ai-workflow doctor\`: Verify installation.
+- \`ai-workflow collect-evidence\`: Generate EVIDENCE.json.
+
+##  Rules & Personas
+Adhere to the specific rules and personas defined in \`.claude/rules/\`. 
+- Always follow the **Branch Gate** policy (never work on \`main\`).
+- Always follow the **SDD Workflow** (Spec -> Plan -> PR -> Evidence).
+
+##  Completion Contract
+Every task completion MUST follow the payload format defined in the individual rule files.
+`;
+    await fs.writeFile(targetPath, instructions);
+  }
+
+  async exists(p) {
+    try {
+      await fs.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/adapters/platforms/codex.js

@@ -0,0 +1,100 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { COMPLETION_STATUS_TEXT } from "../../core/statuses.js";
+
+/**
+ * Codex Adapter - Transforms OpenCode agents, skills, and commands into Codex-native formats.
+ */
+export class CodexAdapter {
+  constructor({ cwd }) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Transforms an OpenCode agent into a Codex prompt with completion contract.
+   */
+  async transformAgent(filePath) {
+    const content = await fs.readFile(filePath, "utf8");
+    const fileName = path.basename(filePath, ".md");
+    
+    const hardenedContent = `${content}
+
+##  Completion Contract (Mandatory)
+Every task completion MUST provide the following payload:
+1. **Status**: ${COMPLETION_STATUS_TEXT}
+2. **Scope reviewed**: Brief summary of what was analyzed.
+3. **Findings**: Evidence-based discoveries.
+4. **Files affected**: List of all concrete paths modified or created.
+5. **Validation/evidence**: Commands run and their results.
+6. **Risks/notes**: Any caveats or technical debt introduced.
+7. **Required manager action**: Clear next step for the orchestrator.
+8. **Can manager continue**: [yes/no]
+`;
+
+    return {
+      content: hardenedContent,
+      name: fileName
+    };
+  }
+
+  /**
+   * Deploys agents, skills, and commands to Codex-native directories.
+   * Mapping:
+   * - Agents -> .github/agents/
+   * - Skills -> .agents/skills/
+   * - Commands -> .codex/prompts/
+   */
+  async deploy(installRoot = ".ai-workflow") {
+    const sourceAgentsDir = path.join(this.cwd, installRoot, "opencode/agents");
+    const sourceSkillsDir = path.join(this.cwd, installRoot, "opencode/skills");
+    const sourceCommandsDir = path.join(this.cwd, installRoot, "opencode/commands");
+
+    // 1. Deploy Agents to .github/agents/
+    const codexAgentsDir = path.join(this.cwd, ".github/agents");
+    await fs.mkdir(codexAgentsDir, { recursive: true });
+    
+    const agentFiles = await fs.readdir(sourceAgentsDir).catch(() => []);
+    for (const file of agentFiles) {
+      if (!file.endsWith(".md")) continue;
+      const transformed = await this.transformAgent(path.join(sourceAgentsDir, file));
+      await fs.writeFile(path.join(codexAgentsDir, `${transformed.name}.md`), transformed.content);
+    }
+
+    // 2. Deploy Skills to .agents/skills/
+    const codexSkillsDir = path.join(this.cwd, ".agents/skills");
+    await fs.mkdir(codexSkillsDir, { recursive: true });
+
+    const skillFolders = await fs.readdir(sourceSkillsDir).catch(() => []);
+    for (const folder of skillFolders) {
+      const skillSource = path.join(sourceSkillsDir, folder, "SKILL.md");
+      if (await this.exists(skillSource)) {
+        const targetDir = path.join(codexSkillsDir, folder);
+        await fs.mkdir(targetDir, { recursive: true });
+        const content = await fs.readFile(skillSource, "utf8");
+        await fs.writeFile(path.join(targetDir, "SKILL.md"), content);
+      }
+    }
+
+    // 3. Deploy Commands to .codex/prompts/
+    const codexPromptsDir = path.join(this.cwd, ".codex/prompts");
+    await fs.mkdir(codexPromptsDir, { recursive: true });
+
+    const commandFiles = await fs.readdir(sourceCommandsDir).catch(() => []);
+    for (const file of commandFiles) {
+      if (!file.endsWith(".md") && !file.endsWith(".toml")) continue;
+      // Codex prompts work best as .md
+      const targetFileName = file.endsWith(".toml") ? `${path.basename(file, ".toml")}.md` : file;
+      const content = await fs.readFile(path.join(sourceCommandsDir, file), "utf8");
+      await fs.writeFile(path.join(codexPromptsDir, targetFileName), content);
+    }
+  }
+
+  async exists(p) {
+    try {
+      await fs.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}