@shahmarasy/prodo 0.1.0

package/dist/validate.js

@@ -0,0 +1,226 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runValidate = runValidate;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const artifact_registry_1 = require("./artifact-registry");
+const consistency_1 = require("./consistency");
+const errors_1 = require("./errors");
+const output_index_1 = require("./output-index");
+const paths_1 = require("./paths");
+const template_resolver_1 = require("./template-resolver");
+const utils_1 = require("./utils");
+const validator_1 = require("./validator");
+function sidecarPath(filePath) {
+    const parsed = node_path_1.default.parse(filePath);
+    return node_path_1.default.join(parsed.dir, `${parsed.name}.artifact.json`);
+}
+async function loadArtifactDoc(filePath) {
+    const sidecar = sidecarPath(filePath);
+    if (await (0, utils_1.fileExists)(sidecar)) {
+        const payload = await (0, utils_1.readJsonFile)(sidecar);
+        return {
+            frontmatter: payload.frontmatter ?? {},
+            body: typeof payload.body === "string" ? payload.body : ""
+        };
+    }
+    const raw = await promises_1.default.readFile(filePath, "utf8");
+    const parsed = (0, gray_matter_1.default)(raw);
+    return {
+        frontmatter: parsed.data,
+        body: parsed.content
+    };
+}
+async function loadLatestArtifacts(cwd) {
+    const defs = await (0, artifact_registry_1.listArtifactDefinitions)(cwd);
+    const loaded = [];
+    for (const def of defs) {
+        const type = def.name;
+        const active = await (0, output_index_1.getActiveArtifactPath)(cwd, type);
+        const fallback = async () => {
+            const files = await (0, utils_1.listFilesSortedByMtime)((0, paths_1.outputDirPath)(cwd, type, def.output_dir));
+            return files[0];
+        };
+        const latest = active ?? (await fallback());
+        if (!latest)
+            continue;
+        const parsed = await loadArtifactDoc(latest);
+        loaded.push({
+            type,
+            file: latest,
+            doc: parsed
+        });
+    }
+    return loaded;
+}
+async function listHtmlFiles(dir) {
+    if (!(await (0, utils_1.fileExists)(dir)))
+        return [];
+    const entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
+        .map((entry) => node_path_1.default.join(dir, entry.name));
+}
+function formatIssue(issue) {
+    const location = issue.file ? ` (${issue.file})` : "";
+    const field = issue.field ? ` [${issue.field}]` : "";
+    const check = issue.check ? ` [${issue.check}]` : "";
+    const fix = issue.suggestion ? `\n  Suggestion: ${issue.suggestion}` : "";
+    return `- [${issue.level.toUpperCase()}] ${issue.code}${check}${field}: ${issue.message}${location}${fix}`;
+}
+async function writeReport(targetPath, issues) {
+    const status = issues.some((issue) => issue.level === "error") ? "FAIL" : "PASS";
+    const schemaIssues = issues.filter((issue) => issue.check === "schema");
+    const coverageIssues = issues.filter((issue) => issue.check === "tag_coverage");
+    const relevanceIssues = issues.filter((issue) => issue.check === "contract_relevance");
+    const semanticIssues = issues.filter((issue) => issue.check === "semantic_consistency");
+    const gate = (set) => (set.some((issue) => issue.level === "error") ? "FAIL" : "PASS");
+    const content = [
+        "# Prodo Validation Report",
+        "",
+        `Status: **${status}**`,
+        `Generated at: ${new Date().toISOString()}`,
+        "",
+        "## Gate Results",
+        `- Schema pass: ${gate(schemaIssues)}`,
+        `- Tag coverage pass: ${gate(coverageIssues)}`,
+        `- Contract relevance pass: ${gate(relevanceIssues)}`,
+        `- Semantic consistency pass: ${gate(semanticIssues)}`,
+        "",
+        "## Findings",
+        issues.length === 0 ? "- No issues found." : issues.map(formatIssue).join("\n"),
+        ""
+    ].join("\n");
+    await (0, utils_1.ensureDir)(node_path_1.default.dirname(targetPath));
+    await promises_1.default.writeFile(targetPath, content, "utf8");
+}
+async function runValidate(cwd, options) {
+    const normalizedPath = (0, paths_1.normalizedBriefPath)(cwd);
+    if (!(await (0, utils_1.fileExists)(normalizedPath))) {
+        throw new errors_1.UserError("Missing `.prodo/briefs/normalized-brief.json`. Run `prodo-init` and create it first.");
+    }
+    const normalizedBrief = await (0, utils_1.readJsonFile)(normalizedPath);
+    const loaded = await loadLatestArtifacts(cwd);
+    const issues = [];
+    for (const artifact of loaded) {
+        const template = await (0, template_resolver_1.resolveTemplate)({
+            cwd,
+            artifactType: artifact.type
+        });
+        const headings = template ? (0, template_resolver_1.extractRequiredHeadingsFromTemplate)(template.content) : [];
+        const schemaCheck = await (0, validator_1.validateSchema)(cwd, artifact.type, artifact.doc, headings);
+        issues.push(...schemaCheck.issues.map((issue) => ({ ...issue, file: artifact.file })));
+        if (artifact.type === "workflow") {
+            const ext = node_path_1.default.extname(artifact.file).toLowerCase();
+            if (ext !== ".md") {
+                issues.push({
+                    level: "error",
+                    code: "workflow_markdown_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Workflow explanation artifact must be Markdown (.md).",
+                    suggestion: "Regenerate workflow so explanation is written to .md."
+                });
+            }
+            const mmdPath = node_path_1.default.join(node_path_1.default.dirname(artifact.file), `${node_path_1.default.parse(artifact.file).name}.mmd`);
+            if (!(await (0, utils_1.fileExists)(mmdPath))) {
+                issues.push({
+                    level: "error",
+                    code: "workflow_mermaid_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Workflow Mermaid companion file (.mmd) is missing.",
+                    suggestion: "Regenerate workflow so markdown and .mmd are produced as a pair."
+                });
+            }
+            else {
+                const mmdRaw = await promises_1.default.readFile(mmdPath, "utf8");
+                const mermaidLike = /(^|\n)\s*flowchart\s+/i.test(mmdRaw) || /(^|\n)\s*graph\s+/i.test(mmdRaw);
+                if (!mermaidLike) {
+                    issues.push({
+                        level: "error",
+                        code: "workflow_mermaid_invalid",
+                        check: "schema",
+                        artifactType: artifact.type,
+                        file: mmdPath,
+                        message: "Workflow Mermaid file is invalid or prose-only.",
+                        suggestion: "Ensure .mmd file contains valid Mermaid diagram syntax."
+                    });
+                }
+            }
+        }
+        if (artifact.type === "wireframe") {
+            const ext = node_path_1.default.extname(artifact.file).toLowerCase();
+            if (ext !== ".md") {
+                issues.push({
+                    level: "error",
+                    code: "wireframe_markdown_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Wireframe explanation artifact must be Markdown (.md).",
+                    suggestion: "Regenerate wireframe so explanation is written to .md."
+                });
+            }
+            const htmlPath = node_path_1.default.join(node_path_1.default.dirname(artifact.file), `${node_path_1.default.parse(artifact.file).name}.html`);
+            if (!(await (0, utils_1.fileExists)(htmlPath))) {
+                issues.push({
+                    level: "error",
+                    code: "wireframe_html_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Wireframe HTML companion file is missing.",
+                    suggestion: "Regenerate wireframe so markdown and .html are produced as a pair."
+                });
+            }
+            else {
+                const htmlRaw = await promises_1.default.readFile(htmlPath, "utf8");
+                const htmlLooksValid = /<!doctype html>/i.test(htmlRaw) || /<html[\s>]/i.test(htmlRaw);
+                if (!htmlLooksValid) {
+                    issues.push({
+                        level: "error",
+                        code: "wireframe_html_invalid",
+                        check: "schema",
+                        artifactType: artifact.type,
+                        file: htmlPath,
+                        message: "Wireframe output is not valid HTML content.",
+                        suggestion: "Ensure wireframe companion HTML contains a valid document structure."
+                    });
+                }
+            }
+            const htmlFiles = await listHtmlFiles(node_path_1.default.dirname(artifact.file));
+            if (htmlFiles.length < 1) {
+                issues.push({
+                    level: "error",
+                    code: "wireframe_screens_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Wireframe must include at least one HTML screen artifact.",
+                    suggestion: "Regenerate wireframe to create paired .md and .html screen files."
+                });
+            }
+        }
+    }
+    issues.push(...(await (0, consistency_1.checkConsistency)(cwd, loaded, normalizedBrief)));
+    if (options.strict) {
+        for (const issue of issues) {
+            if (issue.level === "warning")
+                issue.level = "error";
+        }
+    }
+    const finalReportPath = options.report ? node_path_1.default.resolve(cwd, options.report) : (0, paths_1.reportPath)(cwd);
+    if (!(0, utils_1.isPathInside)(node_path_1.default.join(cwd, "product-docs"), finalReportPath)) {
+        throw new errors_1.UserError("Validation report must be inside `product-docs/`.");
+    }
+    await writeReport(finalReportPath, issues);
+    const pass = !issues.some((issue) => issue.level === "error");
+    return { pass, reportPath: finalReportPath, issues };
+}

