agent-workflow-kit-cli 1.0.0-mvp

package/dist/cli/commands/init.js

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import chalk from "chalk";
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { detectProjectModules } from "../../core/detector.js";
+import { renderTemplate, readStaticTemplateFile, getStackRules, getStackSkills, } from "../../core/renderer.js";
+import { updateFileWithBlock, writeRuleWithChunking, } from "../../core/emitter.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function printSuccessAndNextSteps(options) {
+    console.log(chalk.bold.green("\n🎉 Initialization completed successfully!"));
+    if (!options.dryRun) {
+        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")}`));
+        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(`   run: npx agent-workflow-kit-cli doctor --install-hook`));
+        console.log(chalk.white(`3. Export custom skills to register with your AI agent (e.g. Antigravity):`));
+        console.log(chalk.cyan(`   run: npx agent-workflow-kit-cli export antigravity`));
+        console.log(chalk.dim("------------------------------------------\n"));
+    }
+}
+export async function runInit(options) {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan("\n🚀 Agent Workflow Kit - Initializing..."));
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(`${chalk.bold("Stack Selection:")} ${chalk.green(options.stack)}`);
+    console.log(`${chalk.bold("Agent Profile:")}   ${chalk.green(options.agent)}`);
+    console.log(`${chalk.bold("Dry Run:")}         ${options.dryRun ? chalk.yellow("Enabled 🧪") : chalk.gray("Disabled")}`);
+    console.log(chalk.dim("------------------------------------------\n"));
+    let modules;
+    if (options.stack !== "auto") {
+        modules = [{ dir: cwd, name: ".", stacks: [options.stack] }];
+    }
+    else {
+        modules = await detectProjectModules(cwd);
+    }
+    if (modules.length === 0) {
+        console.log(chalk.yellow("No standard stacks detected automatically. Creating general agent guidelines at root."));
+        const finalAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            stackContent: "",
+        });
+        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."));
+        }
+        printSuccessAndNextSteps(options);
+        return;
+    }
+    const isMonorepo = modules.length > 1 || (modules.length === 1 && modules[0].name !== ".");
+    // Write root AGENTS.md 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 rootAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            stackContent: monorepoContent.trim(),
+        });
+        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}`));
+        }
+        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."));
+            }
+        }
+    }
+    // Process each module
+    for (const mod of modules) {
+        console.log(chalk.cyan(`\nProcessing module: ${mod.name} (stacks: ${mod.stacks.join(", ")})`));
+        let stackContent = "";
+        for (const stack of mod.stacks) {
+            try {
+                const rendered = await renderTemplate(`${stack}/AGENTS.md.hbs`, {});
+                stackContent += rendered + "\n\n";
+            }
+            catch (err) {
+                console.warn(chalk.yellow(`Could not load template for stack '${stack}': ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
+        stackContent = stackContent.trim();
+        // Render AGENTS.md for this module
+        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}`));
+        }
+        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 rules and skills for each stack in this module
+        for (const stack of mod.stacks) {
+            // A. Rules
+            const rules = await getStackRules(stack);
+            for (const rule of rules) {
+                const relativeRulePath = `${stack}/rules/${rule}`;
+                try {
+                    const ruleContent = await readStaticTemplateFile(relativeRulePath);
+                    const targetRulePath = path.join(mod.dir, ".agents", "rules", rule);
+                    if (options.dryRun) {
+                        console.log(chalk.gray(`[Dry Run] Would write rule to ${targetRulePath} (length: ${ruleContent.length} chars)`));
+                    }
+                    else {
+                        await writeRuleWithChunking(targetRulePath, ruleContent);
+                        console.log(chalk.green(`✔️ Wrote rule ${rule} to ${mod.name}/.agents/rules/${rule}`));
+                    }
+                }
+                catch (err) {
+                    console.error(chalk.red(`Failed to copy rule ${rule}: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            }
+            // B. Skills
+            const skills = await getStackSkills(stack);
+            for (const skill of skills) {
+                const relativeSkillPath = `${stack}/skills/${skill}`;
+                try {
+                    const skillContent = await readStaticTemplateFile(relativeSkillPath);
+                    const targetSkillPath = path.join(mod.dir, ".agents", "skills", skill);
+                    if (options.dryRun) {
+                        console.log(chalk.gray(`[Dry Run] Would write skill to ${targetSkillPath}`));
+                    }
+                    else {
+                        await fs.mkdir(path.dirname(targetSkillPath), { recursive: true });
+                        await fs.writeFile(targetSkillPath, skillContent, "utf8");
+                        console.log(chalk.green(`✔️ Wrote skill ${skill} to ${mod.name}/.agents/skills/${skill}`));
+                    }
+                }
+                catch (err) {
+                    console.error(chalk.red(`Failed to copy skill ${skill}: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            }
+        }
+    }
+    printSuccessAndNextSteps(options);
+}

package/dist/cli/commands/sync.js

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { runInit } from "./init.js";
+export async function runSync(options) {
+    await runInit({
+        stack: "auto",
+        agent: "both",
+        dryRun: options.dryRun,
+    });
+}

package/dist/cli/index.js

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { Command } from "commander";
+import chalk from "chalk";
+import { runInit } from "./commands/init.js";
+import { runSync } from "./commands/sync.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runExport } from "./commands/export.js";
+const program = new Command();
+export function runCli() {
+    program
+        .name("agent-workflow-kit")
+        .description("Generate AI coding workflows/rules/templates for Codex and Antigravity")
+        .version("1.0.0-mvp");
+    program
+        .command("init")
+        .description("Initialize agent guidelines and skills for the repository")
+        .option("--stack <stack>", "Specify target stack: auto | spring-boot | react-ts | fastapi", "auto")
+        .option("--agent <agent>", "Specify target agent profile: both | codex | antigravity", "both")
+        .option("--dry-run", "Output actions to console without writing any files", false)
+        .action(async (options) => {
+        try {
+            await runInit(options);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error running init: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    program
+        .command("sync")
+        .description("Sync generated guidelines and skills inside managed blocks")
+        .option("--dry-run", "Output changes to console without saving", false)
+        .action(async (options) => {
+        try {
+            await runSync(options);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error running sync: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    program
+        .command("doctor")
+        .description("Verify active agent configurations, environment, and run validation tests")
+        .option("--install-hook", "Install a git pre-commit hook to automatically run doctor checks", false)
+        .action(async (options) => {
+        try {
+            await runDoctor(options);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error running doctor: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    program
+        .command("export <target>")
+        .description("Export custom workflows/skills for the target agent (e.g., 'antigravity')")
+        .option("--no-clipboard", "Do not copy the exported instructions to clipboard", false)
+        .action(async (target, options) => {
+        try {
+            await runExport(target, { clipboard: options.clipboard });
+        }
+        catch (err) {
+            console.error(chalk.red(`Error running export: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    program.parse(process.argv);
+}

package/dist/core/detector.js

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { promises as fs } from "fs";
+import path from "path";
+/**
+ * Scans a specific folder directly for manifest configurations.
+ */
+async function detectProjectStackDirect(cwd) {
+    const stacks = [];
+    // 1. Detect Java Spring Boot (pom.xml)
+    try {
+        const pomPath = path.join(cwd, "pom.xml");
+        const stat = await fs.stat(pomPath);
+        if (stat.isFile()) {
+            stacks.push("spring-boot");
+        }
+    }
+    catch {
+        // Ignore
+    }
+    // 2. Detect React + TypeScript (package.json containing react dependency)
+    try {
+        const pkgPath = path.join(cwd, "package.json");
+        const content = await fs.readFile(pkgPath, "utf8");
+        const pkgJson = JSON.parse(content);
+        const hasReact = (pkgJson.dependencies && pkgJson.dependencies.react) ||
+            (pkgJson.devDependencies && pkgJson.devDependencies.react);
+        if (hasReact) {
+            stacks.push("react-ts");
+        }
+    }
+    catch {
+        // Ignore
+    }
+    // 3. Detect Python FastAPI (pyproject.toml or requirements.txt containing fastapi)
+    try {
+        const pyprojectPath = path.join(cwd, "pyproject.toml");
+        const content = await fs.readFile(pyprojectPath, "utf8");
+        if (content.includes("fastapi")) {
+            stacks.push("fastapi");
+        }
+    }
+    catch {
+        try {
+            const reqPath = path.join(cwd, "requirements.txt");
+            const content = await fs.readFile(reqPath, "utf8");
+            if (content.includes("fastapi")) {
+                stacks.push("fastapi");
+            }
+        }
+        catch {
+            // Ignore
+        }
+    }
+    return stacks;
+}
+/**
+ * Scans the workspace directory and subfolders (1-level deep) for monorepo detection.
+ */
+export async function detectProjectStack(cwd) {
+    const stacks = await detectProjectStackDirect(cwd);
+    // Scan 1-level deep subdirectories for potential monorepos/multimodules
+    try {
+        const entries = await fs.readdir(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() &&
+                !entry.name.startsWith(".") &&
+                entry.name !== "node_modules" &&
+                entry.name !== "dist") {
+                const subPath = path.join(cwd, entry.name);
+                const subStacks = await detectProjectStackDirect(subPath);
+                for (const stack of subStacks) {
+                    if (!stacks.includes(stack)) {
+                        stacks.push(stack);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore
+    }
+    return stacks;
+}
+/**
+ * Detects stacks grouped by module directories (root + 1-level deep directories).
+ */
+export async function detectProjectModules(cwd) {
+    const modules = [];
+    const rootStacks = await detectProjectStackDirect(cwd);
+    if (rootStacks.length > 0) {
+        modules.push({
+            dir: cwd,
+            name: ".",
+            stacks: rootStacks,
+        });
+    }
+    try {
+        const entries = await fs.readdir(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() &&
+                !entry.name.startsWith(".") &&
+                entry.name !== "node_modules" &&
+                entry.name !== "dist") {
+                const subPath = path.join(cwd, entry.name);
+                const subStacks = await detectProjectStackDirect(subPath);
+                if (subStacks.length > 0) {
+                    modules.push({
+                        dir: subPath,
+                        name: entry.name,
+                        stacks: subStacks,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore
+    }
+    return modules;
+}

package/dist/core/emitter.js

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { promises as fs } from "fs";
+import path from "path";
+/**
+ * Splits the given string into chunks of at most maxChars.
+ * It tries to split at line boundaries to avoid cutting lines or words.
+ */
+export function chunkText(content, maxChars = 10000) {
+    const lines = content.split("\n");
+    const chunks = [];
+    let currentChunk = [];
+    let currentLength = 0;
+    for (const line of lines) {
+        const lineLen = line.length + 1; // +1 for the newline
+        if (currentLength + lineLen > maxChars && currentChunk.length > 0) {
+            chunks.push(currentChunk.join("\n"));
+            currentChunk = [];
+            currentLength = 0;
+        }
+        currentChunk.push(line);
+        currentLength += lineLen;
+    }
+    if (currentChunk.length > 0) {
+        chunks.push(currentChunk.join("\n"));
+    }
+    return chunks;
+}
+/**
+ * Deletes old rule part files matching the pattern `<rule-name>-part*.md`.
+ */
+async function cleanOldChunks(filePath) {
+    const dir = path.dirname(filePath);
+    const ext = path.extname(filePath);
+    const baseWithoutExt = path.basename(filePath, ext);
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() &&
+                entry.name.startsWith(`${baseWithoutExt}-part`) &&
+                entry.name.endsWith(ext)) {
+                await fs.unlink(path.join(dir, entry.name));
+            }
+        }
+    }
+    catch {
+        // Ignore directory not existing
+    }
+}
+/**
+ * Writes rule file content.
+ * If the content is longer than 10,000 characters, it chunks it into part files
+ * and writes a main rule index referencing them with `@<part-file-name>.md`.
+ */
+export async function writeRuleWithChunking(filePath, content, maxChars = 10000) {
+    // Ensure the target directory exists
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    // Always clean up old parts first to prevent leftover files
+    await cleanOldChunks(filePath);
+    if (content.length <= maxChars) {
+        await fs.writeFile(filePath, content, "utf8");
+        return;
+    }
+    // Need to chunk
+    const chunks = chunkText(content, maxChars);
+    const ext = path.extname(filePath);
+    const baseWithoutExt = path.basename(filePath, ext);
+    const partRefs = [];
+    for (let i = 0; i < chunks.length; i++) {
+        const partFileName = `${baseWithoutExt}-part${i + 1}${ext}`;
+        const partPath = path.join(path.dirname(filePath), partFileName);
+        await fs.writeFile(partPath, chunks[i], "utf8");
+        partRefs.push(`@${partFileName}`);
+    }
+    // Create main rule index file
+    const mainContent = `# ${baseWithoutExt} Rules
+
+This ruleset is split into multiple parts to stay within agent context limitations. The agent MUST load and follow all referenced parts:
+
+${partRefs.map((ref) => `- ${ref}`).join("\n")}
+`;
+    await fs.writeFile(filePath, mainContent, "utf8");
+}
+/**
+ * Updates a file with a managed block content.
+ * If the file does not exist, it creates it with the block wrapper.
+ * If the block does not exist in the file, it appends the block wrapper.
+ * If the block exists, it replaces the content inside the block.
+ */
+export async function updateFileWithBlock(filePath, blockId, newContent) {
+    const startTag = `<!-- AWK-START: ${blockId} -->`;
+    const endTag = `<!-- AWK-END: ${blockId} -->`;
+    const wrappedContent = `${startTag}\n${newContent}\n${endTag}`;
+    let fileContent = "";
+    try {
+        fileContent = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        // File doesn't exist, we will create it
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, wrappedContent, "utf8");
+        return;
+    }
+    // Regex to match the block
+    const escapedStart = startTag.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const escapedEnd = endTag.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const regex = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`);
+    if (regex.test(fileContent)) {
+        const updatedContent = fileContent.replace(regex, wrappedContent);
+        await fs.writeFile(filePath, updatedContent, "utf8");
+    }
+    else {
+        // Append to end of file
+        const separator = fileContent.length > 0 && !fileContent.endsWith("\n") ? "\n\n" : "\n";
+        await fs.writeFile(filePath, `${fileContent}${separator}${wrappedContent}`, "utf8");
+    }
+}

package/dist/core/renderer.js

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import handlebars from "handlebars";
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// The templates directory is located at '../../templates' relative to 'dist/core/renderer.js'
+const TEMPLATES_DIR = path.resolve(__dirname, "../../templates");
+/**
+ * Loads a Handlebars template, compiles it, and renders it with the given context.
+ * @param templatePath Relative path to the template inside the templates directory (e.g. 'common/AGENTS.md.hbs')
+ * @param context Key-value context data for compilation
+ */
+export async function renderTemplate(templatePath, context) {
+    const fullPath = path.join(TEMPLATES_DIR, templatePath);
+    const fileContent = await fs.readFile(fullPath, "utf8");
+    const compiled = handlebars.compile(fileContent);
+    return compiled(context);
+}
+/**
+ * Reads a static rules file as-is without Handlebars interpolation.
+ * @param filePath Relative path inside templates folder (e.g. 'spring-boot/rules/java-style.md')
+ */
+export async function readStaticTemplateFile(filePath) {
+    const fullPath = path.join(TEMPLATES_DIR, filePath);
+    return fs.readFile(fullPath, "utf8");
+}
+/**
+ * Gets all rules files for a stack.
+ */
+export async function getStackRules(stack) {
+    const rulesDir = path.join(TEMPLATES_DIR, stack, "rules");
+    try {
+        const files = await fs.readdir(rulesDir);
+        return files.filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Gets all skills for a stack.
+ */
+export async function getStackSkills(stack) {
+    const skillsDir = path.join(TEMPLATES_DIR, stack, "skills");
+    try {
+        const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+        const skills = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const skillFilePath = path.join(skillsDir, entry.name, "SKILL.md");
+                try {
+                    await fs.access(skillFilePath);
+                    skills.push(`${entry.name}/SKILL.md`);
+                }
+                catch {
+                    // Ignore if SKILL.md doesn't exist
+                }
+            }
+        }
+        return skills;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { runCli } from "./cli/index.js";
+runCli();

package/dist/utils/clipboard.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { execa } from "execa";
+/**
+ * Copies the provided text to the system clipboard in a cross-platform manner using execa.
+ */
+export async function writeToClipboard(text) {
+    try {
+        if (process.platform === "win32") {
+            // Use clip command on Windows
+            await execa("clip", { input: text });
+            return true;
+        }
+        else if (process.platform === "darwin") {
+            // Use pbcopy on macOS
+            await execa("pbcopy", { input: text });
+            return true;
+        }
+        else {
+            // Linux: try xclip first, fallback to xsel
+            try {
+                await execa("xclip", ["-selection", "clipboard"], { input: text });
+                return true;
+            }
+            catch {
+                await execa("xsel", ["--clipboard", "--input"], { input: text });
+                return true;
+            }
+        }
+    }
+    catch (err) {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "agent-workflow-kit-cli",
+  "version": "1.0.0-mvp",
+  "description": "AI-Ready Repository Workflow Generator & Guideline Optimizer for Codex and Antigravity",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "agent-workflow-kit": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "author": "Truong & Cat",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "execa": "^9.2.0",
+    "handlebars": "^4.7.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.9",
+    "typescript": "^5.5.2",
+    "vitest": "^2.1.9"
+  }
+}