Skip to main content

Extending AgentBoot

AgentBoot ships generic. Your organization almost certainly has requirements that are specific to your industry, your compliance regime, or your internal standards. This document explains how to build a domain layer on top of AgentBoot core — without modifying core, without forking the repository, and without coupling your proprietary requirements to the public codebase.

When to extend vs. when to contribute back​

The rule is simple: if it is specific to your organization, extend. If it would be useful to any team in your vertical, contribute back.

Extend when:

  • The requirement is specific to your org's interpretation of a compliance standard, not the standard itself.
  • The requirement references your internal systems, internal terminology, or your private codebase conventions.
  • The persona or trait would only make sense to people who know your company.

Contribute back when:

  • The trait is generic enough to apply to any team in your industry.
  • The domain template would give other teams in your vertical a useful starting point.
  • The bug fix or improvement applies to the core behavior that everyone uses.

When in doubt, start with an extension in your org personas repo. If it proves useful enough that you find yourself wishing other teams could use it, open a contribution proposal issue.

The domain template structure​

AgentBoot provides a domain template under domains/compliance-template/ that shows the structure of a domain layer. A domain layer is a directory that lives alongside your agentboot.config.json (in your org personas repo) and adds to core without replacing it.

A domain layer has this structure:

domains/
  my-domain/
    README.md                     ← explains the domain, how to configure it
    agentboot.domain.json         ← domain manifest: name, version, traits, personas
    traits/
      my-domain-trait.md          ← domain-specific trait definitions
    personas/
      my-domain-reviewer/
        SKILL.md                  ← domain-specific persona
    instructions/
      always-on.md                ← domain-level always-on instructions
      path-scoped/
        *.domain-file.md          ← path-scoped instructions for sensitive file types

The domain manifest (agentboot.domain.json) registers the domain with the build system:

{
  "name": "my-domain",
  "version": "1.0.0",
  "description": "Domain layer for [your domain here]",
  "traits": ["my-domain-trait"],
  "personas": ["my-domain-reviewer"],
  "requires_core_version": ">=1.0.0"
}

To activate the domain, add it to your agentboot.config.json:

{
  "extend": {
    "domains": ["./domains/my-domain"]
  }
}

How to add a domain-specific trait​

A domain-specific trait follows the exact same format as a core trait (see core/traits/critical-thinking.md for the reference implementation). The difference is that it lives in your domain layer and may reference domain-specific concepts.

Example: adding an audit-logging awareness trait

Suppose your domain requires that all database mutations emit audit log entries. You want a trait that makes any reviewing persona aware of this requirement and flags violations.

Create domains/my-domain/traits/audit-logging-awareness.md:

# Trait: Audit Logging Awareness

**ID:** `audit-logging-awareness`
**Category:** Domain compliance
**Configurable:** No

---

## Overview

This trait makes a persona aware that all database mutations in [your domain] must emit
structured audit log entries. Any reviewing persona that composes this trait will flag
missing or malformed audit log calls.

---

## Behavioral Directives

When reviewing code that performs database mutations:

- Verify that every INSERT, UPDATE, and DELETE is accompanied by an audit log call.
- Check that the audit log call captures: the actor (user/service identity), the
  resource affected (table + primary key), the action type, and the timestamp.
- Flag any mutation that relies on a trigger or middleware for audit logging without
  verifying that the trigger/middleware is in place for the affected table.
- Flag audit log calls that do not capture sufficient context to reconstruct the
  state change.

---

## Anti-Patterns to Avoid

- Do not flag read operations (SELECT). Audit requirements apply to mutations only.
- Do not assume audit logging is handled elsewhere without evidence.
- Do not accept "the framework handles this automatically" without verifying that the
  framework is configured to do so for this specific table.

---

## Interaction with Other Traits

- **`critical-thinking: HIGH`** — at HIGH weight, flag even cases where audit logging
  is present but appears incomplete or inconsistent with other tables.
- **`source-citation`** — every audit finding must cite the specific line where the
  mutation occurs and the specific line (or lack thereof) where audit logging is absent.

Then declare the trait in your domain manifest and compose it into your domain personas.

How to add a domain-specific persona​