package/dist/validator.d.ts

@@ -0,0 +1,5 @@
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+export declare function validateSchema(cwd: string, artifactType: ArtifactType, doc: ArtifactDoc, requiredHeadingsOverride?: string[]): Promise<{
+    issues: ValidationIssue[];
+    requiredHeadings: string[];
+}>;

package/dist/validator.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchema = validateSchema;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const _2020_1 = __importDefault(require("ajv/dist/2020"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const markdown_1 = require("./markdown");
+const paths_1 = require("./paths");
+const ajv = new _2020_1.default({ allErrors: true, strict: false });
+(0, ajv_formats_1.default)(ajv);
+async function resolveSchema(cwd, artifactType) {
+    const raw = await promises_1.default.readFile((0, paths_1.schemaPath)(cwd, artifactType), "utf8");
+    return js_yaml_1.default.load(raw);
+}
+function requiredHeadingsFromSchema(schema) {
+    if (!Array.isArray(schema.x_required_headings))
+        return [];
+    return schema.x_required_headings.filter((item) => typeof item === "string");
+}
+async function validateSchema(cwd, artifactType, doc, requiredHeadingsOverride) {
+    const schema = await resolveSchema(cwd, artifactType);
+    const requiredHeadings = requiredHeadingsOverride && requiredHeadingsOverride.length > 0
+        ? requiredHeadingsOverride
+        : requiredHeadingsFromSchema(schema);
+    const workingSchema = { ...schema };
+    delete workingSchema.x_required_headings;
+    const validate = ajv.compile(workingSchema);
+    const valid = validate(doc);
+    const issues = [];
+    if (!valid && validate.errors) {
+        for (const err of validate.errors) {
+            issues.push({
+                level: "error",
+                code: "schema_validation_failed",
+                check: "schema",
+                artifactType,
+                field: err.instancePath || err.schemaPath,
+                message: `Schema validation error: ${err.message ?? "unknown error"}`,
+                suggestion: "Adjust the generated content to satisfy schema requirements."
+            });
+        }
+    }
+    const sections = (0, markdown_1.sectionTextMap)(doc.body);
+    const trMode = String(doc.frontmatter.language ?? "").toLowerCase().startsWith("tr");
+    if (trMode) {
+        return { issues, requiredHeadings: [] };
+    }
+    for (const heading of requiredHeadings) {
+        if (!doc.body.includes(heading)) {
+            issues.push({
+                level: "error",
+                code: "missing_required_heading",
+                check: "schema",
+                artifactType,
+                field: heading,
+                message: `Required section missing: ${heading}`,
+                suggestion: "Regenerate or manually edit the artifact to include all required headings."
+            });
+            continue;
+        }
+        const content = sections.get(heading) ?? "";
+        const isPlaceholder = /(tbd|to be defined|i don't know|unknown|n\/a)/i.test(content);
+        if (content.trim().length < 20 || isPlaceholder) {
+            issues.push({
+                level: "error",
+                code: "weak_required_heading_content",
+                check: "schema",
+                artifactType,
+                field: heading,
+                message: `Section has weak or placeholder content: ${heading}`,
+                suggestion: "Replace placeholders with concrete, actionable details."
+            });
+        }
+    }
+    return { issues, requiredHeadings };
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare function readCliVersion(cwd: string): Promise<string>;

package/dist/version.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCliVersion = readCliVersion;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const utils_1 = require("./utils");
+async function readCliVersion(cwd) {
+    const candidates = [
+        node_path_1.default.join(cwd, "package.json"),
+        node_path_1.default.resolve(__dirname, "..", "package.json")
+    ];
+    for (const candidate of candidates) {
+        if (!(await (0, utils_1.fileExists)(candidate)))
+            continue;
+        try {
+            const raw = await promises_1.default.readFile(candidate, "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+                return parsed.version.trim();
+            }
+        }
+        catch {
+            // ignore and continue
+        }
+    }
+    return "0.0.0";
+}

package/dist/workflow-commands.d.ts

@@ -0,0 +1,7 @@
+export type WorkflowCommand = {
+    name: string;
+    cliSubcommand: string;
+    description: string;
+};
+export declare const WORKFLOW_COMMANDS: WorkflowCommand[];
+export declare function buildWorkflowCommands(artifactTypes: string[]): WorkflowCommand[];

package/dist/workflow-commands.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKFLOW_COMMANDS = void 0;
+exports.buildWorkflowCommands = buildWorkflowCommands;
+const BASE_WORKFLOW_COMMANDS = [
+    { name: "prodo-normalize", cliSubcommand: "normalize", description: "Normalize start brief into normalized brief JSON." },
+    { name: "prodo-prd", cliSubcommand: "prd", description: "Generate PRD artifact from normalized brief." },
+    { name: "prodo-workflow", cliSubcommand: "workflow", description: "Generate workflow artifact." },
+    { name: "prodo-wireframe", cliSubcommand: "wireframe", description: "Generate wireframe artifact." },
+    { name: "prodo-stories", cliSubcommand: "stories", description: "Generate stories artifact." },
+    { name: "prodo-techspec", cliSubcommand: "techspec", description: "Generate technical specification artifact." },
+    { name: "prodo-validate", cliSubcommand: "validate", description: "Run schema and cross-artifact consistency validation." }
+];
+exports.WORKFLOW_COMMANDS = BASE_WORKFLOW_COMMANDS;
+function buildWorkflowCommands(artifactTypes) {
+    const commandByName = new Map(BASE_WORKFLOW_COMMANDS.map((item) => [item.name, item]));
+    for (const type of artifactTypes) {
+        const name = `prodo-${type}`;
+        if (commandByName.has(name))
+            continue;
+        commandByName.set(name, {
+            name,
+            cliSubcommand: type,
+            description: `Generate ${type} artifact from normalized brief.`
+        });
+    }
+    return Array.from(commandByName.values());
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@shahmarasy/prodo",
+  "version": "0.1.0",
+  "description": "CLI-first, prompt-powered product artifact kit",
+  "main": "dist/cli.js",
+  "types": "dist/cli.d.ts",
+  "bin": {
+    "prodo": "bin/prodo.cjs"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "templates/",
+    "presets/",
+    "src/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.cjs",
+    "verify:release": "npm run build && node scripts/verify-release-build.cjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "commander": "^14.0.3",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/presets/fintech/preset.json

@@ -0,0 +1 @@
+{"name":"fintech","priority":1,"min_prodo_version":"0.1.0","version":"1.0.0"}

package/presets/fintech/prompts/prd.md

@@ -0,0 +1,3 @@
+Preset: fintech
+
+Use domain-specific terminology and constraints for fintech products.

package/presets/marketplace/preset.json

@@ -0,0 +1 @@
+{"name":"marketplace","priority":1,"min_prodo_version":"0.1.0","version":"1.0.0"}

package/presets/marketplace/prompts/prd.md

@@ -0,0 +1,3 @@
+Preset: marketplace
+
+Use domain-specific terminology and constraints for marketplace products.

package/presets/saas/preset.json

@@ -0,0 +1 @@
+{"name":"saas","priority":1,"min_prodo_version":"0.1.0","version":"1.0.0"}

package/presets/saas/prompts/prd.md

@@ -0,0 +1,3 @@
+Preset: saas
+
+Use domain-specific terminology and constraints for saas products.

package/src/agent-command-installer.ts

@@ -0,0 +1,174 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { UserError } from "./errors";
+import { ensureDir, fileExists } from "./utils";
+
+export const AI_ALIASES: Record<string, "codex" | "gemini-cli" | "claude-cli"> = {
+  codex: "codex",
+  gemini: "gemini-cli",
+  "gemmini-cli": "gemini-cli",
+  "gemmini": "gemini-cli",
+  "gemini-cli": "gemini-cli",
+  claude: "claude-cli",
+  "claude-cli": "claude-cli"
+};
+
+export type SupportedAi = "codex" | "gemini-cli" | "claude-cli";
+
+type AgentConfig = {
+  baseDir: string;
+  format: "markdown" | "toml" | "skill";
+  extension: string;
+  argsPlaceholder: string;
+};
+
+const AGENT_CONFIG: Record<SupportedAi, AgentConfig> = {
+  "claude-cli": {
+    baseDir: ".claude/commands",
+    format: "markdown",
+    extension: ".md",
+    argsPlaceholder: "$ARGUMENTS"
+  },
+  "gemini-cli": {
+    baseDir: ".gemini/commands",
+    format: "toml",
+    extension: ".toml",
+    argsPlaceholder: "{{args}}"
+  },
+  codex: {
+    baseDir: ".agents/skills",
+    format: "skill",
+    extension: "/SKILL.md",
+    argsPlaceholder: "$ARGUMENTS"
+  }
+};
+
+type ParsedTemplate = {
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
+function parseFrontmatter(content: string): ParsedTemplate {
+  if (!content.startsWith("---")) return { frontmatter: {}, body: content };
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) return { frontmatter: {}, body: content };
+  const fmRaw = content.slice(3, end).trim();
+  const body = content.slice(end + 4).trimStart();
+  const frontmatter = (yaml.load(fmRaw) as Record<string, unknown>) ?? {};
+  return { frontmatter, body };
+}
+
+function renderFrontmatter(frontmatter: Record<string, unknown>): string {
+  if (Object.keys(frontmatter).length === 0) return "";
+  return `---\n${yaml.dump(frontmatter)}---\n`;
+}
+
+function resolveScriptBlock(frontmatter: Record<string, unknown>, argsPlaceholder: string): string {
+  const run = frontmatter.run as Record<string, unknown> | undefined;
+  const runAction = typeof run?.action === "string" ? run.action.trim() : "";
+  const runMode = typeof run?.mode === "string" ? run.mode.trim() : "";
+  if (runAction) {
+    const modeSuffix = runMode ? ` (${runMode})` : "";
+    return `- Internal action: ${runAction}${modeSuffix}`;
+  }
+  const runCommand = typeof run?.command === "string" ? run.command.replace("{ARGS}", argsPlaceholder) : "";
+  if (runCommand) {
+    return `- Command: ${runCommand}`;
+  }
+  const scripts = frontmatter.scripts as Record<string, unknown> | undefined;
+  const sh = typeof scripts?.sh === "string" ? scripts.sh.replace("{ARGS}", argsPlaceholder) : "";
+  const ps = typeof scripts?.ps === "string" ? scripts.ps.replace("{ARGS}", argsPlaceholder) : "";
+  return [`- Bash: ${sh}`, `- PowerShell: ${ps}`].filter((line) => line.length > 8).join("\n");
+}
+
+function toTomlPrompt(body: string, frontmatter: Record<string, unknown>, argsPlaceholder: string): string {
+  const description = String(frontmatter.description ?? "Prodo command");
+  const scriptsBlock = resolveScriptBlock(frontmatter, argsPlaceholder);
+  const promptBody = body.replaceAll("$ARGUMENTS", argsPlaceholder);
+  return `description = "${description.replace(/"/g, '\\"')}"
+
+prompt = """
+${promptBody}
+
+Script options:
+${scriptsBlock}
+"""`;
+}
+
+function toSkill(name: string, body: string, frontmatter: Record<string, unknown>): string {
+  const description = String(frontmatter.description ?? "Prodo workflow command");
+  return `---
+name: ${name}
+description: ${description}
+compatibility: Requires Prodo project scaffold (.prodo)
+metadata:
+  author: prodo
+  source: .prodo/commands/${name}.md
+---
+
+${body}`;
+}
+
+export function resolveAi(ai?: string): SupportedAi | undefined {
+  if (!ai) return undefined;
+  const normalized = AI_ALIASES[ai.trim().toLowerCase()];
+  if (!normalized) {
+    throw new UserError("Unsupported --ai value. Use: codex | gemini-cli | claude-cli");
+  }
+  return normalized;
+}
+
+async function loadCommandTemplateNames(commandTemplatesDir: string): Promise<string[]> {
+  if (!(await fileExists(commandTemplatesDir))) {
+    throw new UserError(`Missing command templates directory: ${commandTemplatesDir}`);
+  }
+  const entries = await fs.readdir(commandTemplatesDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => name.endsWith(".md") && name.startsWith("prodo-"))
+    .map((name) => name.replace(/\.md$/, ""))
+    .sort();
+}
+
+export async function installAgentCommands(projectRoot: string, ai: SupportedAi): Promise<string[]> {
+  const cfg = AGENT_CONFIG[ai];
+  const target = path.join(projectRoot, cfg.baseDir);
+  const commandTemplatesDir = path.join(projectRoot, ".prodo", "commands");
+  const commandNames = await loadCommandTemplateNames(commandTemplatesDir);
+  await ensureDir(target);
+
+  const written: string[] = [];
+  for (const commandName of commandNames) {
+    const templatePath = path.join(commandTemplatesDir, `${commandName}.md`);
+    if (!(await fileExists(templatePath))) {
+      throw new UserError(`Missing command template: ${templatePath}`);
+    }
+    const raw = await fs.readFile(templatePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+
+    if (cfg.format === "skill") {
+      const skillDir = path.join(target, commandName);
+      await ensureDir(skillDir);
+      const outPath = path.join(skillDir, "SKILL.md");
+      const content = toSkill(commandName, parsed.body.replaceAll("$ARGUMENTS", cfg.argsPlaceholder), parsed.frontmatter);
+      await fs.writeFile(outPath, content, "utf8");
+      written.push(outPath);
+      continue;
+    }
+
+    if (cfg.format === "toml") {
+      const outPath = path.join(target, `${commandName}${cfg.extension}`);
+      await fs.writeFile(outPath, toTomlPrompt(parsed.body, parsed.frontmatter, cfg.argsPlaceholder), "utf8");
+      written.push(outPath);
+      continue;
+    }
+
+    const outPath = path.join(target, `${commandName}${cfg.extension}`);
+    const replacedBody = parsed.body.replaceAll("$ARGUMENTS", cfg.argsPlaceholder);
+    await fs.writeFile(outPath, `${renderFrontmatter(parsed.frontmatter)}\n${replacedBody}`, "utf8");
+    written.push(outPath);
+  }
+  return written;
+}