Skip to main content

AgentBoot Concepts

This document explains the conceptual foundation of AgentBoot. Read this before reading the configuration reference or the getting-started guide. The concepts here inform every design decision in the system.

What is a trait​

A trait is a reusable behavioral building block for an AI persona. It captures a single aspect of how an agent should think or communicate — a cognitive stance, an output discipline, or an epistemic commitment.

The analogy from software engineering is the DRY principle applied to AI behavior. Before traits, every persona had to independently specify its approach to things like skepticism, output structure, and evidence requirements. In practice, this meant the same concepts were expressed slightly differently in every persona — sometimes well, sometimes poorly, always inconsistently. When you wanted to improve how all your personas handle uncertainty, you had to touch every file.

Traits solve this. You write critical-thinking once. Every persona that needs skeptical review simply composes it with a weight. Improve the trait definition, and all composing personas improve automatically.

A trait is not:

  • A checklist of domain rules. "Verify that GDPR consent is captured" is not a trait; it is a domain-specific requirement that belongs in a domain layer.
  • A persona. A persona has identity, purpose, and scope. A trait has neither — it only modulates behavior.
  • A prompt template. Traits are building blocks, not invocation patterns.

The trait files in core/traits/ are the authoritative definitions. Each one defines the behavior, the anti-patterns to avoid, and the interaction effects with other traits. (A planned trait weight system will add HIGH / MEDIUM / LOW calibration — see below.)

What is a persona​

A persona is a complete, deployable agent: a composition of traits plus a specialized system prompt that defines the agent's identity, operating context, and mandate.

AgentBoot uses the agentskills.io SKILL.md format for persona files. This means every persona is a Markdown file with YAML frontmatter that specifies its ID, version, traits, scope, and output format — followed by the system prompt in prose. The frontmatter is machine-readable (the build and sync tooling uses it); the prose is human-readable and is what the model receives.

The frontmatter trait block is where trait composition happens:

traits:
  critical-thinking: HIGH
  structured-output: true
  source-citation: true
  confidence-signaling: true

Each trait listed here is resolved from the trait definitions at build time and woven into the persona's effective system prompt. This means the persona author writes what makes their persona unique — the domain knowledge, the operating context, the mandate — and inherits the generic behavioral discipline from the trait definitions.

A persona is not:

  • A chat conversation. Personas are always-on agents that operate within a defined scope, not one-off system prompts.
  • An extension of another persona. Personas compose traits; they do not inherit from each other.
  • A configuration file. The SKILL.md prose is the primary artifact. The frontmatter is metadata, not the definition.

The scope hierarchy​

AgentBoot models your organization as a four-level hierarchy:

org
 └── group
       └── team
             └── repo

This mirrors the way real organizations are actually structured — and the way responsibility and governance work in them.

Org level is where universal rules live. Code review standards that apply to every engineer, security guardrails that the CISO requires on all codebases, output discipline that the organization wants from every AI interaction. Org-level configuration is always active in every repo that is registered with the org.

Group level is for horizontal concerns that cross teams but do not apply to the whole org. A platform engineering group might deploy additional infrastructure review personas to all platform teams. A product group might add user-facing copy review personas that the platform group doesn't need.

Team level is where team-specific customization happens. A team that works in a specific framework, owns a specific kind of system, or has team-level standards that differ from the group default can add configuration at this level. Team-level configuration layers on top of group and org, never replacing it.

Repo level is where path-scoped instructions live. Repos can add instructions that activate only when specific file types or directories are touched. A Lambda functions directory might activate additional serverless-specific review guidance. A database migrations directory might activate schema review guardrails.

Precedence: More specific scopes win on optional behaviors; more general scopes win on mandatory behaviors. Rules (always-on instructions) are mandatory by nature — they cannot be disabled at lower scopes. Personas and traits are optional — lower scopes can add personas or disable traits at their scope. (In a future release, lower scopes will be able to adjust trait weights.) To make a specific behavior mandatory, encode it as a rule rather than marking a persona as required.

This hierarchy matters for two reasons. First, it ensures that governance propagates downward automatically — a new team that registers with the org immediately gets all org-level and group-level configuration without any manual setup. Second, it preserves team autonomy on things that are genuinely team-specific.

Claude Code-native output​

AgentBoot's cross-platform output (SKILL.md + CLAUDE.md + copilot-instructions.md) works everywhere but leaves significant Claude Code capabilities on the table. When the target is Claude Code, AgentBoot should generate a Claude Code-native output that uses the platform's full feature surface.

What Claude Code reads natively (no build step required)​

