agentboot 0.1.0 → 0.3.0

package/docs/extending.md

@@ -1,448 +0,0 @@
-# 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:
-
-```json
-{
-  "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`:
-
-```jsonc
-{
-  "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`:
-
-```markdown
-# 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`:
-
-```markdown
----
-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`:
-
-```markdown
-## 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
-
-```jsonc
-{
-  "org": "my-org",
-  "personas": {
-    "enabled": ["code-reviewer", "security-reviewer", "test-generator"],
-    "extend": "./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.extend` 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`:
-
-```markdown
-## 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/`:
-
-```markdown
----
-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`](concepts.md#compliance-hooks) for the three-layer model.
-
-To add compliance hooks to your domain:
-
-1. Create the hook script in `domains/my-domain/hooks/`:
-
-```bash
-#!/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
-```
-
-2. 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`:
-
-```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
-
-3. Create the corresponding always-on instruction in
-   `domains/my-domain/instructions/always-on.md` (the Layer 2 advisory control):
-
-```markdown
-## 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.
-```
-
-4. 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.
-
-5. Document the honest limitations — which platforms enforce deterministically vs.
-   advisory-only. This transparency builds trust with compliance teams.
-
-**Platform support matrix:**
-
-| Layer | Claude Code | Copilot CLI | IDE (VS Code/IntelliJ) |
-|-------|-------------|-------------|------------------------|
-| Input hook (deterministic) | `UserPromptSubmit` | Pre-prompt hook | Not available |
-| Instruction refusal (advisory) | CLAUDE.md | copilot-instructions.md | copilot-instructions.md |
-| Output hook (advisory) | `Stop` | Not available | Not available |
-| Managed settings (HARD) | MDM paths | Not available | Not available |
-
----
-
-*See also:*
-- [`docs/concepts.md`](concepts.md) — the scope hierarchy and trait system explained
-- [`docs/configuration.md`](configuration.md) — complete `agentboot.config.json` reference
-- [`domains/compliance-template/README.md`](../domains/compliance-template/README.md) — worked example domain template