agent-workflow-kit-cli 1.3.2 → 1.3.4

package/dist/cli/commands/add.js

@@ -11,7 +11,7 @@ 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", "next-js", "nestjs", "express", "fastapi", "python-ai", "dotnet"];
+    const validStacks = ["spring-boot", "react-ts", "next-js", "nestjs", "express", "fastapi", "python-ai", "dotnet", "golang", "rust", "diagram", "devops"];
     if (!validStacks.includes(targetStack)) {
         console.error(chalk.red(`Error: Invalid stack '${stack}'. Supported stacks are: ${validStacks.join(", ")}`));
         process.exit(1);
@@ -40,7 +40,9 @@ export async function runAdd(stack, options) {
     // 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 globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
     const moduleAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+        globalRules,
         stackContent,
     });
     if (options.agent === "antigravity" || options.agent === "both") {

package/dist/cli/commands/doctor.js

@@ -6,7 +6,7 @@ import chalk from "chalk";
 import { promises as fs } from "fs";
 import path from "path";
 import { execa } from "execa";
-import { detectProjectStack } from "../../core/detector.js";
+import { detectProjectModules } from "../../core/detector.js";
 export async function runDoctor(options) {
     const cwd = process.cwd();
     if (options.installHook) {
@@ -55,63 +55,161 @@ npx agent-workflow-kit-cli doctor || exit 1
         return;
     }
     console.log(chalk.blue("Running doctor checks on repository..."));
-    // 1. Detect Stack
-    const stacks = await detectProjectStack(cwd);
-    console.log(chalk.gray(`Detected stacks: ${stacks.join(", ") || "None"}`));
-    if (stacks.length === 0) {
-        console.log(chalk.yellow("No standard stack pack detected. Nothing to validate."));
+    // 1. Detect Modules
+    const modules = await detectProjectModules(cwd);
+    if (modules.length === 0) {
+        console.log(chalk.yellow("No standard project modules detected. Nothing to validate."));
         return;
     }
+    console.log(chalk.gray(`Detected modules: ${modules.map(m => `${m.name} [${m.stacks.join(", ")}]`).join(", ")}`));
     // 2. Validate
     let passed = true;
-    for (const stack of stacks) {
-        console.log(chalk.blue(`\nValidating stack: ${stack}...`));
-        try {
-            if (stack === "spring-boot") {
-                console.log(chalk.gray("Running: ./mvnw clean compile"));
-                await execa("./mvnw", ["clean", "compile"], { cwd, stdio: "inherit" });
-            }
-            else if (stack === "fastapi") {
-                console.log(chalk.gray("Running: ruff check ."));
-                await execa("ruff", ["check", "."], { cwd, stdio: "inherit" });
-            }
-            else if (stack === "python-ai") {
-                let cmd = "ruff";
-                let args = ["check", "."];
-                try {
-                    const hasPoetry = await fs.stat(path.join(cwd, "poetry.lock")).then(s => s.isFile()).catch(() => false);
-                    if (hasPoetry) {
-                        cmd = "poetry";
-                        args = ["run", "python", "-m", "ruff", "check", "."];
+    for (const mod of modules) {
+        console.log(chalk.blue(`\nValidating module: ${mod.name === "." ? "root" : mod.name}...`));
+        for (const stack of mod.stacks) {
+            console.log(chalk.cyan(`  Validating stack: ${stack}...`));
+            try {
+                if (stack === "spring-boot") {
+                    // Check for maven wrapper or gradle wrapper
+                    const hasGradle = (await fs.stat(path.join(mod.dir, "build.gradle")).then((s) => s.isFile()).catch(() => false)) ||
+                        (await fs.stat(path.join(mod.dir, "build.gradle.kts")).then((s) => s.isFile()).catch(() => false));
+                    if (hasGradle) {
+                        let gradlewPath = "./gradlew";
+                        try {
+                            await fs.access(path.join(mod.dir, "gradlew"));
+                        }
+                        catch {
+                            try {
+                                await fs.access(path.join(cwd, "gradlew"));
+                                gradlewPath = path.relative(mod.dir, path.join(cwd, "gradlew")).replace(/\\/g, "/");
+                                if (!gradlewPath.startsWith("."))
+                                    gradlewPath = "./" + gradlewPath;
+                            }
+                            catch {
+                                gradlewPath = "gradle";
+                            }
+                        }
+                        console.log(chalk.gray(`Running: ${gradlewPath} check in ${mod.dir}`));
+                        await execa(gradlewPath, ["check"], { cwd: mod.dir, stdio: "inherit" });
                     }
                     else {
-                        const hasPipenv = await fs.stat(path.join(cwd, "Pipfile")).then(s => s.isFile()).catch(() => false);
-                        if (hasPipenv) {
-                            cmd = "pipenv";
-                            args = ["run", "python", "-m", "ruff", "check", "."];
+                        let mvnwPath = "./mvnw";
+                        try {
+                            await fs.access(path.join(mod.dir, "mvnw"));
                         }
+                        catch {
+                            try {
+                                await fs.access(path.join(cwd, "mvnw"));
+                                mvnwPath = path.relative(mod.dir, path.join(cwd, "mvnw")).replace(/\\/g, "/");
+                                if (!mvnwPath.startsWith("."))
+                                    mvnwPath = "./" + mvnwPath;
+                            }
+                            catch {
+                                mvnwPath = "mvn";
+                            }
+                        }
+                        console.log(chalk.gray(`Running: ${mvnwPath} clean compile in ${mod.dir}`));
+                        await execa(mvnwPath, ["clean", "compile"], { cwd: mod.dir, stdio: "inherit" });
                     }
                 }
-                catch { }
-                console.log(chalk.gray(`Running: ${cmd} ${args.join(" ")}`));
-                await execa(cmd, args, { cwd, stdio: "inherit" });
-            }
-            else if (stack === "react-ts" ||
-                stack === "next-js" ||
-                stack === "nestjs" ||
-                stack === "express") {
-                console.log(chalk.gray("Running: npx tsc --noEmit"));
-                await execa("npx", ["tsc", "--noEmit"], { cwd, stdio: "inherit" });
+                else if (stack === "fastapi") {
+                    console.log(chalk.gray(`Running: ruff check . in ${mod.dir}`));
+                    await execa("ruff", ["check", "."], { cwd: mod.dir, stdio: "inherit" });
+                }
+                else if (stack === "python-ai") {
+                    let cmd = "ruff";
+                    let args = ["check", "."];
+                    try {
+                        const hasPoetry = await fs.stat(path.join(mod.dir, "poetry.lock")).then(s => s.isFile()).catch(() => false);
+                        if (hasPoetry) {
+                            cmd = "poetry";
+                            args = ["run", "ruff", "check", "."];
+                        }
+                        else {
+                            const hasPipenv = await fs.stat(path.join(mod.dir, "Pipfile")).then(s => s.isFile()).catch(() => false);
+                            if (hasPipenv) {
+                                cmd = "pipenv";
+                                args = ["run", "ruff", "check", "."];
+                            }
+                        }
+                    }
+                    catch { }
+                    console.log(chalk.gray(`Running: ${cmd} ${args.join(" ")} in ${mod.dir}`));
+                    await execa(cmd, args, { cwd: mod.dir, stdio: "inherit" });
+                }
+                else if (stack === "react-ts" ||
+                    stack === "next-js" ||
+                    stack === "nestjs" ||
+                    stack === "express") {
+                    let pm = "npm";
+                    try {
+                        const hasYarnLock = await fs.stat(path.join(mod.dir, "yarn.lock")).then((s) => s.isFile()).catch(() => false);
+                        const hasPnpmLock = await fs.stat(path.join(mod.dir, "pnpm-lock.yaml")).then((s) => s.isFile()).catch(() => false);
+                        const hasBunLockb = await fs.stat(path.join(mod.dir, "bun.lockb")).then((s) => s.isFile()).catch(() => false);
+                        const hasBunLock = await fs.stat(path.join(mod.dir, "bun.lock")).then((s) => s.isFile()).catch(() => false);
+                        if (hasYarnLock)
+                            pm = "yarn";
+                        else if (hasPnpmLock)
+                            pm = "pnpm";
+                        else if (hasBunLockb || hasBunLock)
+                            pm = "bun";
+                    }
+                    catch { }
+                    try {
+                        const pkgContent = await fs.readFile(path.join(mod.dir, "package.json"), "utf8");
+                        const pkg = JSON.parse(pkgContent);
+                        const scripts = pkg.scripts || {};
+                        if (scripts.lint) {
+                            console.log(chalk.gray(`Running: ${pm} run lint in ${mod.dir}`));
+                            await execa(pm, ["run", "lint"], { cwd: mod.dir, stdio: "inherit" });
+                        }
+                        console.log(chalk.gray(`Running: npx tsc --noEmit in ${mod.dir}`));
+                        await execa("npx", ["tsc", "--noEmit"], { cwd: mod.dir, stdio: "inherit" });
+                        if (scripts.test) {
+                            const hasVitest = pkg.dependencies?.vitest || pkg.devDependencies?.vitest;
+                            const hasJest = pkg.dependencies?.jest || pkg.devDependencies?.jest;
+                            let args = ["run", "test"];
+                            if (hasVitest || hasJest) {
+                                if (pm === "npm") {
+                                    args = ["run", "test", "--", "--run"];
+                                }
+                                else {
+                                    args = ["run", "test", "--run"];
+                                }
+                            }
+                            console.log(chalk.gray(`Running: ${pm} ${args.join(" ")} in ${mod.dir}`));
+                            await execa(pm, args, { cwd: mod.dir, stdio: "inherit", env: { ...process.env, CI: "true" } });
+                        }
+                    }
+                    catch {
+                        console.log(chalk.gray(`Running: npx tsc --noEmit in ${mod.dir}`));
+                        await execa("npx", ["tsc", "--noEmit"], { cwd: mod.dir, stdio: "inherit" });
+                    }
+                }
+                else if (stack === "dotnet") {
+                    console.log(chalk.gray(`Running: dotnet build in ${mod.dir}`));
+                    await execa("dotnet", ["build"], { cwd: mod.dir, stdio: "inherit" });
+                    console.log(chalk.gray(`Running: dotnet test in ${mod.dir}`));
+                    await execa("dotnet", ["test"], { cwd: mod.dir, stdio: "inherit" });
+                }
+                else if (stack === "golang") {
+                    console.log(chalk.gray(`Running: go build ./... in ${mod.dir}`));
+                    await execa("go", ["build", "./..."], { cwd: mod.dir, stdio: "inherit" });
+                    console.log(chalk.gray(`Running: go test ./... in ${mod.dir}`));
+                    await execa("go", ["test", "./..."], { cwd: mod.dir, stdio: "inherit" });
+                }
+                else if (stack === "rust") {
+                    console.log(chalk.gray(`Running: cargo check in ${mod.dir}`));
+                    await execa("cargo", ["check"], { cwd: mod.dir, stdio: "inherit" });
+                    console.log(chalk.gray(`Running: cargo test in ${mod.dir}`));
+                    await execa("cargo", ["test"], { cwd: mod.dir, stdio: "inherit" });
+                }
+                console.log(chalk.green(`  ✔️ ${stack} validation passed!`));
             }
-            else if (stack === "dotnet") {
-                console.log(chalk.gray("Running: dotnet build"));
-                await execa("dotnet", ["build"], { cwd, stdio: "inherit" });
+            catch (err) {
+                console.error(chalk.red(`  ❌ ${stack} validation failed: ${err instanceof Error ? err.message : String(err)}`));
+                passed = false;
             }
-            console.log(chalk.green(`✔️ ${stack} validation passed!`));
-        }
-        catch (err) {
-            console.error(chalk.red(`❌ ${stack} validation failed: ${err instanceof Error ? err.message : String(err)}`));
-            passed = false;
         }
     }
     if (passed) {

package/dist/cli/commands/init.js

@@ -183,7 +183,9 @@ export async function runInit(options) {
     }
     if (modules.length === 0) {
         console.log(chalk.yellow("No standard stacks detected automatically. Creating general agent guidelines at root."));
+        const globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
         const finalAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            globalRules,
             stackContent: "",
         });
         if (options.agent === "antigravity" || options.agent === "both") {
@@ -219,7 +221,9 @@ export async function runInit(options) {
             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 globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
         const rootAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            globalRules,
             stackContent: monorepoContent.trim(),
         });
         const rootGeminiPath = path.join(cwd, "GEMINI.md");
@@ -276,7 +280,9 @@ export async function runInit(options) {
         // Render agent files for this module
         const geminiPath = path.join(mod.dir, "GEMINI.md");
         const agentsPath = path.join(mod.dir, "AGENTS.md");
+        const globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
         const moduleAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            globalRules,
             stackContent,
         });
         if (options.agent === "antigravity" || options.agent === "both") {

package/dist/core/analyzer.js

@@ -519,6 +519,12 @@ export async function analyzeModule(dir, stacks) {
         else if (stack === "dotnet") {
             context["dotnet"] = await analyzeDotnet(dir);
         }
+        else if (stack === "golang") {
+            context["golang"] = await analyzeGolang(dir);
+        }
+        else if (stack === "rust") {
+            context["rust"] = await analyzeRust(dir);
+        }
     }
     return context;
 }
@@ -605,3 +611,67 @@ async function findCsprojFiles(dir) {
     await traverse(dir);
     return files;
 }
+async function analyzeGolang(dir) {
+    let goVersion = "1.22";
+    let moduleName = path.basename(dir);
+    try {
+        const goModPath = path.join(dir, "go.mod");
+        const content = await fs.readFile(goModPath, "utf8");
+        const lines = content.split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("module ")) {
+                moduleName = trimmed.replace("module ", "").trim();
+            }
+            else if (trimmed.startsWith("go ")) {
+                goVersion = trimmed.replace("go ", "").trim();
+            }
+        }
+    }
+    catch {
+        // Keep default
+    }
+    return { goVersion, moduleName };
+}
+async function analyzeRust(dir) {
+    let projectName = path.basename(dir);
+    let rustEdition = "2021";
+    let isWorkspace = false;
+    try {
+        const cargoTomlPath = path.join(dir, "Cargo.toml");
+        const content = await fs.readFile(cargoTomlPath, "utf8");
+        if (content.includes("[workspace]")) {
+            isWorkspace = true;
+        }
+        // Very basic parsing for name and edition
+        const lines = content.split("\n");
+        let inPackageSection = false;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("[package]")) {
+                inPackageSection = true;
+            }
+            else if (trimmed.startsWith("[")) {
+                inPackageSection = false;
+            }
+            if (inPackageSection) {
+                if (trimmed.startsWith("name")) {
+                    const match = trimmed.match(/name\s*=\s*"(.*)"/);
+                    if (match && match[1]) {
+                        projectName = match[1];
+                    }
+                }
+                else if (trimmed.startsWith("edition")) {
+                    const match = trimmed.match(/edition\s*=\s*"(.*)"/);
+                    if (match && match[1]) {
+                        rustEdition = match[1];
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Keep default
+    }
+    return { projectName, rustEdition, isWorkspace };
+}

package/dist/core/detector.js

@@ -130,6 +130,28 @@ async function detectProjectStackDirect(cwd) {
     catch {
         // Ignore
     }
+    // 5. Detect Golang (go.mod)
+    try {
+        const goModPath = path.join(cwd, "go.mod");
+        const stat = await fs.stat(goModPath);
+        if (stat.isFile()) {
+            stacks.push("golang");
+        }
+    }
+    catch {
+        // Ignore
+    }
+    // 6. Detect Rust (Cargo.toml)
+    try {
+        const cargoTomlPath = path.join(cwd, "Cargo.toml");
+        const stat = await fs.stat(cargoTomlPath);
+        if (stat.isFile()) {
+            stacks.push("rust");
+        }
+    }
+    catch {
+        // Ignore
+    }
     return stacks;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-workflow-kit-cli",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "AI-Ready Repository Workflow Generator & Guideline Optimizer for Codex and Antigravity",
   "type": "module",
   "main": "./dist/index.js",

package/templates/common/AGENTS.md.hbs

@@ -1,3 +1,7 @@
+{{{globalRules}}}
+
+---
+
 # Repository Agent Guidelines
 
 This repository implements the `agent-workflow-kit-cli` standards.

package/templates/common/GLOBAL_RULES.md

@@ -0,0 +1,101 @@
+# UNIVERSAL GLOBAL RULES (GLOBAL_RULES.md)
+
+NOTICE TO AI AGENT: All source code generated in this project – regardless of language, framework, or architecture (Frontend, Backend, AI Agent) – must strictly adhere to the following 4 pillars of engineering rules. Any violations will result in code rejection.
+
+---
+
+## 🏛️ PILLAR 1: DATABASE & MIGRATION GOVERNANCE
+The main goal is to protect data integrity, prevent data loss in Production environments, and optimize core query performance.
+
+### 1.1 Strict No Auto-Sync in Production
+- **Rule:** Never use properties or commands that automatically synchronize schema changes directly to the database in a Production environment (e.g., `synchronize: true` in TypeORM/Hibernate, `prisma db push`, `sequelize.sync()`, or GORM's `db.AutoMigrate()` running automatically at startup).
+- **Mandatory Solution:** All structural changes (adding columns, modifying types, dropping tables, creating indices) must be written in independent, timestamped migration files (e.g., `YYYYMMDDHHMMSS_migration_name`).
+- **Workflow:** Migration files must be verified locally and executed only via the ORM/Driver CLI tool prior to production deployment.
+
+### 1.2 Strict Indexing Strategy
+- **Prerequisite:** Any column frequently appearing in `WHERE` clauses, `JOIN` conditions, or `ORDER BY` statements in large-scale growing tables (e.g., `user_id`, `status`, `created_at`) must be indexed.
+- **Write Prevention:** Avoid indexing columns indiscriminately. For columns with high-frequency updates (`INSERT`/`UPDATE`/`DELETE`), redundant indices will severely degrade write performance.
+- **Unique Constraints:** Identity fields requiring uniqueness (e.g., `email`, `username`, `phone_number`) must be configured with a `UNIQUE` index at the Database level, not just validated in the Application code.
+
+### 1.3 Eliminate N+1 Query Issues
+- **Issue:** Never query child relations inside loops (`for`, `while`, `forEach`) for a list of records (e.g., fetching 100 courses and looping 100 times to execute SQL to get the instructor for each course).
+- **Solution:** Use Eager Loading (direct SQL `JOIN`s, or pre-fetching methods like `.Include()` in EF Core, `Preload` in GORM, `select_related` / `prefetch_related` in Python) to retrieve all relational data in a single query.
+
+### 1.4 Connection Pool Management
+- All database connections must go through a Connection Pool. The AI Agent must not manually open/close connections per request.
+- You must configure explicit limits: `max_connections` (maximum connections), `idle_timeout` (unused connection release time), and `max_lifetime` to prevent database server resource exhaustion.
+
+---
+
+## 🛡️ PILLAR 2: SECURITY & AUTH HARDENING
+Ensure the system is immune to vulnerabilities listed in the OWASP Top 10.
+
+### 2.1 Zero Hardcoded Secrets
+- **Strict Prohibition:** Never write database connection strings, third-party API Keys (e.g., OpenAI, Stripe), JWT secrets, or system passwords directly into the codebase.
+- **Implementation:** All sensitive values must be loaded into the application via Environment Variables or System Env.
+- **Documentation:** Every project must include a `.env.example` file listing all required environment keys with empty values, guiding others on how to configure the project.
+
+### 2.2 JWT Lifecycle & Storage Standards (JSON Web Token)
+- **Access Token:** Configure a short lifespan (minimum 15 minutes, maximum 1 hour) to reduce the window of vulnerability if the token is compromised.
+- **Refresh Token:** Must have a longer expiration (7 days to 30 days) and must be stored in an `HttpOnly`, `Secure`, `SameSite=Strict` cookie on the client side. Storing Refresh Tokens in `localStorage` or `sessionStorage` is strictly prohibited to prevent account takeover via XSS.
+
+### 2.3 Input Validation & Injection Defense
+- **Mass Assignment Defense (Overposting):** Never map client request objects (e.g., `req.body`) directly to database update statements without filtering. Data must be validated and filtered using DTOs (Data Transfer Objects), Pydantic Schemas, or Struct validations.
+- **SQL Injection Defense:** All database queries must use Parameterized Queries (Prepared Statements). String concatenation to construct dynamic SQL/NoSQL queries is strictly prohibited.
+
+### 2.4 CORS & Rate Limiting
+- **CORS:** Using `Origin: '*'` is strictly prohibited in Production. A whitelist of permitted frontend domains must be explicitly defined.
+- **Rate Limiting:** Sensitive or resource-intensive endpoints (e.g., Login, Register, Forgot Password, Send OTP, LLM AI generation APIs) must be protected by rate-limiting middleware (e.g., maximum 5 requests/minute/IP) to defend against DoS and brute-force attacks.
+
+---
+
+## 🚦 PILLAR 3: OBSERVABILITY & STRUCTURED LOGS
+Transition the system from blind debugging to proactive monitoring using structured log data.
+
+### 3.1 Structured Logging Standards
+- Printing raw text directly to the console (e.g., `console.log()`, `fmt.Println()`, `print()`, or `println!()`) is prohibited in Production.
+- **Mandatory Format:** All logs written to stdout/stderr must use JSON format so that Log Aggregators (ELK Stack, Grafana Loki, Datadog) can automatically parse and index them.
+- **Required fields in every JSON log line:**
+```json
+{
+  "timestamp": "2026-06-13T16:00:00.000Z",
+  "level": "ERROR",
+  "trace_id": "c4b37d89-9821-47d3-b12a-7e61a4b9812f",
+  "context": "PaymentService",
+  "message": "Failed to connect to Stripe payment gateway",
+  "error_details": {
+    "code": "STRIPE_TIMEOUT",
+    "stack": "Error: Timeout after 5000ms at StripeClient.request..."
+  }
+}
+```
+
+### 3.2 Strict Log Levels
+The AI Agent must select the appropriate log level for every event:
+- **DEBUG:** Detailed execution flow tracing during development (must be automatically disabled or hidden in Production).
+- **INFO:** Normal but important system events (e.g., Server started on port 8080, cache cleanup completed).
+- **WARN:** Abnormal situations that do not fail the request (e.g., user entered incorrect password, third-party API responded slowly but succeeded).
+- **ERROR:** Severe errors that terminate request execution and require developer intervention (e.g., database connection loss, invoice file write failure, logic errors).
+
+### 3.3 Masking PII (Personally Identifiable Information)
+- Never print sensitive PII into public log systems.
+- Fields containing passwords, credit card numbers, national IDs/passports, and access/refresh tokens must be masked (e.g., converted to `*`) or omitted from the logged objects.
+
+---
+
+## 📦 PILLAR 4: CONTAINER & CI/CD GUARDRAILS
+Ensure applications can be deployed automatically onto Cloud environments (Kubernetes, AWS, Docker Swarm) efficiently and securely.
+
+### 4.1 Mandatory Multi-Stage Builds
+Every Dockerfile must consist of at least 2 stages:
+- **Stage 1 (Build Stage):** Use a base image containing all necessary tools (SDKs, Compilers, devDependencies) to compile the source code and install packages.
+- **Stage 2 (Production Runtime Stage):** Copy only compiled assets and production dependencies (e.g., `dist` folder, compiled binary, node production modules) from Stage 1. This final image must not contain raw source code or development utilities, minimizing bundle size.
+
+### 4.2 Principle of Least Privilege
+- **No Root User:** Never run container processes using the default `root` user. Running containers as root introduces severe security risks in case of container escape vulnerabilities.
+- **Solution:** Initialize a non-privileged user in the Dockerfile (e.g., `USER node` in Node.js, or `useradd -u 1001 appuser` in Go/Rust) and grant appropriate execution permissions to this user.
+
+### 4.3 Health Check API
+- All backend services must expose a dedicated health check endpoint (e.g., `GET /health` or `GET /ready`).
+- This endpoint must check downstream connectivity (e.g., Database, Redis) and return HTTP Status `503 Service Unavailable` if unhealthy.
+- Use the `HEALTHCHECK` directive in the Dockerfile so orchestrators like Kubernetes can detect failures and automatically restart unhealthy containers (Self-healing).

package/templates/devops/AGENTS.md.hbs

@@ -0,0 +1,32 @@
+## 🚀 DevOps & Deployment Automation Guide
+
+### 🔄 DevOps Workflow
+When setting up CI/CD pipelines or containerizing applications, apply these core principles:
+1. **Analyze Project Runtime:** Identify the language ecosystem (Node.js, Python, Go, Rust, Java, .NET) and detect package manager/lockfiles (e.g. `package-lock.json`, `poetry.lock`, `Cargo.lock`, `go.sum`).
+2. **Implement Secure Multi-Stage Builds:** Separate build dependencies from runtime dependencies. The runtime image must be minimal (e.g., alpine, distroless) and must never run as `root`.
+3. **Establish CI/CD Pipelines:** Setup linting, automated testing, and secure Docker image publication workflows inside GitHub Actions.
+
+---
+
+### 🏗️ Available DevOps Templates
+Refer to the detailed rules below:
+- Scaffolding secure Dockerfiles and GitHub Actions workflows: `@devops`
+
+---
+
+### 🏛️ Strict Container & Pipeline Standards
+
+#### 1. Dockerfile Guidelines
+- **Multi-Stage Builds:** Always use a builder stage to download tools, compile source code, and install development headers, then copy only the compiled binaries/compiled assets to the final stage.
+- **Rootless Execution:** Declare a non-privileged user (e.g., `nobody`, `appuser`, `node`) using the `USER` directive in the final stage.
+- **Caching Optimization:** Copy dependency manifest files (like `package.json`, `go.mod`, `Cargo.toml`) and perform installation steps *before* copying the source code directory to maximize layer caching efficiency.
+- **Base Images:** Prefer minimal, stable base images (like `node:20-alpine`, `python:3.11-slim`, `gcr.io/distroless/static`).
+
+#### 2. GitHub Actions CI/CD Rules
+- **Security:** Use secrets (`secrets.GITHUB_TOKEN` or custom registry credentials) to authenticate with registries. Never hardcode credentials.
+- **Phases:** Ensure the pipeline follows a clear linear progression: `Lint` -> `Test` -> `Build Docker` -> `Publish Image` -> `Verify`.
+- **Environment:** Run tests inside appropriate isolation, specifying necessary environment variables as configuration variables.
+
+### 🧪 Verification
+- Validate the Dockerfile builds locally: `docker build -t app:local .`
+- Ensure GitHub Actions workflow schema checks out correctly using visual validators or linting tools.