.claude/
├── CLAUDE.md                          # Project instructions (supports @imports)
├── settings.json                      # Hooks, permissions, env vars
├── settings.local.json                # Local overrides (gitignored)
├── agents/
│   └── {name}/CLAUDE.md               # Custom subagents (not SKILL.md)
├── skills/
│   └── {name}/SKILL.md                # Invocable skills (agentskills.io format)
├── rules/
│   └── {topic}.md                     # Path-scoped rules (paths: frontmatter)
└── .mcp.json                          # MCP server configuration

@import: the key Claude Code feature AgentBoot must use​

Claude Code's CLAUDE.md supports @path/to/file imports that expand inline at load time. This changes the compilation model fundamentally:

Cross-platform output (current): Traits are inlined into SKILL.md at build time. Each compiled persona is a standalone file with all trait content baked in. This is necessary for platforms that don't support file inclusion.

Claude Code-native output (new): Traits stay as separate files. The generated CLAUDE.md uses @imports to compose them at load time:

# Code Reviewer

@.claude/traits/critical-thinking.md
@.claude/traits/structured-output.md
@.claude/traits/source-citation.md

You are a code reviewer. Your job is to find bugs, quality issues...

This has three advantages over inlined output:

  1. Maintainability — traits are maintained in one place. Updates propagate to all composing personas automatically without rebuilding.
  2. Live editing — changing a trait file takes effect immediately without rebuilding.
  3. Transparency — developers can read each trait file independently instead of wading through a monolithic system prompt.

The build system generates one self-contained folder per platform under dist/. Each platform folder (e.g., dist/claude/, dist/copilot/, dist/cursor/, dist/skill/, dist/gemini/) contains everything needed for that platform and nothing it doesn't. The Claude Code folder uses @import-based files; the skill folder uses inlined SKILL.md for cross-platform distribution.

Agent frontmatter: much richer than SKILL.md​

Claude Code's .claude/agents/{name}/CLAUDE.md supports frontmatter fields that the generic SKILL.md format does not:

---
name: review-security
description: Deep security review — OWASP, auth, data handling, PHI
model: opus                              # Per-agent model selection
permissionMode: default                  # default | acceptEdits | bypassPermissions
maxTurns: 25                             # Agentic turn limit
disallowedTools: Edit, Write, Agent      # Tool restrictions (read-only reviewer)
tools: Read, Grep, Glob, Bash            # Tool allowlist (alternative to denylist)
skills:                                  # Preload these skills into agent context
  - hipaa-check
  - review-security
mcpServers:                              # Scoped MCP servers
  - compliance-kb
hooks:                                   # Agent-specific hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./hooks/validate-no-phi.sh"
memory: project                          # Persistent memory scope
isolation: worktree                      # Git worktree isolation
---

AgentBoot's persona.config.json should map to these fields. The compile step should generate Claude Code agent CLAUDE.md files with the full native frontmatter — not just the subset that agentskills.io supports.

Rules use paths:, not globs:​

Claude Code's .claude/rules/ files use paths: in frontmatter (not globs:). The An earlier implementation used globs: which was valid at the time but the current Claude Code documentation specifies paths::

---
paths:
  - "src/api/**/*.ts"
  - "**/*.sql"
  - "**/migrations/**"
---

AgentBoot's gotchas rules and path-scoped instructions should generate paths: frontmatter for Claude Code output and globs: where other platforms expect it.

Hooks belong in settings.json​

Claude Code hooks are configured in .claude/settings.json, not in standalone files. AgentBoot's compliance hooks should generate settings.json entries:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/phi-input-scan.sh",
            "timeout": 5000
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/phi-output-scan.sh"
          }
        ]
      }
    ]
  }
}

The available hook events cover the full agent lifecycle: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStart, SubagentStop, Notification, and more. AgentBoot should generate hook configurations for compliance, audit logging, and guardrail enforcement as part of the sync output.

Managed settings = HARD guardrails​

Claude Code's managed settings (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux) are deployed by MDM and cannot be overridden by any user or project setting. This is the native mechanism for HARD guardrails:

/Library/Application Support/ClaudeCode/
├── managed-settings.json    # Non-overridable settings + hooks
├── managed-mcp.json         # Non-overridable MCP servers
└── CLAUDE.md                # Non-overridable instructions

AgentBoot should generate managed settings artifacts for organizations that deploy via MDM. These map directly to the HARD guardrail tier — PHI scanning hooks, credential blocking, audit logging that no developer can disable.

MCP configuration in .mcp.json​

When personas need external tool access (knowledge bases, data detection, domain lookup), AgentBoot should generate .mcp.json entries:

{
  "mcpServers": {
    "compliance-kb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@my-org/compliance-kb-server"]
    }
  }
}

This is synced to target repos alongside the persona files. Agents that reference MCP servers in their frontmatter (mcpServers: [compliance-kb]) will automatically have access.

Skills with context forking​

Claude Code skills support context: fork which delegates the skill to a subagent with an isolated context. This is the native mechanism for reviewer isolation — the reviewer doesn't see the generation conversation:

---
name: review-code
description: Code review against team standards
context: fork
agent: code-reviewer
allowed-tools: Read, Grep, Glob, Bash
---

AgentBoot's review personas should use this pattern for Claude Code output. The skill is the invocation surface (/review-code), and it forks to the agent, which runs in isolation with its own tools and permissions.

Summary: per-platform compilation targets​

AgentBoot's compile step produces one self-contained folder per platform under dist/. Each folder has everything needed for that platform, nothing it doesn't. Scope hierarchy (core → groups → teams) is preserved within each platform folder. Duplication across platforms is intentional — generated files are cattle not pets. Diffing across platforms (e.g., diff dist/claude/ dist/copilot/) shows exactly what's different between distributions.

dist/
├── claude/                      # Self-contained Claude Code distribution
│   ├── core/
│   │   ├── agents/code-reviewer.md
│   │   ├── skills/review-code.md
│   │   ├── traits/critical-thinking.md
│   │   ├── rules/baseline.md
│   │   ├── CLAUDE.md (with @imports)
│   │   └── settings.json (hooks)
│   ├── groups/{group}/
│   └── teams/{group}/{team}/
│
├── copilot/                     # Self-contained Copilot distribution
│   ├── core/
│   │   ├── .github/copilot-instructions.md
│   │   └── .github/prompts/review-code.md
│   ├── groups/...
│   └── teams/...
│
├── cursor/                      # Self-contained Cursor distribution
│   ├── core/
│   │   └── .cursor/rules/*.md
│   ├── groups/...
│   └── teams/...
│
├── skill/                       # Cross-platform SKILL.md (agentskills.io)
│   ├── core/
│   │   ├── code-reviewer/SKILL.md (traits inlined)
│   │   └── PERSONAS.md
│   ├── groups/...
│   └── teams/...
│
└── gemini/                      # Self-contained Gemini CLI distribution
    ├── core/
    │   └── GEMINI.md
    ├── groups/...
    └── teams/...

The sync engine reads from dist/{platform}/ and writes to target repos in platform-native locations. Organizations choose which platform to deploy per repo based on their agent toolchain.

Prompts as code​

AgentBoot treats AI agent behavior as infrastructure: defined in files, stored in version control, reviewed in pull requests, with a complete audit history.

This is the same shift that happened with Infrastructure as Code (Terraform, Pulumi) and Configuration as Code (Kubernetes manifests, GitHub Actions workflows). Before IaC, every environment was a snowflake — you could not reproduce it, you could not review changes to it, and you could not trace the history of decisions. After IaC, every change is a commit.

Prompts as Code applies the same discipline to AI behavior. Before it, every team's CLAUDE.md was written in isolation, improved informally, and never reviewed. When something went wrong with an agent, there was no diff to examine. When best practice evolved, there was no way to propagate the update.

With AgentBoot:

  • Every change to an agent's behavior is a pull request with a description and a review.
  • Traits and personas have version numbers. You can pin a repo to critical-thinking@1.2 and upgrade deliberately.
  • The sync pipeline means the update propagates to all registered repos automatically after the PR merges.
  • The PERSONAS.md registry is generated from the source files — it is always accurate because it cannot drift from the actual definitions.

This is not bureaucracy for its own sake. It is the mechanism by which a small team can govern AI agent behavior across dozens or hundreds of repos without heroic manual effort.

The distribution model​

AgentBoot follows a hub-and-spoke distribution model:

github.com/acme/personas (hub)
  └── agentboot build && agentboot sync
        ├── repo-A/.claude/
        ├── repo-B/.claude/
        └── repo-N/.claude/

Personas hub naming convention​

The hub repo is the org's single source of truth for all agentic personas, traits, and instructions. The recommended naming convention:

PriorityNameWhen to use
DefaultpersonasUse this. The GitHub org already namespaces it (github.com/acme/personas).
Fallbackagent-personasIf personas is already taken (e.g., marketing/UX personas).

Avoid redundant prefixes — github.com/acme/acme-personas repeats the org name. Avoid tool-specific names — acme-agentboot implies a fork of the build tool. Use short names or abbreviations — "ACME Technologies LLC" is just acme.

The agentboot setup wizard checks for existing personas repos and suggests agent-personas as the fallback when there's a collision.

Hub contents​

The hub is a single private repository that your organization owns, created from the AgentBoot template. It contains:

  • Your agentboot.config.json
  • Any org-specific persona extensions (traits, gotchas, instructions)
  • repos.json listing the spoke repos that receive compiled output

The spoke repos are your actual codebases. They receive compiled persona files, always-on instruction fragments, and path-scoped instructions via the sync script. They do not contain the source of truth — only the compiled output. If a team wants to understand why an agent behaves a certain way, they look at the hub, not their own repo.

The build step (npm run build) resolves all trait compositions, validates frontmatter, generates PERSONAS.md, and produces the compiled output. The sync step (npm run sync) pushes the compiled output to each registered repo and opens a PR. Human review of that PR is the governance checkpoint.

This model has a deliberate property: the spokes are passive. They receive governance; they do not produce it. Teams can add repo-level extensions through the hub's team configuration — they do not commit persona files directly to their own repos. This prevents drift and keeps the hub authoritative.

Public repo pattern​

For private repos, sync creates a PR and the compiled .claude/ content is committed normally. But for public repos, committing org-specific personas would leak private content (org traits, internal gotchas, compliance rules) into a public repository.

The public repo pattern solves this:

  1. Compiled output is gitignored in the public repo (.claude/ in .gitignore)
  2. Repo-specific enrichments live in the hub, not in the target repo, under a public-repos/{repo}/ directory
  3. Sync still writes locally — developers get the files, they just aren't committed
  4. New developers run agentboot connect to pull content from the hub on first clone

The prompts-as-code invariant holds: all content is in version control, reviewed, and audited — it's just in the hub's private git instead of the spoke's public git.

Hub structure with public repos:

acme/personas/
├── core/                          # org-wide (all repos)
├── groups/
├── teams/
├── public-repos/                  # only if org has public repos
│   ├── agentboot/
│   │   ├── rules/no-runtime.md
│   │   └── gotchas/jsonc-parser.md
│   └── oss-library/
│       └── gotchas/wasm-compat.md
├── agentboot.config.json
└── repos.json

Scope merge order with public repos: core/ → groups/{g}/ → teams/{g}/{t}/ → public-repos/{repo}/

The public-repos/ scope is the most specific — it wins on filename conflict.

Developer experience is identical. A developer inside a public repo runs the same commands as in a private repo:

agentboot add gotcha "JSONC parser doesn't handle block comments"

AgentBoot detects the repo is public (from repos.json or git remote), confirms the hub is available and writable, and routes the content to public-repos/{repo}/ in the hub. The developer never changes directories or thinks about where the file goes.

If the hub is not available or not writable, the command errors:

ERROR: Hub repo not found or not writable. Your gotcha cannot be persisted.
       Run `agentboot connect` to link your hub, or check permissions.

This is a hard error, not a warning. Content never falls through to the public repo's git. There is no "write it anyway" option.

repos.json marks public repos explicitly:

[
  { "path": "../api", "label": "API", "platform": "claude" },
  { "path": "../agentboot", "label": "AgentBoot", "platform": "claude", "public": true }
]

The trait weight system​

Planned (Phase 2). Trait weights are designed but not yet implemented. Today, traits are included or excluded (boolean). The weight system described below is the target design for a future release.

Several core traits — critical-thinking is the primary example — expose a weight axis: HIGH, MEDIUM, and LOW. This is not a priority system; it is a calibration system.

The same underlying logic applies at every weight. At HIGH, the threshold for surfacing a concern is very low — the persona speaks up about anything it notices. At LOW, the threshold is high — the persona surfaces only things that clearly matter. MEDIUM is the calibrated default for ordinary review.

Why not just write separate personas for "strict" and "lenient" review? Because the behavioral logic is identical; only the threshold differs. Separate personas would duplicate that logic and diverge over time. The weight system keeps the logic in one place (the trait definition) while letting persona authors calibrate the stance.

In practice: security reviewers use critical-thinking: HIGH because the cost of missing a vulnerability is high. A documentation reviewer might use critical-thinking: MEDIUM because it needs to flag genuine problems without making authors feel attacked by minor nit feedback. A first-pass code review persona for learning environments might use critical-thinking: LOW to reduce noise and keep the feedback focused.

The weight does not override the severity floor. At any weight, CRITICAL findings must always surface. critical-thinking: LOW reduces noise; it does not create blind spots.

Gotchas rules​

A gotchas rule is a path-scoped instruction that encodes hard-won operational knowledge — the kind of information that lives in one engineer's head until they leave and the team rediscovers it the hard way. Every organization has these. AgentBoot makes them a first-class concept.

A gotchas file is a Markdown file with paths: frontmatter that limits when the rule activates. When a developer is working on a file that matches the glob pattern, the gotchas content is automatically included in the agent's context. When working on unrelated files, the gotchas are invisible — zero context cost.

---
paths:
  - "db/**"
  - "**/*.sql"
  - "**/migrations/**"
