agentboot 0.1.0 → 0.2.0

package/README.md

@@ -29,19 +29,20 @@ The output works without AgentBoot installed. Any platform that reads Markdown c
 ## Quickstart
 
 ```bash
-# Install
-npm install agentboot
+# Install (pick one)
+brew tap agentboot-dev/agentboot && brew install agentboot
+npm install -g agentboot
 
 # Set up a new personas repo
-npx agentboot setup
+agentboot setup
 
 # Configure your org
 # Edit agentboot.config.json with your org name, groups, and teams
 
 # Build and sync
-npx agentboot build
-npx agentboot sync --dry-run   # preview first
-npx agentboot sync             # deploy to repos
+agentboot build
+agentboot sync --dry-run   # preview first
+agentboot sync             # deploy to repos
 ```
 
 Your repos now have:
@@ -123,7 +124,7 @@ Everything is driven by `agentboot.config.json`:
 agentboot build          # Compile personas from traits
 agentboot validate       # Pre-build validation checks
 agentboot sync           # Distribute to target repos
-agentboot full-build     # clean → validate → build → sync pipeline
+agentboot dev-build      # clean → validate → build → dev-sync pipeline
 agentboot setup          # Scaffold a new personas repo
 agentboot add <type>     # Create a new persona, trait, or gotcha
 agentboot doctor         # Diagnose configuration issues

package/agentboot.config.json

@@ -5,7 +5,7 @@
   // Convention over configuration: every field has a sensible default.
   // You only need to specify what's different about your organization.
   //
-  // Run `npm run full-build` after editing to validate, compile, and sync.
+  // Run `npm run dev-build` after editing to validate, compile, and sync.
 
   // ---------------------------------------------------------------------------
   // Organization identity
@@ -184,6 +184,9 @@
   // Claude Code-specific output configuration (only applies to "claude" platform).
   // ---------------------------------------------------------------------------
 
+  // Claude Code-specific output (experimental — Phase 2).
+  // Generates settings.json and .mcp.json when uncommented.
+  // Requires Claude Code to support these features.
   // "claude": {
   //   "hooks": {},
   //   "permissions": { "allow": [], "deny": [] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentboot",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Convention over configuration for agentic development teams. The Spring Boot of Claude Code governance.",
   "license": "Apache-2.0",
   "author": "Mike Saavedra <mike@agentboot.dev>",
@@ -44,7 +44,7 @@
     "build": "tsx scripts/compile.ts",
     "validate": "tsx scripts/validate.ts",
     "sync": "tsx scripts/sync.ts",
-    "full-build": "npm run clean && npm run validate && npm run build && npm run dev-sync",
+    "dev-build": "npm run clean && npm run validate && npm run build && npm run dev-sync",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",

package/scripts/cli.ts

@@ -140,7 +140,7 @@ program
 program
   .command("validate")
   .description("Run pre-build validation checks")
-  .option("--strict", "treat warnings as errors")
+  .option("-s, --strict", "treat warnings as errors")
   .action((opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const args = collectGlobalArgs({ config: globalOpts.config });
@@ -163,7 +163,7 @@ program
   .command("sync")
   .description("Distribute compiled output to target repositories")
   .option("--repos-file <path>", "path to repos.json")
-  .option("--dry-run", "preview changes without writing")
+  .option("-d, --dry-run", "preview changes without writing")
   .action((opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const args = collectGlobalArgs({ config: globalOpts.config });
@@ -200,10 +200,10 @@ program
     });
   });
 
-// ---- full-build -----------------------------------------------------------
+// ---- dev-build -----------------------------------------------------------
 
 program
-  .command("full-build")
+  .command("dev-build")
   .description("Run clean → validate → build → dev-sync pipeline")
   .action((_opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
@@ -224,6 +224,10 @@ program
       ["tsx", path.join(SCRIPTS_DIR, "validate.ts"), ...baseArgs],
       { cwd: ROOT, stdio: quiet ? ["inherit", "ignore", "pipe"] : "inherit" },
     );
+    if (valResult.error) {
+      console.error(`Validation failed to start: ${valResult.error.message}`);
+      process.exit(1);
+    }
     if (valResult.status !== 0) {
       console.error("Validation failed.");
       process.exit(valResult.status ?? 1);
@@ -236,6 +240,10 @@ program
       ["tsx", path.join(SCRIPTS_DIR, "compile.ts"), ...baseArgs],
       { cwd: ROOT, stdio: quiet ? ["inherit", "ignore", "pipe"] : "inherit" },
     );
+    if (buildResult.error) {
+      console.error(`Build failed to start: ${buildResult.error.message}`);
+      process.exit(1);
+    }
     if (buildResult.status !== 0) {
       console.error("Build failed.");
       process.exit(buildResult.status ?? 1);
@@ -248,12 +256,17 @@ program
       ["tsx", path.join(SCRIPTS_DIR, "dev-sync.ts"), ...baseArgs],
       { cwd: ROOT, stdio: quiet ? ["inherit", "ignore", "pipe"] : "inherit" },
     );
+    if (syncResult.error) {
+      console.error(`Dev-sync failed to start: ${syncResult.error.message}`);
+      process.exit(1);
+    }
     if (syncResult.status !== 0) {
       console.error("Dev-sync failed.");
       process.exit(syncResult.status ?? 1);
     }
 
-    if (!quiet) console.log("✓ full-build complete");
+    if (!quiet) console.log("✓ dev-build complete");
+    process.exit(0);
   });
 
 // ---- setup (AB-33) --------------------------------------------------------
