agentboot 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# AgentBoot
+
+**Convention over configuration for agentic development teams.**
+
+AgentBoot is a build tool that compiles AI agent personas and distributes them across your organization's repositories. Define once, deploy everywhere. The Spring Boot of AI agent governance.
+
+## The Problem
+
+Every team adopting AI coding tools (Claude Code, GitHub Copilot, Cursor) ends up writing its own CLAUDE.md, its own rules, its own agents — independently, inconsistently, and without governance. There's no standard for distributing agent behavior across repos, no mechanism for enforcing compliance, no way to measure value, and no path for sharing improvements.
+
+AgentBoot solves that. It's the shared foundation everyone was going to build anyway, done once, done well.
+
+## How It Works
+
+AgentBoot is a build tool, not a runtime framework. It produces files and exits.
+
+```
+Source files              Build step              Distributed artifacts
+(traits, personas,   →    agentboot build    →    (.claude/, copilot-
+ instructions, gotchas)                           instructions.md, skills)
+```
+
+1. **Define** personas from composable traits in version-controlled Markdown
+2. **Build** — validate, compile, and lint in one step
+3. **Sync** — distribute compiled artifacts to every registered repo
+
+The output works without AgentBoot installed. Any platform that reads Markdown can consume it.
+
+## Quickstart
+
+```bash
+# Install
+npm install agentboot
+
+# Set up a new personas repo
+npx 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
+```
+
+Your repos now have:
+- Always-on code review and security instructions
+- `/review-code`, `/review-security`, `/gen-tests`, `/gen-testdata` slash commands
+- Agent skills deployable in Claude Code agent mode
+- Platform-native output for Claude Code, GitHub Copilot, and agentskills.io
+
+## What You Get
+
+### Composable traits
+
+Reusable behavioral building blocks. Change a trait once and every persona that uses it updates on the next build.
+
+```
+Security Reviewer  =  critical-thinking + structured-output + source-citation
+Test Generator     =  schema-awareness + structured-output + source-citation
+```
+
+### V1 Personas
+
+| Persona | Invocation | What it does |
+|---|---|---|
+| Code Reviewer | `/review-code` | Finds real bugs, not style nits |
+| Security Reviewer | `/review-security` | Flags vulnerabilities, secrets, risky patterns |
+| Test Generator | `/gen-tests` | Writes tests, audits coverage, finds gaps |
+| Test Data Expert | `/gen-testdata` | Generates realistic synthetic test data |
+
+### Scope hierarchy
+
+Define your org structure once. AgentBoot handles the layers.
+
+```
+Org
+  └── Group (e.g. Platform)
+        ├── Team (e.g. API)       → gets Org + Platform + API personas
+        └── Team (e.g. Frontend)  → gets Org + Platform + Frontend personas
+```
+
+Org-wide rules propagate down. Teams extend without overriding what they shouldn't.
+
+### Multi-platform output
+
+One build produces output for multiple platforms:
+
+| Platform | Output | Location |
+|---|---|---|
+| Claude Code | Agents, skills, rules, traits, CLAUDE.md | `.claude/` |
+| GitHub Copilot | copilot-instructions.md fragments | `.github/` |
+| agentskills.io | Cross-platform SKILL.md | Configurable |
+
+### Build once, deploy everywhere
+
+Your personas repo is the source. Target repos receive the compiled output. One PR to the personas repo rebuilds and syncs to every registered repo.
+
+AgentBoot only writes to `.claude/` and `.github/copilot-instructions.md` — it never touches application code, configuration, or dependencies. Sync PRs are safe to auto-merge.
+
+## Configuration
+
+Everything is driven by `agentboot.config.json`:
+
+```jsonc
+{
+  "org": "your-org",
+  "groups": {
+    "platform": { "teams": ["api", "infra"] },
+    "product": { "teams": ["mobile", "web"] }
+  },
+  "personas": {
+    "enabled": ["code-reviewer", "security-reviewer", "test-generator"],
+    "customDir": "./personas"  // optional: org-specific additions
+  }
+}
+```
+
+## CLI Commands
+
+```bash
+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 setup          # Scaffold a new personas repo
+agentboot add <type>     # Create a new persona, trait, or gotcha
+agentboot doctor         # Diagnose configuration issues
+agentboot status         # Show deployment status
+agentboot lint           # Static analysis for prompt quality
+agentboot uninstall      # Remove AgentBoot from a repo
+agentboot config         # View configuration
+```
+
+Run `agentboot --help` for full usage.
+
+## Extending
+
+AgentBoot ships generic. Your industry has specific requirements. Add domain-specific personas, traits, and gotchas without modifying core:
+
+- **Custom personas** — add to `personas.customDir` path in config
+- **Gotchas** — path-scoped knowledge rules in `core/gotchas/`
+- **Domain layers** — compliance overlays for healthcare, fintech, defense
+
+## Project Status
+
+| Component | Status |
+|---|---|
+| Core traits (6) | Stable |
+| V1 personas (4) | Stable |
+| Build pipeline (validate, compile, sync) | Stable |
+| CLI (12 commands) | Stable |
+| Scope hierarchy + distribution | Stable |
+| Lint + token budgets | Stable |
+| Compliance domain template | Planned |
+| MCP knowledge base | Planned |
+| Cursor / Gemini output | Planned |
+
+## Contributing
+
+AgentBoot grows through community contributions — new personas, domain layers, improved traits, better tooling.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).
+
+---
+
+*Built by [Mike Saavedra](https://github.com/saavyone).*

package/agentboot.config.json

@@ -0,0 +1,207 @@
+{
+  // AgentBoot configuration file.
+  // This is the only file you need to edit to configure AgentBoot for your organization.
+  //
+  // 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.
+
+  // ---------------------------------------------------------------------------
+  // Organization identity
+  // ---------------------------------------------------------------------------
+
+  // The name of your organization. Used in provenance headers written to every
+  // output file, and in PERSONAS.md. Use a slug-friendly value (lowercase, no spaces).
+  "org": "your-org",
+
+  // Human-readable display name. Used in generated docs and headers.
+  "orgDisplayName": "Your Organization",
+
+  // ---------------------------------------------------------------------------
+  // Scope hierarchy: org → group → team
+  //
+  // Personas are scoped and merged top-down:
+  //   - Studio-wide (core/) applies to ALL repos
+  //   - Group-level (groups/{group}/) applies to all teams in that group
+  //   - Team-level (teams/{group}/{team}/) applies to that team only
+  //
+  // On filename conflict, the more specific scope wins.
+  // ---------------------------------------------------------------------------
+
+  "groups": {
+    // Platform group: infrastructure, API, and data engineering teams.
+    "platform": {
+      // Teams within this group. Each becomes a subfolder in dist/teams/platform/.
+      "teams": ["api", "infra", "data"]
+    },
+
+    // Product group: web, mobile, and growth teams.
+    "product": {
+      "teams": ["web", "mobile", "growth"]
+    },
+
+    // Security group: AppSec and compliance.
+    "security": {
+      "teams": ["appsec", "compliance"]
+    }
+  },
+
+  // ---------------------------------------------------------------------------
+  // Personas
+  // ---------------------------------------------------------------------------
+
+  "personas": {
+    // Which personas from core/personas/ to compile and distribute.
+    // Comment out personas your org doesn't want to use.
+    // Valid values: any directory name under core/personas/.
+    "enabled": [
+      "code-reviewer",       // /review-code — PR and code quality reviews
+      "security-reviewer",   // /review-security — vulnerability and risk analysis
+      "test-generator",      // /gen-tests — writes unit and integration tests
+      "test-data-expert"     // /gen-testdata — generates synthetic test data
+    ],
+
+    // Optional: path to an org-specific personas directory.
+    // Personas found here are compiled alongside core personas.
+    // Useful for proprietary personas you don't want in this repo.
+    // Path is relative to this config file.
+    // "customDir": "./personas",
+
+    // Persona output format controls what files are generated per persona.
+    // "skill"   — SKILL.md (agentskills.io-compatible)
+    // "claude"  — CLAUDE.md fragment (Claude Code slash command)
+    // "copilot" — .github/copilot-instructions.md fragment
+    // Default: all three.
+    "outputFormats": ["skill", "claude", "copilot"]
+  },
+
+  // ---------------------------------------------------------------------------
+  // Traits
+  // ---------------------------------------------------------------------------
+
+  "traits": {
+    // Which traits from core/traits/ are active at the org level.
+    // These are available to all personas. Personas select which to use via
+    // their persona.config.json. Setting "enabled" here to a subset restricts
+    // which traits personas can reference.
+    //
+    // Default: all traits in core/traits/ are enabled.
+    // To restrict: list only the traits you want available org-wide.
+    "enabled": [
+      "critical-thinking",    // increases scrutiny, flags assumptions
+      "structured-output",    // enforces machine-parseable output formatting
+      "schema-awareness",     // data modeling, schema contracts, migration safety
+      "source-citation",      // cites code locations and docs in findings
+      "audit-trail",          // decision transparency, reasoning trail
+      "confidence-signaling"  // marks claims with HIGH/MEDIUM/LOW confidence
+    ]
+  },
+
+  // ---------------------------------------------------------------------------
+  // Always-on instructions
+  // ---------------------------------------------------------------------------
+
+  "instructions": {
+    // core/instructions/ contains Markdown fragments that are ALWAYS loaded
+    // in every repo that receives a sync. These are not personas — they are
+    // baseline behavioral guardrails that run before any slash command.
+    //
+    // "enabled": list of filenames (without .md) to distribute.
+    // Default: all files in core/instructions/ are enabled.
+    "enabled": [
+      "baseline.instructions",  // code quality principles, review mindset, scope discipline
+      "security.instructions"   // credential/secret/injection/crypto guardrails
+    ]
+  },
+
+  // ---------------------------------------------------------------------------
+  // Sync configuration
+  // ---------------------------------------------------------------------------
+
+  "sync": {
+    // Path to repos.json — the list of repos that receive compiled output.
+    // repos.json is an array of objects: { path, group?, team? }
+    //   - path: absolute or relative path to the repo root
+    //   - group: optional group name (must match a key in "groups" above)
+    //   - team: optional team name (must be a member of the group's "teams")
+    //
+    // Paths are resolved relative to this config file.
+    "repos": "./repos.json",
+
+    // Where within each target repo to write the compiled files.
+    // Default: ".claude" (writes to {repo}/.claude/)
+    // Also writes copilot-instructions.md to {repo}/.github/ automatically.
+    "targetDir": ".claude",
+
+    // Whether to write a PERSONAS.md inventory to each repo.
+    // Lists all deployed personas, their invocation commands, and descriptions.
+    // Default: true
+    "writePersonasIndex": true,
+
+    // If true, sync will not modify any files. Prints what would change.
+    // Override at runtime with: npm run sync -- --dry-run
+    "dryRun": false
+
+    // PR mode (optional): create a PR instead of writing directly.
+    // Uncomment to enable. Requires `gh` CLI installed.
+    // "pr": {
+    //   "enabled": false,
+    //   "branchPrefix": "agentboot/sync-",
+    //   "titleTemplate": "chore: AgentBoot persona sync"
+    // }
+  },
+
+  // ---------------------------------------------------------------------------
+  // Output / build configuration
+  // ---------------------------------------------------------------------------
+
+  "output": {
+    // Where compiled output is written before syncing to repos.
+    // Structure: dist/{platform}/core/, dist/{platform}/groups/{group}/, etc.
+    // Paths are relative to this config file.
+    "distPath": "./dist",
+
+    // Whether to add provenance headers to compiled output files.
+    // Headers identify the source file and compile timestamp, making it
+    // easy to trace a deployed file back to its origin.
+    // Default: true
+    "provenanceHeaders": true,
+
+    // Whether to fail the build if dist/ already contains files from a
+    // previous build. Forces explicit `rm -rf dist/` before re-building.
+    // Useful in CI to prevent stale artifacts from silently persisting.
+    // Default: false
+    "failOnDirtyDist": false
+
+    // Token budget per persona (estimated tokens). Warns when exceeded.
+    // This is informational — it warns but does not block the build.
+    // Default: 8000
+    // "tokenBudget": { "warnAt": 8000 }
+  },
+
+  // ---------------------------------------------------------------------------
+  // Claude Code-specific output configuration (only applies to "claude" platform).
+  // ---------------------------------------------------------------------------
+
+  // "claude": {
+  //   "hooks": {},
+  //   "permissions": { "allow": [], "deny": [] },
+  //   "mcpServers": {}
+  // },
+
+  // ---------------------------------------------------------------------------
+  // Validation configuration
+  // ---------------------------------------------------------------------------
+
+  "validation": {
+    // Regex patterns that will trigger a validation failure if found in any
+    // trait or persona definition. Extend this list with patterns specific
+    // to your organization (internal hostnames, account IDs, etc.).
+    "secretPatterns": [],
+
+    // If true, validation warnings are treated as errors and block the build.
+    // Default: false (warnings are printed but do not block)
+    "strictMode": false
+  }
+}

package/bin/agentboot.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const cli = join(__dirname, "..", "scripts", "cli.ts");
+
+const result = spawnSync(
+  process.execPath,
+  ["--import", "tsx", cli, ...process.argv.slice(2)],
+  { stdio: "inherit", env: { ...process.env } }
+);
+
+process.exit(result.status ?? 1);

package/core/gotchas/README.md

@@ -0,0 +1,35 @@
+# Gotchas
+
+Gotchas are path-scoped rules that encode battle-tested operational knowledge.
+They activate automatically when developers work on files matching specific paths.
+
+## File Format
+
+Each gotcha is a markdown file in `core/gotchas/` with `paths:` frontmatter:
+
+```markdown
+---
+description: "Brief description of the gotcha"
+paths:
+  - "**/*.lambda.ts"
+  - "functions/**"
+---
+
+# Lambda Deployment Gotchas
+
+- **Cold start penalty:** Lambda cold starts add 1-3s latency...
+```
+
+## Sources for Gotchas
+
+- Post-incident reviews ("what did we learn?")
+- Onboarding notes ("what I wish I knew")
+- Code review comments that repeat
+- Production debugging sessions with non-obvious root causes
+
+## How They Work
+
+During `agentboot build`, gotcha files are compiled into `.claude/rules/` with
+`paths:` frontmatter so Claude Code activates them only for matching files.
+
+During `agentboot sync`, they are distributed to target repos alongside personas.

package/core/instructions/baseline.instructions.md

@@ -0,0 +1,133 @@
+---
+description: AgentBoot baseline — always-on code quality and review guidance
+applyTo: "**"
+---
+
+# AgentBoot Baseline Instructions
+
+These instructions are active in every session. They define the default posture for
+code assistance, review, and generation across the entire codebase.
+
+---
+
+## Code Quality Principles
+
+**Prefer readability over cleverness.** The most important audience for code is the
+next engineer who has to read it, often under pressure. A solution that takes five more
+lines but is immediately understandable is better than a compact one that requires a
+comment explaining what it does.
+
+**Explicit over implicit.** Name what you mean. Avoid magic numbers, implicit defaults,
+and side effects that are not declared in a function's signature or documented in its
+contract. When a function does something surprising, that surprisingness is a defect.
+
+**Small functions with one job.** A function that does multiple unrelated things is
+harder to test, harder to name accurately, and harder to change safely. When a function
+grows past the point where its name accurately describes everything it does, it should
+be split.
+
+**Error paths are first-class.** The happy path is not the only path. Handle errors
+explicitly. Do not let failure modes be an afterthought. When generating code, always
+ask: what happens if this fails?
+
+**Prefer the existing pattern.** When adding code to a codebase that already has an
+established pattern for the problem you are solving, use that pattern — unless you have
+a specific reason not to, and you document that reason. Consistency has compounding
+value. Deviation has compounding cost.
+
+---
+
+## Review Mindset
+
+**Be constructive by default.** The goal of a code review is to ship better software,
+not to demonstrate the reviewer's knowledge. Every finding should help the author
+understand both the problem and the path forward.
+
+**Explain the why, not just the what.** "Change X to Y" is less useful than "Change X
+to Y because Z." The author learns more, the fix is more likely to be correct, and the
+explanation becomes part of the repository's collective knowledge.
+
+**Distinguish must-fix from consider-fixing.** Not all feedback is equal. Be explicit
+about whether a comment represents a blocking concern or a suggestion the author can
+take or leave. Use the severity vocabulary from `core/traits/structured-output.md` when
+precision matters.
+
+**Stay in scope.** If you notice something outside the scope of what you were asked to
+review, note it briefly — once — rather than expanding the review to cover the entire
+codebase. Scope discipline makes reviews faster to complete and easier to act on.
+
+**Assume good intent.** Code that looks wrong was usually written by someone who had
+a reason. Before writing a finding, consider whether there is a plausible explanation
+you are missing. If you cannot think of one, ask — especially for unusual patterns
+that might reflect domain-specific constraints.
+
+---
+
+## Output Format Preferences
+
+**Structured where it adds value.** When reviewing a pull request or analyzing a block
+of code, prefer organized output with clear sections over a stream of prose. Headers,
+bullet points, and severity labels help authors triage quickly.
+
+**Prose where structure would be pedantic.** A one-sentence answer to a one-sentence
+question should be a sentence, not a JSON object. Match the format to the audience and
+the context.
+
+**Lead with the conclusion.** State the finding or recommendation first, then explain
+it. Reviewers who are busy should be able to read the first line of each point and
+know whether to read further.
+
+**Link to the location.** When a finding refers to a specific file and line, say so.
+"The authentication check in `src/auth/middleware.ts` at line 34" is more useful than
+"the authentication check."
+
+---
+
+## Scope Discipline
+
+Do not suggest changes outside the scope of what was requested unless the out-of-scope
+issue is a blocker (a CRITICAL finding in the adjacent code that would make the
+requested change unsafe to ship). When you do flag an out-of-scope issue, make it
+clearly labeled:
+
+> "Out of scope for this review, but worth noting: `src/utils/cache.ts` has an
+> unrelated issue you may want to track separately."
+
+Do not refactor code that was not asked to be refactored. Do not rename variables,
+restructure imports, or reformat files that the author did not touch. Changes generate
+noise in diffs and friction in reviews.
+
+---
+
+## Available Personas
+
+AgentBoot ships these personas. Invoke them as slash commands.
+
+| Persona | Command | When to use |
+|---|---|---|
+| Code Reviewer | `/review-code` | General code quality, architecture, correctness |
+| Security Reviewer | `/review-security` | Vulnerabilities, secrets, auth patterns |
+| Test Generator | `/gen-tests` | Generate unit and integration tests from function signatures |
+| Test Data Expert | `/gen-testdata` | Generate realistic synthetic fixtures and factories |
+
+Each persona has a documented scope. Use the right tool for the job. When in doubt,
+start with `/review-code` and escalate to `/review-security` for any output involving
+authentication, authorization, cryptography, or external data handling.
+
+---
+
+## When to Ask vs. When to Proceed
+
+**Ask before proceeding** when:
+- The correct behavior is ambiguous and the wrong choice would require rework
+- A design decision has significant implications the author may not have considered
+- You need schema, contract, or configuration context that was not provided
+- You are about to make a change that touches multiple files or has blast radius
+
+**Proceed and note** when:
+- The correct path is clear and the stakes of a wrong choice are low
+- The question is answerable from the context already provided
+- Asking would interrupt the author's flow without meaningfully reducing risk
+
+When you proceed and make an assumption, state the assumption. This is the difference
+between acting efficiently and acting opaquely.