agentboot 0.1.0 → 0.2.0

package/docs/plans/prd.md

@@ -1,1862 +0,0 @@
-# AgentBoot — Product Requirements Document
-
-**Version:** 1.0.0-draft
-**Date:** 2026-03-19
-**Author:** AgentBoot Team
-**License:** Apache 2.0
-**Status:** Draft — awaiting review
-
----
-
-## Table of Contents
-
-1. [Executive Summary](#1-executive-summary)
-2. [Problem Statement](#2-problem-statement)
-3. [Target Users](#3-target-users)
-4. [Product Vision](#4-product-vision)
-5. [Design Principles](#5-design-principles)
-6. [Feature Requirements](#6-feature-requirements)
-7. [Non-Goals](#7-non-goals)
-8. [Success Metrics](#8-success-metrics)
-9. [Open Questions](#9-open-questions)
-10. [Glossary](#10-glossary)
-
----
-
-## 1. Executive Summary
-
-### What AgentBoot Is
-
-AgentBoot is a build tool and governance framework for AI agent behavior in software
-engineering organizations. It provides convention-over-configuration defaults for
-composing, distributing, and managing AI personas across development teams — so that
-every engineer in an organization gets consistent, high-quality AI agent behavior
-from day one without building it themselves.
-
-### The Problem
-
-Organizations adopting agentic development tools (Claude Code, GitHub Copilot, Cursor,
-Gemini CLI) face a fragmentation crisis. Every team writes its own CLAUDE.md, its own
-rules, its own agents — independently, inconsistently, and without governance. There is
-no standard for distributing agent behavior across repos, no mechanism for enforcing
-compliance guardrails, no way to measure whether AI personas are delivering value, and
-no path for sharing improvements across teams. The result is duplicated effort, drifting
-quality, compliance gaps, and developer frustration.
-
-### The Solution
-
-AgentBoot applies the same discipline to AI agent behavior that Spring Boot applied to
-Java application configuration: sensible defaults, composable building blocks, a scope
-hierarchy that mirrors organizational structure, and a build-then-distribute pipeline
-that propagates governance automatically. Persona definitions are treated as code —
-version-controlled, reviewed in pull requests, tested, linted, and distributed through
-a hub-and-spoke model. The framework is agent-agnostic in content (using open standards
-like agentskills.io) while being Claude Code-first in delivery (leveraging the richest
-extensibility surface available).
-
-### Target User
-
-AgentBoot serves six distinct user segments across the organization — from individual
-developers who consume personas, to platform/DevEx teams who build and distribute them,
-to IT/Security teams who enforce compliance, to engineering leaders who measure ROI.
-Each segment interacts with AgentBoot through a different surface (plugin, CLI, managed
-settings, dashboard) tailored to their role.
-
-### Origin
-
-AgentBoot started with personal and family projects — building AI personas for small
-codebases where the author needed structured review, test generation, and domain
-expertise. The patterns grew organically as the number of projects increased, then
-were adapted for workplace use when it became clear that the same governance gaps
-existed at organizational scale. What began as a personal toolkit evolved into a
-framework when the realization hit: every team adopting agentic development was going
-to build this anyway, and most would build it poorly.
-
----
-
-## 2. Problem Statement
-
-### 2.1 The Fragmentation Problem
-
-Every team that adopts AI coding tools ends up doing the same thing: writing a
-CLAUDE.md, defining some rules, maybe adding a few custom agents. Most of these are
-mediocre. New teams do not know where to start. Teams in the same organization drift
-apart. Nobody shares anything.
-
-Meanwhile, the teams that invest in building it well — composable traits, structured
-reviewers, compliance guardrails, a distribution pipeline — cannot share their work
-because it is buried in proprietary context.
-
-### 2.2 Specific Pain Points
-
-**Scattered, inconsistent agent configuration.** In a typical organization with 20+
-repositories, each repo has its own CLAUDE.md written independently. An audit of such
-organizations typically reveals that 67% or more of repos have some version of the same
-instructions (e.g., "use TypeScript strict mode"), but expressed in 4+ different
-wordings, maintained independently, and never synchronized. When best practice evolves,
-there is no mechanism to propagate the improvement.
-
-**No governance structure.** Agent behavior is not reviewed, versioned, or audited. A
-developer can change a CLAUDE.md with no pull request, no review, and no record of what
-changed or why. When an agent produces a bad result, there is no diff to examine. When a
-compliance rule needs to be added, there is no guarantee it reaches every repo.
-
-**No distribution mechanism.** Organizations lack a way to push agent behavior updates
-to all their repos simultaneously. Each repo is an island. A platform team that writes
-a better code reviewer has no standard path to deploy it across 50 repos without
-manually touching each one.
-
-**No compliance enforcement.** Regulated industries (healthcare, finance, government)
-need non-negotiable guardrails — PHI scanning, credential blocking, audit logging — that
-cannot be disabled by any developer. Current agent platforms offer this capability
-(managed settings, hooks), but there is no framework for generating, testing, and
-deploying these guardrails systematically.
-
-**No metrics or measurement.** Organizations cannot answer basic questions: Which
-personas are used most? What do they cost? What is the false positive rate? Are they
-improving over time? Without measurement, prompt optimization is guesswork, budget
-justification is impossible, and the investment case for agentic development is based
-on anecdote rather than evidence.
-
-**Developer resistance.** Skeptics and hold-outs will not adopt AI tools voluntarily.
-Without a mechanism for zero-friction deployment (managed settings, repo-embedded
-configuration) and a privacy model that builds trust (no prompt surveillance), a
-significant fraction of the engineering organization will never engage.
-
-**No sharing or reuse.** Knowledge that one team gains — a PostgreSQL gotcha, a
-compliance trait, a well-tuned reviewer — stays siloed. There is no marketplace, no
-contribution model, and no standard format that enables sharing across teams or across
-organizations.
-
-**Context bloat.** CLAUDE.md files grow unbounded because no one prunes them. An audit
-of a typical mid-size organization reveals average CLAUDE.md files of 230+ lines, with
-the longest exceeding 800 lines. Most of this content is duplicated across repos, vague
-("follow best practices"), or stale ("TODO: update this section").
-
-**Vendor lock-in anxiety.** Teams hesitate to invest deeply in agent configuration for
-one platform because they worry about being locked in. If the organization switches
-from Claude Code to Copilot (or vice versa), will they have to rebuild everything?
-
-**No onboarding path.** New developers join the organization and face a wall of AI
-tooling they have never used. They type vague prompts, get vague results, conclude
-"AI does not work for me," and abandon the tools. There is no guided path from
-first interaction to productive use.
-
-### 2.3 Why These Problems Persist
-
-These problems persist because they are coordination problems, not technology problems.
-Any single team can solve them for themselves — but the solution does not scale without
-a framework. Writing a good CLAUDE.md is easy. Writing a governance system that keeps
-50 repos consistent, enforces compliance, measures effectiveness, and onboards new
-developers is hard. That is what AgentBoot provides.
-
----
-
-## 3. Target Users
-
-AgentBoot serves six distinct user segments. Each has different needs, different pain
-points, and a different definition of success.
-
-### 3.1 Developer
-
-**Profile:** Individual contributor who writes code daily. May or may not already use
-AI coding tools. Ranges from junior to staff level.
-
-**Needs:**
-- AI personas that work immediately when they clone a repo — zero setup
-- Clear invocation patterns (`/review-code`, `/gen-tests`) that give structured results
-- Privacy: confidence that their conversations, questions, and false starts are private
-- The ability to ask follow-up questions about persona findings
-- Control over their experience: disable tips, choose models, set preferences
-
-**Pain points:**
-- Does not know where to start with AI tools
-- Gets vague results from vague prompts but does not know how to improve
-- Fears being judged for questions asked to AI ("what is a foreign key?")
-- Persona output is confusing — unclear severity levels, no actionable suggestions
-- Multiple tools (Claude Code, Copilot, Cursor) with different configuration mechanisms
-
-**What success looks like:**
-- Clones a repo, types `/review-code`, gets a structured review with actionable findings
-- Trusts that their AI conversations are private (the "IDE vs PR" mental model)
-- Gradually discovers more personas and becomes more effective over weeks
-- Never runs `agentboot` directly — the framework is invisible to them
-
-### 3.2 Platform / DevEx Team
-
-**Profile:** Engineers responsible for developer tooling, productivity, and
-infrastructure. Typically 1-5 people in a mid-size org. May be a dedicated DevEx team
-or a platform engineering team with tooling responsibilities.
-
-**Needs:**
-- A central repository for managing all AI persona definitions
-- A build pipeline that compiles, validates, and distributes personas
-- Multi-platform support (some teams use Claude Code, others use Copilot)
-- Scaffolding tools for creating new personas, traits, domains, and gotchas
-- Discovery tools for finding and consolidating existing agentic content across repos
-- Testing tools that validate persona behavior before deployment
-- A marketplace for sharing and discovering community content
-
-**Pain points:**
-- Every team has written their own CLAUDE.md independently — massive duplication
-- No way to push an update to 50 repos without touching each one
-- No standard format for defining agent behavior
-- Cannot test whether a persona change improves or regresses behavior
-- Teams resist centralization because they fear losing control of their configuration
-
-**What success looks like:**
-- Single `agentboot build && agentboot sync` deploys updates to every registered repo
-- New personas and traits go through PR review with automated validation
-- `agentboot discover` consolidates scattered agentic content into a governed hub
-- Teams can extend (but not break) the org-wide configuration through the scope hierarchy
-- Monthly testing cost under $200 for the entire persona suite
-
-### 3.3 Engineering Leader
-
-**Profile:** VP of Engineering, CTO, Director of Engineering. Responsible for
-engineering investment decisions, team productivity, and technical strategy.
-
-**Needs:**
-- Evidence that AI tool investment is delivering ROI
-- Adoption metrics: how many developers are using the tools, how often
-- Cost metrics: total spend, spend per team, spend per persona
-- Quality metrics: are bug escape rates improving? Is review turnaround faster?
-- Confidence that governance scales as the organization grows
-
-**Pain points:**
-- Cannot justify AI tool budgets without data
-- Does not know whether teams are actually using the tools or ignoring them
-- Worries about compliance exposure in regulated domains
-- Has seen AI initiatives fail because of poor adoption and lack of governance
-
-**What success looks like:**
-- Monthly dashboard showing adoption rates, cost breakdown, and ROI indicators
-- Evidence of improved PR review turnaround, test coverage, and bug escape rates
-- Confidence that compliance guardrails are active on every repo
-- Can demonstrate value to the board with concrete metrics, not anecdotes
-
-### 3.4 IT / Security
-
-**Profile:** IT operations, security engineering, or compliance team. Responsible for
-device management, security policy, and regulatory compliance.
-
-**Needs:**
-- Non-overridable guardrails that no developer can disable (HARD guardrails)
-- Deployment via MDM (Jamf, Intune, JumpCloud) or server-managed settings
-- Audit trail for compliance reporting
-- PHI/PII scanning hooks that run on every interaction
-- Credential blocking and secret detection
-- Zero-touch deployment: developers should not have to opt in to compliance
-
-**Pain points:**
-- No way to enforce AI compliance across the organization
-- Developer-configured AI tools are a compliance blind spot
-- Cannot guarantee that PHI scanning runs on every Claude Code session
-- No audit evidence of AI governance for regulatory reporting
-
-**What success looks like:**
-- Managed settings deployed via MDM — compliance hooks active on every machine
-- HARD guardrails that cannot be overridden at any scope level
-- Audit trail of persona invocations (without individual prompt content)
-- Clean compliance audits with evidence of AI governance
-- Escalation mechanism for genuinely harmful content (flags, not transcripts)
-
-### 3.5 Skeptic / Hold-out
-
-**Profile:** Experienced engineer who is resistant to AI tools. May have philosophical
-objections, may have had bad experiences, or may simply prefer their existing workflow.
-This segment exists in every organization and will never be zero.
-
-**Needs:**
-- Proof of value without disrupting their workflow
-- Opt-in experience with no forced adoption
-- Honest assessment of AI limitations, not hype
-- Assurance that AI usage is not monitored or judged
-
-**Pain points:**
-- Feels pressured to use AI tools they do not trust
-- Fears that AI metrics will be used in performance reviews
-- Finds AI output noisy, inaccurate, or unhelpful
-- Does not want to learn yet another tool
-
-**What success looks like:**
-- Compliance guardrails activate automatically without their action (managed settings)
-- Persona-generated PR reviews appear in their workflow without them invoking anything
-- Over time, sees the value in structured AI review and begins invoking personas manually
-- Is never shamed, ranked, or penalized for low AI usage
-- Can cleanly remove AgentBoot with one command if they decide it is not for them
-
-### 3.6 Non-Engineer
-
-**Profile:** Product manager, designer, compliance officer, marketing professional.
-Does not use the terminal. Needs AI assistance for structured tasks (document review,
-compliance checking, content analysis).
-
-**Needs:**
-- GUI-first experience with structured forms, not slash commands
-- Role-specific personas (compliance review, document analysis, content checking)
-- Same privacy protections as engineers
-
-**Pain points:**
-- Terminal-based tools are inaccessible
-- Does not understand "install a plugin" or "run a command"
-- AI tools feel designed exclusively for engineers
-
-**What success looks like:**
-- Opens a desktop application (Cowork), sees role-specific tools in a sidebar
-- Fills out a form, gets structured output — never touches a terminal
-- Same personas, same quality, same governance as the engineering tools
-
----
-
-## 4. Product Vision
-
-### 4.1 Positioning
-
-AgentBoot is the Spring Boot of AI agent governance: an opinionated, drop-in foundation
-that gives engineering organizations consistent AI agent behavior from day one without
-building it themselves.
-
-The analogy is precise:
-
-| Spring Boot | AgentBoot |
-|---|---|
-| Convention over configuration for Java apps | Convention over configuration for AI agent behavior |
-| Sensible defaults, override what is different | Sensible persona defaults, extend for your domain |
-| Starter dependencies compose features | Traits compose behavioral building blocks |
-| Auto-configuration detects and configures | `agentboot setup` detects role, tools, org and configures |
-| Spring Boot Actuator for observability | Structured telemetry and `/insights` for measurement |
-| Spring Initializr for scaffolding | `agentboot setup` and `agentboot add` for scaffolding |
-
-### 4.2 The Build Tool Mental Model
-
-AgentBoot is a build tool, not a runtime framework. It produces artifacts that are
-consumed by AI agent platforms. The pipeline is: validate, compile, distribute.
-
-```
-Source files              Build step              Distributed artifacts
-(traits, personas,   →    agentboot build    →    (.claude/, copilot-
- instructions, gotchas)                           instructions.md, plugins)
-```
-
-This distinction matters because:
-- AgentBoot has zero runtime footprint — it produces files and exits
-- The distributed artifacts work without AgentBoot installed
-- Any platform that reads Markdown, YAML, or JSON can consume the output
-- The build step is where governance happens (validation, composition, linting)
-- Teams can inspect, understand, and modify the distributed output
-
-### 4.3 Where AgentBoot Is Going
-
-**Phase 1 (Foundation):** Build system, CLI, core personas, hub-and-spoke distribution,
-scope hierarchy. The minimum viable governance system.
-
-**Phase 2 (Native Distribution):** Claude Code plugin packaging, private marketplace,
-managed settings generation. Native delivery through the platform's own mechanisms.
-
-**Phase 3 (Cross-Platform and Enterprise):** MCP server for multi-agent organizations,
-cross-platform output generation (Copilot, Cursor, Gemini), structured knowledge store.
-
-**Phase 4 (Ecosystem):** Public marketplace, community contributions, domain layers for
-regulated industries, SuperClaude partnership for trait format standardization.
-
-### 4.4 The Long-Term Vision
-
-AgentBoot becomes the place where AI agent governance content lives — the "npm of AI
-personas." Not because of marketing, but because that is where the traits, personas,
-gotchas, and domain layers are. Organizations that need governance adopt AgentBoot
-because it is the standard. Contributors share their knowledge because it reaches the
-most people. The ecosystem grows because useful content attracts users who become
-contributors who add more useful content.
-
----
-
-## 5. Design Principles
-
-Ordered by priority. These principles inform every design decision and resolve
-ambiguity when requirements conflict.
-
-### 5.1 Composition Over Inheritance (Priority: Highest)
-
-Personas compose traits. They do not inherit from each other. If two personas share
-behavior, that behavior belongs in a trait that both compose.
-
-This is the foundational design constraint, established as Design Principle #1 from
-the earliest AgentBoot designs. Object-oriented inheritance applied to personas
-("security-reviewer extends code-reviewer extends base-reviewer") creates fragile
-chains where changes to a parent have unpredictable effects on children. Composition
-is flat, predictable, and inspectable.
-
-**Implication:** There is no persona hierarchy. There is no `extends` keyword. Traits
-are the unit of reuse. Personas are the unit of deployment.
-
-### 5.2 Scoped Conventions (Priority: Highest)
-
-AgentBoot models organizations as a four-level hierarchy: Org, Group, Team, Repo.
-More specific scopes layer on top of general ones. For optional behaviors, team
-overrides group overrides core. For mandatory behaviors, inheritance is top-down
-(org wins).
-
-This hierarchy mirrors how real organizations structure responsibility and governance.
-It ensures that governance propagates downward automatically (a new team gets all
-org-level and group-level configuration without manual setup) while preserving team
-autonomy on things that are genuinely team-specific.
-
-**Implication:** The scope hierarchy is not optional. Every piece of configuration has
-a scope. Conflict resolution is deterministic: mandatory rules cascade down, optional
-rules override up.
-
-### 5.3 Prompts as Code (Priority: High)
-
-AI agent behavior is 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).
-
-Every change to an agent's behavior is a pull request with a description and a review.
-Traits and personas have version numbers. The sync pipeline propagates updates
-automatically after the PR merges.
-
-**Implication:** All persona definitions live in a Git repository. All changes go
-through PR review. The build system enforces validation rules that block invalid
-configurations from merging.
-
-### 5.4 Privacy First (Priority: High)
-
-AgentBoot will never collect, transmit, or surface raw developer prompts to
-organizational dashboards, managers, or analytics pipelines. This is a design
-invariant, not a configuration option.
-
-The organization gets aggregate patterns, not transcripts. High rephrase rates are
-framed as persona quality problems, not developer intelligence problems. The
-`rawPrompts` configuration section contains three `false` fields that cannot be set
-to `true`. They exist to make the design intent explicit.
-
-AgentBoot is honest about the boundaries: this commitment covers what AgentBoot does.
-It does not and cannot override what the API provider or the organization does
-independently through other channels (Compliance API, network monitoring, data exports).
-
-**Implication:** No telemetry field contains prompt text. No dashboard shows individual
-developer activity. No feature ranks, shames, gamifies, or surveys developer AI usage.
-The escalation exception (genuinely harmful content) flags the category, never the
-transcript.
-
-### 5.5 Agent-Agnostic Content, Claude Code-First Delivery (Priority: High)
-
-Content (traits, personas, gotchas, instructions) is written in agent-agnostic formats
-(Markdown, agentskills.io SKILL.md). Delivery (plugins, managed settings, hooks,
-native agent frontmatter) leverages Claude Code's extensibility surface to the fullest.
-
-If a feature "just does not work without Claude Code" — that is acceptable. Non-CC
-platforms get the content (SKILL.md, instruction files, MCP servers); CC platforms get
-the full governance surface (hooks, managed settings, subagent isolation, agent memory).
-AgentBoot documents this gap honestly rather than pretending all agents are equal.
-
-**Implication:** Marketplace content is stored in agent-agnostic format. The build
-system produces platform-specific output. CC-specific enhancements go in metadata
-(persona.config.json), not in the content itself.
-
-### 5.6 Easy Exit Builds Trust for Easy Entry (Priority: High)
-
-`agentboot uninstall` is a first-class command, not an afterthought. It tracks what it
-manages (via a manifest), archives what it replaces, and restores what was there before.
-An organization that knows they can cleanly remove the tool in one command is more
-willing to try it.
-
-No vendor lock-in, no orphaned files, no scavenger hunt. The uninstall command removes
-exactly the files AgentBoot manages and preserves everything the team authored locally.
-
-**Implication:** Every synced file is tracked in `.agentboot-manifest.json`. Original
-files are archived during setup. The uninstall path is tested in integration tests.
-
-### 5.7 Convention Over Configuration (Priority: Medium-High)
-
-AgentBoot ships with sensible defaults for everything. Organizations configure what is
-different about their organization, not everything from scratch. A single config file
-(`agentboot.config.json`) and a `build && sync` command are sufficient to get started.
-
-**Implication:** Core personas and traits ship ready to deploy. The setup wizard
-determines the right configuration based on role detection, not manual specification.
-The "happy path" requires minimal configuration.
-
-### 5.8 Build-Time Composition, Not Runtime Resolution (Priority: Medium)
-
-Traits are composed into personas at build time. The compiled output is complete and
-standalone. Agents receive a single file (or a set of files with @imports for CC-native
-output) with all trait content already resolved. No runtime resolution, no dynamic
-includes on platforms that do not support them.
-
-The exception is Claude Code-native output, where `@import` in CLAUDE.md composes
-trait files at load time — but these files are pre-generated by the build system,
-not resolved dynamically.
-
-**Implication:** The cross-platform SKILL.md output is fully self-contained. The
-CC-native output uses @imports but all imported files are generated and present.
-No runtime API calls to resolve trait definitions.
-
-### 5.9 Honest Limitations (Priority: Medium)
-
-AgentBoot documents what works, what does not, and what the actual limitations are on
-each platform. Compliance hooks exist on Claude Code but not on Copilot or Cursor.
-Managed settings are CC-only. Subagent isolation requires `context: fork`, which is
-CC-only. These gaps are documented per platform rather than hidden.
-
-**Implication:** Per-platform feature matrices are part of the documentation.
-Non-CC delivery is labeled "best-effort." No feature is marketed as cross-platform
-unless it actually works cross-platform.
-
-### 5.10 Hub-and-Spoke Distribution (Priority: Medium)
-
-One central repository (the hub) contains the source of truth for all persona
-definitions. Target repositories (spokes) receive compiled artifacts via the sync
-pipeline. Spokes are passive — they receive governance, they do not produce it.
-Teams customize through the hub's scope hierarchy, not by committing persona files
-directly to their repos.
-
-**Implication:** The sync pipeline is one-way (hub to spoke). Local modifications
-to synced files are detected and warned about. The hub repository is the authoritative
-source for governance decisions.
-
----
-
-## 6. Feature Requirements
-
-### 6.1 Build System
-
-#### 6.1.1 Validation (`agentboot validate`)
-
-Pre-build validation that catches configuration errors before compilation. Runs five
-checks: persona existence (every persona referenced in config has a directory),
-trait reference resolution (every trait referenced by a persona exists), SKILL.md
-frontmatter validity (required fields present, values in allowed ranges), PERSONAS.md
-synchronization (generated registry matches actual persona definitions), and secret
-scanning (no credentials, API keys, or internal URLs in persona content).
-
-**Who it serves:** Platform teams and CI pipelines. Validation runs automatically as
-the first stage of the build pipeline and as a standalone CI gate on every PR to the
-personas repository.
-
-**Why it matters:** Without validation, invalid configurations silently produce broken
-output. A missing trait reference could result in an empty persona. A credential
-accidentally included in a trait file could be synced to every repo in the
-organization. Validation catches these errors before they propagate.
-
-#### 6.1.2 Compilation (`agentboot build`)
-
-The core build step. Loads `agentboot.config.json`, resolves trait references from
-each persona's `persona.config.json`, and produces two distinct compilation targets:
-cross-platform output and Claude Code-native output.
-
-**Cross-platform output** produces standalone SKILL.md files (agentskills.io format
-with traits inlined), copilot-instructions.md, and generic CLAUDE.md. This output
-works on any platform that reads Markdown instruction files.
-
-**Claude Code-native output** produces the full `.claude/` directory structure:
-agents with rich frontmatter (model, permissionMode, maxTurns, disallowedTools,
-mcpServers, hooks, memory, isolation), skills with `context: fork`, rules with
-`paths:` frontmatter, separate trait files for `@import` composition, a CLAUDE.md
-using `@imports`, settings.json with hook entries, and `.mcp.json` with server
-configurations.
-
-**Who it serves:** Platform teams running the build pipeline. CI systems that produce
-artifacts on merge.
-
-**Why it matters:** The two-target compilation is what makes AgentBoot both
-cross-platform and CC-optimized. Organizations choose which format to deploy per repo.
-Claude Code users get the full governance surface (hooks, managed settings, isolation).
-Non-CC users get the content (personas, instructions, rules) without the enforcement
-mechanisms.
-
-#### 6.1.3 Sync (`agentboot sync`)
-
-Distributes compiled output to target repositories. Reads `repos.json`, which lists
-each target repo with its platform and team assignment. Merges scopes according to the
-four-level hierarchy (org, group, team, repo), with team-level configuration layering
-on top of group and org configuration. Writes the appropriate output format based on
-each repo's declared platform.
-
-Sync supports multiple modes: local filesystem writes, GitHub API (creates PRs via
-the API), and GitLab API (creates merge requests). A dry-run mode shows what would
-change without writing anything. Each sync writes an `.agentboot-manifest.json`
-tracking every managed file and its content hash, enabling clean uninstall and
-drift detection.
-
-**Who it serves:** Platform teams and CI pipelines. In steady state, sync runs
-automatically on merge to the personas repo's main branch.
-
-**Why it matters:** Sync is the mechanism that turns the hub-and-spoke model from
-theory into practice. Without it, every repo update is manual. With it, a single
-PR to the personas repo propagates governance to every registered repo
-automatically — with human review at the PR merge point as the governance checkpoint.
-
-#### 6.1.4 Scope Merging
-
-The scope merge algorithm implements the four-level hierarchy. For each target repo,
-the sync step composes: org-level configuration (always active), group-level
-configuration (based on the repo's group assignment), team-level configuration (based
-on the repo's team assignment), and repo-level overrides.
-
-Optional behaviors follow "most specific wins" — a team can override a group default.
-Mandatory behaviors follow "most general wins" — an org can mark traits or personas
-as required, and no lower scope can disable them. A team-level configuration that
-attempts to disable a mandatory org-level guardrail causes a build failure.
-
-**Who it serves:** Organizations with multiple groups and teams that need both
-centralized governance and team-level customization.
-
-**Why it matters:** Without scope merging, organizations face a false choice between
-centralized control (which frustrates teams) and team autonomy (which breaks
-governance). The scope hierarchy provides both: mandatory rules propagate down,
-optional customization layers up.
-
-### 6.2 CLI
-
-#### 6.2.1 Interactive Setup Wizard (`agentboot setup`)
-
-The primary entry point for all users. An interactive wizard that asks a series of
-questions to determine the user's role (developer, platform team, IT/security,
-exploring), their AI tools (Claude Code, Copilot, Cursor, mixed), their organization
-context (existing AgentBoot setup, no setup, solo), team size, compliance requirements,
-and device management infrastructure.
-
-Based on the answers, the wizard executes the appropriate setup: Quick Start (solo
-developer — deploys files directly to the current repo), Standard Setup (platform
-team — scaffolds the org personas repo with config, personas, and traits), or
-Enterprise Setup (IT — generates managed settings for MDM deployment plus marketplace
-template).
-
-The wizard auto-detects as much as possible before asking: git remote for org name,
-`.claude/` in the current repo for existing setup, managed settings on disk for
-existing governance, installed Claude Code version, and platform tools in PATH.
-
-**Who it serves:** Every first-time user, regardless of role.
-
-**Why it matters:** The setup wizard is the difference between "read the docs for
-30 minutes then configure" and "answer 3-7 questions and you are running." Progressive
-disclosure ensures that solo developers are not overwhelmed with enterprise options,
-while platform teams get the full scaffolding they need.
-
-#### 6.2.2 Discovery (`agentboot discover`)
-
-Scans repositories, machines, and configurations for existing AI agent content —
-CLAUDE.md files, Copilot instructions, Cursor rules, MCP servers, hooks, skills,
-agents, and anything else that represents agentic maturity the organization already
-has. Supports scanning a single repo, a directory of repos, all repos in a GitHub
-organization (via API), local machine configuration, and managed settings paths.
-
-Discovery produces five actions: a detailed inventory report (Markdown), a classify-
-and-ingest pipeline (decompose existing content into traits, personas, gotchas, and
-instructions), an overlap analysis (find near-duplicate content across repos), a
-migration plan (what becomes what, with estimated reduction), and a config export
-(generate `agentboot.config.json` from the discovered repo structure).
-
-Discovery and migration are non-destructive. They never modify, move, or delete
-existing files. They create new files in the AgentBoot personas repo. The originals
-stay untouched. The organization reviews, tests, and deploys at their pace via PR.
-
-**Who it serves:** Platform teams evaluating AgentBoot for an organization that already
-has scattered agentic content.
-
-**Why it matters:** Most organizations adopting AgentBoot are not starting from zero.
-They have 20+ repos with independent CLAUDE.md files, custom agents, and instruction
-files. Without discovery, consolidation is a manual audit. With it, AgentBoot finds
-everything, identifies duplication, and produces a migration plan that typically
-achieves 80-85% line reduction through deduplication and centralization.
-
-#### 6.2.3 Build and Distribution Commands
-
-`agentboot build` compiles personas with options for specific output formats
-(claude-code, copilot, cross-platform, plugin, all) and a validate-only dry run.
-`agentboot sync` distributes to repos with support for local filesystem, GitHub API,
-and GitLab API modes, plus single-repo targeting and dry-run. `agentboot export`
-generates distributable artifacts (plugin directory, marketplace scaffold, managed
-settings for MDM, reusable GitHub Actions workflow, MCP server package).
-`agentboot publish` pushes the plugin to a configured marketplace with version bumping.
-
-**Who it serves:** Platform teams managing the build and distribution pipeline.
-
-**Why it matters:** These commands form the core build pipeline. They are designed to
-work in both interactive (developer workstation) and non-interactive (CI/CD) modes,
-with every command supporting `--non-interactive` flags.
-
-#### 6.2.4 Scaffolding (`agentboot add`)
-
-Scaffolds new components: personas, traits, domains, gotchas, hooks, and repo
-registrations. Each scaffold creates the appropriate directory structure with template
-files that follow the format standards.
-
-The `add prompt` subcommand ingests raw prompt text from multiple sources (inline text,
-file, clipboard, URL, batch decomposition of an existing CLAUDE.md). It classifies the
-content (trait, gotcha, persona rule, or always-on instruction), formats it to the
-appropriate standard, and saves it to the correct location. A dry-run mode previews
-without writing.
-
-**Who it serves:** Platform teams creating new content and anyone contributing to the
-personas repository.
-
-**Why it matters:** Scaffolding reduces the barrier to adding new governance content.
-The `add prompt` command is particularly valuable during migration: it takes the
-scattered, unstructured content found by `discover` and transforms it into properly
-formatted AgentBoot content.
-
-#### 6.2.5 Diagnostics (`agentboot doctor`, `agentboot status`)
-
-`agentboot doctor` checks environment health: Claude Code version, Node.js version,
-git version, configuration validity, persona completeness, sync status, plugin state,
-and managed settings status. Every problem includes a fix command.
-
-`agentboot doctor --diagnose` runs a layered isolation test to pinpoint whether a
-problem is in AgentBoot core, org config, org traits, org personas, or org extensions.
-Each layer adds one piece of the stack; the layer where it breaks is the layer that
-has the bug.
-
-`agentboot status` provides a deployment dashboard: enabled personas and traits, repo
-registration status with platform and sync version, plugin state, and managed settings
-status.
-
-**Who it serves:** Anyone troubleshooting issues. Platform teams monitoring deployment.
-
-**Why it matters:** "Is this my bug or AgentBoot's bug?" is a question every
-organization will ask. The diagnostic tools answer it systematically rather than
-requiring manual investigation.
-
-#### 6.2.6 Linting (`agentboot lint`)
-
-Static analysis of persona definitions. Checks for vague language ("be thorough",
-"try to"), token budget violations, credentials in prompt text, conflicting
-instructions across traits, unused traits, and security issues. Configurable severity
-thresholds (error, warning, info).
-
-Token budget analysis calculates per-persona context cost and flags personas that
-exceed configurable limits. This prevents context bloat — the gradual growth of prompt
-content that wastes tokens without adding value.
-
-**Who it serves:** Platform teams authoring personas, and CI pipelines gating merges.
-
-**Why it matters:** Prompt quality is the product. A governance framework that produces
-vague, bloated, or conflicting prompts is actively wasting money and developer trust.
-Linting enforces a minimum quality bar automatically.
-
-#### 6.2.7 Testing (`agentboot test`)
-
-Multi-type test runner supporting deterministic tests (free, every commit),
-behavioral tests (LLM invocation, ~$0.50/test), snapshot regression tests (compare
-output across versions), and LLM-as-judge evaluation (Opus evaluates quality on
-multiple dimensions). Supports cost caps, per-persona targeting, CI mode with exit
-codes and JSON output, and flake tolerance (2-of-3 pass).
-
-Full details in section 6.7 (Testing).
-
-**Who it serves:** Platform teams validating persona behavior before deployment.
-
-**Why it matters:** AI persona output is non-deterministic. Traditional testing
-approaches (exact output matching) do not work. The multi-layer test pyramid provides
-confidence at each level: schema tests are free and fast, behavioral tests verify
-that personas catch known bugs, snapshot tests detect regressions, and LLM-as-judge
-evaluates qualitative dimensions that pattern matching cannot assess.
-
-#### 6.2.8 Additional Commands
-
-`agentboot connect` provides developer self-service for connecting to an organization's
-marketplace (CLI equivalent of `/agentboot:connect`). `agentboot upgrade` pulls the
-latest AgentBoot core into an organization's personas repo. `agentboot validate` is the
-CI-friendly validation-only command with strict mode. `agentboot search` queries the
-marketplace for traits, gotchas, personas, and domains. `agentboot metrics` reads
-telemetry and reports per-persona, per-team, and per-period statistics.
-`agentboot cost-estimate` projects per-persona monthly cost across the organization.
-`agentboot review` generates guided human review sessions with curated samples.
-`agentboot issue` streamlines bug reporting with auto-attached diagnostics and
-privacy-safe redaction. `agentboot uninstall` provides clean removal with manifest
-tracking, original file restoration, and mixed content handling.
-
-**Who it serves:** Various segments depending on the command.
-
-**Why it matters:** Each command addresses a specific workflow gap. Together, they form
-a complete CLI that covers the full lifecycle from setup through daily use to removal.
-
-### 6.3 Persona System
-
-#### 6.3.1 Traits
-
-Reusable behavioral building blocks. Each trait captures a single aspect of how an
-agent should think or communicate — a cognitive stance, an output discipline, or an
-epistemic commitment. Traits support weight configurations (HIGH / MEDIUM / LOW,
-mapping to a 0.0-1.0 numeric scale) and are composed at build time.
-
-Core traits include: critical-thinking (skepticism calibration), structured-output
-(consistent output formatting), source-citation (evidence requirements), confidence-
-signaling (uncertainty communication), audit-trail (compliance logging), and
-schema-awareness (data structure understanding). Additional traits include
-creative-suggestion (proactive improvement ideas) and cost-awareness (resource
-efficiency).
-
-The trait weight system is a calibration system, not a priority system. At HIGH, the
-threshold for surfacing a concern is very low. At LOW, the threshold is high. The
-weight does not override the severity floor — at any weight, CRITICAL findings always
-surface. The numeric scale (0.0-1.0) provides finer calibration for advanced use cases
-while the named weights (HIGH/MEDIUM/LOW) serve as the simplified interface.
-
-**Who it serves:** Platform teams authoring personas, and the marketplace community
-sharing behavioral building blocks.
-
-**Why it matters:** Before traits, every persona independently specified 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.
-Traits solve this: write the behavior once, compose it everywhere, improve it in one
-place.
-
-#### 6.3.2 Personas
-
-Complete, deployable agents composed from traits plus a specialized system prompt that
-defines identity, operating context, and mandate. Use the agentskills.io SKILL.md
-format (Markdown with YAML frontmatter). The frontmatter specifies ID, version, traits,
-scope, and output format. The prose is the system prompt.
-
-Core V1 personas: code-reviewer (code review against team standards), security-
-reviewer (vulnerability analysis, OWASP, auth, data handling), test-generator
-(unit and integration test generation from function signatures), and test-data-expert
-(realistic synthetic test data generation).
-
-Each persona has a `persona.config.json` that specifies build metadata: which traits
-to compose, at what weight, the target model, permission mode, tool restrictions,
-MCP servers, hooks, and autonomy level.
-
-**Who it serves:** All developers (as consumers) and platform teams (as authors).
-
-**Why it matters:** Personas are the user-facing product. Everything else in AgentBoot
-— traits, the build system, the scope hierarchy, the distribution pipeline — exists to
-make personas work well. A persona that catches SQL injection, explains the risk,
-suggests the fix, and cites the relevant standard is the experience that makes
-developers trust and adopt the system.
-
-#### 6.3.3 Gotchas Rules
-
-Path-scoped instructions that encode hard-won operational knowledge. Each gotchas file
-is a Markdown file with `paths:` frontmatter that limits when the rule activates. When
-a developer is working on files that match 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.
-
-Gotchas capture the kind of information that lives in one engineer's head until they
-leave: "PostgreSQL partitions do NOT inherit `relrowsecurity`," "UUID primary keys
-cause exponential INSERT slowdown," "Lambda cold starts are 10x worse with VPC
-networking." Technology-specific, not org-specific — making them highly shareable.
-
-**Who it serves:** All developers (as consumers), platform teams and individual
-contributors (as authors), and the marketplace community (as shareable knowledge).
-
-**Why it matters:** Gotchas rules capture 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.
-
-#### 6.3.4 Always-On Instructions
-
-Universal guardrails distributed to every repo regardless of persona configuration.
-These are the org-wide rules that apply to every AI interaction: security baselines,
-output format standards, coding conventions. They load at session start and remain
-active throughout.
-
-**Who it serves:** The entire organization. IT/Security teams who need guarantees
-that certain rules are always active.
-
-**Why it matters:** Some rules should never be opt-in. A security baseline, a coding
-standard, a compliance requirement — these must apply everywhere. Always-on
-instructions are the mechanism for universal governance.
-
-#### 6.3.5 Domain Layers
-
-Complete packages of traits, personas, gotchas, and instructions for a specific
-compliance regime or technology stack. A healthcare domain layer includes PHI-awareness
-traits, HIPAA reviewer personas, patient data gotchas, and compliance-specific
-always-on instructions. A fintech domain layer includes PCI-DSS compliance traits,
-financial data reviewers, and transaction security gotchas.
-
-Domain layers are the highest-effort contribution to the marketplace but also the
-highest value. They package everything an organization needs to govern AI behavior
-in a regulated domain.
-
-**Who it serves:** Organizations in regulated industries (healthcare, finance,
-government) that need domain-specific compliance guardrails.
-
-**Why it matters:** Regulated industries cannot adopt AI tools without compliance
-guardrails. Building these guardrails from scratch is expensive and error-prone.
-Domain layers provide a tested, community-maintained foundation that organizations
-can adopt and extend.
-
-#### 6.3.6 Per-Persona Extensions
-
-Teams can extend base personas without forking them. An extension file adds
-domain-specific rules to a base persona. The base definition stays unmodified and
-receives upstream improvements automatically. This prevents the anti-pattern of
-copying a persona, modifying it, and maintaining a fork that diverges over time.
-
-**Who it serves:** Teams that need team-specific customization of org-wide personas.
-
-**Why it matters:** Without extensions, teams face a false choice: use the org persona
-as-is (too generic) or fork it (diverges and rots). Extensions provide the middle path:
-customize behavior while staying on the upstream upgrade path.
-
-### 6.4 Delivery and Distribution
-
-#### 6.4.1 Claude Code Plugin
-
-The primary delivery method for Claude Code users. AgentBoot output is packaged as a
-CC plugin — a directory containing agents, skills, hooks, rules, MCP configuration,
-and settings — distributable through a private marketplace.
-
-The organization creates a private marketplace (a Git repository with a
-marketplace.json catalog). Engineers install with a single command:
-`/plugin marketplace add org/personas` and `/plugin install org-plugin`. IT can
-force-enable the plugin via managed settings, requiring zero developer action.
-
-Plugin packaging is produced by `agentboot export --format plugin`. The plugin name
-becomes the namespace prefix for all skills (e.g., `/acme:review-code`).
-
-**Who it serves:** All Claude Code users in the organization.
-
-**Why it matters:** The plugin is the native CC distribution mechanism. It supports
-namespace isolation (preventing conflicts), version pinning, force-enable via managed
-settings, and live reload without restart. It is the path of least resistance for CC
-organizations.
-
-#### 6.4.2 Marketplace
-
-Three-layer marketplace ecosystem: Core (maintained by AgentBoot, Apache 2.0),
-Verified (community-contributed, reviewed by maintainers, meets quality standards),
-and Community (unreviewed, valid format only, buyer-beware).
-
-Full details in section 6.9 (Marketplace).
-
-**Who it serves:** All users who need pre-built governance content.
-
-**Why it matters:** The marketplace is the mechanism that turns AgentBoot from a
-framework into an ecosystem. A framework solves the governance problem for one
-organization. An ecosystem solves it for the industry.
-
-#### 6.4.3 Managed Settings
-
-AgentBoot generates managed settings artifacts for deployment via MDM (Jamf, Intune,
-JumpCloud, Kandji) or Anthropic's server-managed settings. Managed settings are
-deployed to OS-level paths and cannot be overridden by any user or project
-configuration.
-
-Managed settings carry HARD guardrails only: compliance hooks, credential blocking,
-audit logging, and forced plugin installation. They are not used for persona delivery
-(that is what the plugin and sync are for). This separation keeps compliance and
-convenience in distinct channels.
-
-`agentboot export --format managed` produces the artifacts. IT deploys them through
-their existing MDM infrastructure.
-
-**Who it serves:** IT/Security teams responsible for compliance enforcement.
-
-**Why it matters:** HARD guardrails must be non-overridable. A PHI scanning hook in a
-healthcare organization cannot be disabled by a developer who finds it inconvenient.
-Managed settings are the only mechanism that provides OS-level enforcement.
-
-#### 6.4.4 MCP Server
-
-AgentBoot exposed as an MCP (Model Context Protocol) server that any MCP-compatible
-agent can consume. Provides persona invocation, trait lookup, governance status, and
-knowledge base access as MCP tools and resources.
-
-The MCP server is the cross-platform bridge. It works in Claude Code, Copilot, Cursor,
-Gemini CLI, and any other MCP client. Organizations with mixed toolchains use the MCP
-server to ensure everyone gets governed personas regardless of which tool they use.
-
-**Who it serves:** Multi-agent organizations with engineers using different AI tools.
-
-**Why it matters:** Without MCP, each platform needs its own delivery mechanism (plugin
-for CC, instruction files for Copilot, rules for Cursor). MCP provides a single
-channel that serves all platforms identically with the same persona definitions and
-invocation interface.
-
-#### 6.4.5 Direct Sync
-
-The fallback/bootstrap delivery method. AgentBoot's sync script writes compiled files
-directly to target repos' `.claude/`, `.github/`, and `.cursor/` directories. When a
-developer clones the repo, the personas are already there with zero setup.
-
-This is the simplest mental model (files in a directory), works offline, and requires
-no plugin system dependency. It scales well to dozens of repos but creates sync PR
-noise at hundreds.
-
-**Who it serves:** All developers in repos registered for sync, and organizations that
-cannot use the plugin system.
-
-**Why it matters:** The "repo already has it" model provides the lowest-friction
-developer experience. The developer never installs anything — governance is in the
-repo they are already working in.
-
-#### 6.4.6 Non-Claude Code Delivery
-
-For Copilot: generates `copilot-instructions.md`, path-scoped `.instructions.md`
-files, `.prompt.md` slash command files, and agentskills.io SKILL.md files. For
-Cursor: generates `.cursor/rules/` files, `.cursorrules`, and SKILL.md files. For
-Gemini CLI: generates `GEMINI.md` and SKILL.md files.
-
-The `repos.json` platform field determines which format each repo receives. The MCP
-server is the equalizer for multi-platform organizations.
-
-**Who it serves:** Organizations using tools other than Claude Code.
-
-**Why it matters:** Honest cross-platform support is a competitive differentiator.
-AgentBoot does not pretend all platforms are equal — it documents the governance gaps
-per platform — but it does provide the best possible experience on each one.
-
-### 6.5 Privacy and Telemetry
-
-#### 6.5.1 Three-Tier Privacy Model
-
-**Tier 1 (Private):** Raw prompts, conversation history, session transcripts, files
-read during exploration. These stay on the developer's machine. AgentBoot does not
-read, transmit, or reference them. Retention is session duration or developer's
-choice.
-
-**Tier 2 (Privileged):** Aggregated patterns extracted by LLM analysis via the
-`/insights` skill. The analysis uses the same Claude API trust boundary the developer
-already uses for every prompt. The developer sees insights first and approves what gets
-shared. Patterns, not transcripts, are the output.
-
-**Tier 3 (Organizational):** Persona output metrics — invocation counts, cost,
-findings severity distribution, model usage, and duration. Anonymized by default (no
-developer ID). Team-level attribution via the scope field enables budget tracking
-without identifying individuals.
-
-**Who it serves:** All users. Developers get privacy. The organization gets metrics.
-
-**Why it matters:** The privacy model is a product differentiator. In a market where
-enterprises are deploying AI monitoring tools, AgentBoot takes the opposite stance:
-it helps organizations improve their AI governance without being the tool that surveys
-their developers. The best prompt optimization system is one that developers feed
-willingly because they trust it.
-
-#### 6.5.2 `/insights` Skill
-
-A skill that sends session transcripts to the Claude API (Haiku for speed/cost) for
-pattern extraction. Presents personal prompt insights to the developer: session counts,
-most-used personas, common topics, rephrase rates, cost, and improvement suggestions.
-The developer optionally approves sharing anonymized patterns to the org aggregate.
-
-The analysis prompt is explicitly designed to extract patterns, not judge. It frames
-everything as persona improvement opportunities, not developer deficiencies. It does
-not quote developer prompts, judge question quality, identify knowledge deficiencies,
-or produce output that could embarrass the developer if shared.
-
-**Who it serves:** Developers (personal analytics) and the organization (aggregate
-patterns for persona optimization).
-
-**Why it matters:** Without insights, prompt optimization is guesswork. With insights,
-the organization knows "auth patterns are asked about 89 times across 23 developers"
-and can act on it (create an auth-patterns skill). The mechanism respects privacy while
-enabling organizational learning.
-
-#### 6.5.3 Org Dashboard
-
-Aggregate metrics visible to engineering leaders and platform teams: active seats,
-persona invocations, cost per team, model mix, persona effectiveness (rephrase rates,
-false positive rates), common knowledge gaps, and cost efficiency analysis.
-
-The dashboard shows investment metrics (cost, adoption, ROI) and outcome metrics (PR
-quality, bug rates, coverage). It never shows process metrics (what developers typed,
-how many times they rephrased, what they asked about).
-
-Optional per-developer usage tracking with three formats: `false` (no developer
-identity, the default), `hashed` (consistent anonymous ID), and `email` (full
-attribution). Full attribution requires clear communication to the team and is
-intended for cost allocation and license optimization, not surveillance.
-
-**Who it serves:** Engineering leaders, platform teams, and org owners.
-
-**Why it matters:** Leaders need evidence that the AI investment is delivering value.
-The dashboard provides it without violating developer privacy.
-
-#### 6.5.4 Escalation Exception
-
-One exception to prompt privacy: genuinely harmful content (attempted exfiltration,
-guardrail circumvention, harassment, malware generation). The system flags the
-category locally first (the developer sees the flag), then reports the flag (category
-and date, not the transcript) to a designated compliance contact. The compliance team
-can request the transcript through a formal process (like a legal hold), not through
-the analytics pipeline.
-
-Implemented via a `UserPromptSubmit` hook using Haiku for fast evaluation. The prompt
-is explicitly scoped to harmful categories only — not quality, intelligence, or
-competence.
-
-**Who it serves:** IT/Security and compliance teams.
-
-**Why it matters:** Complete privacy absolutism is irresponsible in an enterprise
-context. The escalation exception provides a narrow, transparent mechanism for
-genuinely harmful content while maintaining the broader privacy commitment.
-
-#### 6.5.5 Telemetry Configuration
-
-Privacy configuration in `agentboot.config.json` includes telemetry settings (enabled,
-includeDevId, devIdFormat, includeCost, includeScope, destination), insights settings
-(enabled, autoShareAnonymized, escalation categories and contact), and rawPrompts
-settings (collect: false, transmit: false, surfaceToOrg: false — fields that cannot be
-set to true, existing to make design intent explicit).
-
-**Who it serves:** Platform teams configuring privacy settings for their organization.
-
-**Why it matters:** Privacy is not a binary. Different organizations have different
-requirements. The configuration provides a spectrum from fully anonymous to fully
-attributed, with clear documentation of the implications of each setting.
-
-### 6.6 Knowledge Layer
-
-#### 6.6.1 Stage 1: Flat Files (Default)
-
-The current and default knowledge system. Markdown files loaded into context:
-always-on instructions at session start, path-scoped rules when matching files are
-read, trait content composed at build time, and skills loaded on invocation.
-
-Works for 5-50 knowledge items. Zero infrastructure. Version-controlled in git.
-Human-readable and editable. Most organizations stay at this stage permanently.
-
-**Who it serves:** All organizations.
-
-**Why it matters:** Flat files are the right default. They require no infrastructure,
-no databases, no embedding APIs. They work immediately and scale to the needs of most
-teams.
-
-#### 6.6.2 Stage 2: Structured Knowledge Store
-
-A queryable layer on top of flat files. Files gain optional frontmatter for structured
-fields (type, technology, tags, severity, domain, learned_from). The build system
-generates a SQLite index from this frontmatter. An MCP server exposes tag/category
-queries: search by technology and severity, get by ID, find related items, and list
-by type and tag.
-
-Handles 50-500 knowledge items. Zero new infrastructure (SQLite is a single file
-shipped with the MCP server). The flat files remain the source of truth — the index
-is derived, not authoritative.
-
-**Who it serves:** Mature organizations with extensive accumulated knowledge (gotchas,
-ADRs, incident learnings, standards, patterns).
-
-**Why it matters:** When an organization has 200 gotchas and 50 ADRs, loading
-everything into context is wasteful. Structured queries allow personas to retrieve
-only the relevant knowledge for the current task.
-
-#### 6.6.3 Stage 3: Vector / RAG
-
-Semantic retrieval via embeddings. Instead of querying by tags and categories, the
-persona describes what it is looking at and the knowledge base returns the most
-semantically relevant items. Built on sqlite-vss (vector search extension for SQLite),
-keeping zero new infrastructure.
-
-The key use case is context-aware review: "this code is doing token refresh validation"
-retrieves the incident report about token expiry race conditions, even though the code
-does not mention "race condition." The connection is semantic, not keyword-based.
-
-Handles 500+ knowledge items. Requires embedding API calls (incremental, only changed
-items). Cost is minimal (~$0.20 for 1,000 items).
-
-**Who it serves:** Compliance-heavy industries where accumulated knowledge (incidents,
-ADRs, patterns) is as valuable as the code itself.
-
-**Why it matters:** The progression from rules to knowledge to organizational memory
-is the long-term value of the knowledge layer. A security reviewer that cites last
-year's incident report is qualitatively different from one that only checks rules.
-
-#### 6.6.4 Stable MCP Interface
-
-The MCP interface stays identical across all three stages. Personas do not know or care
-whether the backing store is flat files, SQLite, or pgvector. They call the same MCP
-tools. An organization can upgrade from Stage 2 to Stage 3 without rewriting any
-persona definitions.
-
-**Who it serves:** Platform teams managing knowledge infrastructure.
-
-**Why it matters:** The abstraction boundary between personas and the knowledge store
-means organizations can evolve their knowledge infrastructure without touching their
-persona definitions. This is why MCP-first matters — the interface is the contract.
-
-### 6.7 Testing
-
-#### 6.7.1 Unit and Schema Tests (Layer 1)
-
-Config validation against JSON schema, frontmatter parsing for all persona SKILL.md
-files, trait composition (injection markers, weight resolution, missing references,
-circular dependencies), lint rules (vague language, token budget, credentials,
-conflicts), and sync logic (scope merging, output format selection, manifest generation,
-PERSONAS.md registry).
-
-Free. Runs on every commit. Must pass to merge. Uses vitest.
-
-**Who it serves:** AgentBoot core maintainers and platform teams with custom content.
-
-**Why it matters:** The foundation of the test pyramid. Catches configuration errors,
-format violations, and composition bugs before they reach compilation.
-
-#### 6.7.2 Integration Tests (Layer 2)
-
-Full build pipeline (validate, compile, sync produces expected output), CC-native
-output validation (agent frontmatter, @imports, paths: frontmatter, settings.json
-hooks, .mcp.json), cross-platform output validation (standalone SKILL.md, copilot-
-instructions.md), plugin export validation (structure, claude plugin validate),
-discover and ingest (finds files, identifies duplicates, generates migration plan,
-non-destructive guarantee), and uninstall (removes managed files only, preserves
-local files, handles mixed content, restores archive).
-
-Free. Runs on every commit and PR. Uses vitest with temp directories and test repo
-fixtures.
-
-**Who it serves:** AgentBoot core maintainers.
-
-**Why it matters:** Integration tests verify that the full pipeline works end-to-end.
-A unit test might pass on trait composition, but the integration test catches when the
-compiled output misses a hook entry in settings.json.
-
-#### 6.7.3 Behavioral Tests (Layer 3)
-
-LLM invocation with known inputs, asserting on output patterns. Test cases defined in
-YAML format specifying persona, model (Haiku for cost), setup files, prompts, and
-assertions (findings_min/max, severity_includes/excludes, text_matches/excludes,
-confidence_min, output_contains, output_structure, json_schema, token_max,
-duration_max_ms).
-
-Uses `claude -p` with structured JSON output, bypass permissions, and no session
-persistence. Flake tolerance (2-of-3 runs) handles non-determinism. Cost: ~$5/PR
-for 4 personas.
-
-**Who it serves:** Platform teams validating persona behavior before deployment.
-
-**Why it matters:** The core novel challenge in testing AI personas. Traditional
-tests cannot verify that a persona catches a SQL injection vulnerability. Behavioral
-tests use the cheapest model (Haiku) to verify that the prompt structure elicits the
-right behavior — if it works on Haiku, it will work better on Sonnet/Opus.
-
-#### 6.7.4 Snapshot / Regression Tests (Layer 4)
-
-Compare persona output across versions to detect regressions. Snapshots store
-structured summaries (finding counts, patterns, tokens, duration), not full prose.
-Run after persona prompt changes, trait updates, model changes, and weekly for provider
-drift detection.
-
-Flags differences for human review: MATCH (identical), CHANGED (new findings — is the
-change correct?), and REGRESSION (previously caught findings now missed — investigate).
-
-Cost: ~$5 per persona change.
-
-**Who it serves:** Platform teams managing persona quality over time.
-
-**Why it matters:** Without regression testing, a persona improvement might silently
-break an existing capability. Snapshot tests make these regressions visible before
-deployment.
-
-#### 6.7.5 LLM-as-Judge (Layer 5)
-
-A separate LLM call (Opus as judge) evaluates persona output on qualitative dimensions:
-completeness, accuracy, specificity, prioritization, and tone. Test cases include
-ground truth (known issues in the code) so the judge can evaluate whether the persona
-found what it should have found.
-
-Run on major persona rewrites, new personas, model migrations, and quarterly quality
-audits. Cost: ~$20 per run.
-
-**Who it serves:** Platform teams making major persona changes.
-
-**Why it matters:** Pattern matching cannot evaluate whether a review is "thorough" or
-whether the tone is "professional." LLM-as-judge applies consistent qualitative
-evaluation at scale, filling the gap between structural assertions and human review.
-
-#### 6.7.6 Human Review (Layer 6)
-
-Guided human review sessions via `agentboot review`. Presents randomly sampled persona
-outputs from the last 7 days with structured questions (accuracy, severity, additions,
-removals). Takes 10-15 minutes per persona.
-
-Triggers: new persona ships (3-5 real PRs), major trait change (before/after), quarterly
-audit (random sample of 20 outputs), quality escalation (specific disputed finding).
-
-**Who it serves:** Platform teams and domain experts.
-
-**Why it matters:** Humans make judgment calls that no automated test can make. The
-review tool makes this sustainable (structured, guided, 1 hour/month for 4 personas)
-rather than ad hoc.
-
-#### 6.7.7 Mutation Testing
-
-Deliberately introduces known bugs into persona prompts and verifies that tests catch
-the regressions. Validates that the test suite actually detects the problems it claims
-to detect.
-
-**Who it serves:** Platform teams validating test suite quality.
-
-**Why it matters:** "Who tests the tests?" Mutation testing answers this question by
-proving that behavioral tests catch regressions when they should.
-
-### 6.8 Developer Onboarding
-
-#### 6.8.1 First-Session Welcome
-
-A brief orientation (~80 tokens) generated as part of the CLAUDE.md that AgentBoot
-syncs. Lists available personas with invocation commands, provides 3-4 tips for
-effective use, mentions the privacy commitment, and directs new users to `/learn`.
-Loads once per session and fades into background context after a few sessions.
-
-**Who it serves:** Developers opening Claude Code in an AgentBoot-governed repo for
-the first time.
-
-**Why it matters:** The first interaction determines whether a developer engages or
-abandons. A wall of text loses them. A brief, actionable orientation converts them.
-
-#### 6.8.2 `/learn` Skill
-
-A context-aware training assistant, not a static tutorial. Provides a topic browser
-(Getting Started, Going Deeper, Quick Reference), answers specific questions
-("how do I review one file?"), and delivers contextual explanations (severity levels,
-persona concepts, prompting tips).
-
-The skill uses `disable-model-invocation: true` for static content and normal model
-invocation for free-form questions.
-
-**Who it serves:** Developers at any skill level who want to understand the persona
-system better.
-
-**Why it matters:** The `/learn` skill provides help at the moment of need. Instead of
-sending developers to documentation, it answers their question in context.
-
-#### 6.8.3 Curated External Resources
-
-AgentBoot does not build training content. It curates links to the best existing
-resources organized by skill level (Beginner, Intermediate, Advanced, Cost Management).
-Sources include Anthropic documentation, community guides, and AgentBoot's own
-reference documentation.
-
-The resource list lives in a skill (updatable without rebuilding) and is checked
-periodically for link freshness.
-
-**Who it serves:** Developers who want to go deeper than `/learn` covers.
-
-**Why it matters:** AgentBoot should not duplicate existing high-quality training
-content. Curation is the right approach — point people to the best resources rather
-than building inferior alternatives.
-
-#### 6.8.4 Onboarding Checklist
-
-A generated checklist (`agentboot onboarding-checklist`) built from the organization's
-actual AgentBoot configuration. Includes: Claude Code installation verification,
-plugin installation check, first code review, first test generation, persona
-exploration, personal preference setup, and first `/insights` run.
-
-Exportable as Markdown or email format for sharing with new team members.
-
-**Who it serves:** Platform teams onboarding new developers.
-
-**Why it matters:** A generic onboarding guide is less effective than one built from
-the organization's actual configuration. The generated checklist uses real persona
-names, real skill invocations, and real marketplace information.
-
-#### 6.8.5 Contextual Tips
-
-Optional tips that appear in persona output when patterns suggest the developer is new:
-first invocation of a persona, vague prompts, repeated rephrasing. Rate-limited (max
-1 per session), disable-able by the developer, and generated by the persona itself
-(part of the persona prompt, not a separate system).
-
-**Who it serves:** New developers learning to use personas effectively.
-
-**Why it matters:** Tips at the moment of need are more effective than documentation.
-A developer who types "review this" and gets a tip about being more specific learns
-faster than one who reads a guide about prompting.
-
-#### 6.8.6 Org-Authored Tips
-
-The organization's platform team can add custom onboarding content in an `onboarding/`
-directory in the personas repo: welcome messages, tips specific to the org's stack and
-conventions, and links to internal resources. This content is synced alongside persona
-files.
-
-**Who it serves:** Organizations with institutional knowledge to transfer.
-
-**Why it matters:** Org-authored tips capture what a senior engineer would tell a new
-hire sitting next to them: "the security reviewer is strict about SQL parameterization
-because we had a production incident." This knowledge transfer is version-controlled,
-available 24/7, and scales beyond one-on-one conversations.
-
-### 6.9 Marketplace
-
-#### 6.9.1 Core Layer (Layer 1)
-
-Traits and personas maintained by the AgentBoot project. The reference implementations.
-Apache 2.0 licensed. Tested in CI on every commit. Included when you run
-`agentboot setup`.
-
-Contents: core traits (critical-thinking, structured-output, source-citation,
-confidence-signaling, audit-trail, schema-awareness), core personas (code-reviewer,
-security-reviewer, test-generator, test-data-expert), and baseline instructions.
-
-**Who it serves:** Every AgentBoot user.
-
-**Why it matters:** The core layer is the foundation. It provides immediate value
-without any community contribution and establishes the quality bar for the ecosystem.
-
-#### 6.9.2 Verified Layer (Layer 2)
-
-Community-contributed content reviewed by AgentBoot maintainers and meeting quality
-standards. Listed in the official marketplace.
-
-Quality requirements: reviewed by at least one maintainer, follows format standards,
-has behavioral tests (at least deterministic), documentation (README, use case,
-configuration), Apache 2.0 or MIT license, no org-specific content, and attribution
-to contributor.
-
-Review process: contributor opens PR, automated checks run (lint, test, format, license
-scan), maintainer reviews for quality, generalizability, and overlap, accepted content
-is merged with attribution.
-
-**Who it serves:** Organizations looking for pre-built governance content for common
-use cases.
-
-**Why it matters:** The Verified layer is where the marketplace becomes valuable beyond
-core. A healthcare organization can install a PHI-awareness trait that has been reviewed,
-tested, and used by other healthcare organizations — rather than building it from scratch.
-
-#### 6.9.3 Community Layer (Layer 3)
-
-Anything published to a public marketplace. Not reviewed by AgentBoot maintainers.
-Only requirement: valid frontmatter / `agentboot.domain.json` and declared license.
-
-**Who it serves:** Anyone looking for specialized or experimental governance content.
-
-**Why it matters:** Low barrier to entry enables experimentation and niche use cases.
-Community content may be excellent or terrible — the explicit labeling ensures users
-understand the trust level.
-
-#### 6.9.4 Contribution Model
-
-Contributions flow through `agentboot publish` (one-command sharing that strips
-org-specific content, validates format, generates README, and opens a PR). Attribution
-is permanent and visible in content frontmatter, contributor profiles, and build output.
-
-Motivations served: professional reputation (usage stats, linkable profiles), reciprocity
-(attribution on everything installed), content improvement (feedback from production
-usage), and org visibility (contributing organizations listed publicly).
-
-AgentBoot does not gamify contributions — no leaderboards, badges, streak counters,
-or points. These attract gaming behavior, not quality.
-
-**Who it serves:** Anyone with governance knowledge to share.
-
-**Why it matters:** The biggest barrier to contribution is friction, not motivation.
-A developer who has a great PostgreSQL gotchas file will share it if it takes 30
-seconds. They will not if it takes 30 minutes. `agentboot publish` makes sharing
-as close to zero-friction as possible.
-
-#### 6.9.5 Plugin Packaging
-
-Each logical marketplace grouping (core, healthcare domain, fintech domain,
-infrastructure gotchas) becomes a CC plugin installable independently. Cross-listing
-with complementary projects (such as SuperClaude) enables ecosystem convergence without
-bundling dependencies.
-
-**Who it serves:** Claude Code users who want to pick and choose governance content.
-
-**Why it matters:** Plugin packaging turns marketplace content into one-command
-installations. A developer can install `ab-healthcare` and immediately have PHI-aware
-review personas.
-
-#### 6.9.6 Trust and Quality
-
-Quality mechanisms: version pinning (orgs pin to specific versions of marketplace
-content), license scanning (incompatible licenses block the build), trait isolation
-(a bad community trait cannot break a core persona), trust signals (badges, download
-count, update freshness, test coverage, compatible versions).
-
-**Who it serves:** Organizations evaluating marketplace content for production use.
-
-**Why it matters:** Trust is the currency of a marketplace. Without quality signals,
-organizations will not use community content in production. The three-layer structure
-(Core, Verified, Community) with explicit trust levels addresses this.
-
----
-
-## 7. Non-Goals
-
-AgentBoot explicitly does not do the following. These boundaries are intentional
-design decisions, not missing features.
-
-### 7.1 AgentBoot Is Not a Learning Management System
-
-AgentBoot provides contextual assists and curated resource links, not courses, modules,
-progress tracking, or certificates. It does not track who completed what training. It
-does not gate persona access behind training completion. The `/learn` skill is a
-helpful assistant, not a course catalog.
-
-The onboarding problem is real, but the solution is lightweight help at the moment of
-need, not a formal training program. Organizations that need formal AI training should
-use dedicated LMS platforms.
-
-### 7.2 AgentBoot Is Not a Surveillance Tool
-
-AgentBoot does not collect, transmit, or surface raw developer prompts. It does not
-rank developers by AI skill or prompt quality. It does not gamify usage with
-leaderboards, badges, or streaks. It does not correlate AI usage with performance
-reviews. It does not make AI usage mandatory.
-
-The privacy model is a design invariant, not a configuration option. An organization
-that wants conversation monitoring has that capability through their API provider's
-Compliance API and enterprise data governance tools. AgentBoot is not that channel.
-
-### 7.3 AgentBoot Does Not Compete with Content Libraries
-
-AgentBoot is the governance and distribution layer, not a content library competing
-with projects like SuperClaude, ArcKit, spec-kit, or Trail of Bits configurations.
-These projects produce content (traits, agents, skills). AgentBoot distributes,
-governs, and orchestrates content.
-
-The recommended relationship is marketplace curation (point to upstream, cross-list)
-rather than bundling. AgentBoot works without any third-party content; third-party
-content works without AgentBoot. They are complementary, not competitive.
-
-### 7.4 AgentBoot Is Not a Runtime Framework
-
-AgentBoot is a build tool. It produces artifacts and exits. It has zero runtime
-footprint. The distributed output works without AgentBoot installed. There is no
-"AgentBoot runtime" that must be running for personas to function.
-
-The exception is the MCP server, which is a separate, optional package
-(`@agentboot/mcp-server`) that runs as a process. Even this is opt-in and not required
-for core functionality.
-
-### 7.5 AgentBoot Does Not Promise Universal Platform Parity
-
-AgentBoot is honest about platform capabilities. Claude Code gets the full governance
-surface (hooks, managed settings, subagent isolation, agent memory, plugin system).
-Non-CC platforms get the content (personas, instructions, rules) but not the
-enforcement mechanisms.
-
-AgentBoot documents these gaps per platform rather than pretending all agents are equal
-or promising features it cannot deliver. The compliance story for non-CC platforms is:
-instruction-based refusal plus CI-based review plus organizational policy.
-
-### 7.6 AgentBoot Does Not Manage AI Models
-
-AgentBoot specifies which model a persona should use (in persona.config.json and agent
-frontmatter), but it does not manage model access, API keys, billing, or rate limiting.
-Those are the responsibility of the AI platform (Anthropic Console, GitHub Settings,
-Cursor settings).
-
-### 7.7 AgentBoot Does Not Replace Code Review
-
-AI code review is a complement to human code review, not a replacement. AgentBoot
-personas produce findings that humans evaluate and act on. Even at the highest autonomy
-level (Phase 3: Autonomous), the output is reviewed post-hoc by humans.
-
-The test plan explicitly states: "Agents test agents, but humans always decide.
-Automation removes burden, not judgment."
-
-### 7.8 AgentBoot Does Not Do Dynamic Agent Orchestration
-
-AgentBoot does not provide a runtime agent orchestration system with message passing,
-state machines, or complex multi-agent workflows. The `/review` meta-skill is a
-lightweight routing layer that reads a configuration file and dispatches to the
-appropriate persona. The persona arbitrator (V2+) resolves conflicts between
-concurrent reviewers. Neither constitutes a full orchestration framework.
-
----
-
-## 8. Success Metrics
-
-### 8.1 Adoption Metrics
-
-| Metric | Measurement | Target |
-|---|---|---|
-| Organizations using AgentBoot | GitHub template uses, marketplace installs | Growth rate |
-| Active developers per org | Persona invocation telemetry (anonymous) | 70%+ of licensed seats |
-| Persona invocations per day (org-wide) | Telemetry aggregate | Trending upward |
-| Time from setup to first persona invocation | Wizard completion to first `/review-code` | Under 10 minutes |
-| Repos governed per org | `agentboot status` repo count | Growth rate |
-| Skeptic conversion rate | Developers who start at zero usage and reach 1+ sessions/week | 30%+ within 90 days |
-
-### 8.2 Contribution Metrics
-
-| Metric | Measurement | Target |
-|---|---|---|
-| Marketplace items (Verified) | Marketplace repo count | Growth rate |
-| Community contributors | Unique PR authors to marketplace | Growth rate |
-| Contribution-to-install ratio | Items contributed vs. items installed | Healthy ratio (not vanity) |
-| Domain layers available | Complete domain packages in marketplace | 3+ by V2 |
-| Trait reuse rate | How many personas compose each trait (average) | 3+ personas per core trait |
-
-### 8.3 Quality Metrics
-
-| Metric | Measurement | Target |
-|---|---|---|
-| Persona false positive rate | Rephrase rates, finding dismissal rates | Under 20% |
-| Bug escape rate delta | Production bugs that a persona should have caught (before/after) | Measurable reduction |
-| Test coverage delta | Coverage change in repos with test-generator persona | Measurable increase |
-| PR review turnaround | Time from PR open to first AI review | Under 5 minutes |
-| Behavioral test pass rate | CI test results | 95%+ |
-| Lint pass rate on first commit | How often persona changes pass lint without fixes | 80%+ |
-
-### 8.4 Cost Metrics
-
-| Metric | Measurement | Target |
-|---|---|---|
-| Avg cost per persona invocation | Telemetry (tokens * model rate) | Trending downward |
-| Model mix efficiency | % of invocations on Haiku/Sonnet vs. Opus | 80%+ on Sonnet or cheaper |
-| Automated test cost per month | CI billing | Under $200 for 4 personas |
-| Token budget compliance | % of personas within token budget | 95%+ |
-| Cost per finding | Total cost / total findings | Trending downward |
-
-### 8.5 Governance Metrics
-
-| Metric | Measurement | Target |
-|---|---|---|
-| Sync coverage | % of repos receiving governance updates | 100% of registered repos |
-| Managed settings deployment | % of developer machines with HARD guardrails | 100% of managed machines |
-| Compliance hook activation | % of sessions where compliance hooks are active | 100% on managed machines |
-| ADR exception count | Approved exceptions via ADR governance | Low and stable |
-| Escalation flag rate | Harmful content flags per period | Low (zero is ideal) |
-
-### 8.6 Developer Experience Metrics
-
-| Metric | Measurement | Target |
-|---|---|---|
-| Setup completion rate | % of users who complete `agentboot setup` | 90%+ |
-| Uninstall rate | % of orgs that uninstall within 90 days | Under 10% |
-| `/learn` invocations | How often developers seek help | Trending downward (learning) |
-| Tip dismissal rate | How often contextual tips are disabled | Under 30% |
-| NPS (Net Promoter Score) | Developer survey | Positive |
-
----
-
-## 9. Open Questions
-
-Open questions discovered during PRD authoring have been resolved or deferred.
-See the internal tracking document for remaining items.
-
----
-
-## 10. Glossary
-
-### Agent
-
-A Claude Code concept. An agent is a custom AI assistant defined in
-`.claude/agents/{name}/CLAUDE.md` with rich frontmatter (model, permissionMode,
-maxTurns, disallowedTools, mcpServers, hooks, memory, isolation). Agents are distinct
-from the base Claude Code assistant. In AgentBoot, personas are compiled into agents
-for CC-native output.
-
-### ADR (Architecture Decision Record)
-
-A formal exception governance mechanism. When a developer intentionally deviates from
-a persona's recommendation, an ADR documents the rationale, gets reviewer approval,
-and becomes a permanent record. The persona learns to accept the deviation for that
-specific case. ADRs handle permanent, approved deviations (as opposed to temporary
-elevation for debugging).
-
-### Agent-Agnostic
-
-Content that works across multiple AI agent platforms without modification. Traits
-(Markdown), personas (SKILL.md via agentskills.io), and gotchas (Markdown with glob
-patterns) are agent-agnostic. Hooks, managed settings, and agent frontmatter are
-agent-specific (Claude Code only).
-
-### agentskills.io
-
-An open standard for AI agent skill definitions. Uses SKILL.md format (Markdown with
-YAML frontmatter). Supported by 26+ agent platforms. AgentBoot uses agentskills.io as
-the cross-platform persona format.
-
-### Always-On Instructions
-
-Universal guardrails distributed to every repo regardless of persona configuration.
-These load at session start and remain active throughout. Used for org-wide rules that
-apply to every AI interaction (security baselines, coding standards, compliance
-requirements).
-
-### Autonomy Progression
-
-A three-phase model for persona independence. Phase 1 (Advisory): persona produces
-findings, human decides. Phase 2 (Auto-approve): persona applies low-risk fixes
-automatically, high-risk findings require human review. Phase 3 (Autonomous): persona
-operates independently, human reviews post-hoc. Promotion between phases is a
-governance decision requiring evidence (false-positive rates, test coverage, team
-approval).
-
-### Build Pipeline
-
-The three-stage process: validate (pre-build checks), compile (resolve traits, produce
-output), sync (distribute to repos). The pipeline is: validate, compile, sync.
-
-### CC-First Delivery
-
-The principle that Claude Code is the primary delivery target. Content is agent-agnostic
-(portable Markdown). Delivery leverages CC's full feature surface (plugins, hooks,
-managed settings, MCP, agents, skills, rules). Non-CC platforms get the content but
-not the enforcement mechanisms.
-
-### Cowork
-
-Anthropic's desktop application for non-technical users. Cowork plugins are the same
-format as Claude Code plugins but appear in a GUI with form-based input rather than
-slash commands. AgentBoot personas packaged as plugins work in both CC and Cowork.
-
-### Compilation Target
-
-One of two output formats produced by `agentboot build`. The cross-platform target
-produces standalone SKILL.md files with traits inlined. The CC-native target produces
-the full `.claude/` directory structure with @imports, rich frontmatter, hooks, and
-MCP configuration.
-
-### Convention Over Configuration
-
-The principle that AgentBoot ships with sensible defaults for everything. Organizations
-configure what is different about their situation, not everything from scratch. Borrowed
-from the Spring Boot design philosophy.
-
-### Domain Layer
-
-A complete package of traits, personas, gotchas, and instructions for a specific
-compliance regime or technology stack. Examples: healthcare-compliance (PHI, HIPAA,
-FHIR), fintech-compliance (PCI-DSS, SOX), govtech-fedramp. Domain layers are the
-highest-value, highest-effort marketplace contribution.
-
-### Gotcha (Gotchas Rule)
-
-A path-scoped instruction that encodes hard-won operational knowledge. Activated when
-a developer works on files matching the glob pattern. Invisible (zero context cost)
-when working on unrelated files. Technology-specific, not org-specific — making them
-highly shareable. Example: "PostgreSQL partitions do NOT inherit relrowsecurity."
-
-### HARD Guardrail
-
-A non-overridable compliance rule deployed via MDM (managed settings) or marked
-`required: true` in the org config. Cannot be elevated, overridden, or disabled at any
-scope level. A team-level config that attempts to disable a HARD guardrail causes a
-build failure. Used for rules where violation is a compliance incident (PHI scanning,
-credential blocking, audit logging).
-
-### Hub-and-Spoke Distribution
-
-The distribution model. One central repository (the hub, the personas repo) contains
-the source of truth. Target repositories (spokes, the actual codebases) receive
-compiled artifacts via the sync pipeline. One-way flow: hub publishes, spokes receive.
-Spokes do not produce governance.
-
-### Managed Settings
-
-Claude Code configuration files deployed to OS-level paths
-(`/Library/Application Support/ClaudeCode/` on macOS, `/etc/claude-code/` on Linux)
-via MDM. Cannot be overridden by any user or project setting. Used for HARD guardrails
-and forced plugin installation.
-
-### Marketplace
-
-The three-layer ecosystem for sharing governance content. Core (maintained by AgentBoot),
-Verified (community-contributed, reviewed), Community (unreviewed, buyer-beware).
-Physically, a marketplace is a Git repository with a marketplace.json catalog.
-
-### MCP (Model Context Protocol)
-
-A protocol for AI agents to interact with external tools and data sources. MCP servers
-expose tools and resources that agents can consume. Supported by Claude Code, Copilot,
-Cursor, and Gemini CLI. AgentBoot uses MCP for cross-platform persona serving and
-knowledge base access.
-
-### Persona
-
-A complete, deployable agent. A composition of traits plus a specialized system prompt
-that defines the agent's identity, operating context, and mandate. Personas compose
-traits; they do not inherit from each other. In AgentBoot, personas are defined as
-SKILL.md files and compiled into platform-specific output.
-
-### persona.config.json
-
-Build metadata for a persona. Specifies which traits to compose, at what weight, the
-target model, permission mode, tool restrictions, MCP servers, hooks, and autonomy
-level. Read by the compile step to generate output.
-
-### Persona Arbitrator
-
-A dedicated persona (V2+) that resolves conflicts when multiple reviewer personas
-produce contradictory findings on the same code. Only invoked when the `/review`
-meta-skill detects conflicting findings. Not invoked on every review.
-
-### Plugin
-
-A Claude Code distribution unit that bundles agents, skills, hooks, rules, MCP
-configuration, and settings into a single installable package. Distributed via
-marketplaces (public or private). The primary delivery method for CC users.
-
-### Prompts as Code
-
-The principle that AI agent behavior is treated as infrastructure: defined in files,
-stored in version control, reviewed in pull requests, tested, linted, and measured.
-Analogous to Infrastructure as Code (Terraform) and Configuration as Code (Kubernetes).
-
-### Scope Hierarchy
-
-The four-level organizational model: Org, Group, Team, Repo. More specific scopes
-layer on top of general ones. Optional behaviors follow "most specific wins." Mandatory
-behaviors follow "most general wins." Determines how configuration is merged during
-sync.
-
-### Self-Improvement Reflections
-
-An optional mechanism where personas write brief reflections after completing their
-task. Reflections accumulate into a dataset revealing patterns. Three phases:
-Phase A (humans edit personas from observation), Phase B (reflections + review skill),
-Phase C (automated accuracy tracking).
-
-### SKILL.md
-
-The agentskills.io format for persona definitions. Markdown with YAML frontmatter
-(name, description, traits, scope, output format) followed by the system prompt in
-prose. The cross-platform persona format.
-
-### SME Discoverability Fragment
-
-A lightweight always-on CLAUDE.md section (~100 tokens) auto-generated by the build
-system. Lists all available personas and how to invoke them. Makes personas
-discoverable without consulting external documentation.
-
-### SOFT Guardrail
-
-An important default that can be temporarily elevated. Deployed via the shared repo
-(not MDM). Elevation mechanism: developer invokes `/elevate` with a reason, receives
-time-bounded bypass (default 30 minutes), audit log entry created, guardrail
-automatically re-engages on TTL expiry.
-
-### Structured Telemetry
-
-Persona invocation metrics emitted as structured JSON (GELF/NDJSON format). Fields
-include persona_id, model, scope, input/output tokens, cost, findings, duration, and
-timestamp. No developer ID by default. No prompt text. Human-queryable with `jq`.
-
-### Team Champion
-
-A designated engineer on each team (typically tech lead or senior IC) who runs sync,
-reviews sync PRs, files quality feedback, onboards teammates, and proposes governance
-improvements. A rotating responsibility taking minutes per week in steady state.
-
-### Trait
-
-A reusable behavioral building block for an AI persona. Captures a single aspect of
-how an agent should think or communicate. Supports weight configurations
-(HIGH/MEDIUM/LOW or 0.0-1.0). Composed at build time. The DRY principle applied to
-AI behavior. Write once, compose everywhere, improve in one place.
-
-### Trait Weight
-
-A calibration system for traits that support variable intensity. Named weights
-(HIGH/MEDIUM/LOW) map to numeric values (0.7/0.5/0.3). Additional values: OFF (0.0)
-and MAX (1.0). The weight adjusts the threshold for action, not the type of action.
-At any weight, CRITICAL findings always surface.
-
-### Two-Channel MDM Distribution
-
-Enterprise distribution model separating non-negotiable enforcement (Channel 1: MDM-
-deployed managed settings for HARD guardrails) from team-customizable configuration
-(Channel 2: Git-based hub-and-spoke for SOFT guardrails, traits, personas, skills).
-
----
-
-*End of Product Requirements Document.*