@@ -293,7 +306,7 @@ program
       }
     } catch { /* no git, use default */ }
 
-    console.log(chalk.cyan(`  Detected org: ${orgName}`));
+    console.log(chalk.cyan(`  Detected org: ${orgName}`) + chalk.gray(" (edit agentboot.config.json to change)"));
 
     // Scaffold config
     const configContent = JSON.stringify({
@@ -351,8 +364,8 @@ program
   .argument("<name>", "name for the new item (lowercase-with-hyphens)")
   .action((type: string, name: string) => {
     // Validate name format
-    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-      console.error(chalk.red(`Name must be lowercase alphanumeric with hyphens: got '${name}'`));
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
+      console.error(chalk.red(`Name must be 1-64 lowercase alphanumeric chars with hyphens: got '${name}'`));
       process.exit(1);
     }
 
@@ -636,7 +649,13 @@ program
       process.exit(1);
     }
 
-    const config = loadConfig(configPath);
+    let config;
+    try {
+      config = loadConfig(configPath);
+    } catch (e: unknown) {
+      console.error(chalk.red(`Failed to parse config: ${e instanceof Error ? e.message : String(e)}`));
+      process.exit(1);
+    }
     const pkgPath = path.join(ROOT, "package.json");
     const version = fs.existsSync(pkgPath) ? JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version : "unknown";
 
@@ -734,7 +753,13 @@ program
       process.exit(1);
     }
 
-    const config = loadConfig(configPath);
+    let config;
+    try {
+      config = loadConfig(configPath);
+    } catch (e: unknown) {
+      console.error(chalk.red(`Failed to parse config: ${e instanceof Error ? e.message : String(e)}`));
+      process.exit(1);
+    }
     const isJson = opts.format === "json";
     if (!isJson) console.log(chalk.bold("\nAgentBoot — lint\n"));
 
@@ -752,6 +777,7 @@ program
 
     const personasDir = path.join(cwd, "core", "personas");
     const enabledPersonas = config.personas?.enabled ?? [];
+    const enabledTraits = config.traits?.enabled ?? [];
     const tokenBudget = config.output?.tokenBudget?.warnAt ?? 8000;
 
     // Vague language patterns
@@ -861,7 +887,6 @@ program
 
         // Check for unused trait
         const traitName = file.replace(/\.md$/, "");
-        const enabledTraits = config.traits?.enabled ?? [];
         if (enabledTraits.length > 0 && !enabledTraits.includes(traitName)) {
           findings.push({ rule: "unused-trait", severity: "info", file: `core/traits/${file}`, message: `Trait not in traits.enabled list` });
         }
@@ -921,7 +946,7 @@ program
   .command("uninstall")
   .description("Remove AgentBoot managed files from a repository")
   .option("--repo <path>", "target repository path")
-  .option("--dry-run", "preview what would be removed")
+  .option("-d, --dry-run", "preview what would be removed")
   .action((opts) => {
     const targetRepo = opts.repo ? path.resolve(opts.repo) : process.cwd();
     const dryRun = opts.dryRun ?? false;
@@ -1023,9 +1048,12 @@ program
   .description("View configuration (read-only)")
   .argument("[key]", "config key (e.g., personas.enabled)")
   .argument("[value]", "not yet supported")
-  .action((key?: string, value?: string) => {
+  .action((key: string | undefined, value: string | undefined, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
     const cwd = process.cwd();
-    const configPath = path.join(cwd, "agentboot.config.json");
+    const configPath = globalOpts.config
+      ? path.resolve(globalOpts.config)
+      : path.join(cwd, "agentboot.config.json");
 
     if (!fs.existsSync(configPath)) {
       console.error(chalk.red("No agentboot.config.json found."));

package/scripts/compile.ts

@@ -236,8 +236,12 @@ function buildClaudeOutput(
   const invocation = personaConfig?.invocation ?? `/${personaName}`;
   const skillName = invocation.replace(/^\//, "");
   const description = personaConfig?.description ?? personaName;
-  // Escape newlines and quotes in description to prevent YAML injection
-  const safeDescription = description.replace(/\n/g, " ").replace(/"/g, '\\"');
+  // Escape for YAML double-quoted strings
+  const safeDescription = description
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, " ")
+    .replace(/---/g, "\\-\\-\\-");
 
   // AB-18: CC skill frontmatter with context:fork → delegates to agent
   const frontmatterLines: string[] = [
@@ -363,9 +367,12 @@ function compilePersona(
     const model = personaConfig?.model;  // undefined = omit from frontmatter
     const permMode = personaConfig?.permissionMode;
     const agentDescription = personaConfig?.description ?? personaName;
-    // Escape newlines and quotes in description to prevent YAML injection.
-    // JS '\\"' produces the string \" which is the correct YAML double-quote escape.
-    const safeDescription = agentDescription.replace(/\n/g, " ").replace(/"/g, '\\"');
+    // Escape for YAML double-quoted strings: backslashes, quotes, newlines, and --- sequences.
+    const safeDescription = agentDescription
+      .replace(/\\/g, "\\\\")   // backslashes first (before other escapes add more)
+      .replace(/"/g, '\\"')     // double quotes
+      .replace(/\n/g, " ")      // newlines → spaces
+      .replace(/---/g, "\\-\\-\\-"); // prevent YAML document markers
     const withoutFrontmatter = composed.replace(/^---\n[\s\S]*?\n---\n*/, "");
     const agentFrontmatter: string[] = [
       "---",
@@ -651,7 +658,23 @@ function generateSettingsJson(
     }
   }
 
-  log(chalk.yellow("  ⚠ Generating settings.json with hooks/permissions — these will be synced to all target repos"));
+  // Security: hooks execute shell commands in target repos — warn prominently
+  if (hooks) {
+    log(chalk.red("  ⚠ CAUTION: settings.json contains hooks that execute shell commands in target repos."));
+    log(chalk.red("    Review claude.hooks in agentboot.config.json carefully before syncing."));
+    // Validate hook event names against known CC events
+    const validEvents = [
+      "PreToolUse", "PostToolUse", "Notification", "Stop",
+      "SubagentStop", "SubagentStart",
+    ];
+    for (const key of Object.keys(hooks)) {
+      if (!validEvents.includes(key)) {
+        log(chalk.yellow(`    ⚠ Unknown hook event: "${key}" — may not be recognized by Claude Code`));
+      }
+    }
+  } else {
+    log(chalk.yellow("  ⚠ Generating settings.json with permissions — these will be synced to all target repos"));
+  }
 
   const settings: Record<string, unknown> = {};
   if (hooks) settings.hooks = hooks;
@@ -755,7 +778,7 @@ function main(): void {
   }
 
   if (config.personas?.customDir) {
-    const extendDir = path.resolve(configDir, config.personas.extend);
+    const extendDir = path.resolve(configDir, config.personas.customDir);
     if (fs.existsSync(extendDir)) {
       for (const entry of fs.readdirSync(extendDir)) {
         const dir = path.join(extendDir, entry);

package/scripts/dev-sync.ts

@@ -7,7 +7,7 @@
  *
  * Usage:
  *   npm run dev-sync         (after npm run build)
- *   npm run full-build && npm run dev-sync
+ *   npm run dev-build && npm run dev-sync
  */
 
 import fs from "node:fs";

package/scripts/lib/config.ts

@@ -133,5 +133,21 @@ export function loadConfig(configPath: string): AgentBootConfig {
   }
   const raw = fs.readFileSync(configPath, "utf-8");
   const stripped = stripJsoncComments(raw);
-  return JSON.parse(stripped) as AgentBootConfig;
+  const parsed = JSON.parse(stripped);
+
+  // Minimal runtime validation for critical fields
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("Config must be a JSON object");
+  }
+  if (typeof parsed.org !== "string" || parsed.org.length === 0) {
+    throw new Error('Config requires a non-empty "org" field (string)');
+  }
+  if (parsed.personas?.enabled !== undefined && !Array.isArray(parsed.personas.enabled)) {
+    throw new Error('"personas.enabled" must be an array of strings');
+  }
+  if (parsed.sync?.targetDir !== undefined && typeof parsed.sync.targetDir !== "string") {
+    throw new Error('"sync.targetDir" must be a string');
+  }
+
+  return parsed as AgentBootConfig;
 }

package/scripts/validate.ts

@@ -110,7 +110,7 @@ function checkPersonaExistence(config: AgentBootConfig, configDir: string): Chec
 
   const corePersonasDir = path.join(ROOT, "core", "personas");
   const extendDir = config.personas?.customDir
-    ? path.resolve(configDir, config.personas.extend)
+    ? path.resolve(configDir, config.personas.customDir)
     : null;
 
   // Collect all available persona directories.
@@ -183,7 +183,7 @@ function checkTraitReferences(config: AgentBootConfig, configDir: string): Check
   // Scan all persona.config.json files.
   const personaRoots: string[] = [path.join(ROOT, "core", "personas")];
   if (config.personas?.customDir) {
-    const ext = path.resolve(configDir, config.personas.extend);
+    const ext = path.resolve(configDir, config.personas.customDir);
     if (fs.existsSync(ext)) personaRoots.push(ext);
   }
 
@@ -243,7 +243,7 @@ function checkSkillFrontmatter(config: AgentBootConfig, configDir: string): Chec
 
   const personaRoots: string[] = [path.join(ROOT, "core", "personas")];
   if (config.personas?.customDir) {
-    const ext = path.resolve(configDir, config.personas.extend);
+    const ext = path.resolve(configDir, config.personas.customDir);
     if (fs.existsSync(ext)) personaRoots.push(ext);
   }
 
@@ -295,9 +295,14 @@ function checkSkillFrontmatter(config: AgentBootConfig, configDir: string): Chec
 // ---------------------------------------------------------------------------
 
 function buildSecretPatterns(config: AgentBootConfig): RegExp[] {
-  const configPatterns = (config.validation?.secretPatterns ?? []).map(
-    (p) => new RegExp(p)
-  );
+  const configPatterns: RegExp[] = [];
+  for (const p of config.validation?.secretPatterns ?? []) {
+    try {
+      configPatterns.push(new RegExp(p));
+    } catch (e: unknown) {
+      console.error(`  ⚠ Invalid secretPattern regex "${p}": ${e instanceof Error ? e.message : String(e)} — skipping`);
+    }
+  }
   return [...DEFAULT_SECRET_PATTERNS, ...configPatterns];
 }
 
@@ -311,7 +316,7 @@ function checkNoSecrets(config: AgentBootConfig, configDir: string): CheckResult
   ];
 
   if (config.personas?.customDir) {
-    const ext = path.resolve(configDir, config.personas.extend);
+    const ext = path.resolve(configDir, config.personas.customDir);
     if (fs.existsSync(ext)) scanRoots.push(ext);
   }
 

package/.github/ISSUE_TEMPLATE/persona-request.md

@@ -1,62 +0,0 @@
----
-name: Persona request
-about: Propose a new persona for AgentBoot core
-title: "persona: [name here]"
-labels: persona-request
-assignees: ""
----
-
-## Persona name
-
-<!-- What would you call this persona? This becomes the display name in PERSONAS.md. -->
-
-## Invocation
-
-<!-- What slash command would invoke it? e.g., /review-architecture, /audit-deps -->
-
-## Use case
-
-<!-- What problem does this persona solve? Describe the situation: what does a developer
-     want to do, what is painful about doing it today, and how does this persona make
-     it better? Be concrete. -->
-
-## What traits would it compose?
-
-<!-- List the core traits this persona would use, with weights where applicable.
-     Example:
-     - critical-thinking: HIGH
-     - structured-output: true
-     - source-citation: true
-
-     If this persona requires a new trait that does not exist yet, explain what that
-     trait would do and why existing traits are insufficient. -->
-
-## Example invocation
-
-<!-- Show a realistic prompt a developer would give this persona and describe
-     the output they would expect. This is the primary way maintainers evaluate
-     whether the persona is scoped correctly and fills a real gap. -->
-
-**Input:**
-```
-[paste a realistic prompt here]
-```
-
-**Expected output structure:**
-```
-[describe or sketch the expected output here]
-```
-
-## Why core, not a domain extension?
-
-<!-- AgentBoot core contains only generic, domain-agnostic personas that are useful
-     to any engineering team regardless of industry. Explain why this persona fits
-     that bar.
-
-     If it is specific to a compliance regime, a framework, an industry, or an internal
-     standard, it should be a domain extension instead. See docs/extending.md. -->
-
-## Additional context
-
-<!-- Anything else that would help maintainers evaluate this proposal. Links to
-     prior art, related issues, examples from other tools, etc. -->

package/.github/ISSUE_TEMPLATE/quality-feedback.md

@@ -1,67 +0,0 @@
----
-name: Quality feedback
-about: Report bad or unexpected output from a persona
-title: "quality: [persona-id] [brief description]"
-labels: quality-feedback
-assignees: ""
----
-
-## Persona name
-
-<!-- Which persona produced the bad output? e.g., code-reviewer, security-reviewer -->
-
-## What you asked it to do
-
-<!-- Describe what you asked the persona to do. Include the exact prompt or command
-     if you can. If the input is large, include the most relevant portion. -->
-
-**Prompt / invocation:**
-```
-[paste your prompt here]
-```
-
-**Input (if relevant):**
-```
-[paste the code, file, or context you gave it, or a representative excerpt]
-```
-
-## What it actually did
-
-<!-- Describe what the persona produced. If the output was long, include the most
-     relevant portion — the finding that was wrong, the section that was missing,
-     the format that was broken, etc. -->
-
-**Actual output:**
-```
-[paste the relevant portion of the output here]
-```
-
-## What you expected
-
-<!-- Describe what you expected it to do instead. Be specific. "Better output" is
-     not actionable. "The persona should have flagged the missing null check on line 14
-     but instead flagged a style preference" is actionable. -->
-
-## Claude Code version
-
-<!-- Run `claude --version` and paste the output here. -->
-
-## Trait weight or config (if known)
-
-<!-- If you know which trait weight was active for this persona (HIGH / MEDIUM / LOW),
-     include it here. If you modified any agentboot.config.json settings that might
-     be relevant, include those too. -->
-
-## Is this a regression?
-
-<!-- Did this persona work correctly before and then stop working? If so, when did you
-     last see it working correctly, and do you know of any changes (to Claude Code,
-     to AgentBoot, to the persona file) that happened around that time? -->
-
-- [ ] Yes, this worked correctly before
-- [ ] No, this is a first-time deployment and it has never worked correctly
-- [ ] Unknown
-
-## Additional context
-
-<!-- Anything else that would help reproduce or understand the issue. -->

package/.github/workflows/cla.yml

@@ -1,25 +0,0 @@
-name: CLA Assistant
-on:
-  issue_comment:
-    types: [created]
-  pull_request_target:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  actions: write
-  contents: write
-  pull-requests: write
-  statuses: write
-
-jobs:
-  cla:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: contributor-assistant/github-action@v2
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          path-to-signatures: "signatures/cla.json"
-          path-to-document: "https://github.com/agentboot-dev/agentboot/blob/main/CLA.md"
-          branch: "main"
-          allowlist: "saavyone,dependabot[bot]"

package/.github/workflows/validate.yml

@@ -1,49 +0,0 @@
-name: Validate
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-jobs:
-  validate:
-    name: Validate and build
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "18"
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Validate personas and traits
-        run: npm run validate
-        # Exits 1 if any persona is missing required frontmatter fields,
-        # any trait referenced in a persona does not exist, or
-        # agentboot.config.json fails schema validation.
-
-      - name: Build
-        run: npm run build
-        # Resolves all trait compositions and produces compiled output in .build/.
-        # Fails if any persona cannot be compiled (missing trait, malformed SKILL.md, etc.).
-
-      - name: Check PERSONAS.md is up to date
-        run: |
-          # The build step regenerates PERSONAS.md from the compiled persona set.
-          # If the committed PERSONAS.md differs from the regenerated version,
-          # this step fails. Run `npm run build` locally and commit the updated
-          # PERSONAS.md to fix this check.
-          if ! git diff --exit-code PERSONAS.md; then
-            echo ""
-            echo "PERSONAS.md is out of date."
-            echo "Run 'npm run build' locally and commit the updated PERSONAS.md."
-            exit 1
-          fi

package/.idea/agentboot.iml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module type="JAVA_MODULE" version="4">
-  <component name="NewModuleRootManager" inherit-compiler-output="true">
-    <exclude-output />
-    <content url="file://$MODULE_DIR$" />
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-  </component>
-</module>

package/.idea/misc.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectRootManager" version="2">
-    <output url="file://$PROJECT_DIR$/out" />
-  </component>
-</project>

package/.idea/modules.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectModuleManager">
-    <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/agentboot.iml" filepath="$PROJECT_DIR$/.idea/agentboot.iml" />
-    </modules>
-  </component>
-</project>

package/.idea/vcs.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="VcsDirectoryMappings">
-    <mapping directory="" vcs="Git" />
-  </component>
-</project>