agent-workflow-kit-cli 1.2.0 → 1.3.0

package/dist/cli/commands/add.js

@@ -8,6 +8,7 @@ import path from "path";
 import { renderTemplate, readStaticTemplateFile, getStackRules, getStackSkills, } from "../../core/renderer.js";
 import { updateFileWithBlock, writeRuleWithChunking, } from "../../core/emitter.js";
 import { analyzeModule } from "../../core/analyzer.js";
+import { updateGitignore } from "./init.js";
 export async function runAdd(stack, options) {
     const targetStack = stack.toLowerCase();
     const validStacks = ["spring-boot", "react-ts", "fastapi", "python-ai"];
@@ -36,26 +37,63 @@ export async function runAdd(stack, options) {
         console.error(chalk.red(`Error loading template for stack '${targetStack}': ${err instanceof Error ? err.message : String(err)}`));
         process.exit(1);
     }
-    // 3. Write or Update AGENTS.md in the target directory
+    // 3. Write or Update AGENTS.md and/or GEMINI.md in the target directory
+    const geminiPath = path.join(targetDir, "GEMINI.md");
     const agentsPath = path.join(targetDir, "AGENTS.md");
     const moduleAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
         stackContent,
     });
-    if (options.dryRun) {
-        console.log(chalk.gray(`[Dry Run] Would write/update AGENTS.md at ${agentsPath}`));
+    if (options.agent === "antigravity" || options.agent === "both") {
+        if (options.dryRun) {
+            console.log(chalk.gray(`[Dry Run] Would write/update GEMINI.md at ${geminiPath}`));
+        }
+        else {
+            try {
+                await fs.access(geminiPath);
+                await updateFileWithBlock(geminiPath, "STACK_PACK", stackContent);
+                console.log(chalk.green(`✔️ Updated STACK_PACK block in ${geminiPath}`));
+            }
+            catch {
+                await fs.mkdir(targetDir, { recursive: true });
+                await fs.writeFile(geminiPath, moduleAgentsContent, "utf8");
+                console.log(chalk.green(`✔️ Created ${geminiPath}`));
+            }
+        }
     }
-    else {
-        try {
-            await fs.access(agentsPath);
-            await updateFileWithBlock(agentsPath, "STACK_PACK", stackContent);
-            console.log(chalk.green(`✔️ Updated STACK_PACK block in ${agentsPath}`));
+    if (options.agent === "codex" || options.agent === "both") {
+        if (options.dryRun) {
+            console.log(chalk.gray(`[Dry Run] Would write/update AGENTS.md at ${agentsPath}`));
+        }
+        else {
+            try {
+                await fs.access(agentsPath);
+                await updateFileWithBlock(agentsPath, "STACK_PACK", stackContent);
+                console.log(chalk.green(`✔️ Updated STACK_PACK block in ${agentsPath}`));
+            }
+            catch {
+                await fs.mkdir(targetDir, { recursive: true });
+                await fs.writeFile(agentsPath, moduleAgentsContent, "utf8");
+                console.log(chalk.green(`✔️ Created ${agentsPath}`));
+            }
         }
-        catch {
-            await fs.mkdir(targetDir, { recursive: true });
-            await fs.writeFile(agentsPath, moduleAgentsContent, "utf8");
-            console.log(chalk.green(`✔️ Created ${agentsPath}`));
+    }
+    // Write IDE Rules to target directory
+    const ideRulesContent = await renderTemplate("common/ide-rules.hbs", {
+        agent: options.agent,
+    });
+    const ideFiles = [".cursorrules", ".copilot-instructions.md", ".clinerules"];
+    for (const file of ideFiles) {
+        if (options.dryRun) {
+            console.log(chalk.gray(`[Dry Run] Would write IDE rule file to ${path.join(targetDir, file)}`));
+        }
+        else {
+            await fs.writeFile(path.join(targetDir, file), ideRulesContent, "utf8");
         }
     }
+    if (!options.dryRun) {
+        console.log(chalk.green(`✔️ Created IDE prompt anchors at ${targetDir} (.cursorrules, .copilot-instructions.md, .clinerules)`));
+    }
+    await updateGitignore(targetDir, options.dryRun);
     // 4. Copy rules and skills for the target stack
     const stackCtx = analysis[targetStack] || {};
     // A. Copy Rules

package/dist/cli/commands/adr.js

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import chalk from "chalk";
+import { ADRService } from "../../core/awos/adr.js";
+export async function createAdrCommand(options) {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan("\n📝 Creating New Architectural Decision Record (ADR)"));
+    console.log(chalk.dim("------------------------------------------"));
+    const title = options.title || "Decision Title";
+    const status = options.status || "proposed";
+    const context = options.context || "Explain the problem or background context.";
+    const decision = options.decision || "Detail what will change and what decision is made.";
+    const consequences = options.consequences || "What are the positive or negative consequences of this path?";
+    const decisionMaker = options.decisionMaker || "AWOS System";
+    const created = await ADRService.create(cwd, {
+        title,
+        status,
+        context,
+        decision,
+        consequences,
+        metadata: {
+            decisionMakerRole: decisionMaker,
+        },
+    });
+    console.log(chalk.bold.green(`\n🎉 ADR Created Successfully!`));
+    console.log(`${chalk.bold("ID:")}      ${created.id}`);
+    console.log(`${chalk.bold("File:")}    docs/adr/${created.id}.md`);
+    console.log(`${chalk.bold("Title:")}   ${created.title}`);
+    console.log(`${chalk.bold("Status:")}  ${created.status}\n`);
+}
+export async function listAdrsCommand() {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan("\n📖 Architectural Decision Records (ADRs)"));
+    console.log(chalk.dim("------------------------------------------"));
+    const list = await ADRService.list(cwd);
+    if (list.length === 0) {
+        console.log(chalk.gray("No ADRs found under 'docs/adr/'."));
+        return;
+    }
+    for (const adr of list) {
+        let statusColor = chalk.yellow;
+        if (adr.status === "accepted")
+            statusColor = chalk.green;
+        else if (adr.status === "rejected")
+            statusColor = chalk.red;
+        else if (adr.status === "superseded")
+            statusColor = chalk.gray;
+        console.log(`${chalk.bold.green(`- ${adr.id}`)}: ${adr.title} (${statusColor(adr.status)}) [${adr.date}]`);
+        if (adr.metadata?.decisionMakerRole) {
+            console.log(chalk.gray(`  Decision Maker: ${adr.metadata.decisionMakerRole}`));
+        }
+    }
+    console.log("");
+}
+export async function showAdrCommand(id) {
+    const cwd = process.cwd();
+    const adr = await ADRService.load(cwd, id);
+    let statusColor = chalk.yellow;
+    if (adr.status === "accepted")
+        statusColor = chalk.green;
+    else if (adr.status === "rejected")
+        statusColor = chalk.red;
+    else if (adr.status === "superseded")
+        statusColor = chalk.gray;
+    console.log(chalk.bold.cyan(`\n🔍 ADR Details: ${adr.id}`));
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(`${chalk.bold("Title:")}        ${adr.title}`);
+    console.log(`${chalk.bold("Date:")}         ${adr.date}`);
+    console.log(`${chalk.bold("Status:")}       ${statusColor(adr.status)}`);
+    if (adr.metadata?.decisionMakerRole) {
+        console.log(`${chalk.bold("Role:")}         ${adr.metadata.decisionMakerRole}`);
+    }
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(chalk.bold("Context:"));
+    console.log(`  ${adr.context}\n`);
+    console.log(chalk.bold("Decision:"));
+    console.log(`  ${adr.decision}\n`);
+    console.log(chalk.bold("Consequences:"));
+    console.log(`  ${adr.consequences}\n`);
+    console.log(chalk.dim("------------------------------------------\n"));
+}
+export async function searchAdrsCommand(keyword) {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan(`\n🔎 Searching ADRs for keyword: '${keyword}'`));
+    console.log(chalk.dim("------------------------------------------"));
+    const results = await ADRService.search(cwd, keyword);
+    if (results.length === 0) {
+        console.log(chalk.yellow("No decisions found matching the keyword."));
+        return;
+    }
+    console.log(chalk.green(`Found ${results.length} matching ADRs:\n`));
+    for (const adr of results) {
+        console.log(`${chalk.bold.green(`- ${adr.id}`)}: ${adr.title} (${adr.status})`);
+    }
+    console.log("");
+}

package/dist/cli/commands/export.js

@@ -101,6 +101,19 @@ export async function runExport(target, options) {
         output += `=============================\n\n`;
     }
     output = output.trim();
+    if (options.output) {
+        console.log(chalk.blue(`Writing exported workflows to file: ${options.output}...`));
+        try {
+            const fullOutputPath = path.resolve(cwd, options.output);
+            await fs.mkdir(path.dirname(fullOutputPath), { recursive: true });
+            await fs.writeFile(fullOutputPath, output, "utf8");
+            console.log(chalk.green(`✔️ Successfully exported ${parsedSkills.length} custom workflow(s) to ${options.output}!`));
+        }
+        catch (err) {
+            console.error(chalk.red(`❌ Failed to write export file: ${err instanceof Error ? err.message : String(err)}`));
+        }
+        return;
+    }
     if (options.clipboard) {
         console.log(chalk.blue("Copying exported workflows to clipboard..."));
         const success = await writeToClipboard(output);

package/dist/cli/commands/init.js

@@ -18,7 +18,8 @@ function printSuccessAndNextSteps(options) {
         console.log(chalk.bold.cyan("\n👉 Next Steps:"));
         console.log(chalk.dim("------------------------------------------"));
         console.log(chalk.white(`1. Open & review the generated guidelines:`));
-        console.log(chalk.gray(`   - Root: ${chalk.underline("AGENTS.md")}`));
+        const targetFile = options.agent === "antigravity" ? "GEMINI.md" : "AGENTS.md";
+        console.log(chalk.gray(`   - Root: ${chalk.underline(targetFile)}`));
         console.log(chalk.gray(`   - Stack rules: ${chalk.underline(".agents/rules/")}`));
         console.log(chalk.white(`2. Setup automatic git pre-commit hook validation:`));
         console.log(chalk.cyan(`   npx agent-workflow-kit-cli doctor --install-hook`));
@@ -27,6 +28,56 @@ function printSuccessAndNextSteps(options) {
         console.log(chalk.dim("------------------------------------------\n"));
     }
 }
+export async function updateGitignore(targetDir, dryRun) {
+    const gitignorePath = path.join(targetDir, ".gitignore");
+    const rulesToIgnore = [".cursorrules", ".copilot-instructions.md", ".clinerules"];
+    if (dryRun) {
+        console.log(chalk.gray(`[Dry Run] Would update .gitignore in ${targetDir} to exclude IDE rule files.`));
+        return;
+    }
+    try {
+        let content = "";
+        try {
+            content = await fs.readFile(gitignorePath, "utf8");
+        }
+        catch {
+            // gitignore does not exist
+        }
+        const lines = content.split("\n").map((l) => l.trim());
+        const missingRules = rulesToIgnore.filter((rule) => !lines.includes(rule));
+        if (missingRules.length > 0) {
+            const separator = content.length > 0 && !content.endsWith("\n") ? "\n\n" : "";
+            const newContent = content +
+                separator +
+                "# Agent Workflow Kit IDE rules\n" +
+                missingRules.join("\n") +
+                "\n";
+            await fs.writeFile(gitignorePath, newContent, "utf8");
+            console.log(chalk.green("✔️ Updated .gitignore to exclude IDE rules."));
+        }
+    }
+    catch (err) {
+        console.warn(chalk.yellow(`Could not update .gitignore: ${err instanceof Error ? err.message : String(err)}`));
+    }
+}
+async function writeWorkspaceIdeRulesAndGitignore(cwd, options) {
+    const ideRulesContent = await renderTemplate("common/ide-rules.hbs", {
+        agent: options.agent,
+    });
+    const ideFiles = [".cursorrules", ".copilot-instructions.md", ".clinerules"];
+    for (const file of ideFiles) {
+        if (options.dryRun) {
+            console.log(chalk.gray(`[Dry Run] Would write root ${file}`));
+        }
+        else {
+            await fs.writeFile(path.join(cwd, file), ideRulesContent, "utf8");
+        }
+    }
+    if (!options.dryRun) {
+        console.log(chalk.green("✔️ Created workspace IDE prompt anchors (.cursorrules, .copilot-instructions.md, .clinerules)"));
+    }
+    await updateGitignore(cwd, options.dryRun);
+}
 export async function runInit(options) {
     const cwd = process.cwd();
     console.log(chalk.bold.cyan("\n🚀 Agent Workflow Kit - Initializing..."));
@@ -47,40 +98,74 @@ export async function runInit(options) {
         const finalAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
             stackContent: "",
         });
-        if (options.dryRun) {
-            console.log(chalk.gray(`[Dry Run] Would write root AGENTS.md`));
+        if (options.agent === "antigravity" || options.agent === "both") {
+            if (options.dryRun) {
+                console.log(chalk.gray(`[Dry Run] Would write root GEMINI.md`));
+            }
+            else {
+                const geminiPath = path.join(cwd, "GEMINI.md");
+                await fs.writeFile(geminiPath, finalAgentsContent, "utf8");
+                console.log(chalk.green("✔️ Created root GEMINI.md with general guidelines."));
+            }
         }
-        else {
-            const agentsPath = path.join(cwd, "AGENTS.md");
-            await fs.writeFile(agentsPath, finalAgentsContent, "utf8");
-            console.log(chalk.green("✔️ Created root AGENTS.md with general guidelines."));
+        if (options.agent === "codex" || options.agent === "both") {
+            if (options.dryRun) {
+                console.log(chalk.gray(`[Dry Run] Would write root AGENTS.md`));
+            }
+            else {
+                const agentsPath = path.join(cwd, "AGENTS.md");
+                await fs.writeFile(agentsPath, finalAgentsContent, "utf8");
+                console.log(chalk.green("✔️ Created root AGENTS.md with general guidelines."));
+            }
         }
+        await writeWorkspaceIdeRulesAndGitignore(cwd, options);
         printSuccessAndNextSteps(options);
         return;
     }
     const isMonorepo = modules.length > 1 || (modules.length === 1 && modules[0].name !== ".");
-    // Write root AGENTS.md with monorepo details
+    // Write root files with monorepo details
     if (isMonorepo) {
         let monorepoContent = "### 📦 Monorepo Multi-Module Project Structure\n\nThis repository is configured as a monorepo. Please load and follow the stack-specific guidelines in each subdirectory:\n\n";
         for (const mod of modules) {
-            monorepoContent += `- **${mod.name}** (${mod.stacks.join(", ")}): Stack rules and guidelines are located at [${mod.name}/AGENTS.md](file:///${mod.dir.replace(/\\/g, "/")}/AGENTS.md)\n`;
+            const isAntigravity = options.agent === "antigravity";
+            const targetFileName = isAntigravity ? "GEMINI.md" : "AGENTS.md";
+            monorepoContent += `- **${mod.name}** (${mod.stacks.join(", ")}): Stack rules and guidelines are located at [${mod.name}/${targetFileName}](file:///${mod.dir.replace(/\\/g, "/")}/${targetFileName})\n`;
         }
         const rootAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
             stackContent: monorepoContent.trim(),
         });
+        const rootGeminiPath = path.join(cwd, "GEMINI.md");
         const rootAgentsPath = path.join(cwd, "AGENTS.md");
-        if (options.dryRun) {
-            console.log(chalk.gray(`[Dry Run] Would write root AGENTS.md containing monorepo navigation:\n${monorepoContent}`));
+        if (options.agent === "antigravity" || options.agent === "both") {
+            if (options.dryRun) {
+                console.log(chalk.gray(`[Dry Run] Would write root GEMINI.md containing monorepo navigation:\n${monorepoContent}`));
+            }
+            else {
+                try {
+                    await fs.access(rootGeminiPath);
+                    await updateFileWithBlock(rootGeminiPath, "STACK_PACK", monorepoContent.trim());
+                    console.log(chalk.green("✔️ Updated STACK_PACK block in root GEMINI.md."));
+                }
+                catch {
+                    await fs.writeFile(rootGeminiPath, rootAgentsContent, "utf8");
+                    console.log(chalk.green("✔️ Created root GEMINI.md for monorepo."));
+                }
+            }
         }
-        else {
-            try {
-                await fs.access(rootAgentsPath);
-                await updateFileWithBlock(rootAgentsPath, "STACK_PACK", monorepoContent.trim());
-                console.log(chalk.green("✔️ Updated STACK_PACK block in root AGENTS.md."));
+        if (options.agent === "codex" || options.agent === "both") {
+            if (options.dryRun) {
+                console.log(chalk.gray(`[Dry Run] Would write root AGENTS.md containing monorepo navigation:\n${monorepoContent}`));
             }
-            catch {
-                await fs.writeFile(rootAgentsPath, rootAgentsContent, "utf8");
-                console.log(chalk.green("✔️ Created root AGENTS.md for monorepo."));
+            else {
+                try {
+                    await fs.access(rootAgentsPath);
+                    await updateFileWithBlock(rootAgentsPath, "STACK_PACK", monorepoContent.trim());
+                    console.log(chalk.green("✔️ Updated STACK_PACK block in root AGENTS.md."));
+                }
+                catch {
+                    await fs.writeFile(rootAgentsPath, rootAgentsContent, "utf8");
+                    console.log(chalk.green("✔️ Created root AGENTS.md for monorepo."));
+                }
             }
         }
     }
@@ -100,23 +185,42 @@ export async function runInit(options) {
             }
         }
         stackContent = stackContent.trim();
-        // Render AGENTS.md for this module
+        // Render agent files for this module
+        const geminiPath = path.join(mod.dir, "GEMINI.md");
         const agentsPath = path.join(mod.dir, "AGENTS.md");
         const moduleAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
             stackContent,
         });
-        if (options.dryRun) {
-            console.log(chalk.gray(`[Dry Run] Would write AGENTS.md at ${agentsPath}`));
+        if (options.agent === "antigravity" || options.agent === "both") {
+            if (options.dryRun) {
+                console.log(chalk.gray(`[Dry Run] Would write GEMINI.md at ${geminiPath}`));
+            }
+            else {
+                try {
+                    await fs.access(geminiPath);
+                    await updateFileWithBlock(geminiPath, "STACK_PACK", stackContent);
+                    console.log(chalk.green(`✔️ Updated STACK_PACK block in ${mod.name}/GEMINI.md`));
+                }
+                catch {
+                    await fs.writeFile(geminiPath, moduleAgentsContent, "utf8");
+                    console.log(chalk.green(`✔️ Created ${mod.name}/GEMINI.md`));
+                }
+            }
         }
-        else {
-            try {
-                await fs.access(agentsPath);
-                await updateFileWithBlock(agentsPath, "STACK_PACK", stackContent);
-                console.log(chalk.green(`✔️ Updated STACK_PACK block in ${mod.name}/AGENTS.md`));
+        if (options.agent === "codex" || options.agent === "both") {
+            if (options.dryRun) {
+                console.log(chalk.gray(`[Dry Run] Would write AGENTS.md at ${agentsPath}`));
             }
-            catch {
-                await fs.writeFile(agentsPath, moduleAgentsContent, "utf8");
-                console.log(chalk.green(`✔️ Created ${mod.name}/AGENTS.md`));
+            else {
+                try {
+                    await fs.access(agentsPath);
+                    await updateFileWithBlock(agentsPath, "STACK_PACK", stackContent);
+                    console.log(chalk.green(`✔️ Updated STACK_PACK block in ${mod.name}/AGENTS.md`));
+                }
+                catch {
+                    await fs.writeFile(agentsPath, moduleAgentsContent, "utf8");
+                    console.log(chalk.green(`✔️ Created ${mod.name}/AGENTS.md`));
+                }
             }
         }
         // Copy common skills for this module
@@ -186,5 +290,7 @@ export async function runInit(options) {
             }
         }
     }
+    // Write workspace-level IDE rules and update gitignore
+    await writeWorkspaceIdeRulesAndGitignore(cwd, options);
     printSuccessAndNextSteps(options);
 }

package/dist/cli/commands/profile.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import chalk from "chalk";
+import { getRepositoryContext } from "../../core/awos/intelligence.js";
+import { loadProfile, validateArchitecture } from "../../core/awos/profiles.js";
+export async function runProfileCheck(options) {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan("\n🔎 AWOS Architecture Profile Linter"));
+    console.log(chalk.dim("------------------------------------------"));
+    const context = await getRepositoryContext(cwd);
+    const targetProfileName = options.profile || context.architecture;
+    console.log(`Target Profile: ${chalk.green(targetProfileName)} (detected from ${chalk.yellow(context.stack)})`);
+    console.log(chalk.dim("------------------------------------------\n"));
+    try {
+        const profile = await loadProfile(targetProfileName);
+        console.log(chalk.gray("Scanning workspace files for structural rules constraints..."));
+        const violations = await validateArchitecture(cwd, profile);
+        if (violations.length === 0) {
+            console.log(chalk.bold.green("\n🎉 Congratulations! Zero architecture or package boundaries violations found."));
+            return;
+        }
+        console.log(chalk.bold.red(`\n⚠️ Found ${violations.length} architectural rule violations:\n`));
+        for (const v of violations) {
+            const color = v.severity === "error" ? chalk.red : chalk.yellow;
+            console.log(`${color(`[${v.severity.toUpperCase()}]`)} ${chalk.underline(v.filePath)}`);
+            console.log(chalk.gray(`  Rule: ${v.ruleName} - ${v.message}\n`));
+        }
+        process.exit(1);
+    }
+    catch (err) {
+        throw new Error(`Profile check failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/cli/commands/role.js

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import chalk from "chalk";
+import path from "path";
+import { RoleRegistry } from "../../core/awos/registry.js";
+const DEFAULT_ROLES_DIR = ".agents/roles";
+export async function listRoles() {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan("\n👥 Discovered Agent Role Catalog"));
+    console.log(chalk.dim("------------------------------------------"));
+    const dir = path.join(cwd, DEFAULT_ROLES_DIR);
+    const list = await RoleRegistry.discover(dir);
+    if (list.length === 0) {
+        console.log(chalk.gray(`No roles found under '${DEFAULT_ROLES_DIR}/'.`));
+        return;
+    }
+    for (const role of list) {
+        console.log(`${chalk.bold.green(`- ${role.id}`)}: ${role.name}`);
+        console.log(chalk.gray(`  ${role.description}\n`));
+    }
+}
+export async function showRole(id) {
+    const cwd = process.cwd();
+    const dir = path.join(cwd, DEFAULT_ROLES_DIR);
+    const role = await RoleRegistry.load(id, dir);
+    console.log(chalk.bold.cyan(`\n🔍 Agent Role: ${role.id}`));
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(`${chalk.bold("Name:")}        ${role.name}`);
+    console.log(`${chalk.bold("Description:")} ${role.description}`);
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(chalk.bold("Responsibilities:"));
+    for (const resp of role.responsibilities) {
+        console.log(`  - ${resp}`);
+    }
+    console.log(chalk.bold("\nRequired Inputs:"));
+    for (const inp of role.requiredInputs) {
+        console.log(`  - ${inp}`);
+    }
+    console.log(chalk.bold("\nExpected Outputs:"));
+    for (const out of role.expectedOutputs) {
+        console.log(`  - ${out}`);
+    }
+    console.log(chalk.bold("\nValidation Checklist:"));
+    for (const item of role.validationChecklist) {
+        console.log(`  - ${item}`);
+    }
+    console.log(chalk.bold("\nReview Checklist:"));
+    for (const item of role.reviewChecklist) {
+        console.log(`  - ${item}`);
+    }
+    console.log(chalk.dim("------------------------------------------\n"));
+}
+export async function validateRoles() {
+    const cwd = process.cwd();
+    const dir = path.join(cwd, DEFAULT_ROLES_DIR);
+    try {
+        const list = await RoleRegistry.discover(dir);
+        if (list.length === 0) {
+            console.log(chalk.yellow(`No roles discovered to validate under '${DEFAULT_ROLES_DIR}/'.`));
+            return;
+        }
+        for (const role of list) {
+            RoleRegistry.validate(role);
+            console.log(chalk.green(`✔️ Role '${role.id}' is schema valid.`));
+        }
+        console.log(chalk.bold.green(`\n🎉 All ${list.length} agent roles validated successfully!`));
+    }
+    catch (err) {
+        console.error(chalk.bold.red(`\n❌ Agent Role validation failed:`));
+        console.error(chalk.red(`  ${err instanceof Error ? err.message : String(err)}`));
+        process.exit(1);
+    }
+}

package/dist/cli/commands/run.js

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import chalk from "chalk";
+import { promises as fs } from "fs";
+import path from "path";
+import { WorkflowRuntime } from "../../core/awos/runtime.js";
+export async function runWorkflowCommand(workflowPath, options) {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan("\n🚀 AWOS Workflow Executor"));
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(`Workflow File: ${chalk.green(workflowPath)}`);
+    console.log(`Dry Run:       ${options.dryRun ? chalk.yellow("Enabled 🧪") : chalk.gray("Disabled")}`);
+    console.log(chalk.dim("------------------------------------------\n"));
+    let graph;
+    try {
+        const fullPath = path.resolve(cwd, workflowPath);
+        const content = await fs.readFile(fullPath, "utf8");
+        graph = JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to load workflow file: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let inputs = {};
+    if (options.inputs) {
+        try {
+            const inputsPath = path.resolve(cwd, options.inputs);
+            const content = await fs.readFile(inputsPath, "utf8");
+            inputs = JSON.parse(content);
+        }
+        catch {
+            // Inline JSON parsing
+            try {
+                inputs = JSON.parse(options.inputs);
+            }
+            catch (err) {
+                throw new Error(`Failed to parse inputs parameters: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    const runtime = new WorkflowRuntime(cwd);
+    const result = await runtime.run(graph, inputs, { dryRun: options.dryRun });
+    console.log(chalk.dim("\n------------------------------------------"));
+    if (result.status === "SUCCESS") {
+        console.log(chalk.bold.green(`✔️ Workflow execution succeeded! Run ID: ${result.runId}`));
+    }
+    else if (result.status === "PAUSED") {
+        console.log(chalk.bold.yellow(`⚠️ Workflow execution paused. Resume using: awk run resume ${result.runId}`));
+    }
+    else {
+        console.log(chalk.bold.red(`❌ Workflow execution failed. Run ID: ${result.runId}`));
+    }
+}
+export async function resumeWorkflowCommand(runId) {
+    const cwd = process.cwd();
+    const runFile = path.resolve(cwd, `.agents/state/runs/${runId}.json`);
+    console.log(chalk.bold.cyan(`\n🚀 AWOS Workflow Executor - Resuming Run '${runId}'`));
+    console.log(chalk.dim("------------------------------------------"));
+    try {
+        const runContent = await fs.readFile(runFile, "utf8");
+        const runState = JSON.parse(runContent);
+        console.log(`Active step state was: ${chalk.yellow(runState.status)}`);
+        // Simulate resumption by completing approval steps
+        runState.status = "EXECUTING";
+        const pausedStepIdx = runState.steps.findIndex((s) => s.status === "WAITING_APPROVAL");
+        if (pausedStepIdx !== -1) {
+            runState.steps[pausedStepIdx].status = "COMPLETED";
+            runState.steps[pausedStepIdx].completedAt = new Date().toISOString();
+            console.log(`✔️ Human approved step: ${chalk.green(runState.steps[pausedStepIdx].name)}`);
+        }
+        await fs.writeFile(runFile, JSON.stringify(runState, null, 2), "utf8");
+        console.log(chalk.green(`✔️ Run '${runId}' successfully resumed & marked completed!`));
+    }
+    catch (err) {
+        throw new Error(`Failed to resume execution run '${runId}': ${err instanceof Error ? err.message : String(err)}`);
+    }
+}