A domain persona follows the same SKILL.md format as a core persona. The difference is that its system prompt can reference your domain's specific requirements, terminology, and standards — because it lives in your domain layer, not in core.

Example: adding a compliance reviewer

Create domains/my-domain/personas/compliance-reviewer/SKILL.md:

---
id: compliance-review
name: Compliance Reviewer
version: 1.0.0
traits:
  critical-thinking: HIGH
  structured-output: true
  source-citation: true
  audit-logging-awareness: true
scope: pr
output_format: structured
---

You are the compliance reviewer for [your domain]. Your mandate is to verify that
code changes conform to [your domain]'s compliance requirements before they merge.

[Your domain-specific system prompt here. Describe the compliance context, the
specific requirements the persona should enforce, and the scope of review.]

## Output Schema

...

## What Not To Do

...

How to add path-scoped instructions for sensitive file types​

Path-scoped instructions activate only when the user's working context involves matching file patterns. They are one of the most powerful features in AgentBoot because they let you add domain-specific guidance exactly where it is needed without polluting every interaction.

Create a file in domains/my-domain/instructions/path-scoped/. The filename determines the glob pattern that activates the instruction:

path-scoped/
  *.migration.sql.md    ← activates when the user is working on migration files
  config/secrets*.md   ← activates when working in the secrets config directory
  api/*/handlers/*.md  ← activates when working on API handler files

The content of the file is an instruction fragment that is prepended to the system prompt when the path pattern matches. Keep it focused and specific — path-scoped instructions should add exactly the context that matters for that file type, not general guidance.

Example domains/my-domain/instructions/path-scoped/*.migration.sql.md:

## Database Migration Context

You are working on a database migration file for [your domain].

Migrations in this domain must:
- [List your domain-specific migration requirements here]

Before suggesting any migration change, verify:
- [Your pre-migration verification checklist]

How org-level customization works​

The extend field in agentboot.config.json is the integration point for all customization. It can reference:

  • Local directories (relative to agentboot.config.json): "./personas", "./domains/my-domain"
  • Domain manifests: an array of domain paths, each resolved and merged in order
{
  "org": "my-org",
  "personas": {
    "enabled": ["code-reviewer", "security-reviewer", "test-generator"],
    "customDir": "./personas"
  },
  "extend": {
    "domains": [
      "./domains/my-domain",
      "./domains/my-second-domain"
    ],
    "instructions": "./instructions/org-always-on.md"
  }
}

Precedence rules for extend:

  1. Core traits and personas form the base.
  2. Domain layers are applied in the order listed. Later domains can add to but not remove core traits or personas.
  3. The personas.customDir directory adds org-specific personas on top of domain layers.
  4. Team-level configuration (scoped via group/team in repos.json) layers on top of all of the above for repos in that team.

Nothing in a domain layer can disable a core trait or persona that a higher scope has marked required. Extensions add; they do not subtract. This is the guarantee that org-level governance always propagates downward.

Per-persona extensions​

Domain layers can extend individual personas without modifying the base definition. This is the "extend without modify" pattern — critical for multi-product organizations where each product has specific requirements that should layer on top of the generic persona.

Create an extension file at domains/my-domain/extensions/{persona-name}.md:

## Additional Review Rules (My Domain)

When reviewing code in this domain, also check for:

- All API endpoints must validate the `X-Tenant-ID` header before processing
- Database connections must use the read replica for GET endpoints
- Event payloads must include `correlationId` for distributed tracing

The persona reads its extension file during the Setup phase (before beginning review). Extension rules add to the base persona's rules — they do not replace them. If an extension rule conflicts with a base rule, the extension is ignored and the conflict is logged.

This pattern was validated in a production implementation, where product-level extensions added HIPAA-specific checks to the generic code reviewer, security reviewer, and test data expert without changing any base agent definitions.

How to add gotchas rules​

Gotchas rules are path-scoped instructions that encode battle-tested operational knowledge. They are the single highest-value extension you can add — developers immediately see value when the agent warns them about a pitfall they would have hit.

Create gotchas files in domains/my-domain/instructions/path-scoped/:

---
paths:
  - "**/*.lambda.ts"
  - "functions/**"
description: "Lambda deployment gotchas"
---

# Lambda Gotchas