description: "PostgreSQL and RDS gotchas"
---

# PostgreSQL / RDS Gotchas

- **Partitions do NOT inherit `relrowsecurity`.** Enable RLS explicitly on each
  partition.
- **Always verify `relrowsecurity` is ON, not just that policies exist.** Policies
  without enforcement = no protection.
- **UUID PK causes exponential INSERT slowdown.** Drop ALL indexes before bulk load,
  recreate after.

Gotchas rules belong in your domain layer or in team-level extensions — they are organization-specific by nature. AgentBoot core does not ship gotchas because they are inherently tied to your stack and your production incidents.

The pattern is powerful because it captures knowledge at the exact moment it is needed. A developer writing a database migration sees the PostgreSQL gotchas. A developer writing a Lambda handler sees the serverless gotchas. No one has to remember to consult a wiki page or ask the right person.

Compliance hooks​

AgentBoot supports a defense-in-depth model for compliance enforcement, using the hook system provided by the target agent platform.

The model has three layers, in decreasing order of enforcement strength:

  1. Input hook (deterministic): A pre-prompt hook that scans user input before the model sees it. If the hook detects a violation (PHI, credentials, internal URLs), it blocks the request with a non-zero exit code. This is the strongest available technical control.

  2. Instruction-based refusal (advisory): An always-on instruction fragment that tells the model to refuse to process sensitive content. This is prompt-level, not deterministic — the model may not recognize all violations. But it is active in every interaction and costs nothing when not triggered.

  3. Output hook (advisory): A post-response hook that scans the model's output for compliance violations. This layer can log and warn but cannot block — in Claude Code, the Stop hook fires after the response has already rendered to the developer. This is an architectural constraint, not a bug. Document it honestly.

