Package Layout (Reference)¶
Audience. Engineers navigating the
agent_baton/source tree. Every Python subpackage in the project, with a one-line purpose and the load-bearing module(s) cited bypath:line. Use this as a map when you don't yet know where a class lives. For why the layering exists, see ../architecture.md §Design philosophy.
Top-level layout¶
agent_baton/
__init__.py - Public API exports (ExecutionEngine, IntelligentPlanner, ...)
models/ - Layer 1. Pure dataclasses. No internal deps.
utils/ - Small helpers (frontmatter parsing).
core/ - Layer 2. Subsystems, organised by concern.
api/ - Layer 4a. FastAPI app and routes.
cli/ - Layer 4b. argparse subcommand modules.
_bundled_agents/- Distributable agent .md files vendored into the wheel.
pmo-ui/ - Layer 4c. React/Vite frontend (separate root).
Imports flow downward only:
models → core/* (peer-level) → engine/runtime → CLI/API.
The full dependency contract is documented in
../architecture.md §Design philosophy. It is
enforced by import-graph tests in tests/.
agent_baton/models/ — Layer 1¶
24 modules of dataclasses. Every module imports only from dataclasses,
enum, typing, and the standard library. No internal imports.
| Module | Key types | Notes |
|---|---|---|
execution.py |
MachinePlan, PlanPhase, PlanStep, PlanGate, TeamMember, SynthesisSpec, ExecutionState, StepResult, GateResult, ApprovalResult, PlanAmendment, ExecutionAction, ActionType, StepStatus, PhaseStatus, InteractionTurn, FeedbackQuestion, FeedbackResult, FileAttribution, ConsolidationResult |
The plan and state core. ~1700 lines, the largest model file. |
enums.py |
RiskLevel, TrustLevel, BudgetTier, ExecutionMode, GateOutcome, FailureClass, GitStrategy, AgentCategory |
Cross-cutting enums. |
agent.py |
AgentDefinition |
Parsed from .md frontmatter. |
events.py |
Event |
EventBus payload (topic, task_id, sequence, payload). |
knowledge.py |
KnowledgeDocument, KnowledgePack, KnowledgeAttachment, KnowledgeGapSignal, KnowledgeGapRecord, ResolvedDecision |
Knowledge delivery types. |
manager.py |
ProjectCharter, ScopeMap, Workstream, TeamBlueprint, RoleCard, ScopeContract, ContextBundle, ContextReference, KnowledgePlan, MissingKnowledgePack, ManagerDecision |
Manager-mode PMO sidecar types (Pydantic v2, JSON round-trippable). Note: unlike this file's other models, these are Pydantic BaseModel, not plain dataclasses. |
pmo.py |
PmoProject, PmoCard, PmoSignal, ProgramHealth, PmoConfig, InterviewQuestion, InterviewAnswer |
PMO board types — the portfolio Kanban overlay (core/pmo/), unrelated to manager-mode. |
bead.py |
Bead, BeadLink |
Structured agent memory. |
usage.py |
AgentUsageRecord, TaskUsageRecord |
Token / cost accounting. |
retrospective.py |
Retrospective, AgentOutcome, KnowledgeGap, RosterRecommendation, SequencingNote, TeamCompositionRecord, ConflictRecord |
Retro reports. |
trace.py |
TaskTrace, TraceEvent |
Per-task execution DAG. |
decision.py |
DecisionRequest, DecisionResolution, ContributionRequest |
Human-in-loop decisions. |
pattern.py |
LearnedPattern, PlanStructureHint, TeamPattern |
Pattern-learner outputs. |
budget.py |
BudgetRecommendation |
Budget tuner output. |
feedback.py |
RetrospectiveFeedback |
Closed-loop feedback record. |
context_profile.py |
AgentContextProfile, TaskContextProfile |
Context efficiency profiles. |
registry.py |
RegistryEntry, RegistryIndex |
Distribution registry types. |
escalation.py |
Escalation |
Governance escalation records. |
improvement.py |
Recommendation, Experiment, Anomaly, TriggerConfig, ImprovementReport, ImprovementConfig, RecommendationCategory, RecommendationStatus, ExperimentStatus, AnomalySeverity |
Improvement-loop types. |
learning.py |
LearningEvidence, LearningIssue |
Closed-loop learning ledger. |
parallel.py |
ExecutionRecord, ResourceLimits |
Concurrency configuration. |
plan.py |
MissionLogEntry |
Mission-log entries. |
reference.py |
ReferenceDocument |
Distributable reference docs. |
session.py |
SessionCheckpoint, SessionParticipant, SessionState |
Daemon session tracking. |
All model types implement to_dict() / from_dict() for JSON
round-tripping. Enum fields use typed enum instances internally and
serialize to .value strings only at the to_dict() boundary
(ADR-09).
agent_baton/utils/¶
| Module | Purpose |
|---|---|
utils/frontmatter.py |
parse_frontmatter() — YAML frontmatter extraction from .md files. |
agent_baton/core/ — Layer 2¶
The execution engine and all subsystems. Each subpackage is documented below with its load-bearing module(s).
core/engine/ — execution state machine¶
The heart of Agent Baton. Owns plan state and the action loop.
| Module | Class / function | Purpose |
|---|---|---|
executor.py |
ExecutionEngine (line 308) |
The state machine. ~6900 LOC. Implements ExecutionDriver. |
planner.py |
IntelligentPlanner (line 760) |
Data-driven plan creation. Consults AgentRouter, PatternLearner, BudgetTuner, PolicyEngine, KnowledgeResolver, BeadAnalyzer. |
dispatcher.py |
PromptDispatcher (line 161) |
Stateless prompt assembly: delegation prompts, gate prompts, path-enforcement bash guards. |
gates.py |
GateRunner (line 67), DryRunGateRunner (line 338) |
Stateless gate evaluator (test/build/lint/spec/review). |
persistence.py |
StatePersistence (line 30) |
Atomic JSON I/O for ExecutionState; manages active-task-id.txt. |
protocols.py |
ExecutionDriver (line 22) |
The 15-method interface between runtime and engine. |
classifier.py |
TaskClassifier (Protocol), KeywordClassifier, HaikuClassifier, FallbackClassifier |
Plan-sizing classifier (Haiku → keyword fallback). |
knowledge_resolver.py |
KnowledgeResolver |
4-layer knowledge resolution with per-step token budget. |
knowledge_gap.py |
parse_knowledge_gap(), determine_escalation() |
Parses KNOWLEDGE_GAP/CONFIDENCE/TYPE signals. |
knowledge_telemetry.py |
KnowledgeTelemetry |
Knowledge-usage events. |
bd_bead_store.py |
BdBeadStore (line 49) |
Bead-store surface (write/read/query/ready/close/annotate/link) backed by the external bd tool. Replaces the removed SQLite BeadStore (ADR-13b). |
bd_client.py |
BdClient (line 74), BdError, BdNotAvailable |
The single subprocess seam to the bd CLI; all invocations use --json. |
bd_mapping.py |
(mapping helpers) | Lossless Bead ⇄ bd issue mapping via metadata.baton blob + synthetic labels (bead-type:, scope:, source:, task:). |
bead_backend.py |
make_bead_store() (line 41) |
Backend selector; always returns BdBeadStore or raises BdNotAvailable. Default backend bd. |
bead_signal.py |
parse_bead_signals(), parse_bead_feedback() |
Parses BEAD_DISCOVERY/DECISION/WARNING/USEFUL/STALE. |
bead_selector.py |
BeadSelector |
Three-tier prompt-injection selection. |
bead_decay.py |
decay_beads() |
Retention-based archival. |
plan_reviewer.py |
PlanReviewer |
Plan-quality static checks. |
worktree_manager.py |
WorktreeManager |
Wave 1.3 git-worktree per-step isolation. |
takeover.py |
(takeover support) | Wave 5.1 human-takeover. |
| (gate-retry) | built into executor.py |
Phase D single gate-retry on first gate failure (BATON_GATE_RETRY). |
foresight.py |
Foresight |
Predictive next-step hinting. |
cost_estimator.py |
(estimator) | Token cost estimation per step. |
team_board.py |
TeamBoard |
Team-step coordination state. |
team_registry.py |
TeamRegistry |
Team composition lookup. |
team_tools.py |
(helpers) | Team-step utilities. |
soul_registry.py |
SoulRegistry |
Agent persona / soul records. |
soul_router.py |
SoulRouter |
Soul-aware routing. |
dry_run_launcher.py |
(launcher) | Engine-internal dry-run helper. |
flags.py |
feature-flag helpers | Reads BATON_*_ENABLED env vars. |
errors.py |
engine-specific exceptions |
core/runtime/ — async execution layer¶
Wraps the synchronous engine in an async loop. Implements daemon mode.
| Module | Class | Purpose |
|---|---|---|
worker.py |
TaskWorker |
Async event loop driving a single task. |
supervisor.py |
WorkerSupervisor |
Daemon lifecycle: pidfile, log rotation, graceful shutdown. |
scheduler.py |
StepScheduler, SchedulerConfig |
Bounded-concurrency dispatch (asyncio.Semaphore). |
launcher.py |
AgentLauncher (Protocol), DryRunLauncher, LaunchResult |
Launcher interface + test stub. |
claude_launcher.py |
ClaudeCodeLauncher, ClaudeCodeConfig |
Real claude CLI subprocess launcher. |
headless.py |
HeadlessClaude, HeadlessConfig, HeadlessResult |
Synchronous claude --print wrapper used by Forge and baton execute run. |
context.py |
ExecutionContext |
Wires EventBus, engine, and EventPersistence correctly. |
decisions.py |
DecisionManager |
Persists human decision requests. |
signals.py |
SignalHandler |
POSIX SIGTERM/SIGINT graceful shutdown. |
daemon.py |
daemonize() |
Classic UNIX double-fork. |
tenancy_context.py |
tenancy helpers | F0.2 tenancy attribution. |
_redaction.py |
redaction helpers | Strips API keys from launcher stderr. |
core/orchestration/ — agent discovery and routing¶
| Module | Class | Purpose |
|---|---|---|
registry.py |
AgentRegistry |
Loads .md agents from ~/.claude/agents/ and .claude/agents/ (project takes precedence). |
router.py |
AgentRouter, StackProfile |
Stack detection (PACKAGE_SIGNALS, FRAMEWORK_SIGNALS); flavored agent routing. |
context.py |
ContextManager |
Manages .claude/team-context/ files. |
knowledge_registry.py |
KnowledgeRegistry, _TFIDFIndex |
Knowledge-pack discovery and TF-IDF index. |
core/storage/ — persistence and federation¶
| Module | Class / function | Purpose |
|---|---|---|
__init__.py |
get_project_storage(), detect_backend(), get_pmo_central_store(), get_central_storage(), get_sync_engine() |
Backend factories. |
protocol.py |
StorageBackend (Protocol) |
34-method persistence interface. |
sqlite_backend.py |
SqliteStorage |
SQLite implementation; 31-table project schema. |
file_backend.py |
FileStorage |
Legacy JSON/JSONL implementation. |
schema.py |
PROJECT_SCHEMA_DDL, CENTRAL_SCHEMA_DDL, MIGRATIONS |
DDL constants. |
connection.py |
ConnectionManager |
WAL-mode helper, schema migrations. |
queries.py |
QueryEngine |
Ad-hoc SQL with structured helpers. |
migrate.py |
StorageMigrator |
Schema-version migrations. |
migration_backup.py |
(backup helpers) | Pre-migration snapshots. |
sync.py |
SyncEngine, SyncTableSpec, SyncResult, auto_sync_current_project() |
Incremental one-way sync project → central. |
central.py |
CentralStore |
Read-only central.db query interface. |
derived_bead_store.py |
DerivedBeadStore (line 71) |
Rebuildable bead analytics (edges/clusters/handoffs) in baton-derived.db, derived from the bd system of record. |
pmo_sqlite.py |
PmoSqliteStore |
PMO data store (lives in central.db). |
user_store.py |
(user store) | users + approval_log (in central.db). |
conflict_store.py |
(conflict store) | Bead-conflict persistence. |
handoff_store.py |
(handoff store) | Wave 3.2 handoff beads. |
release_store.py |
(release store) | Release artifact tracking. |
slo_store.py |
(SLO store) | SLO targets and observations. |
deployment_profile_store.py |
(deployment profiles) | Per-environment deployment profiles. |
adapters/__init__.py |
ExternalSourceAdapter (Protocol), ExternalItem, AdapterRegistry |
External work-tracker interface. |
adapters/ado.py |
AdoAdapter |
Azure DevOps adapter. |
core/events/ — pub/sub event bus¶
| Module | Class / function | Purpose |
|---|---|---|
bus.py |
EventBus |
In-process pub/sub with glob topic routing. |
events.py |
19 event factories | step_dispatched(), step_completed(), gate_passed(), etc. |
persistence.py |
EventPersistence |
Append-only JSONL log per task. |
projections.py |
project_task_view(), TaskView, PhaseView, StepView |
Materialized views for dashboards. |
core/observe/ — observability¶
| Module | Class | Purpose |
|---|---|---|
trace.py |
TraceRecorder, TraceRenderer |
Per-task DAG tracing. |
usage.py |
UsageLogger |
TaskUsageRecord JSONL appender. |
telemetry.py |
AgentTelemetry, TelemetryEvent |
Tool-call/file-op telemetry. |
dashboard.py |
DashboardGenerator |
Markdown dashboard renderer. |
retrospective.py |
RetrospectiveEngine |
Auto-generated post-task retros. |
context_profiler.py |
ContextProfiler |
Per-agent context-efficiency metrics. |
archiver.py |
DataArchiver |
Retention-based cleanup. |
incidents.py |
(incident store) | Production incidents. |
jsonl_scanner.py |
(scanner) | Fixes the usage counter from raw JSONL. |
pagerduty.py |
(PD shipper) | PagerDuty alerts. |
prometheus.py |
(metrics) | Prometheus exposition. |
slo_computer.py |
(SLO computer) | Computes SLOs from usage. |
cost_forecaster.py |
(forecaster) | Token-cost projection. |
core/observability/ — OTel and FinOps¶
| Module | Class | Purpose |
|---|---|---|
otel_exporter.py |
OTelJSONLExporter, current_exporter() |
OTLP-shaped JSONL spans (env-gated by BATON_OTEL_ENABLED). |
chargeback.py |
ChargebackBuilder, ChargebackReport |
F0.2 cost attribution by org/team/project/user/cost_center. |
attribution_coverage.py |
CoverageScanner, AttributionCoverageReport |
% of usage_records rows with non-default tenancy. |
prometheus.py |
(metrics) | OTel-side Prometheus support. |
core/govern/ — policy and compliance¶
| Module | Class | Purpose |
|---|---|---|
classifier.py |
DataClassifier, ClassificationResult |
Auto-classifies risk + guardrail preset. |
policy.py |
PolicyEngine, PolicyRule, PolicyViolation, PolicySet |
5 built-in presets; rule types path_block/path_allow/tool_restrict/require_agent/require_gate. |
compliance.py |
ComplianceReportGenerator, ComplianceEntry, ComplianceReport |
Compliance report builder. |
validator.py |
AgentValidator, ValidationResult |
Agent-frontmatter validator. |
spec_validator.py |
SpecValidator, SpecCheck, SpecValidationResult |
Spec-callable validation. |
escalation.py |
EscalationManager |
Escalation history. |
override_log.py |
(override log) | Hash-chained compliance audit log. |
aibom.py |
(AI BOM) | AI Bill of Materials emission. |
budget.py |
(budget guards) | Token-budget enforcement. |
_redaction.py |
redaction helpers | PII/secret redaction. |
core/improve/ — agent improvement loop¶
| Module | Class | Purpose |
|---|---|---|
scoring.py |
PerformanceScorer, AgentScorecard, TeamScorecard |
Per-agent + per-team health ratings. |
vcs.py |
AgentVersionControl, ChangelogEntry |
Agent definition versioning + changelog. |
loop.py |
ImprovementLoop |
Consolidated ImprovementReport builder. |
proposals.py |
ProposalManager |
Recommendation lifecycle. |
rollback.py |
RollbackManager, RollbackEntry |
Undo snapshots for applied changes. |
triggers.py |
TriggerEvaluator |
Auto-trigger conditions. |
conflict_detection.py |
(conflict detection) | Bead-graph conflict mining. |
cost_anomaly.py |
(anomaly detection) | Cost-spike alerting. |
handoff_score.py |
(handoff scoring) | Wave 3.2 handoff quality. |
maintainer.py |
(maintainer) | Long-running improvement housekeeping. |
new_metrics.py |
(metrics) | Newer scorecard metrics. |
readiness.py |
(readiness) | Production-readiness checks. |
core/learn/ — closed-loop learning¶
| Module | Class | Purpose |
|---|---|---|
pattern_learner.py |
PatternLearner |
Mines LearnedPattern from usage logs. |
budget_tuner.py |
BudgetTuner |
Recommends budget tier changes. |
engine.py |
LearningEngine |
Closed-loop detect → analyze → apply orchestrator. |
ledger.py |
LearningLedger |
SQLite CRUD for LearningIssue. |
overrides.py |
LearnedOverrides |
learned-overrides.json reader/writer. |
resolvers.py |
resolve_* functions |
Type-specific resolution strategies. |
interviewer.py |
LearningInterviewer |
Structured CLI dialogue for human-directed decisions. |
recommender.py |
Recommender |
Unified recommendation aggregator. |
bead_analyzer.py |
BeadAnalyzer |
Mines historical beads → PlanStructureHint. |
signals.py |
(signal helpers) | Learning-signal parsing. |
core/intel/ — intelligence helpers¶
| Module | Class | Purpose |
|---|---|---|
bead_synthesizer.py |
BeadSynthesizer |
Wave 2.1 — bead graph (edges + clusters), deterministic. |
handoff_synthesizer.py |
HandoffSynthesizer |
Wave 3.2 — compact handoff section between steps. |
debate.py |
(debate runner) | D4 multi-agent debate (opt-in, never auto-invoked). |
knowledge_ranker.py |
KnowledgeRanker |
Re-orders knowledge candidates by effectiveness × recency × usage (bd-0184). |
context_harvester.py |
(harvester) | Context-file discovery from history. |
core/pmo/ — portfolio management overlay¶
| Module | Class | Purpose |
|---|---|---|
store.py |
PmoStore |
Reads/writes PMO config + completed-plan archive. |
scanner.py |
PmoScanner |
Builds Kanban board state from registered projects. |
forge.py |
ForgeSession |
Consultative plan creation with SSE progress streaming. |
core/distribute/ — packaging and registry¶
| Module | Class | Purpose |
|---|---|---|
sharing.py |
PackageBuilder, PackageManifest |
Builds .tar.gz distributable packages. |
packager.py |
PackageVerifier, PackageDependency, EnhancedManifest, PackageValidationResult |
Checksum + dependency validation. |
registry_client.py |
RegistryClient |
Local-registry directory manager. |
experimental/async_dispatch.py |
AsyncDispatcher, AsyncTask |
Experimental — not exercised in production. |
experimental/incident.py |
IncidentManager, IncidentPhase, IncidentTemplate |
Experimental P1-P4 incident templates. |
experimental/transfer.py |
ProjectTransfer, TransferManifest |
Experimental cross-project transfer. |
core/gates/ — CI gate runners¶
| Module | Class | Purpose |
|---|---|---|
ci_gate.py |
CIGateRunner (line 171), CIGateResult (line 63), parse_ci_gate_config() (line 121) |
Polls gh run list/view every 15s; opt-in CI gate. |
core/audit/ — post-hoc compliance¶
| Module | Class | Purpose |
|---|---|---|
dispatch_verifier.py |
DispatchVerifier |
Read-only worktree-isolation compliance (baton execute verify-dispatch, audit-isolation). |
core/exec/ — sandboxed command execution¶
| Module | Purpose |
|---|---|
runner.py |
Shell command runner with whitelist environment. |
sandbox.py |
Process sandbox helpers. |
script_lint.py |
Lints command scripts before execution. |
auditor_gate.py |
Auditor-driven execution gate. |
core/knowledge/ — knowledge lifecycle¶
| Module | Purpose |
|---|---|
lifecycle.py |
Pack create/update/retire lifecycle. |
effectiveness.py |
Knowledge-effectiveness telemetry. |
ab_testing.py |
A/B testing of knowledge variants. |
adr_harvester.py |
Mines ADRs into knowledge docs. |
review_harvester.py |
Mines code reviews into knowledge docs. |
codebase_brief.py |
Generates codebase brief documents. |
core/immune/ — incident detection¶
| Module | Purpose |
|---|---|
daemon.py |
Long-running incident-detection daemon. |
triage.py |
Auto-triages new incidents. |
scheduler.py |
Schedules sweeps. |
sweeper.py |
Periodic state sweeper. |
cache.py |
Decision cache. |
core/release/ — release readiness¶
| Module | Purpose |
|---|---|
readiness.py |
Release-readiness assessment. |
mrp.py |
Minimum Release Plan generator. |
notes.py |
Auto-generated release notes. |
profile_checker.py |
Deployment-profile compatibility check. |
conflict_predictor.py |
Predicts merge conflicts before release. |
core/specs/ — spec storage¶
| Module | Purpose |
|---|---|
store.py |
Spec document store. |
core/config/ — project config¶
| Module | Class | Purpose |
|---|---|---|
project_config.py |
ProjectConfig |
Optional baton.yaml loader (walks up from cwd). |
manager.py |
ManagerConfig |
Manager-mode PMO config (manager_mode/team/scoping/context/knowledge_packs/policies/gates/reporting sections) from the same baton.yaml; fails early on invalid values. |
core/manager/ — manager-mode PMO layer¶
Post-processor around IntelligentPlanner.create_plan() output — see
docs/internal/manager-mode-pmo-design.md.
Config lives in core/config/manager.py
(above); Pydantic models live in
models/manager.py (below).
| Module | Class | Purpose |
|---|---|---|
planner.py |
ManagerModePlanner |
Orchestrates the builders below; single entry point called from plan_cmd.py. |
charter.py |
ProjectCharterBuilder |
Deterministic project charter from task summary, classifier output, and detected stack. |
scope.py |
ScopeMapBuilder |
Workstream decomposition of the plan's phases. |
team_blueprint.py |
TeamBlueprintBuilder |
Team composition, role cards, and workstream-owner assignment. |
role_cards.py |
render_role_card() |
Role-card Markdown renderer. |
context_bundles.py |
ScopeContractBuilder, is_nontrivial_step() |
Per-step scope contract + context bundle builders (token-budget-aware). |
knowledge_plan.py |
KnowledgePlanBuilder, audit_packs() |
Wraps KnowledgeRegistry/KnowledgeResolver; missing/stale pack detection; backs baton knowledge list/scan/show/audit/propose. |
phase_policy.py |
PhasePolicyApplier |
The only PMO component that mutates the MachinePlan graph — injects adversarial-review steps and rescopes gates per ManagerConfig.policies/gates. |
reports.py |
ManagerReportBuilder |
Builds manager-brief.md (post-planning) and manager-report.md (during/after execution); backs baton report and baton team. |
decisions.py |
DecisionPacketBuilder |
Typed ManagerDecision wrapper over core/runtime/decisions.py::DecisionManager; appends decision-log.jsonl. |
artifacts.py |
ManagerArtifacts, write_all() |
Sidecar artifact container + writer (traversal order also used for --dry-run/--save previews). |
paths.py |
ManagerArtifactPaths |
Single source of truth for sidecar file paths under executions/<task_id>/. |
enrich.py |
maybe_enrich_charter() |
Optional BATON_MANAGER_ENRICH LLM polish of charter wording; stub/off by default. |
agent_baton/api/ — Layer 4a¶
create_app() factory in api/server.py
returns a FastAPI application. Singleton DI lives in
api/deps.py.
| Subdirectory | Modules |
|---|---|
api/middleware/ |
auth.py (TokenAuthMiddleware), cors.py (configure_cors()), user_identity.py (UserIdentityMiddleware) |
api/routes/ |
health.py (2), plans.py (2), executions.py (6), agents.py (2), observe.py (3), decisions.py (3), events.py (1), webhooks.py (3), pmo.py (36), pmo_h3.py (6), learn.py (5) |
api/models/ |
requests.py (Pydantic request bodies), responses.py (Pydantic responses) |
api/webhooks/ |
dispatcher.py (WebhookDispatcher), registry.py (WebhookRegistry), payloads.py |
Endpoint count: 64 across 10 main route modules + 6 H3-PMO endpoints.
agent_baton/cli/ — Layer 4b¶
cli/main.py auto-discovers commands
via pkgutil.iter_modules from
cli/commands/. Each module exports
register(subparsers) and handler(args).
| Group | Directory | Top commands |
|---|---|---|
| Execution | commands/execution/ |
execute, plan, status, daemon, async, decide |
| Observability | commands/observe/ |
dashboard, trace, usage, telemetry, context-profile, retro, cleanup, migrate-storage, context, query |
| Governance | commands/govern/ |
classify, compliance, policy, escalations, validate, spec-check, detect |
| Improvement | commands/improve/ |
scores, evolve, patterns, budget, changelog, anomalies, experiment, improve, learn |
| Distribution | commands/distribute/ |
package, publish, pull, verify-package, install, transfer |
| Agents | commands/agents/ |
agents, route, events, incident |
| Top-level | commands/ |
pmo, sync, query, source, serve, beads, uninstall |
The CLI output contract is _print_action() at
cli/commands/execution/execute.py:568
— the public API surface read by Claude.
Cross-cutting load-bearing files¶
If you change one of these you change a contract.
| File | What it defines |
|---|---|
agent_baton/__init__.py |
The package's public re-exports. |
agent_baton/core/__init__.py |
The core layer's re-exports + layer documentation. |
agent_baton/models/execution.py |
The plan and state shape. |
agent_baton/core/engine/protocols.py |
The runtime↔engine contract (ExecutionDriver). |
agent_baton/core/storage/protocol.py |
The persistence contract (StorageBackend). |
agent_baton/cli/commands/execution/execute.py |
The Claude-facing wire format (_print_action()). |