- **Cold start penalty scales with bundle size.** Keep handler files under 5MB.
  Tree-shake aggressively. Do not import the entire AWS SDK — import only the
  client you need (`@aws-sdk/client-s3`, not `aws-sdk`).
- **Environment variables are NOT encrypted at rest by default.** Use SSM
  Parameter Store or Secrets Manager for anything sensitive. Never put API keys
  in Lambda env vars directly.
- **Timeout default is 3 seconds.** If your handler does any I/O, set timeout
  explicitly. A timed-out Lambda still gets billed for the full duration.
- **Do not use `console.log` with objects in production.** Use structured logging
  (`JSON.stringify` with defined fields) or the Lambda Powertools logger.

Sources for gotchas:

  • Post-incident reviews ("what did we learn?")
  • Onboarding notes ("what I wish I knew")
  • Code review comments that keep repeating the same feedback
  • Production debugging sessions where the root cause was non-obvious

The best gotchas rules are specific, actionable, and explain why — not just what. "Don't do X" is less useful than "Don't do X because Y will happen, and here's how to verify you haven't done it."

How to add compliance hooks​

For organizations with compliance requirements (HIPAA, SOC 2, PCI DSS, GDPR), AgentBoot supports a defense-in-depth hook model. See docs/concepts.md for the three-layer model.

To add compliance hooks to your domain:

  1. Create the hook script in domains/my-domain/hooks/:
#!/bin/bash
# hooks/sensitive-data-scan.sh
# Exit 2 = block request, Exit 0 = allow

INPUT="$1"

# Patterns to detect
if echo "$INPUT" | grep -qE '\b\d{3}-\d{2}-\d{4}\b'; then
  echo '{"error": "SSN pattern detected. Remove before continuing."}' >&2
  exit 2
fi
if echo "$INPUT" | grep -qE '\b(sk|pk)_(live|test)_[A-Za-z0-9]{24,}\b'; then
  echo '{"error": "API key detected. Remove before continuing."}' >&2
  exit 2
fi
exit 0
  1. Create a hook configuration fragment in domains/my-domain/hooks/settings.json that the build system merges into each target repo's .claude/settings.json:
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/sensitive-data-scan.sh",
            "timeout": 5000
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/sensitive-data-output-scan.sh"
          }
        ]
      }
    ]
  }
}

Claude Code supports a comprehensive set of hook events. The most relevant for compliance:

  • UserPromptSubmit — scan input before the model sees it (Layer 1, deterministic)
  • PreToolUse — intercept specific tool calls (e.g., block Bash(rm -rf *))
  • PostToolUse — scan tool output for sensitive data
  • Stop — scan model output (Layer 3, advisory — fires after render)
  • SessionStart — audit logging of session initiation
  1. Create the corresponding always-on instruction in domains/my-domain/instructions/always-on.md (the Layer 2 advisory control):
## Sensitive Data Policy

You must never process, store, or output real customer data, personally identifiable
information, production credentials, or internal API keys. If user input appears to
contain any of these, stop immediately, explain what you detected, and ask the user
to remove it before continuing.
  1. For HARD guardrails (non-overridable), generate managed settings artifacts in domains/my-domain/managed/ for MDM deployment:
managed/
  managed-settings.json    → /Library/Application Support/ClaudeCode/ (macOS)
  managed-mcp.json         → /Library/Application Support/ClaudeCode/ (macOS)
  CLAUDE.md                → /Library/Application Support/ClaudeCode/ (macOS)

Managed settings cannot be overridden by any project or user configuration. This is the native Claude Code mechanism for HARD guardrails.

  1. Document the honest limitations — which platforms enforce deterministically vs. advisory-only. This transparency builds trust with compliance teams.

Platform support matrix:

LayerClaude CodeCopilot CLIIDE (VS Code/IntelliJ)
Input hook (deterministic)UserPromptSubmitPre-prompt hookNot available
Instruction refusal (advisory)CLAUDE.mdcopilot-instructions.mdcopilot-instructions.md
Output hook (advisory)StopNot availableNot available
Managed settings (HARD)MDM pathsNot availableNot available

See also:

  • docs/concepts.md — the scope hierarchy and trait system explained
  • docs/configuration.md — complete agentboot.config.json reference
  • Use agentboot add domain <name> to scaffold a domain template