The three layers are complementary. The input hook catches what it can deterministically. The instruction catches what the model can recognize. The output hook provides audit evidence and catches leakage that the instruction missed. No single layer is sufficient alone.

AgentBoot generalizes this from healthcare PHI to any sensitive data pattern — PII, credentials, internal API keys, production URLs, customer data. The hook templates are configurable per organization through the domain layer.

Honest limitation: Not all agent platforms support hooks. Claude Code has full hook support (PreToolUse, PostToolUse, Stop). GitHub Copilot CLI has limited pre-prompt hooks. IDE-based agents generally have no hook mechanism. AgentBoot documents these gaps per platform rather than promising universal enforcement.

ADR governance​

When a persona flags something, and the developer intentionally chose to do it differently, the organization needs a mechanism to say "this is an approved exception." Without this, every guardrail violation becomes a battle, and engineers start ignoring review findings.

AgentBoot supports Architecture Decision Records (ADRs) as the exception governance mechanism. The lifecycle is:

  1. Review — a persona flags a finding during review
  2. Propose — the developer uses /create-adr or /propose-exception to draft a formal exception with rationale
  3. Approve — a designated reviewer (CODEOWNERS, tech lead) reviews the exception PR and approves or rejects it
  4. Commit — the approved exception becomes a permanent record in the ADR index, and the persona learns to accept the deviation for that specific case

ADRs live in the personas repo (not the target repo) because they are governance artifacts, not code artifacts. They are tracked in an adrs/index.json that the build system can reference.

This is complementary to the temporary elevation pattern (where a developer needs a one-time bypass for debugging). ADRs handle permanent, approved deviations. Temporary elevation handles emergency access with audit trail and auto-expiry. A mature governance system needs both.

Numeric trait weights​

Planned (Phase 2). Numeric weights are part of the same future weight system.

The HIGH / MEDIUM / LOW weight system described earlier is the simplified interface. Under the hood, traits that support calibration use a numeric 0.0–1.0 scale that maps to finer-grained behavior:

NumericNamedTypical Use
0.0OFFTrait inactive
0.3LOWLight review — trust the author, flag only clear defects
0.5MEDIUMStandard — question choices, verify claims
0.7HIGHThorough — actively look for hidden issues
1.0MAXAdversarial — assume hostile input, verify everything

In persona.config.json, you can use either form:

{
  "traits": {
    "critical-thinking": "HIGH",
    "creative-suggestion": 0.3
  }
}

The build system resolves named weights to their numeric equivalents. The persona's compiled SKILL.md receives the calibration instructions appropriate for its weight.

The creative-suggestion trait (planned) is the counterpart to critical-thinking. Where critical thinking is the tear-down dial (skepticism), creative suggestion is the build-up dial (proactive improvement suggestions). Security reviewers typically use high critical thinking and low creative suggestion. Code reviewers use moderate levels of both.

Self-improvement reflections​

Personas can optionally write a brief reflection after completing their task. The reflection is saved to .claude/reflections/{persona-name}/{timestamp}.md and captures: what the persona was asked to do, what it found, what it was uncertain about, and what it would do differently next time.

Over time, these reflections accumulate into a dataset that reveals patterns: which findings are most common, which areas have the most uncertainty, which personas are invoked most frequently. A /review-reflections skill can summarize these patterns for human review — identifying trait calibration opportunities, missing rules, or personas that need additional training data.

