New Capability: Codified Agent Onboarding Process
Date: April 12, 2026 Origin: Corrective Action Report -- Hone's onboarding hit 3/10 registration points before Chris caught it Impact: Every new AI agent is now fully registered across all 13 systems in one pass, with no registration points missed
What Was Built
The Value-First Team codified a complete agent onboarding process, transforming what was previously an ad-hoc, recall-dependent activity into a 13-point structural checklist owned by a single agent. Before today, when a leader created a new agent, downstream registration across documentation, databases, CMS, CRM, and website data depended entirely on whichever agent performed the work remembering every registration point from context. During Hone's onboarding earlier today, that approach failed decisively: Aegis declared onboarding "complete" after addressing only 3 of approximately 10 registration points, wrote to a deprecated file without reading its header, and a HubSpot task was assigned to the wrong person. Chris caught all three failures manually.
The response was structural, not behavioral. Aegis's agent definition (.claude/agents/aegis.md) was rewritten with a mandatory 13-point checklist, a delegation model specifying who owns each step, and a read-before-write rule for unfamiliar files. A new implementation spec (agents/organizational-enablement/AGENT.md) was created with a 5-phase workflow (Intake, Documentation, Artifacts, External Registration, Verification) that walks through every registration point mechanically. The deprecated org-roster.yaml file was deleted entirely -- it was stale by 15+ agents and served as an attractive nuisance for agents who encountered it without reading its deprecation header.
The delegation model is the architectural centerpiece. Aegis performs steps 3 through 10 directly (INDEX.md, Dewey index, MEMORY.md, job descriptions, org chart HTML, website data, Agent Office DB). Steps 11 and 12 are delegated to Ledger (HubSpot Friend record creation) and Canon (Sanity contributor record creation) respectively -- Aegis never writes to HubSpot or Sanity directly. Step 13 is a verification pass where Aegis re-reads or queries every target to confirm the entry appeared. Onboarding cannot be reported as complete until all 13 steps are addressed and verified.
Infrastructure Changes
| Area | Before | After |
|---|---|---|
| Onboarding process | Implicit, depends on agent recall | 13-point checklist, mechanically followed |
| Onboarding ownership | No single owner | Aegis owns end-to-end; leaders provide only steps 1-2 |
| Registration completeness | 3/10 on Hone's first attempt | Structural checklist prevents partial completion |
org-roster.yaml |
Deprecated but present (attractive nuisance) | Deleted. Canonical sources: INDEX.md + ai-team-structure.ts |
| Deprecated file protection | None | Read-before-write rule for unfamiliar files |
| HubSpot write governance | Aegis could theoretically write directly | Explicit rule: all CRM writes through Ledger |
| Sanity write governance | Aegis could theoretically write directly | Explicit rule: all CMS writes through Canon |
| Verification standard | Declared complete without proof | 12-target verification pass required |
Implementation
| File | Purpose |
|---|---|
.claude/agents/aegis.md |
Rewritten agent definition: 13-point checklist, delegation model table, read-before-write rule, CAR reference |
agents/organizational-enablement/AGENT.md |
New implementation spec: 5-phase workflow, output templates, team interactions, validation gates |
Leadership/reports/2026-04-12-corrective-incomplete-agent-onboarding.md |
CAR documenting the incident, root cause, and 10 prior verification-failure incidents |
Usage
Onboard a new agent (after leader creates agent def + AGENT.md):
Spawn Aegis (subagent_type: "aegis"):
"Onboard agent {codename}. The agent definition is at .claude/agents/{codename}.md
and the implementation spec is at agents/{directory}/AGENT.md. Complete all 13
registration points and report status for each."
Run a health check (drift detection):
Spawn Aegis (subagent_type: "aegis"):
"Run agent roster health check. Count reconciliation across all sources,
name reconciliation, and property reconciliation. Report drift."
Verify a single agent's registration:
Spawn Aegis (subagent_type: "aegis"):
"Verify registration completeness for {codename}. Check all 13 points
and report which are present and which are missing."
Leader Applications
V (Operations)
When V creates a new Operations org agent (agent def + AGENT.md), V hands off to Aegis for the remaining 11 registration steps. V no longer needs to track which files, databases, or external systems require updates. The delegation model ensures V's agents are fully registered without V performing any downstream work.
Sage (Customer)
Aegis reports to Sage and operates within the Customer org's Organizational Experience group. Sage directs Aegis for weekly health checks to ensure agent data consistency across Sanity (the website source of truth), HubSpot Friend records, INDEX.md, and the Agent Office DB. When Sage creates Customer org agents, the same handoff applies.
Pax (Finance)
When Pax creates Finance org agents, the handoff to Aegis is identical. No direct application beyond agent creation handoff -- Pax's domain (revenue, compliance, capacity) does not intersect with agent lifecycle management.
Dependencies
| Dependency | Role | Status |
|---|---|---|
| Ledger | HubSpot write gateway -- creates Friend record | Confirmed operational |
| Canon | Sanity write gateway -- creates contributor record | Confirmed operational |
| Owning leader | Creates agent def + AGENT.md before Aegis begins | Process requirement |
skills/ai-leadership/INDEX.md |
Agent roster -- Aegis adds entries and updates counts | Confirmed |
.claude/codebase-index.md |
Dewey index -- Aegis updates sections 390 + domain | Confirmed |
data/agent-office.db |
SQLite agent registry | Confirmed |
apps/website/src/data/ai-team-structure.ts |
Website team page data | Confirmed |
Related Incidents
This is the 10th incident in the "declaring multi-step processes complete without end-to-end verification" pattern family, across 3 sub-patterns:
| Sub-Pattern | Prior Incidents |
|---|---|
| Multi-step completion without verification | Paragon data drift (Mar 10), HubSpot course integrity (Mar 12), Inngest pipeline (Mar 30), Founding Pathfinder payments (Apr 9) |
| Writing/asserting without reading state | Portal documents filter (Mar 2), Sanity write context loss (Mar 11), All-hands duplicate properties (Mar 14) |
| Using defaults without verifying applicability | Supabase connectivity (Mar 15), URL assumption (Mar 16), Meeting documentation dual role (Apr 9) |
Cross-cutting lesson: behavioral prevention (rules, memory entries, self-correction triggers) has a ceiling. After 6 escalating behavioral fixes, the only effective resolution was structural enforcement. The 13-point onboarding checklist is the structural fix for this instance.
Verification
- Checklist exists:
Grep "Registration Points" .claude/agents/aegis.md-- 13 numbered items - Delegation model exists:
Grep "Delegation Model" .claude/agents/aegis.md-- table mapping steps to owners - Implementation spec exists:
agents/organizational-enablement/AGENT.md-- 5 phases present - Read-before-write rule codified:
Grep "read-before-write" .claude/agents/aegis.md - CAR reference embedded:
Grep "2026-04-12-corrective" .claude/agents/aegis.md - Baseline roster: 89 agent definitions, 87 Sanity contributors (2 gap to be closed on next health check)
Filed by: V (COO) Capability Owner: Aegis (Organizational Enablement) Review: Chris Carolan (Advisory Committee)