workflow-agent-cli 1.1.6 → 2.0.0

package/dist/cli/index.js

@@ -8,7 +8,7 @@ import {
   hasConfig,
   loadConfig,
   validateScopeDefinitions
-} from "../chunk-VFN3BY56.js";
+} from "../chunk-4BIDFDSR.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -16,9 +16,9 @@ import { Command } from "commander";
 // src/cli/commands/init.ts
 import * as p from "@clack/prompts";
 import chalk from "chalk";
-import { existsSync } from "fs";
-import { writeFile, mkdir } from "fs/promises";
-import { join, dirname } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { join as join4, dirname } from "path";
 import { fileURLToPath } from "url";
 
 // src/templates/renderer.ts
@@ -189,18 +189,6 @@ async function renderTemplateFile(templatePath, outputPath, context) {
   await fs.mkdir(path.dirname(outputPath), { recursive: true });
   await fs.writeFile(outputPath, rendered, "utf-8");
 }
-async function renderTemplateDirectory(templateDir, outputDir, context) {
-  const files = await fs.readdir(templateDir);
-  const rendered = [];
-  for (const file of files) {
-    if (!file.match(/\.(md|ts|json)$/)) continue;
-    const templatePath = path.join(templateDir, file);
-    const outputPath = path.join(outputDir, file);
-    await renderTemplateFile(templatePath, outputPath, context);
-    rendered.push(file);
-  }
-  return rendered;
-}
 async function getProjectName(projectPath) {
   try {
     const pkgPath = path.join(projectPath, "package.json");
@@ -229,13 +217,666 @@ async function validateTemplateDirectory(templateDir) {
   }
 }
 
+// src/templates/metadata.ts
+var templateMetadata = {
+  "AGENT_EDITING_INSTRUCTIONS.md": {
+    filename: "AGENT_EDITING_INSTRUCTIONS.md",
+    displayName: "Agent Editing Instructions",
+    mandatory: true,
+    category: "workflow",
+    validators: ["implementation-plan"],
+    description: "Core rules for AI agents: implementation plans, coding standards, architecture"
+  },
+  "BRANCHING_STRATEGY.md": {
+    filename: "BRANCHING_STRATEGY.md",
+    displayName: "Branching Strategy",
+    mandatory: true,
+    category: "workflow",
+    validators: ["branch-name", "pr-title"],
+    description: "Git branch naming conventions, PR requirements, merge policies"
+  },
+  "TESTING_STRATEGY.md": {
+    filename: "TESTING_STRATEGY.md",
+    displayName: "Testing Strategy",
+    mandatory: true,
+    category: "development",
+    validators: ["test-coverage"],
+    description: "Testing pyramid, Vitest/Playwright patterns, when tests are required"
+  },
+  "SELF_IMPROVEMENT_MANDATE.md": {
+    filename: "SELF_IMPROVEMENT_MANDATE.md",
+    displayName: "Self-Improvement Mandate",
+    mandatory: true,
+    category: "workflow",
+    validators: [],
+    description: "Continuous improvement tracking, changelog requirements"
+  },
+  "SINGLE_SOURCE_OF_TRUTH.md": {
+    filename: "SINGLE_SOURCE_OF_TRUTH.md",
+    displayName: "Single Source of Truth",
+    mandatory: true,
+    category: "workflow",
+    validators: [],
+    description: "Canonical code locations, service patterns, avoiding duplication"
+  },
+  "COMPONENT_LIBRARY.md": {
+    filename: "COMPONENT_LIBRARY.md",
+    displayName: "Component Library",
+    mandatory: false,
+    category: "development",
+    validators: [],
+    description: "UI component patterns, design tokens, decision tree"
+  },
+  "DEPLOYMENT_STRATEGY.md": {
+    filename: "DEPLOYMENT_STRATEGY.md",
+    displayName: "Deployment Strategy",
+    mandatory: false,
+    category: "development",
+    validators: [],
+    description: "Deployment workflow, environments, migrations, rollback"
+  },
+  "LIBRARY_INVENTORY.md": {
+    filename: "LIBRARY_INVENTORY.md",
+    displayName: "Library Inventory",
+    mandatory: false,
+    category: "development",
+    validators: [],
+    description: "Dependency catalog, approved libraries, new library process"
+  },
+  "SCOPE_CREATION_WORKFLOW.md": {
+    filename: "SCOPE_CREATION_WORKFLOW.md",
+    displayName: "Scope Creation Workflow",
+    mandatory: false,
+    category: "workflow",
+    validators: [],
+    description: "Workflow for AI agents creating custom scopes"
+  },
+  "CUSTOM_SCOPE_TEMPLATE.md": {
+    filename: "CUSTOM_SCOPE_TEMPLATE.md",
+    displayName: "Custom Scope Template",
+    mandatory: false,
+    category: "workflow",
+    validators: [],
+    description: "Template for defining custom scope packages"
+  },
+  "PROJECT_TEMPLATE_README.md": {
+    filename: "PROJECT_TEMPLATE_README.md",
+    displayName: "Project Template README",
+    mandatory: false,
+    category: "documentation",
+    validators: [],
+    description: "Meta-document describing project structure"
+  },
+  "Guidelines.md": {
+    filename: "Guidelines.md",
+    displayName: "Custom Guidelines",
+    mandatory: false,
+    category: "documentation",
+    validators: [],
+    description: "Placeholder for custom user guidelines"
+  }
+};
+function getMandatoryTemplates() {
+  return Object.values(templateMetadata).filter((t) => t.mandatory);
+}
+function getOptionalTemplates() {
+  return Object.values(templateMetadata).filter((t) => !t.mandatory);
+}
+function getMandatoryTemplateFilenames() {
+  return getMandatoryTemplates().map((t) => t.filename);
+}
+
+// src/utils/hooks.ts
+import { existsSync } from "fs";
+import { readFile, writeFile, unlink, chmod, rename, mkdir } from "fs/promises";
+import { join } from "path";
+function getGitHooksDir(projectPath = process.cwd()) {
+  return join(projectPath, ".git", "hooks");
+}
+function hasGitRepo(projectPath = process.cwd()) {
+  return existsSync(join(projectPath, ".git"));
+}
+function generatePreCommitHook(config) {
+  const checks = config?.preCommit || ["validate-branch", "check-guidelines"];
+  const checkCommands = checks.map((check) => {
+    switch (check) {
+      case "validate-branch":
+        return "  workflow validate branch";
+      case "validate-commit":
+        return "  workflow validate commit";
+      case "check-guidelines":
+        return "  workflow doctor --check-guidelines-only 2>/dev/null || true";
+      default:
+        return "";
+    }
+  }).filter(Boolean).join("\n");
+  return `#!/bin/sh
+# Workflow Agent pre-commit hook
+# Auto-generated - do not edit manually
+# To reinstall: workflow hooks install
+# To uninstall: workflow hooks uninstall
+
+# Skip in CI environment
+if [ -n "\${CI:-}" ] || [ -n "\${GITHUB_ACTIONS:-}" ] || [ -n "\${GITLAB_CI:-}" ]; then
+  exit 0
+fi
+
+# Run workflow checks
+${checkCommands}
+
+# Run original hook if it exists
+if [ -f ".git/hooks/pre-commit.original" ]; then
+  .git/hooks/pre-commit.original "$@"
+fi
+`;
+}
+function generateCommitMsgHook(config) {
+  const checks = config?.commitMsg || ["validate-commit"];
+  const checkCommands = checks.map((check) => {
+    switch (check) {
+      case "validate-commit":
+        return '  workflow validate commit "$(cat "$1")"';
+      default:
+        return "";
+    }
+  }).filter(Boolean).join("\n");
+  return `#!/bin/sh
+# Workflow Agent commit-msg hook
+# Auto-generated - do not edit manually
+# To reinstall: workflow hooks install
+# To uninstall: workflow hooks uninstall
+
+# Skip in CI environment
+if [ -n "\${CI:-}" ] || [ -n "\${GITHUB_ACTIONS:-}" ] || [ -n "\${GITLAB_CI:-}" ]; then
+  exit 0
+fi
+
+# Run workflow checks
+${checkCommands}
+
+# Run original hook if it exists
+if [ -f ".git/hooks/commit-msg.original" ]; then
+  .git/hooks/commit-msg.original "$@"
+fi
+`;
+}
+async function isWorkflowHook(hookPath) {
+  try {
+    const content = await readFile(hookPath, "utf-8");
+    return content.includes("Workflow Agent") && content.includes("Auto-generated");
+  } catch {
+    return false;
+  }
+}
+async function getHookStatus(hookType, projectPath = process.cwd()) {
+  const hooksDir = getGitHooksDir(projectPath);
+  const hookPath = join(hooksDir, hookType);
+  const originalPath = join(hooksDir, `${hookType}.original`);
+  const status = {
+    installed: false,
+    hookType,
+    hasExistingHook: false,
+    wrappedOriginal: false
+  };
+  if (!existsSync(hookPath)) {
+    return status;
+  }
+  status.hasExistingHook = true;
+  if (await isWorkflowHook(hookPath)) {
+    status.installed = true;
+    status.wrappedOriginal = existsSync(originalPath);
+  }
+  return status;
+}
+async function getAllHooksStatus(projectPath = process.cwd()) {
+  return Promise.all([
+    getHookStatus("pre-commit", projectPath),
+    getHookStatus("commit-msg", projectPath)
+  ]);
+}
+async function installSingleHook(hookType, config, projectPath = process.cwd()) {
+  const hooksDir = getGitHooksDir(projectPath);
+  const hookPath = join(hooksDir, hookType);
+  const originalPath = join(hooksDir, `${hookType}.original`);
+  const result = {
+    success: false,
+    hookType,
+    wrappedExisting: false
+  };
+  try {
+    if (!existsSync(hooksDir)) {
+      await mkdir(hooksDir, { recursive: true });
+    }
+    if (existsSync(hookPath)) {
+      const isOurs = await isWorkflowHook(hookPath);
+      if (!isOurs) {
+        await rename(hookPath, originalPath);
+        result.wrappedExisting = true;
+      }
+    }
+    const hookContent = hookType === "pre-commit" ? generatePreCommitHook(config) : generateCommitMsgHook(config);
+    await writeFile(hookPath, hookContent, "utf-8");
+    await chmod(hookPath, 493);
+    result.success = true;
+  } catch (error) {
+    result.error = error instanceof Error ? error.message : String(error);
+  }
+  return result;
+}
+async function installHooks(config, projectPath = process.cwd()) {
+  if (!hasGitRepo(projectPath)) {
+    return [{
+      success: false,
+      hookType: "pre-commit",
+      wrappedExisting: false,
+      error: "No git repository found. Run git init first."
+    }];
+  }
+  const results = await Promise.all([
+    installSingleHook("pre-commit", config, projectPath),
+    installSingleHook("commit-msg", config, projectPath)
+  ]);
+  return results;
+}
+async function uninstallSingleHook(hookType, projectPath = process.cwd()) {
+  const hooksDir = getGitHooksDir(projectPath);
+  const hookPath = join(hooksDir, hookType);
+  const originalPath = join(hooksDir, `${hookType}.original`);
+  const result = {
+    success: false,
+    hookType,
+    wrappedExisting: false
+  };
+  try {
+    if (!existsSync(hookPath)) {
+      result.success = true;
+      return result;
+    }
+    const isOurs = await isWorkflowHook(hookPath);
+    if (!isOurs) {
+      result.error = "Hook is not managed by Workflow Agent";
+      return result;
+    }
+    await unlink(hookPath);
+    if (existsSync(originalPath)) {
+      await rename(originalPath, hookPath);
+      result.wrappedExisting = true;
+    }
+    result.success = true;
+  } catch (error) {
+    result.error = error instanceof Error ? error.message : String(error);
+  }
+  return result;
+}
+async function uninstallHooks(projectPath = process.cwd()) {
+  return Promise.all([
+    uninstallSingleHook("pre-commit", projectPath),
+    uninstallSingleHook("commit-msg", projectPath)
+  ]);
+}
+
+// src/utils/git-repo.ts
+import { execa } from "execa";
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile2 } from "fs/promises";
+import { join as join2 } from "path";
+async function isGitRepo(projectPath = process.cwd()) {
+  try {
+    await execa("git", ["rev-parse", "--git-dir"], { cwd: projectPath });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function getGitRemoteUrl(projectPath = process.cwd()) {
+  try {
+    const { stdout } = await execa("git", ["remote", "get-url", "origin"], { cwd: projectPath });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function isGitHubRemote(remoteUrl) {
+  if (!remoteUrl) return false;
+  return remoteUrl.includes("github.com");
+}
+function parseGitHubUrl(remoteUrl) {
+  if (!remoteUrl || !isGitHubRemote(remoteUrl)) return null;
+  const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+  if (match) {
+    return {
+      owner: match[1],
+      repo: match[2].replace(/\.git$/, "")
+    };
+  }
+  return null;
+}
+async function getDefaultBranch(projectPath = process.cwd()) {
+  try {
+    const { stdout } = await execa("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+      cwd: projectPath
+    });
+    return stdout.trim().replace("refs/remotes/origin/", "") || "main";
+  } catch {
+    try {
+      const { stdout } = await execa("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: projectPath
+      });
+      return stdout.trim() || "main";
+    } catch {
+      return "main";
+    }
+  }
+}
+async function getRepoInfo(projectPath = process.cwd()) {
+  const isRepo = await isGitRepo(projectPath);
+  if (!isRepo) {
+    return {
+      isGitRepo: false,
+      remoteUrl: null,
+      isGitHub: false,
+      github: null,
+      defaultBranch: null
+    };
+  }
+  const remoteUrl = await getGitRemoteUrl(projectPath);
+  const isGitHub = isGitHubRemote(remoteUrl);
+  const github = parseGitHubUrl(remoteUrl);
+  const defaultBranch = await getDefaultBranch(projectPath);
+  return {
+    isGitRepo: true,
+    remoteUrl,
+    isGitHub,
+    github,
+    defaultBranch
+  };
+}
+async function detectPackageManager(projectPath = process.cwd()) {
+  if (existsSync2(join2(projectPath, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (existsSync2(join2(projectPath, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (existsSync2(join2(projectPath, "bun.lockb"))) {
+    return "bun";
+  }
+  if (existsSync2(join2(projectPath, "package-lock.json"))) {
+    return "npm";
+  }
+  try {
+    const pkgPath = join2(projectPath, "package.json");
+    if (existsSync2(pkgPath)) {
+      const pkg = JSON.parse(await readFile2(pkgPath, "utf-8"));
+      if (pkg.packageManager) {
+        if (pkg.packageManager.startsWith("pnpm")) return "pnpm";
+        if (pkg.packageManager.startsWith("yarn")) return "yarn";
+        if (pkg.packageManager.startsWith("bun")) return "bun";
+      }
+    }
+  } catch {
+  }
+  return "npm";
+}
+async function isMonorepo(projectPath = process.cwd()) {
+  if (existsSync2(join2(projectPath, "pnpm-workspace.yaml"))) {
+    return true;
+  }
+  try {
+    const pkgPath = join2(projectPath, "package.json");
+    if (existsSync2(pkgPath)) {
+      const pkg = JSON.parse(await readFile2(pkgPath, "utf-8"));
+      if (pkg.workspaces) {
+        return true;
+      }
+    }
+  } catch {
+  }
+  if (existsSync2(join2(projectPath, "lerna.json"))) {
+    return true;
+  }
+  if (existsSync2(join2(projectPath, "nx.json"))) {
+    return true;
+  }
+  if (existsSync2(join2(projectPath, "turbo.json"))) {
+    return true;
+  }
+  return false;
+}
+async function getPackageScripts(projectPath = process.cwd()) {
+  try {
+    const pkgPath = join2(projectPath, "package.json");
+    if (!existsSync2(pkgPath)) {
+      return {};
+    }
+    const pkg = JSON.parse(await readFile2(pkgPath, "utf-8"));
+    return pkg.scripts || {};
+  } catch {
+    return {};
+  }
+}
+async function getProjectInfo(projectPath = process.cwd()) {
+  const packageManager = await detectPackageManager(projectPath);
+  const monorepo = await isMonorepo(projectPath);
+  const scripts = await getPackageScripts(projectPath);
+  return {
+    packageManager,
+    isMonorepo: monorepo,
+    hasLintScript: "lint" in scripts,
+    hasTypecheckScript: "typecheck" in scripts || "type-check" in scripts,
+    hasFormatScript: "format" in scripts || "format:check" in scripts,
+    hasTestScript: "test" in scripts,
+    hasBuildScript: "build" in scripts
+  };
+}
+function getInstallCommand(packageManager) {
+  switch (packageManager) {
+    case "pnpm":
+      return "pnpm install --frozen-lockfile";
+    case "yarn":
+      return "yarn install --frozen-lockfile";
+    case "bun":
+      return "bun install --frozen-lockfile";
+    case "npm":
+    default:
+      return "npm ci";
+  }
+}
+function getRunCommand(packageManager, script, isMonorepo2 = false) {
+  switch (packageManager) {
+    case "pnpm":
+      return isMonorepo2 ? `pnpm -r run ${script}` : `pnpm run ${script}`;
+    case "yarn":
+      return isMonorepo2 ? `yarn workspaces run ${script}` : `yarn run ${script}`;
+    case "bun":
+      return `bun run ${script}`;
+    case "npm":
+    default:
+      return isMonorepo2 ? `npm run ${script} --workspaces --if-present` : `npm run ${script}`;
+  }
+}
+
+// src/utils/github-actions.ts
+import { existsSync as existsSync3 } from "fs";
+import { writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
+import { join as join3 } from "path";
+function generateCIWorkflowContent(options) {
+  const {
+    packageManager,
+    isMonorepo: isMonorepo2,
+    checks,
+    nodeVersions,
+    defaultBranch,
+    hasLintScript,
+    hasTypecheckScript,
+    hasFormatScript,
+    hasTestScript,
+    hasBuildScript
+  } = options;
+  const installCmd = getInstallCommand(packageManager);
+  const steps = [];
+  steps.push(`      - name: Checkout
+        uses: actions/checkout@v4`);
+  let cacheType = packageManager;
+  if (packageManager === "bun") {
+    cacheType = "npm";
+  }
+  const useMatrix = nodeVersions.length > 1;
+  const nodeVersionValue = useMatrix ? `\${{ matrix.node-version }}` : nodeVersions[0] || "20";
+  steps.push(`
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '${nodeVersionValue}'
+          cache: '${cacheType}'`);
+  if (packageManager === "pnpm") {
+    steps.push(`
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9`);
+  }
+  steps.push(`
+      - name: Install dependencies
+        run: ${installCmd}`);
+  if (checks.includes("lint")) {
+    if (hasLintScript) {
+      const lintCmd = getRunCommand(packageManager, "lint", isMonorepo2);
+      steps.push(`
+      - name: Lint
+        run: ${lintCmd}`);
+    } else {
+      steps.push(`
+      - name: Lint
+        run: echo "No lint script configured - add 'lint' to package.json scripts"`);
+    }
+  }
+  if (checks.includes("typecheck")) {
+    if (hasTypecheckScript) {
+      const typecheckCmd = getRunCommand(packageManager, "typecheck", isMonorepo2);
+      steps.push(`
+      - name: Type check
+        run: ${typecheckCmd}`);
+    } else {
+      steps.push(`
+      - name: Type check
+        run: npx tsc --noEmit`);
+    }
+  }
+  if (checks.includes("format")) {
+    if (hasFormatScript) {
+      const formatCmd = getRunCommand(packageManager, "format:check", isMonorepo2);
+      steps.push(`
+      - name: Format check
+        run: ${formatCmd} || npx prettier --check "**/*.{ts,tsx,js,jsx,json,md}"`);
+    } else {
+      steps.push(`
+      - name: Format check
+        run: npx prettier --check "**/*.{ts,tsx,js,jsx,json,md}"`);
+    }
+  }
+  if (checks.includes("build")) {
+    if (hasBuildScript) {
+      const buildCmd = getRunCommand(packageManager, "build", isMonorepo2);
+      steps.push(`
+      - name: Build
+        run: ${buildCmd}`);
+    } else {
+      steps.push(`
+      - name: Build
+        run: echo "No build script configured - add 'build' to package.json scripts"`);
+    }
+  }
+  if (checks.includes("test")) {
+    if (hasTestScript) {
+      const testCmd = getRunCommand(packageManager, "test", isMonorepo2);
+      steps.push(`
+      - name: Test
+        run: ${testCmd}`);
+    } else {
+      steps.push(`
+      - name: Test
+        run: echo "No test script configured - add 'test' to package.json scripts"`);
+    }
+  }
+  let matrixStrategy = "";
+  if (useMatrix) {
+    matrixStrategy = `
+    strategy:
+      matrix:
+        node-version: [${nodeVersions.map((v) => `'${v}'`).join(", ")}]`;
+  }
+  const workflow = `# Workflow Agent CI Pipeline
+# Auto-generated - modifications will be preserved on regeneration
+# To regenerate: workflow github:setup
+
+name: CI
+
+on:
+  push:
+    branches: [${defaultBranch}, develop]
+  pull_request:
+    branches: [${defaultBranch}, develop]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest${matrixStrategy}
+
+    steps:
+${steps.join("\n")}
+`;
+  return workflow;
+}
+async function createCIWorkflow(options = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  const workflowsDir = join3(projectPath, ".github", "workflows");
+  const workflowPath = join3(workflowsDir, "ci.yml");
+  const result = {
+    success: false,
+    filePath: workflowPath
+  };
+  try {
+    const projectInfo = await getProjectInfo(projectPath);
+    const packageManager = options.packageManager || projectInfo.packageManager;
+    const isMonorepo2 = options.isMonorepo ?? projectInfo.isMonorepo;
+    const checks = options.ciConfig?.checks || ["lint", "typecheck", "format", "build", "test"];
+    const nodeVersions = options.nodeVersions || ["20"];
+    const defaultBranch = options.defaultBranch || "main";
+    if (!existsSync3(workflowsDir)) {
+      await mkdir2(workflowsDir, { recursive: true });
+    }
+    const content = generateCIWorkflowContent({
+      packageManager,
+      isMonorepo: isMonorepo2,
+      checks,
+      nodeVersions,
+      defaultBranch,
+      hasLintScript: projectInfo.hasLintScript,
+      hasTypecheckScript: projectInfo.hasTypecheckScript,
+      hasFormatScript: projectInfo.hasFormatScript,
+      hasTestScript: projectInfo.hasTestScript,
+      hasBuildScript: projectInfo.hasBuildScript
+    });
+    await writeFile2(workflowPath, content, "utf-8");
+    result.success = true;
+  } catch (error) {
+    result.error = error instanceof Error ? error.message : String(error);
+  }
+  return result;
+}
+function hasCIWorkflow(projectPath = process.cwd()) {
+  const workflowsDir = join3(projectPath, ".github", "workflows");
+  const possibleNames = ["ci.yml", "ci.yaml", "main.yml", "main.yaml"];
+  return possibleNames.some((name) => existsSync3(join3(workflowsDir, name)));
+}
+
 // src/cli/commands/init.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
 async function initCommand(options) {
   console.log(chalk.bold.cyan("\n\u{1F680} Workflow Agent Initialization\n"));
   const cwd = process.cwd();
-  const isNonInteractive = !!(options.preset && options.name);
+  const isNonInteractive = !!(options.preset && options.name) || !!options.yes;
   if (hasConfig(cwd) && !options.yes && !isNonInteractive) {
     const shouldContinue = await p.confirm({
       message: "Workflow Agent is already configured. Continue and overwrite?",
@@ -275,10 +916,10 @@ async function initCommand(options) {
     try {
       const presetModule = await import(`@workflow/scopes-${preset}`);
       scopes = presetModule.scopes || presetModule.default.scopes;
-      const spinner4 = p.spinner();
-      spinner4.start(`Loading ${presetModule.default?.name || preset} preset`);
+      const spinner5 = p.spinner();
+      spinner5.start(`Loading ${presetModule.default?.name || preset} preset`);
       await new Promise((resolve) => setTimeout(resolve, 500));
-      spinner4.stop(`\u2713 Loaded ${scopes.length} scopes from preset`);
+      spinner5.stop(`\u2713 Loaded ${scopes.length} scopes from preset`);
     } catch (error) {
       console.log(chalk.yellow(`
 \u26A0\uFE0F  Could not load preset package. Using basic scopes.`));
@@ -302,54 +943,139 @@ async function initCommand(options) {
     enforcement: "strict",
     language: "en"
   };
-  const configPath = join(cwd, "workflow.config.json");
-  await writeFile(configPath, JSON.stringify(config, null, 2));
-  const workflowDir = join(cwd, ".workflow");
-  if (!existsSync(workflowDir)) {
-    await mkdir(workflowDir, { recursive: true });
-  }
-  const shouldGenerateGuidelines = await p.confirm({
-    message: "Generate workflow guidelines from templates?",
-    initialValue: true
-  });
-  if (p.isCancel(shouldGenerateGuidelines)) {
-    p.cancel("Initialization cancelled");
-    process.exit(0);
+  const configPath = join4(cwd, "workflow.config.json");
+  await writeFile3(configPath, JSON.stringify(config, null, 2));
+  const workflowDir = join4(cwd, ".workflow");
+  if (!existsSync4(workflowDir)) {
+    await mkdir3(workflowDir, { recursive: true });
   }
-  if (shouldGenerateGuidelines) {
-    const spinner4 = p.spinner();
-    spinner4.start("Generating guidelines...");
-    try {
-      const templatesDir = join(__dirname, "../../templates");
-      await validateTemplateDirectory(templatesDir);
-      const context = await buildTemplateContext(config, cwd);
-      const guidelinesDir = join(cwd, "guidelines");
-      await mkdir(guidelinesDir, { recursive: true });
-      const renderedFiles = await renderTemplateDirectory(templatesDir, guidelinesDir, context);
-      spinner4.stop(`\u2713 Generated ${renderedFiles.length} guideline documents`);
-    } catch (error) {
-      spinner4.stop("\u26A0\uFE0F  Could not generate guidelines");
-      console.log(chalk.yellow(`
-Reason: ${error instanceof Error ? error.message : String(error)}`));
-      console.log(chalk.dim("You can manually copy guidelines later if needed."));
+  const repoInfo = await getRepoInfo(cwd);
+  const projectInfo = await getProjectInfo(cwd);
+  const mandatoryTemplates = getMandatoryTemplates();
+  const optionalTemplates = getOptionalTemplates();
+  console.log(chalk.dim(`
+\u{1F4CB} Generating ${mandatoryTemplates.length} mandatory guidelines...`));
+  const guidelinesDir = join4(cwd, "guidelines");
+  const templatesDir = join4(__dirname, "../../templates");
+  let mandatoryGenerated = 0;
+  let optionalGenerated = 0;
+  try {
+    await validateTemplateDirectory(templatesDir);
+    const context = await buildTemplateContext(config, cwd);
+    await mkdir3(guidelinesDir, { recursive: true });
+    for (const template of mandatoryTemplates) {
+      try {
+        const templatePath = join4(templatesDir, template.filename);
+        const outputPath = join4(guidelinesDir, template.filename);
+        await renderTemplateFile(templatePath, outputPath, context);
+        mandatoryGenerated++;
+      } catch (error) {
+        console.log(chalk.yellow(`  \u26A0\uFE0F  Could not generate ${template.filename}`));
+      }
+    }
+    console.log(chalk.green(`\u2713 Generated ${mandatoryGenerated} mandatory guidelines`));
+    let shouldGenerateOptional = isNonInteractive;
+    if (!isNonInteractive) {
+      const response = await p.confirm({
+        message: `Generate ${optionalTemplates.length} optional guidelines (deployment, library inventory, etc.)?`,
+        initialValue: true
+      });
+      shouldGenerateOptional = !p.isCancel(response) && response;
+    }
+    if (shouldGenerateOptional) {
+      for (const template of optionalTemplates) {
+        try {
+          const templatePath = join4(templatesDir, template.filename);
+          const outputPath = join4(guidelinesDir, template.filename);
+          await renderTemplateFile(templatePath, outputPath, context);
+          optionalGenerated++;
+        } catch {
+        }
+      }
+      console.log(chalk.green(`\u2713 Generated ${optionalGenerated} optional guidelines`));
+    }
+  } catch (error) {
+    console.log(chalk.yellow(`
+\u26A0\uFE0F  Could not generate guidelines: ${error instanceof Error ? error.message : String(error)}`));
+    console.log(chalk.dim("You can manually copy guidelines later if needed."));
+  }
+  if (hasGitRepo(cwd)) {
+    let shouldInstallHooks = isNonInteractive;
+    if (!isNonInteractive) {
+      const response = await p.confirm({
+        message: "Install git hooks for pre-commit validation?",
+        initialValue: true
+      });
+      shouldInstallHooks = !p.isCancel(response) && response;
+    }
+    if (shouldInstallHooks) {
+      const hookSpinner = p.spinner();
+      hookSpinner.start("Installing git hooks...");
+      const hookResults = await installHooks(config.hooks, cwd);
+      const allSuccess = hookResults.every((r) => r.success);
+      if (allSuccess) {
+        hookSpinner.stop("\u2713 Installed git hooks");
+      } else {
+        hookSpinner.stop("\u26A0\uFE0F  Some hooks could not be installed");
+      }
+    }
+  }
+  if (repoInfo.isGitHub) {
+    const existingCI = hasCIWorkflow(cwd);
+    if (!existingCI) {
+      console.log(chalk.dim("\n\u{1F527} Setting up GitHub Actions CI (mandatory for GitHub repos)..."));
+      const ciResult = await createCIWorkflow({
+        projectPath: cwd,
+        packageManager: projectInfo.packageManager,
+        isMonorepo: projectInfo.isMonorepo,
+        ciConfig: config.ci,
+        defaultBranch: repoInfo.defaultBranch || "main"
+      });
+      if (ciResult.success) {
+        console.log(chalk.green("\u2713 Created GitHub Actions CI workflow"));
+        console.log(chalk.dim(`  File: .github/workflows/ci.yml`));
+      } else {
+        console.log(chalk.yellow(`\u26A0\uFE0F  Could not create CI workflow: ${ciResult.error}`));
+      }
+    } else {
+      console.log(chalk.dim("\n\u2713 GitHub Actions CI workflow already exists"));
+    }
+  } else if (repoInfo.isGitRepo) {
+    let shouldSetupCI = false;
+    if (!isNonInteractive) {
+      const response = await p.confirm({
+        message: "No GitHub remote detected. Create CI workflow anyway?",
+        initialValue: false
+      });
+      shouldSetupCI = !p.isCancel(response) && response;
+    }
+    if (shouldSetupCI) {
+      const ciResult = await createCIWorkflow({
+        projectPath: cwd,
+        packageManager: projectInfo.packageManager,
+        isMonorepo: projectInfo.isMonorepo,
+        defaultBranch: repoInfo.defaultBranch || "main"
+      });
+      if (ciResult.success) {
+        console.log(chalk.green("\u2713 Created CI workflow"));
+      }
     }
   }
   p.outro(chalk.green("\u2713 Workflow Agent initialized successfully!"));
   console.log(chalk.dim("\nNext steps:"));
   console.log(chalk.dim("  1. Review your configuration in workflow.config.json"));
-  if (shouldGenerateGuidelines) {
-    console.log(chalk.dim("  2. Review generated guidelines in guidelines/ directory"));
-    console.log(chalk.dim("  3. Run: workflow validate branch"));
-    console.log(chalk.dim("  4. Run: workflow doctor (for optimization suggestions)\n"));
-  } else {
-    console.log(chalk.dim("  2. Run: workflow validate branch"));
-    console.log(chalk.dim("  3. Run: workflow doctor (for optimization suggestions)\n"));
+  console.log(chalk.dim("  2. Review generated guidelines in guidelines/ directory"));
+  console.log(chalk.dim("  3. Run: workflow validate branch"));
+  console.log(chalk.dim("  4. Run: workflow doctor (for health check)\n"));
+  if (repoInfo.isGitHub) {
+    console.log(chalk.cyan("\u{1F4A1} Recommended: Enable branch protection on GitHub"));
+    console.log(chalk.dim("   Settings \u2192 Branches \u2192 Add rule \u2192 Require status checks\n"));
   }
 }
 
 // src/cli/commands/validate.ts
 import chalk2 from "chalk";
-import { execa } from "execa";
+import { execa as execa2 } from "execa";
 async function validateCommand(type, value, _options = {}) {
   const config = await loadConfig();
   if (!config) {
@@ -362,7 +1088,7 @@ async function validateCommand(type, value, _options = {}) {
     switch (type) {
       case "branch": {
         if (!targetValue) {
-          const { stdout } = await execa("git", ["branch", "--show-current"]);
+          const { stdout } = await execa2("git", ["branch", "--show-current"]);
           targetValue = stdout.trim();
         }
         result = await validateBranchName(targetValue, config);
@@ -370,7 +1096,7 @@ async function validateCommand(type, value, _options = {}) {
       }
       case "commit": {
         if (!targetValue) {
-          const { stdout } = await execa("git", ["log", "-1", "--pretty=%s"]);
+          const { stdout } = await execa2("git", ["log", "-1", "--pretty=%s"]);
           targetValue = stdout.trim();
         }
         result = await validateCommitMessage(targetValue, config);
@@ -464,30 +1190,290 @@ async function suggestCommand(feedback, options = {}) {
 
 // src/cli/commands/doctor.ts
 import chalk5 from "chalk";
-async function doctorCommand() {
+
+// src/validators/guidelines.ts
+import { existsSync as existsSync5 } from "fs";
+import { readFile as readFile3, readdir } from "fs/promises";
+import { join as join5 } from "path";
+function getEffectiveMandatoryTemplates(guidelinesConfig) {
+  const coreMandatory = getMandatoryTemplateFilenames();
+  if (!guidelinesConfig) {
+    return coreMandatory;
+  }
+  let mandatory = [...coreMandatory];
+  if (guidelinesConfig.additionalMandatory) {
+    for (const template of guidelinesConfig.additionalMandatory) {
+      if (!mandatory.includes(template) && templateMetadata[template]) {
+        mandatory.push(template);
+      }
+    }
+  }
+  if (guidelinesConfig.optionalOverrides) {
+    mandatory = mandatory.filter((t) => !guidelinesConfig.optionalOverrides.includes(t));
+  }
+  return mandatory;
+}
+async function validateGuidelinesExist(projectPath = process.cwd(), config) {
+  const guidelinesDir = join5(projectPath, "guidelines");
+  const result = {
+    valid: true,
+    missingMandatory: [],
+    presentMandatory: [],
+    presentOptional: [],
+    errors: []
+  };
+  if (!existsSync5(guidelinesDir)) {
+    const mandatory2 = getEffectiveMandatoryTemplates(config?.guidelines);
+    result.valid = false;
+    result.missingMandatory = mandatory2;
+    result.errors.push("Guidelines directory does not exist. Run: workflow init");
+    return result;
+  }
+  let existingFiles = [];
+  try {
+    existingFiles = await readdir(guidelinesDir);
+  } catch (error) {
+    result.valid = false;
+    result.errors.push(`Cannot read guidelines directory: ${error instanceof Error ? error.message : String(error)}`);
+    return result;
+  }
+  const mandatory = getEffectiveMandatoryTemplates(config?.guidelines);
+  for (const template of mandatory) {
+    if (existingFiles.includes(template)) {
+      result.presentMandatory.push(template);
+    } else {
+      result.missingMandatory.push(template);
+    }
+  }
+  const allTemplateNames = Object.keys(templateMetadata);
+  for (const file of existingFiles) {
+    if (allTemplateNames.includes(file) && !mandatory.includes(file)) {
+      result.presentOptional.push(file);
+    }
+  }
+  if (result.missingMandatory.length > 0) {
+    result.valid = false;
+    result.errors.push(
+      `Missing mandatory guidelines: ${result.missingMandatory.join(", ")}. Run: workflow init`
+    );
+  }
+  return result;
+}
+async function validateGitHubActionsSetup(projectPath = process.cwd()) {
+  const workflowsDir = join5(projectPath, ".github", "workflows");
+  const result = {
+    valid: true,
+    hasWorkflowFile: false,
+    hasLintCheck: false,
+    hasTypecheckCheck: false,
+    hasFormatCheck: false,
+    hasBuildCheck: false,
+    hasTestCheck: false,
+    errors: [],
+    warnings: []
+  };
+  if (!existsSync5(workflowsDir)) {
+    result.valid = false;
+    result.errors.push("GitHub Actions workflows directory does not exist. Run: workflow github:setup");
+    return result;
+  }
+  let workflowFiles = [];
+  try {
+    workflowFiles = await readdir(workflowsDir);
+  } catch (error) {
+    result.valid = false;
+    result.errors.push(`Cannot read workflows directory: ${error instanceof Error ? error.message : String(error)}`);
+    return result;
+  }
+  const ciWorkflowNames = ["ci.yml", "ci.yaml", "main.yml", "main.yaml", "build.yml", "build.yaml", "test.yml", "test.yaml"];
+  const ciWorkflows = workflowFiles.filter((f) => ciWorkflowNames.includes(f.toLowerCase()));
+  if (ciWorkflows.length === 0) {
+    result.valid = false;
+    result.errors.push("No CI workflow file found. Run: workflow github:setup");
+    return result;
+  }
+  result.hasWorkflowFile = true;
+  const workflowPath = join5(workflowsDir, ciWorkflows[0]);
+  let workflowContent = "";
+  try {
+    workflowContent = await readFile3(workflowPath, "utf-8");
+  } catch (error) {
+    result.warnings.push(`Cannot read workflow file: ${error instanceof Error ? error.message : String(error)}`);
+    return result;
+  }
+  const contentLower = workflowContent.toLowerCase();
+  if (contentLower.includes("lint") || contentLower.includes("eslint")) {
+    result.hasLintCheck = true;
+  } else {
+    result.warnings.push("CI workflow may be missing lint check");
+  }
+  if (contentLower.includes("typecheck") || contentLower.includes("type-check") || contentLower.includes("tsc")) {
+    result.hasTypecheckCheck = true;
+  } else {
+    result.warnings.push("CI workflow may be missing typecheck");
+  }
+  if (contentLower.includes("format") || contentLower.includes("prettier")) {
+    result.hasFormatCheck = true;
+  } else {
+    result.warnings.push("CI workflow may be missing format check");
+  }
+  if (contentLower.includes("build")) {
+    result.hasBuildCheck = true;
+  } else {
+    result.warnings.push("CI workflow may be missing build step");
+  }
+  if (contentLower.includes("test") && !contentLower.includes("typecheck")) {
+    result.hasTestCheck = true;
+  } else {
+    result.warnings.push("CI workflow may be missing test step");
+  }
+  const mandatoryChecks = [result.hasLintCheck, result.hasTypecheckCheck, result.hasFormatCheck];
+  if (!mandatoryChecks.every(Boolean)) {
+    result.valid = false;
+    result.errors.push("CI workflow is missing mandatory checks (lint, typecheck, format)");
+  }
+  return result;
+}
+
+// src/cli/commands/doctor.ts
+async function doctorCommand(options = {}) {
+  const cwd = process.cwd();
+  if (options.checkGuidelinesOnly) {
+    const result = await validateGuidelinesExist(cwd);
+    if (!result.valid) {
+      console.error(chalk5.red("\u2717 Missing mandatory guidelines"));
+      for (const missing of result.missingMandatory) {
+        console.error(chalk5.red(`  \u2022 ${missing}`));
+      }
+      process.exit(1);
+    }
+    process.exit(0);
+  }
   console.log(chalk5.bold.cyan("\n\u{1F3E5} Workflow Agent Health Check\n"));
   const config = await loadConfig();
+  let hasErrors = false;
+  let hasWarnings = false;
+  console.log(chalk5.bold("\u{1F4CB} Configuration"));
   if (!config) {
-    console.error(chalk5.red("\u2717 No workflow configuration found"));
-    console.log(chalk5.yellow("  Run: workflow init"));
+    console.error(chalk5.red("  \u2717 No workflow configuration found"));
+    console.log(chalk5.yellow("    Run: workflow init"));
     process.exit(1);
   }
-  console.log(chalk5.green("\u2713 Configuration loaded successfully"));
-  console.log(chalk5.dim(`  Project: ${config.projectName}`));
-  console.log(chalk5.dim(`  Scopes: ${config.scopes.length} configured`));
-  console.log(chalk5.dim(`  Enforcement: ${config.enforcement}`));
-  console.log(chalk5.dim(`  Language: ${config.language}`));
-  console.log(chalk5.cyan("\n\u{1F4A1} Suggestions:\n"));
-  console.log(chalk5.dim("  \u2022 Health check analysis coming soon"));
-  console.log(chalk5.dim("  \u2022 Git history analysis coming soon"));
-  console.log(chalk5.dim("  \u2022 Optimization recommendations coming soon"));
+  console.log(chalk5.green("  \u2713 Configuration loaded successfully"));
+  console.log(chalk5.dim(`    Project: ${config.projectName}`));
+  console.log(chalk5.dim(`    Scopes: ${config.scopes.length} configured`));
+  console.log(chalk5.dim(`    Enforcement: ${config.enforcement}`));
+  console.log(chalk5.dim(`    Language: ${config.language}`));
+  console.log(chalk5.bold("\n\u{1F4DA} Guidelines"));
+  const guidelinesResult = await validateGuidelinesExist(cwd, config);
+  if (guidelinesResult.valid) {
+    console.log(chalk5.green(`  \u2713 All ${guidelinesResult.presentMandatory.length} mandatory guidelines present`));
+    if (guidelinesResult.presentOptional.length > 0) {
+      console.log(chalk5.dim(`    + ${guidelinesResult.presentOptional.length} optional guidelines`));
+    }
+  } else {
+    hasErrors = true;
+    console.log(chalk5.red(`  \u2717 Missing ${guidelinesResult.missingMandatory.length} mandatory guidelines:`));
+    for (const missing of guidelinesResult.missingMandatory) {
+      console.log(chalk5.red(`    \u2022 ${missing}`));
+    }
+    console.log(chalk5.yellow("    Run: workflow init"));
+  }
+  console.log(chalk5.bold("\n\u{1F517} Git Hooks"));
+  if (!hasGitRepo(cwd)) {
+    console.log(chalk5.yellow("  \u26A0 No git repository found"));
+    hasWarnings = true;
+  } else {
+    const hookStatuses = await getAllHooksStatus(cwd);
+    const installedHooks = hookStatuses.filter((h) => h.installed);
+    if (installedHooks.length === hookStatuses.length) {
+      console.log(chalk5.green(`  \u2713 All ${installedHooks.length} hooks installed`));
+      for (const hook of hookStatuses) {
+        const extra = hook.wrappedOriginal ? " (wrapping original)" : "";
+        console.log(chalk5.dim(`    \u2022 ${hook.hookType}${extra}`));
+      }
+    } else if (installedHooks.length > 0) {
+      hasWarnings = true;
+      console.log(chalk5.yellow(`  \u26A0 ${installedHooks.length}/${hookStatuses.length} hooks installed`));
+      for (const hook of hookStatuses) {
+        if (hook.installed) {
+          console.log(chalk5.green(`    \u2713 ${hook.hookType}`));
+        } else {
+          console.log(chalk5.yellow(`    \u2717 ${hook.hookType}`));
+        }
+      }
+      console.log(chalk5.yellow("    Run: workflow hooks install"));
+    } else {
+      hasWarnings = true;
+      console.log(chalk5.yellow("  \u26A0 No hooks installed"));
+      console.log(chalk5.yellow("    Run: workflow hooks install"));
+    }
+  }
+  console.log(chalk5.bold("\n\u{1F680} CI/CD Pipeline"));
+  const repoInfo = await getRepoInfo(cwd);
+  if (!repoInfo.isGitRepo) {
+    console.log(chalk5.dim("  \u25CB No git repository (CI check skipped)"));
+  } else if (!repoInfo.isGitHub) {
+    console.log(chalk5.dim("  \u25CB Not a GitHub repository (CI check skipped)"));
+    console.log(chalk5.dim(`    Remote: ${repoInfo.remoteUrl || "none"}`));
+  } else {
+    console.log(chalk5.dim(`    Repository: ${repoInfo.github?.owner}/${repoInfo.github?.repo}`));
+    const ciResult = await validateGitHubActionsSetup(cwd);
+    if (ciResult.valid) {
+      console.log(chalk5.green("  \u2713 GitHub Actions CI configured correctly"));
+      const checks = [
+        ciResult.hasLintCheck && "lint",
+        ciResult.hasTypecheckCheck && "typecheck",
+        ciResult.hasFormatCheck && "format",
+        ciResult.hasBuildCheck && "build",
+        ciResult.hasTestCheck && "test"
+      ].filter(Boolean);
+      console.log(chalk5.dim(`    Checks: ${checks.join(", ")}`));
+    } else if (!ciResult.hasWorkflowFile) {
+      hasErrors = true;
+      console.log(chalk5.red("  \u2717 No CI workflow found"));
+      console.log(chalk5.yellow("    Run: workflow github:setup"));
+    } else {
+      hasWarnings = true;
+      console.log(chalk5.yellow("  \u26A0 CI workflow may be incomplete"));
+      for (const warning of ciResult.warnings) {
+        console.log(chalk5.yellow(`    \u2022 ${warning}`));
+      }
+      console.log(chalk5.yellow("    Run: workflow github:setup to regenerate"));
+    }
+  }
+  console.log(chalk5.bold("\n\u{1F4A1} Suggestions"));
+  if (repoInfo.isGitHub && hasCIWorkflow(cwd)) {
+    console.log(chalk5.cyan("  \u2192 Enable branch protection on GitHub"));
+    console.log(chalk5.dim("    Settings \u2192 Branches \u2192 Add rule"));
+    console.log(chalk5.dim("    \u2611 Require status checks to pass before merging"));
+    console.log(chalk5.dim("    \u2611 Require branches to be up to date before merging"));
+  }
+  if (config.enforcement !== "strict") {
+    console.log(chalk5.cyan(`  \u2192 Consider switching to 'strict' enforcement`));
+    console.log(chalk5.dim(`    Current: ${config.enforcement}`));
+  }
+  if (config.scopes.length < 5) {
+    console.log(chalk5.cyan("  \u2192 Consider adding more scopes for better organization"));
+    console.log(chalk5.dim("    Run: workflow config add scope <name>"));
+  }
+  console.log(chalk5.bold("\n\u{1F4CA} Summary"));
+  if (hasErrors) {
+    console.log(chalk5.red("  \u2717 Health check failed - issues found"));
+    process.exit(1);
+  } else if (hasWarnings) {
+    console.log(chalk5.yellow("  \u26A0 Health check passed with warnings"));
+  } else {
+    console.log(chalk5.green("  \u2713 All checks passed"));
+  }
+  console.log("");
 }
 
 // src/cli/commands/setup.ts
 import * as p3 from "@clack/prompts";
 import chalk6 from "chalk";
-import { readFileSync, writeFileSync, existsSync as existsSync2 } from "fs";
-import { join as join2 } from "path";
+import { readFileSync, writeFileSync, existsSync as existsSync6 } from "fs";
+import { join as join6 } from "path";
 var WORKFLOW_SCRIPTS = {
   "workflow:init": "workflow-agent init",
   "workflow:validate": "workflow-agent validate",
@@ -497,8 +1483,8 @@ var WORKFLOW_SCRIPTS = {
 async function setupCommand() {
   p3.intro(chalk6.bgBlue(" workflow-agent setup "));
   const cwd = process.cwd();
-  const packageJsonPath = join2(cwd, "package.json");
-  if (!existsSync2(packageJsonPath)) {
+  const packageJsonPath = join6(cwd, "package.json");
+  if (!existsSync6(packageJsonPath)) {
     p3.cancel("No package.json found in current directory");
     process.exit(1);
   }
@@ -555,15 +1541,15 @@ async function setupCommand() {
 // src/cli/commands/scope-create.ts
 import * as p4 from "@clack/prompts";
 import chalk7 from "chalk";
-import { existsSync as existsSync3 } from "fs";
-import { writeFile as writeFile2, mkdir as mkdir2, readFile } from "fs/promises";
-import { join as join3 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { writeFile as writeFile4, mkdir as mkdir4, readFile as readFile4 } from "fs/promises";
+import { join as join7 } from "path";
 async function scopeCreateCommand(options) {
   console.log(chalk7.bold.cyan("\n\u{1F3A8} Create Custom Scope Package\n"));
   const cwd = process.cwd();
   const isNonInteractive = !!(options.name && options.scopes && options.presetName);
-  const isMonorepo = existsSync3(join3(cwd, "pnpm-workspace.yaml"));
-  if (isMonorepo) {
+  const isMonorepo2 = existsSync7(join7(cwd, "pnpm-workspace.yaml"));
+  if (isMonorepo2) {
     console.log(chalk7.dim("\u2713 Detected monorepo workspace\n"));
   }
   const packageNameInput = isNonInteractive ? options.name : await p4.text({
@@ -696,8 +1682,8 @@ async function scopeCreateCommand(options) {
   let outputDir;
   if (options.outputDir) {
     outputDir = options.outputDir;
-  } else if (isMonorepo) {
-    outputDir = join3(cwd, "packages", `scopes-${packageName}`);
+  } else if (isMonorepo2) {
+    outputDir = join7(cwd, "packages", `scopes-${packageName}`);
   } else {
     const customDir = await p4.text({
       message: "Output directory:",
@@ -708,9 +1694,9 @@ async function scopeCreateCommand(options) {
       p4.cancel("Operation cancelled");
       process.exit(0);
     }
-    outputDir = join3(cwd, customDir);
+    outputDir = join7(cwd, customDir);
   }
-  if (existsSync3(outputDir)) {
+  if (existsSync7(outputDir)) {
     const shouldOverwrite = await p4.confirm({
       message: `Directory ${outputDir} already exists. Overwrite?`,
       initialValue: false
@@ -720,10 +1706,10 @@ async function scopeCreateCommand(options) {
       process.exit(0);
     }
   }
-  const spinner4 = p4.spinner();
-  spinner4.start("Creating package structure...");
+  const spinner5 = p4.spinner();
+  spinner5.start("Creating package structure...");
   try {
-    await mkdir2(join3(outputDir, "src"), { recursive: true });
+    await mkdir4(join7(outputDir, "src"), { recursive: true });
     const packageJson = {
       name: `@workflow/scopes-${packageName}`,
       version: "1.0.0",
@@ -763,8 +1749,8 @@ async function scopeCreateCommand(options) {
         access: "public"
       }
     };
-    await writeFile2(
-      join3(outputDir, "package.json"),
+    await writeFile4(
+      join7(outputDir, "package.json"),
       JSON.stringify(packageJson, null, 2),
       "utf-8"
     );
@@ -776,8 +1762,8 @@ async function scopeCreateCommand(options) {
       },
       include: ["src/**/*"]
     };
-    await writeFile2(
-      join3(outputDir, "tsconfig.json"),
+    await writeFile4(
+      join7(outputDir, "tsconfig.json"),
       JSON.stringify(tsconfig, null, 2),
       "utf-8"
     );
@@ -791,7 +1777,7 @@ export default defineConfig({
   sourcemap: true,
 });
 `;
-    await writeFile2(join3(outputDir, "tsup.config.ts"), tsupConfig, "utf-8");
+    await writeFile4(join7(outputDir, "tsup.config.ts"), tsupConfig, "utf-8");
     const indexTs = `import type { Scope } from '@hawkinside_out/workflow-agent/config';
 
 export const scopes: Scope[] = ${JSON.stringify(scopes, null, 2)};
@@ -805,7 +1791,7 @@ export const preset = {
 
 export default preset;
 `;
-    await writeFile2(join3(outputDir, "src", "index.ts"), indexTs, "utf-8");
+    await writeFile4(join7(outputDir, "src", "index.ts"), indexTs, "utf-8");
     if (!options.noTest) {
       const testFile = `import { describe, it, expect } from 'vitest';
 import { scopes, preset } from './index.js';
@@ -846,12 +1832,12 @@ describe('${presetName} Scope Preset', () => {
   });
 });
 `;
-      await writeFile2(join3(outputDir, "src", "index.test.ts"), testFile, "utf-8");
+      await writeFile4(join7(outputDir, "src", "index.test.ts"), testFile, "utf-8");
     }
-    spinner4.stop("\u2713 Package structure created");
-    if (isMonorepo) {
-      const workspaceFile = join3(cwd, "pnpm-workspace.yaml");
-      const workspaceContent = await readFile(workspaceFile, "utf-8");
+    spinner5.stop("\u2713 Package structure created");
+    if (isMonorepo2) {
+      const workspaceFile = join7(cwd, "pnpm-workspace.yaml");
+      const workspaceContent = await readFile4(workspaceFile, "utf-8");
       const packagePath = `packages/scopes-${packageName}`;
       if (!workspaceContent.includes(packagePath) && !workspaceContent.includes("packages/*")) {
         console.log(chalk7.yellow("\n\u26A0\uFE0F  Add the following to pnpm-workspace.yaml:"));
@@ -886,7 +1872,7 @@ describe('${presetName} Scope Preset', () => {
       console.log(chalk7.dim("  4. Use in other projects: pnpm add @workflow/scopes-" + packageName + "\n"));
     }
   } catch (error) {
-    spinner4.stop("\u2717 Failed to create package");
+    spinner5.stop("\u2717 Failed to create package");
     console.error(chalk7.red("\nError:"), error);
     process.exit(1);
   }
@@ -895,9 +1881,9 @@ describe('${presetName} Scope Preset', () => {
 // src/cli/commands/scope-migrate.ts
 import * as p5 from "@clack/prompts";
 import chalk8 from "chalk";
-import { existsSync as existsSync4 } from "fs";
-import { writeFile as writeFile3, mkdir as mkdir3, readFile as readFile2 } from "fs/promises";
-import { join as join4 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { writeFile as writeFile5, mkdir as mkdir5, readFile as readFile5 } from "fs/promises";
+import { join as join8 } from "path";
 async function scopeMigrateCommand(options) {
   console.log(chalk8.bold.cyan("\n\u{1F504} Migrate Scopes to Custom Package\n"));
   const cwd = process.cwd();
@@ -935,8 +1921,8 @@ async function scopeMigrateCommand(options) {
     p5.cancel("Migration cancelled");
     process.exit(0);
   }
-  const isMonorepo = existsSync4(join4(cwd, "pnpm-workspace.yaml"));
-  if (isMonorepo) {
+  const isMonorepo2 = existsSync8(join8(cwd, "pnpm-workspace.yaml"));
+  if (isMonorepo2) {
     console.log(chalk8.dim("\n\u2713 Detected monorepo workspace\n"));
   }
   const packageNameInput = options.name || await p5.text({
@@ -980,8 +1966,8 @@ async function scopeMigrateCommand(options) {
   let outputDir;
   if (options.outputDir) {
     outputDir = options.outputDir;
-  } else if (isMonorepo) {
-    outputDir = join4(cwd, "packages", `scopes-${packageName}`);
+  } else if (isMonorepo2) {
+    outputDir = join8(cwd, "packages", `scopes-${packageName}`);
   } else {
     const customDir = await p5.text({
       message: "Output directory:",
@@ -992,9 +1978,9 @@ async function scopeMigrateCommand(options) {
       p5.cancel("Migration cancelled");
       process.exit(0);
     }
-    outputDir = join4(cwd, customDir);
+    outputDir = join8(cwd, customDir);
   }
-  if (existsSync4(outputDir)) {
+  if (existsSync8(outputDir)) {
     const shouldOverwrite = await p5.confirm({
       message: `Directory ${outputDir} already exists. Overwrite?`,
       initialValue: false
@@ -1004,10 +1990,10 @@ async function scopeMigrateCommand(options) {
       process.exit(0);
     }
   }
-  const spinner4 = p5.spinner();
-  spinner4.start("Migrating scopes to package...");
+  const spinner5 = p5.spinner();
+  spinner5.start("Migrating scopes to package...");
   try {
-    await mkdir3(join4(outputDir, "src"), { recursive: true });
+    await mkdir5(join8(outputDir, "src"), { recursive: true });
     const packageJson = {
       name: `@workflow/scopes-${packageName}`,
       version: "1.0.0",
@@ -1047,8 +2033,8 @@ async function scopeMigrateCommand(options) {
         access: "public"
       }
     };
-    await writeFile3(
-      join4(outputDir, "package.json"),
+    await writeFile5(
+      join8(outputDir, "package.json"),
       JSON.stringify(packageJson, null, 2),
       "utf-8"
     );
@@ -1060,8 +2046,8 @@ async function scopeMigrateCommand(options) {
       },
       include: ["src/**/*"]
     };
-    await writeFile3(
-      join4(outputDir, "tsconfig.json"),
+    await writeFile5(
+      join8(outputDir, "tsconfig.json"),
       JSON.stringify(tsconfig, null, 2),
       "utf-8"
     );
@@ -1075,7 +2061,7 @@ export default defineConfig({
   sourcemap: true,
 });
 `;
-    await writeFile3(join4(outputDir, "tsup.config.ts"), tsupConfig, "utf-8");
+    await writeFile5(join8(outputDir, "tsup.config.ts"), tsupConfig, "utf-8");
     const indexTs = `import type { Scope } from '@hawkinside_out/workflow-agent/config';
 
 export const scopes: Scope[] = ${JSON.stringify(config.scopes, null, 2)};
@@ -1089,7 +2075,7 @@ export const preset = {
 
 export default preset;
 `;
-    await writeFile3(join4(outputDir, "src", "index.ts"), indexTs, "utf-8");
+    await writeFile5(join8(outputDir, "src", "index.ts"), indexTs, "utf-8");
     const testFile = `import { describe, it, expect } from 'vitest';
 import { scopes, preset } from './index.js';
 import { ScopeSchema } from '@hawkinside_out/workflow-agent/config';
@@ -1132,11 +2118,11 @@ describe('${presetName} Scope Preset (Migrated)', () => {
   });
 });
 `;
-    await writeFile3(join4(outputDir, "src", "index.test.ts"), testFile, "utf-8");
-    spinner4.stop("\u2713 Package created from migrated scopes");
-    if (isMonorepo) {
-      const workspaceFile = join4(cwd, "pnpm-workspace.yaml");
-      const workspaceContent = await readFile2(workspaceFile, "utf-8");
+    await writeFile5(join8(outputDir, "src", "index.test.ts"), testFile, "utf-8");
+    spinner5.stop("\u2713 Package created from migrated scopes");
+    if (isMonorepo2) {
+      const workspaceFile = join8(cwd, "pnpm-workspace.yaml");
+      const workspaceContent = await readFile5(workspaceFile, "utf-8");
       const packagePath = `packages/scopes-${packageName}`;
       if (!workspaceContent.includes(packagePath) && !workspaceContent.includes("packages/*")) {
         console.log(chalk8.yellow("\n\u26A0\uFE0F  Add the following to pnpm-workspace.yaml:"));
@@ -1150,7 +2136,7 @@ describe('${presetName} Scope Preset (Migrated)', () => {
       initialValue: false
     });
     if (!p5.isCancel(keepConfig) && !keepConfig) {
-      const configPath = join4(cwd, "workflow.config.json");
+      const configPath = join8(cwd, "workflow.config.json");
       const updatedConfig = {
         ...config,
         scopes: [],
@@ -1158,7 +2144,7 @@ describe('${presetName} Scope Preset (Migrated)', () => {
         preset: `scopes-${packageName}`
         // Reference the new package
       };
-      await writeFile3(configPath, JSON.stringify(updatedConfig, null, 2), "utf-8");
+      await writeFile5(configPath, JSON.stringify(updatedConfig, null, 2), "utf-8");
       console.log(chalk8.green("\u2713 Updated workflow.config.json"));
       console.log(chalk8.dim("  \u2022 Cleared inline scopes"));
       console.log(chalk8.dim(`  \u2022 Added preset reference: scopes-${packageName}
@@ -1185,12 +2171,249 @@ describe('${presetName} Scope Preset (Migrated)', () => {
     }
     console.log(chalk8.dim("\u{1F4A1} Tip: You can now reuse this scope package across multiple projects!\n"));
   } catch (error) {
-    spinner4.stop("\u2717 Migration failed");
+    spinner5.stop("\u2717 Migration failed");
     console.error(chalk8.red("\nError:"), error);
     process.exit(1);
   }
 }
 
+// src/cli/commands/hooks.ts
+import chalk9 from "chalk";
+async function hooksCommand(action) {
+  const cwd = process.cwd();
+  switch (action) {
+    case "install":
+      await installHooksAction(cwd);
+      break;
+    case "uninstall":
+      await uninstallHooksAction(cwd);
+      break;
+    case "status":
+      await statusHooksAction(cwd);
+      break;
+    default:
+      console.error(chalk9.red(`Unknown action: ${action}`));
+      console.log(chalk9.dim("Available actions: install, uninstall, status"));
+      process.exit(1);
+  }
+}
+async function installHooksAction(cwd) {
+  console.log(chalk9.bold.cyan("\n\u{1F517} Installing Workflow Agent Git Hooks\n"));
+  if (!hasGitRepo(cwd)) {
+    console.error(chalk9.red("\u2717 No git repository found"));
+    console.log(chalk9.yellow("  Run: git init"));
+    process.exit(1);
+  }
+  const config = await loadConfig();
+  const hooksConfig = config?.hooks;
+  const results = await installHooks(hooksConfig, cwd);
+  let hasErrors = false;
+  for (const result of results) {
+    if (result.success) {
+      if (result.wrappedExisting) {
+        console.log(chalk9.green(`\u2713 Installed ${result.hookType} hook (wrapped existing hook)`));
+      } else {
+        console.log(chalk9.green(`\u2713 Installed ${result.hookType} hook`));
+      }
+    } else {
+      console.error(chalk9.red(`\u2717 Failed to install ${result.hookType}: ${result.error}`));
+      hasErrors = true;
+    }
+  }
+  if (!hasErrors) {
+    console.log(chalk9.green("\n\u2713 Git hooks installed successfully"));
+    console.log(chalk9.dim("\nHooks will run automatically on commit."));
+    console.log(chalk9.dim("They will be skipped in CI environments."));
+  } else {
+    process.exit(1);
+  }
+}
+async function uninstallHooksAction(cwd) {
+  console.log(chalk9.bold.cyan("\n\u{1F513} Uninstalling Workflow Agent Git Hooks\n"));
+  if (!hasGitRepo(cwd)) {
+    console.error(chalk9.red("\u2717 No git repository found"));
+    process.exit(1);
+  }
+  const results = await uninstallHooks(cwd);
+  let hasErrors = false;
+  for (const result of results) {
+    if (result.success) {
+      if (result.wrappedExisting) {
+        console.log(chalk9.green(`\u2713 Removed ${result.hookType} hook (restored original)`));
+      } else {
+        console.log(chalk9.green(`\u2713 Removed ${result.hookType} hook`));
+      }
+    } else if (result.error) {
+      console.error(chalk9.red(`\u2717 Failed to remove ${result.hookType}: ${result.error}`));
+      hasErrors = true;
+    }
+  }
+  if (!hasErrors) {
+    console.log(chalk9.green("\n\u2713 Git hooks uninstalled successfully"));
+  } else {
+    process.exit(1);
+  }
+}
+async function statusHooksAction(cwd) {
+  console.log(chalk9.bold.cyan("\n\u{1F4CA} Workflow Agent Git Hooks Status\n"));
+  if (!hasGitRepo(cwd)) {
+    console.error(chalk9.red("\u2717 No git repository found"));
+    process.exit(1);
+  }
+  const statuses = await getAllHooksStatus(cwd);
+  for (const status of statuses) {
+    const icon = status.installed ? "\u2713" : "\u2717";
+    const color = status.installed ? chalk9.green : chalk9.yellow;
+    let message = `${icon} ${status.hookType}`;
+    if (status.installed) {
+      message += " - installed";
+      if (status.wrappedOriginal) {
+        message += " (wrapping original hook)";
+      }
+    } else if (status.hasExistingHook) {
+      message += " - existing hook (not managed by Workflow Agent)";
+    } else {
+      message += " - not installed";
+    }
+    console.log(color(message));
+  }
+  const allInstalled = statuses.every((s) => s.installed);
+  if (!allInstalled) {
+    console.log(chalk9.dim("\nTo install hooks: workflow hooks install"));
+  }
+}
+
+// src/cli/commands/github-actions.ts
+import chalk10 from "chalk";
+import * as p6 from "@clack/prompts";
+async function githubCommand(action) {
+  const cwd = process.cwd();
+  switch (action) {
+    case "setup":
+      await setupAction(cwd);
+      break;
+    case "check":
+      await checkAction(cwd);
+      break;
+    default:
+      console.error(chalk10.red(`Unknown action: ${action}`));
+      console.log(chalk10.dim("Available actions: setup, check"));
+      process.exit(1);
+  }
+}
+async function setupAction(cwd) {
+  console.log(chalk10.bold.cyan("\n\u{1F527} Setting Up GitHub Actions CI\n"));
+  const repoInfo = await getRepoInfo(cwd);
+  if (!repoInfo.isGitRepo) {
+    console.error(chalk10.red("\u2717 No git repository found"));
+    console.log(chalk10.yellow("  Run: git init"));
+    process.exit(1);
+  }
+  if (!repoInfo.isGitHub) {
+    console.log(chalk10.yellow("\u26A0\uFE0F  No GitHub remote detected"));
+    const shouldContinue = await p6.confirm({
+      message: "Create GitHub Actions workflow anyway?",
+      initialValue: true
+    });
+    if (p6.isCancel(shouldContinue) || !shouldContinue) {
+      p6.cancel("Setup cancelled");
+      process.exit(0);
+    }
+  } else {
+    console.log(chalk10.dim(`Repository: ${repoInfo.github?.owner}/${repoInfo.github?.repo}`));
+  }
+  if (hasCIWorkflow(cwd)) {
+    const shouldOverwrite = await p6.confirm({
+      message: "CI workflow already exists. Overwrite?",
+      initialValue: false
+    });
+    if (p6.isCancel(shouldOverwrite) || !shouldOverwrite) {
+      p6.cancel("Setup cancelled");
+      process.exit(0);
+    }
+  }
+  const projectInfo = await getProjectInfo(cwd);
+  console.log(chalk10.dim(`Package manager: ${projectInfo.packageManager}`));
+  console.log(chalk10.dim(`Monorepo: ${projectInfo.isMonorepo ? "yes" : "no"}`));
+  const config = await loadConfig();
+  const ciConfig = config?.ci;
+  const spinner5 = p6.spinner();
+  spinner5.start("Creating CI workflow...");
+  const result = await createCIWorkflow({
+    projectPath: cwd,
+    packageManager: projectInfo.packageManager,
+    isMonorepo: projectInfo.isMonorepo,
+    ciConfig,
+    defaultBranch: repoInfo.defaultBranch || "main"
+  });
+  if (result.success) {
+    spinner5.stop(chalk10.green("\u2713 Created CI workflow"));
+    console.log(chalk10.dim(`  File: ${result.filePath}`));
+    console.log(chalk10.green("\n\u2713 GitHub Actions CI setup complete"));
+    console.log(chalk10.dim("\nThe workflow will run on:"));
+    console.log(chalk10.dim("  \u2022 Push to main/develop branches"));
+    console.log(chalk10.dim("  \u2022 Pull requests to main/develop branches"));
+    console.log(chalk10.dim("\nChecks included:"));
+    const checks = ciConfig?.checks || ["lint", "typecheck", "format", "build", "test"];
+    for (const check of checks) {
+      const hasScript = check === "lint" ? projectInfo.hasLintScript : check === "typecheck" ? projectInfo.hasTypecheckScript : check === "format" ? projectInfo.hasFormatScript : check === "test" ? projectInfo.hasTestScript : check === "build" ? projectInfo.hasBuildScript : false;
+      const status = hasScript ? chalk10.green("\u2713") : chalk10.yellow("\u26A0");
+      const note = hasScript ? "" : " (add script to package.json)";
+      console.log(chalk10.dim(`  ${status} ${check}${note}`));
+    }
+    console.log(chalk10.cyan("\n\u{1F4A1} Recommended: Enable branch protection"));
+    console.log(chalk10.dim("  Go to GitHub \u2192 Settings \u2192 Branches \u2192 Add rule"));
+    console.log(chalk10.dim('  Enable "Require status checks to pass before merging"'));
+    console.log(chalk10.dim('  Select the "ci" status check'));
+  } else {
+    spinner5.stop(chalk10.red("\u2717 Failed to create CI workflow"));
+    console.error(chalk10.red(`  Error: ${result.error}`));
+    process.exit(1);
+  }
+}
+async function checkAction(cwd) {
+  console.log(chalk10.bold.cyan("\n\u{1F50D} Checking GitHub Actions CI Setup\n"));
+  const result = await validateGitHubActionsSetup(cwd);
+  if (result.hasWorkflowFile) {
+    console.log(chalk10.green("\u2713 CI workflow file found"));
+  } else {
+    console.log(chalk10.red("\u2717 No CI workflow file found"));
+    console.log(chalk10.yellow("  Run: workflow github:setup"));
+    process.exit(1);
+  }
+  const checks = [
+    { name: "Lint", present: result.hasLintCheck },
+    { name: "Type check", present: result.hasTypecheckCheck },
+    { name: "Format", present: result.hasFormatCheck },
+    { name: "Build", present: result.hasBuildCheck },
+    { name: "Test", present: result.hasTestCheck }
+  ];
+  console.log(chalk10.dim("\nCI checks:"));
+  for (const check of checks) {
+    const icon = check.present ? chalk10.green("\u2713") : chalk10.yellow("\u26A0");
+    console.log(`  ${icon} ${check.name}`);
+  }
+  if (result.errors.length > 0) {
+    console.log(chalk10.red("\nErrors:"));
+    for (const error of result.errors) {
+      console.log(chalk10.red(`  \u2022 ${error}`));
+    }
+  }
+  if (result.warnings.length > 0) {
+    console.log(chalk10.yellow("\nWarnings:"));
+    for (const warning of result.warnings) {
+      console.log(chalk10.yellow(`  \u2022 ${warning}`));
+    }
+  }
+  if (result.valid) {
+    console.log(chalk10.green("\n\u2713 CI setup is valid"));
+  } else {
+    console.log(chalk10.red("\n\u2717 CI setup has issues"));
+    console.log(chalk10.yellow("  Run: workflow github:setup"));
+    process.exit(1);
+  }
+}
+
 // src/cli/index.ts
 var program = new Command();
 program.name("workflow").description("A self-evolving workflow management system for AI agent development").version("1.0.0");
@@ -1199,7 +2422,9 @@ program.command("validate <type>").description("Validate branch name, commit mes
 program.command("config <action>").description("Manage workflow configuration").argument("<action>", "Action: get, set, add, remove").argument("[key]", "Config key").argument("[value]", "Config value").action(configCommand);
 program.command("suggest").description("Submit an improvement suggestion").argument("<feedback>", "Your improvement suggestion").option("--author <author>", "Your name or username").option("--category <category>", "Category: feature, bug, documentation, performance, other").action(suggestCommand);
 program.command("setup").description("Add workflow scripts to package.json").action(setupCommand);
-program.command("doctor").description("Run health check and get optimization suggestions").action(doctorCommand);
+program.command("doctor").description("Run health check and get optimization suggestions").option("--check-guidelines-only", "Only check mandatory guidelines exist (exits 0 or 1)").action(doctorCommand);
+program.command("hooks").description("Manage git hooks (install, uninstall, status)").argument("<action>", "Action: install, uninstall, status").action(hooksCommand);
+program.command("github").description("Manage GitHub Actions CI (setup, check)").argument("<action>", "Action: setup, check").action(githubCommand);
 program.command("scope:create").description("Create a custom scope package").option("--name <name>", 'Package name (e.g., "fintech", "gaming")').option("--scopes <scopes>", "Comma-separated scopes (format: name:description:emoji:category)").option("--preset-name <preset>", "Preset display name").option("--output-dir <dir>", "Output directory").option("--no-test", "Skip test file generation").action(scopeCreateCommand);
 program.command("scope:migrate").description("Migrate inline scopes to a custom package").option("--name <name>", "Package name for the preset").option("--output-dir <dir>", "Output directory").option("--keep-config", "Keep inline scopes in config after migration").action(scopeMigrateCommand);
 program.parse();