The self-improvement loop progresses through three phases:

  • Phase A (current): Humans edit persona definitions based on observed behavior
  • Phase B (design target): Reflections + /review-reflections skill
  • Phase C (future): Automated accuracy tracking

This is opt-in — not all agent platforms support file write-back, and not all organizations want the overhead. Enable it in agentboot.config.json when ready.

Reviewer selection​

When a codebase has multiple reviewer personas (code, security, architecture, cost), developers should not have to decide which one to invoke. A reviewer selection config maps file paths and change types to the appropriate reviewer(s):

{
  "rules": [
    { "glob": "**/*.sql", "reviewers": ["code-reviewer", "security-reviewer"] },
    { "glob": "infra/**", "reviewers": ["code-reviewer", "cost-reviewer"] },
    { "glob": "src/auth/**", "reviewers": ["security-reviewer"] }
  ],
  "default": ["code-reviewer"]
}

A /review meta-skill reads this config, inspects the current diff, and routes to the appropriate persona(s). The developer invokes /review and the system decides which specialists are needed. This is the orchestrator pattern from the origin designs — a lightweight routing layer, not a complex agent-to-agent messaging system.

HARD/SOFT guardrail elevation​

Not all guardrails are equal. Some rules must never be bypassed — a PHI scrubber in a healthcare org, a credential scanner in a fintech. Others are important defaults that a senior engineer may need to temporarily override for debugging or experimentation.

AgentBoot distinguishes two tiers:

HARD guardrails are deployed via MDM (managed device management) or marked required: true in the org config. They cannot be elevated, overridden, or disabled at any scope level. The build system enforces this — a team-level config that attempts to disable a HARD guardrail causes a build failure. HARD guardrails are for rules where violation is a compliance incident, not a judgment call.

SOFT guardrails are deployed via the shared repo and can be temporarily elevated. The elevation mechanism:

  1. Developer invokes /elevate {guardrail-name} with a reason
  2. The skill grants a time-bounded bypass (default TTL: 30 minutes)
  3. An audit log entry is created: who elevated, what, why, when, TTL
  4. When the TTL expires, the guardrail automatically re-engages
  5. All actions taken during the elevation window are logged

For larger organizations where automated elevation creates audit risk, AgentBoot also supports a manual escalation model: the developer files a GitHub issue requesting bypass, a designated approver grants or denies it, and the decision is recorded. This is the pattern used in a large enterprise design, where the team size and compliance requirements made automated elevation inappropriate.

A mature governance system needs both HARD/SOFT tiers and both temporary elevation (for debugging) and permanent exceptions (ADRs, described above).

Team champions​

Technical distribution of personas is necessary but not sufficient. Adoption requires a human governance layer — someone on each team who understands the persona system, syncs updates, files quality feedback, and answers questions from teammates.

AgentBoot calls this role the Team Champion. Each team designates one engineer (typically a tech lead or senior IC) who:

  • Runs npm run sync to pull the latest persona updates into team repos
  • Reviews sync PRs before merging (the governance checkpoint)
  • Files GitHub issues against the personas repo when a persona produces poor findings or misses something it should have caught
  • Onboards new team members on how to use the persona system
  • Proposes new gotchas rules, trait calibration changes, or team-level extensions based on their team's experience

The Team Champion is not a full-time role — it is a rotating responsibility that takes minutes per week in steady state. The value is having a named person accountable for the feedback loop between the team and the personas repo.

This pattern was validated in a large engineering organization, where the studio has multiple siloed development teams. Without Team Champions, persona updates would land in team repos without anyone understanding what changed or why. With them, each team has a human bridge between the governance system and the developers who use it daily.

SME discoverability​

When an organization has domain expert personas (compliance SMEs, FHIR experts, architecture advisors), developers need to know they exist before they can use them. A persona that no one knows about delivers no value.

AgentBoot addresses this with a discoverability fragment — a lightweight always-on CLAUDE.md section (~100 tokens) that lists all available personas and how to invoke them:

## Available Personas

| Command | What it does |
|---------|-------------|
| `/review-code` | Code review against team standards |
| `/review-security` | Security-focused review (OWASP, auth, data handling) |
| `/gen-tests` | Generate unit and integration tests |
| `/gen-testdata` | Generate realistic synthetic test data |
| `/sme-compliance` | HIPAA/GDPR/SOC2 compliance questions |

This fragment is auto-generated by the build system from the compiled persona registry. It costs virtually nothing per session (the token count is trivial) but makes personas discoverable without consulting external documentation. A developer who did not know the test data expert existed will see it listed and try it.

The fragment is regenerated on every build, so it stays in sync with the actual persona inventory automatically. Personas that are disabled at a scope level are excluded from that scope's fragment.

MCP-first tool integrations​

When personas need to interact with external systems — knowledge bases, data detection services, domain lookup APIs, test data generators — AgentBoot recommends building these as MCP (Model Context Protocol) servers from day one.

MCP is now GA in Claude Code, VS Code (Copilot), and the CLI. It is also supported by Cursor, Gemini CLI, and other agent platforms. An MCP server built for one agent works identically in all of them — with no modification.

This matters for two reasons:

  1. Investment protection. If your organization builds a knowledge base MCP server for Claude Code, it works in Copilot agent mode and Cursor without rework. If you build it as a Claude Code-specific tool, you rebuild from scratch for every platform.

  2. Clean migration path. An MCP server that reads markdown files today can be swapped for one backed by pgvector or a vector DB tomorrow — the persona definitions don't change. The MCP interface is the abstraction boundary.

The alternative — having personas read files directly via Grep/Glob — is simpler for V1 but creates migration work later. The upfront cost of an MCP wrapper is a thin server; the long-term benefit is zero-change migration and multi-platform compatibility.

For AgentBoot, this means: domain layers that need external data access should define MCP server specifications alongside their persona definitions. The build system can generate MCP configuration stanzas that get synced to target repos.

Structured telemetry​

Persona invocations should emit structured JSON logs from day one — not plain text. The difference matters when you need to answer questions like "which persona is invoked most often?", "what is the average token cost per review?", or "which teams use the security reviewer least?"

AgentBoot specifies a telemetry format based on GELF (Graylog Extended Log Format) / NDJSON with defined fields:

{
  "persona_id": "review-security",
  "model": "claude-sonnet-4-6",
  "scope": "team:platform/api",
  "product": "my-app",
  "session_id": "abc123",
  "input_tokens": 4200,
  "output_tokens": 1800,
  "outcome": "completed",
  "findings": { "CRITICAL": 0, "ERROR": 1, "WARN": 3, "INFO": 2 },
  "duration_ms": 12400,
  "timestamp": "2026-03-19T14:30:00Z"
}

This is emitted by the audit-trail trait (which all review personas should compose). The log is human-queryable with jq from day one — no dashboarding infrastructure required to start getting value.

Telemetry enables:

  • Cost optimization — identify which personas and models cost the most per finding
  • Coverage tracking — ensure security reviews are happening on every repo
  • Quality feedback — correlate finding severity with actual bug rates
  • Adoption metrics — measure which teams are using the system and which aren't

Plain text log lines (PERSONA_START agent=review-code) are an anti-pattern. They cannot be queried, aggregated, or analyzed without parsing. Start structured.

Persona arbitrator​

When multiple reviewer personas examine the same code, they may produce conflicting findings. A security reviewer might flag a pattern as risky while an architecture reviewer considers it the correct approach for the domain. A code reviewer might suggest refactoring something that the cost reviewer flags as an unnecessary token expenditure.

The persona arbitrator is a dedicated persona that resolves these conflicts. It:

  1. Receives the conflicting findings from both personas
  2. Understands the scope hierarchy and which persona has authority in the conflict
  3. Produces a reasoned resolution — either accepting one finding over the other with an explanation, or escalating to human review when the conflict is genuinely ambiguous

The arbitrator is not invoked on every review — only when the /review meta-skill detects that two or more reviewers produced contradictory findings on the same code location. This keeps it lightweight.

Without an arbitrator, conflict resolution falls to the developer, who may not have the context to judge between a security concern and an architecture rationale. The arbitrator provides that context by reading both personas' reasoning and the relevant rules at each scope level.

This is a V2+ feature for organizations running multiple reviewer personas. For V1 with a single code reviewer and security reviewer, conflicts are rare enough that human resolution is sufficient.

Autonomy progression​

Not all personas should operate at the same level of independence. A documentation generator might be fully autonomous (generate and commit without human review), while a security reviewer should always require human sign-off on its findings.

AgentBoot models this as a three-phase autonomy progression, tracked per persona:

PhaseNameBehavior
1AdvisoryPersona produces findings. Human reviews and decides what to act on. No automated actions.
2Auto-approvePersona produces findings and applies low-risk fixes automatically (formatting, import ordering, missing type annotations). High-risk findings still require human review.
3AutonomousPersona operates independently — produces findings, applies fixes, commits changes. Human reviews the output post-hoc.

The current autonomy phase is declared in persona.config.json:

{
  "autonomy": "advisory"
}

Promotion from one phase to the next is a governance decision, not a technical configuration change. It should require evidence: the persona has been operating at Phase 1 for N weeks with an acceptable false-positive rate, so the team approves promotion to Phase 2. This evidence-based progression prevents premature automation and builds trust in the persona system.

Phase 3 (Autonomous) should be reserved for personas with high confidence scores, extensive behavioral test coverage, and explicit team approval. Most organizations will run most personas at Phase 1 indefinitely — and that is fine. Advisory mode is the right default for critical review personas.

Two-channel MDM distribution​

For enterprise organizations with managed device fleets, AgentBoot supports a two-channel distribution model that separates non-negotiable enforcement from team-customizable configuration:

Channel 1: MDM (Managed Device Management) Deploys via JumpCloud, Jamf, Intune, or equivalent to:

  • managed-settings.json — Claude Code settings that cannot be overridden by any user
  • managed-mcp.json — MCP server configurations that are always active

This channel carries HARD guardrails only — the rules where organizational compliance requires zero possibility of developer override. PHI scanning hooks, credential blocking, audit logging requirements. MDM-deployed settings take precedence over all other configuration sources.

Channel 2: Git (Shared Repo) Distributes via the standard hub-and-spoke model:

  • SOFT guardrails, traits, personas, skills
  • Team-level customizations
  • Always-on instructions

This channel carries everything that benefits from version control, code review, and team-level customization.

The two channels serve different trust levels. MDM is "the organization enforces this on your machine." Git is "the team agreed to use this in their repos." Both are necessary for enterprise governance; neither is sufficient alone.

This is an enterprise add-on, not a core requirement. Most organizations start with Channel 2 only and add MDM enforcement when compliance requirements or team size demand it. AgentBoot documents the pattern so organizations that need it know exactly how to implement it.

Proactive human action notifications​

When AgentBoot performs an action that requires human follow-up to take effect, it must tell the user what to do. The user should never have to guess why something isn't working after running a command. This is a core value-add.

Examples:

  • After dev-sync or sync changes .claude/ files: "Restart Claude Code to pick up persona changes"
  • After sync changes files in target repos: list which repos were updated
  • After any config change affecting runtime behavior: tell the user what to restart or reload
  • After publish: "Plugin published. Developers run claude plugin install ..."
  • After uninstall: "Removed N files. Restart Claude Code if a session is active."

Every command that produces side effects ends with a "next steps" line if human action is needed. No silent state changes.

Anti-patterns​

These patterns were tried in AgentBoot's origin implementations and should be avoided. Each was rejected for a specific reason.

Overcommitting on V1 scope​

An early design specified 25 V1 personas and 8 milestones. For a 2-person founding team, this would have taken months and risked V1 never shipping. A revised design scoped V1 to 6 personas and 6 milestones — buildable in weeks.

Rule: Start with 3-6 personas that address your highest-value use cases. Add more after the first ones are deployed, used, and refined. A shipped persona system with 4 personas beats a designed system with 25 that never launches.

Plain text log lines​

An early design used plain text log output (PERSONA_START agent=review-code). This cannot be queried, aggregated, or analyzed without custom parsing. When you need to answer "how many security reviews ran last week?", plain text requires grep and regex. Structured JSON requires jq '.persona_id == "review-security"' | wc -l.

Rule: Use structured telemetry (GELF/NDJSON) from day one. The upfront cost is trivial; the analysis benefit is permanent.

Runtime trait inclusion​

Early designs proposed @include directives that would resolve trait references at runtime — the agent would read and compose trait files during each session. This breaks on platforms that don't support file inclusion (Copilot, Cursor) and wastes tokens re-reading trait files on every invocation.

Rule: Traits are composed at build time. The compiled output is complete and standalone. The agent receives a single file with all trait content already inlined. No runtime resolution.

Vendor-locked persona formats​

An enterprise Copilot deployment explicitly rejected Copilot-proprietary prompt files as the primary persona definition format (decision D-01). Prompt files (*.prompt.md) are VS Code-specific and not recognized by CLI agent mode or other tools. The agentskills.io SKILL.md format was chosen instead because it works across 26+ platforms.

Rule: Use open standards for persona definitions. Vendor-specific formats can coexist as convenience layers (e.g., IDE slash commands) but must not be the authoritative definition.

Forking base personas for customization​

When a product team needs to add domain-specific rules to a reviewer, the temptation is to copy the base persona, modify it, and maintain the fork. This creates divergence — improvements to the base persona never reach the fork, and the fork accumulates product-specific cruft that makes it unmaintainable.

Rule: Use the per-persona extension pattern instead. The base persona reads its extension file at setup time and incorporates the additional rules. The base definition stays unmodified and receives upstream improvements automatically.

Deep inheritance hierarchies​

Object-oriented inheritance applied to personas ("security-reviewer extends code-reviewer extends base-reviewer") creates fragile chains where changes to a parent persona have unpredictable effects on children. This was explicitly rejected as Design Principle #1 in AgentBoot's earliest design: composition over inheritance.

Rule: Personas compose traits. They do not inherit from each other. If two personas share behavior, that behavior belongs in a trait that both compose.

See also: