build-platform-agent — the reusable platform-agent builder
A platform agent = a real staff-account AI identity in this system: a real
AiAgent registry row, a real AdminUser/Enrollment/CommunityMember identity
triple, a system prompt, and (once wired) real ProofDesk ticket-linkage and a real
Agent Detail transparency page at /admin/agents/:id. Reese is the first real
agent built this way (Phase 1: identity/DM/ticket-linkage/transparency — PR #1251,
live; Phase 2: signal-driven autonomous outreach — PR #1319, live). This skill takes
as little as a name + one line of intent and produces a complete, previewed agent
identity — reusing the exact shared modules Reese's own Phase 1 code now calls.
THE non-negotiable boundary (read first)
This skill's default mode is PREVIEW. Running it produces a draft config, a draft
system prompt, and a dry-run identity-seed report — zero real AiAgent rows, zero real
staff accounts, zero real messages sent. Committing a real identity (calling
seedAgentIdentity() for real, adding a real AGENT_REGISTRY entry) is a SEPARATE,
explicit step that requires the producer to say so outright — never inferred from "the
preview looked good." Any capability beyond reactive identity/reply (DM-initiation,
autonomous outreach, any outbound communication) additionally requires Ali's sign-off
before that agent's AiAgent.enabled flag is ever set true in production — see the
Governance checklist below and docs/PROOFDESK_STATUS.md's matching section.
Step 0 — is this really a new agent?
Before drafting anything, check: does the requested capability already belong to an
existing agent? A real case from this repo (2026-09-04): Ali asked to review the
"Reese family" of agents for sprawl. Three separately-registered AiAgent rows
(ReeseAutonomousOutreachSweep, ReeseOutreachFollowUps,
ReeseStudentSupportSupersessionResolver) looked like 3 extra agents but turned out
to be the SAME Reese identity, persona, and largely the same code — just 3
independently-pausable cron entry points for 3 distinct behaviors, each with no
system_prompt/tools_granted/reports_to of its own. The real gap that turn
uncovered was different: ReesePresenceHeartbeat, a live cron that had been calling
instrumentCronJob('ReesePresenceHeartbeat', ...) every minute since Phase 1 with
no matching AiAgent row at all — silently running untracked, no kill switch, no
monitoring. The fix wasn't a new agent identity; it was one missing registry row.
Ask, in order:
- Is this a new persona/identity (something that should talk to students or managers, have its own voice, own tickets)? → proceed with this skill's full identity build below.
- Is this a new scheduled/on-demand BEHAVIOR of an agent that already has an
identity (like Reese's 3 legitimate cron kill-switches)? → it may only need its
own
AGENT_REGISTRYrow (for the pause switch + observabilityinstrumentCronJob()already gives any registered name — seereferences/trust-and-hierarchy.md's "Registering a behavior, not an identity"), reusing the parent agent's existingsystem_prompt/AdminUser/persona. Do not build a second full identity for it. - Is a cron/job already calling
instrumentCronJob('<name>', ...)with no matching registry row? GrepagentRegistrySeed.tsfor the exact name before assuming it needs anything built at all — it may just need registering.
Only proceed past this point once the answer is genuinely "new identity."
What to say to run it
Give me the two required lines; everything else has a sane default I derive.
- name — e.g. "CurriculumQA" (becomes
agentName/displayName;email=slugify(name)@colaberry.com= the idempotency key downstream). - intent — one line: what the agent does and why it exists.
Optionally override any Tier-2/3 field below.
The KEY runtime facts (author against these — do not fight them)
- Identity is 4 real rows, not a special case.
AdminUser(roleai_staff,is_ai_operated: true,agent_idlinked back to theAiAgentrow) is the SAME model real human staff use.Enrollment(required FK target forCommunityMember) andCommunityMember(presence row) exist so the agent shows up in the People panel and can hold a DM room, exactly like a real staff member. - The
AiAgentregistry row must exist FIRST.seedAgentIdentity()(backend/src/services/agentBlueprint/agentIdentitySeed.ts) throws if it doesn't — by design, a fail-loud guard against an orphaned identity. The registry entry is added toAGENT_REGISTRYinbackend/src/services/agentRegistrySeed.ts(currently ~150+ entries; Reese's ownseedReeseIdentity()call is wired in at line ~2305, right after theAGENT_REGISTRYfindOrCreate loop inseedAgentRegistry()). This is a real code change (one array entry + one seed-call line), not a config toggle — flag it as the first concrete implementation step once a real commit is approved. - The transparency page is ALREADY generic — confirmed, not assumed.
backend/src/services/reese/agentDetailService.ts'sgetAgentDetail(agentId), its route (GET /api/admin/agents/:id, mounted inbackend/src/routes/admin/agentDetailRoutes.tsviaadminRoutes.ts), and the frontend consumer (frontend/src/pages/admin/AgentDetailPage.tsx+frontend/src/services/agentDetailApi.ts) contain no agent-name string literals in logic — only a header comment. It degrades gracefully (empty, not broken) for anyAiAgentrow that doesn't yet have the full identity linkage. No code change is needed here for a new agent — it lights up automatically once identity/prompt/ tickets exist for the new agent'sAiAgent.id. What it needs from YOUR new agent to show real data (not empty fields):system_prompt/tools_granted/persona_versionpopulated on theAiAgentrow (identity-seed does this), a linkedAdminUser(viaagent_id), and tickets usingassigned_to_type: 'ai_staff'+assigned_to_id= the agent's realAdminUser.id(the ticket-linkage module does this automatically). - Reactive vs. proactive is a real fork, not a toggle. Identity + a reply loop (agent responds when messaged) is the reactive baseline every agent gets. Proactive/ autonomous behavior (the agent initiates contact on its own) is a SEPARATE, much more agent-specific build — see "If this agent needs to be proactive" below. Do not build proactive capability just because it's possible; most agents built from this skill should stay reactive-only.
- Identity and trust/hierarchy are two separate layers — don't conflate them.
Everything above (AdminUser/Enrollment/CommunityMember/system_prompt) makes the
agent EXIST and be able to talk. It says nothing about who it reports to, what
it's allowed to do, or how trustworthy it is — that's a second, mostly-independent
layer:
reports_to_type/reports_to_id(org chart), a permission tier (AGENT_PERMISSIONSinagentPermissionService.ts), an autonomy level (inert until explicitly activated — see below), and GOALS™ evidence quality. A brand-new agent with perfect identity but no reports-to/permission-tier wiring is real and functional but organizationally invisible and defaults to the most restrictive tier. Seereferences/trust-and-hierarchy.mdfor the full mechanics; step E.5 below is where this actually gets set. system_promptfeeds TWO different conversation paths, not one. The manager- conversation prompt (agentManagerConversationPrompt.ts, the Admin > Agents > Talk tab) readsAiAgent.system_promptDIRECTLY — set it on the registry entry and managers can talk to this agent immediately, no extra file needed. The student/learner-facing prompt (agentSystemPrompt.ts, what Derivation rule 2 below builds) is DIFFERENT — it takes apersonaBlockas a plain function argument, never reads the DB column at all. Setting onlysystem_promptgets you a working manager conversation but NOT a working student conversation, and vice versa — most agents need both, built separately.- The Talk tab's real ACTIONS (goal-setting, 1:1 scheduling, standing directives,
task assignment, approve/reject) are free the moment
system_promptworks — no per-agent wiring. All eight manager-intent classifiers are generic, keyed onagentIdalone, with zero agent-specific code anywhere in them. Seereferences/trust-and-hierarchy.md's "Manager-conversation ACTIONS are free" section — do not add a step to this skill's build flow to "wire up" these capabilities; there is nothing to wire for a new agent. - The Trust & Control tab's Role Charter (
AgentRoleCharter) is real, manager- authored, and NOT seeded automatically — same posture as the other 5 manager-authored tables (AgentGoal/AgentOneOnOne/AgentReportSubscription/AgentMemoryProposal/ManagerDirective), now 6 total. A brand-new agent's charter readscharter: nullhonestly until a manager writes one viaPUT /api/admin/agents/:id/charter. Unlike the other 5 (where an honest empty state is fine), consider filling this one out at build time if the new agent's purpose is already well understood — seereferences/trust-and-hierarchy.md's table for the exact field shape and limits. tools_grantedhas no enum — reuse the existing tool chest before inventing a new tool name.backend/src/services/reese/agentToolCapabilities.ts'sTOOL_CAPABILITIESis the real, shared registry every agent's transparency page reads/produces view is derived from (35 real tool strings documented as of 2026-09-04). Check there first: if an existing tool's real reads/produces already match what your new agent's capability actually does, grant that same tool name — don't inventmy_agent_does_the_thing_v2. Only add a newTOOL_CAPABILITIESentry when the capability is genuinely new, grounded in the real implementing code, same as every existing entry. A tool granted but never added there isn't silently dropped — it surfaces honestly asundocumentedToolson the transparency page — but that's a signal to go document it, not a shippable end state.
Parameters
Tier 1 — required
name, intent.
Tier 2 — shape (override the derivation)
email (default slugify(name)@colaberry.com), role (AdminUser.role, default
'ai_staff'), communityRole (CommunityMember.role — one of 'student' | 'mentor' | 'staff', default 'mentor'), agentType (AiAgent.agent_type — a free-form string;
Reese used 'ai_staff_mentor', added as a new literal at the end of the existing
AiAgentType union in backend/src/models/AiAgent.ts since it's a closed type, not a
DB enum — a new agent with a genuinely new role shape adds its own literal the same
way), category (AiAgent.category — Reese used 'student_success'), enrollmentDefaults
(company/payment_status/payment_method/payment_mode/enrollment_type/
portal_enabled — Reese's own honest-placeholder values: 'Colaberry' /
'paid'/'invoice'/'live'/'standard'/false, safe defaults for any
non-transactional staff row), proactive (boolean, default false — see below),
reportsTo (exactly one of: a real org_members.id this agent reports to directly
as AI Leadership, or the exact agent_name of an already-registered agent it reports
through as AI Staff — never both, never neither; see step E.5), department
(AiAgent.department — a real column, distinct from category; leave unset rather
than guessing if none of the ~existing values genuinely fit), permissionTier (one
of read_only/suggest_only/write_with_audit/communication — see step E.5;
silently accepting the DEFAULT_PERMISSION fallback, suggest_only, without
deciding is a real gap this repo has already hit, not a safe default to assume).
Tier 3 — fine (leave blank to auto-generate)
personaBlock (the full voice/persona text — see Derivation rule 2), closingLine
(the conversational-framing sentence appended after persona + learner context; default
mirrors Reese's DM framing — override if the new agent's surface isn't a DM thread),
toolsGranted (AiAgent.tools_granted JSONB array — empty [] by default; only
populate once the agent actually has tool access to declare on its transparency page),
ticketType (a TicketType literal the agent's ticket-linkage will use — must be a
real value from backend/src/models/Ticket.ts's union, e.g. 'student_support' for a
student-facing agent, 'curriculum' for a content-review agent; add a new literal to
that union if none fits, the same way Reese Phase 2 added 'reese_autonomous_outreach'),
entityType (a free-form string tag for the ticket's entity_type/entity_id dedup
key — Reese used 'community_room'), pilotCohortGate (boolean, default false —
only turn on if proactive: true and the agent needs an eligible-population gate).
Derivation rules (fill every blank before writing)
- Identity config, built from Tier 1/2 inputs, in the exact shape
agentBlueprint/agentIdentitySeed.ts'sAgentIdentityConfigexpects:{ agentName, email, displayName, role, communityRole, enrollmentDefaults, pilotCohortGate }. - Persona block, written against
docs/CORY_PERSONA_SPEC.md's locked pattern (the spec Reese's own voice was transplanted from, name-swapped): aVOICE PRINCIPLES (locked)section and aGUARDRAILS (never do these)section, always including "never pretend to be human or hide that you are an AI" and a neutral- pronoun ("they/them") line — these two are non-negotiable across every agent built this way, not just Reese's. Everything else in the persona is genuinely agent-specific — do not copy Reese's exact voice for a different agent, derive a new one matched to the new agent's actual job. - Ticket-linkage shape:
title/descriptiontemplates,ticketType,entityType— mirrorreeseTicketLinkService.ts'sensureReeseTicketForRoom()as the worked example, substituting the new agent's own domain language.
Execution (idempotent, key on agentName/email)
A. Preview first, always. Call previewAgentIdentity(config)
(backend/src/services/agentBlueprint/agentIdentitySeed.ts) — read-only, zero
writes by construction (only ever calls .findOne, never findOrCreate/create/
update). Report aiAgent.exists — if false, the AGENT_REGISTRY entry doesn't
exist yet, and that's the real next step, not a bug in the preview.
B. Call buildAgentSystemPrompt(personaBlock, previewEnrollmentId, { agentLabel, closingLine }) (backend/src/services/agentBlueprint/agentSystemPrompt.ts) with a
placeholder/non-existent enrollment id — the graceful-degradation path returns a
valid persona-only prompt (proven in this skill's own worked example, see below),
which is the honest state for a brand-new agent with no conversation history yet.
C. Describe (do not create) what the Agent Detail transparency page would show once
real — grounded in step A's real preview ids, per "The KEY runtime facts" above.
D. Report back (see Output section) and STOP. Do not call seedAgentIdentity()
for real, do not add the AGENT_REGISTRY entry, do not create anything — that is a
separate, explicit step (E-H below), only taken when the producer says so outright.
E. (real commit, explicit step only) Add one AGENT_REGISTRY entry in
backend/src/services/agentRegistrySeed.ts and wire a seedAgentIdentity(config)
call after the registry loop in seedAgentRegistry(), mirroring
reeseIdentitySeed.ts's thin-wrapper pattern (export seedXxxIdentity(),
getXxxEnrollmentId(), getXxxAdminUserId(), delegating to the generic module —
do not duplicate the generic module's logic).
E.5. (real commit, REQUIRED) Wire trust & hierarchy on the same AGENT_REGISTRY
entry (step E) — this is not optional polish, it's the difference between a
working agent and an organizationally-invisible one:
reports_to: set exactly one ofreports_to_type: 'human'+reports_to_id: <org_members.id>(this agent is AI Leadership), orreports_to_type: 'agent'+reports_to_id: <existing AiAgent.id>(AI Staff, reporting through an agent that must already exist). Set viaseedAgentIdentity()'s self-heal (step E) or an explicit follow-up update — never leave both null on a ticket-creating agent,enforceReportsToGate()will reject its tickets. Verify the chain actually resolves to a real human (resolveReportsToHuman(), max 5 hops) before calling this done — a misconfigured chain fails closed (returnsnull), not loudly.- Permission tier: add an entry to
AGENT_PERMISSIONSinagentPermissionService.tskeyed on the exactagent_name, choosing one of the 4 real tiers deliberately. Skipping this is not a safe no-op — the agent silently getsDEFAULT_PERMISSION(suggest_only, effectively read+propose only,requiresEvaluateSend: false), which is fine for a genuinely low-trust agent but wrong for one that's supposed to write or communicate. department(the real column, notcategory): set if a genuine value fits; leavenullrather than forcing a guess —nullrenders honestly as "Unclassified" on the transparency page, which is more honest than a wrong guess.- Autonomy level — know that it's inert by default.
AiAgent.autonomy_level(DB default'observe') has ZERO effect on the live ABAC gate (agentAuthorizationService.ts) until something explicitly callsreactivateAgent()(agentReactivationService.ts), which stampsautonomy_level_set_atat the same time. Until then, effective autonomy is silently derived from the permission tier (step 2) vialevelForTier(). Do not setautonomy_levelon the registry entry expecting it to do anything — it won't, until a human deliberately runs the reactivation flow. - Full mechanics, the 4-rung autonomy ladder, HITL rules, and the GOALS™
live/fixed scoring detail:
references/trust-and-hierarchy.md. F. (real commit) Wire ticket-linkage: a thin wrapper file (mirroringreeseTicketLinkService.ts) callingensureAgentTicketForRoom()/logAgentExchangeActivity()(agentBlueprint/agentTicketLinkService.ts) with the new agent's own title/description/type/entityType/intent-prefix. G. (real commit) Wire a reply loop if the agent is conversational, mirroringreeseReplyService.ts's loop-guard/scope-guard pattern (never reply to your own messages; only reply within your own room membership). G.5. (real commit, REQUIRED if this agent creates tickets — see below) Satisfydirectives/register-ticket-creating-agent.md, the Agent Ticket Standard — codified from real bugs found and fixed in all 6 of this platform's other ticket-creating agents (cory-engine, CoryBrain, workforce_intelligence_engine, InboxCaseEngine, Reese, bpos_orchestrator) during the 2026-08-15–17 audit sweep. Any new agent that opens tickets (step F above) is exactly the kind of agent that standard governs — do not treat it as optional or "can add later." Concretely, before this agent is considered built: - The ticket-creation call's
entity_type/entity_id(or title) dedup key is stable across repeated cycles for the same finding — never a fresh id/UUID regenerated every run (the exact live bug PR #1554 fixed for cory-engine: 1,731 duplicate tickets from a dedup key keyed on a per-cycle decision id). tools_grantedon theAGENT_REGISTRYentry (step E above) lists this agent's real capabilities, re-verified against its actual code — not copied from a sibling entry.- If this agent's tickets ever need to close on anything other than a human
manually resolving them, the resolver re-derives the SAME live signal the
ticket was opened under. A ticket-age or elapsed-wall-clock-time check
("close after N days untouched") is permanently banned as a closure
condition in this codebase — it was removed once already for being
dishonest and this week's own history shows the temptation to reintroduce
it keeps recurring. Comparing two persisted timestamps to each other
(e.g. to order two records) is fine; comparing either to
Date.now()/new Date()to decide closure is exactly the forbidden pattern. - Register the resolver (if any) as a real
AiAgentcron row (trigger_type: 'cron', a realschedule) — or state in theAGENT_REGISTRYentry'sdescriptionexactly why none is needed. - Any bulk/historical ticket cleanup ships as
--plan/--apply/--revert, never a single irreversible script, and is proven idempotent by actually running--applytwice and confirming the second run makes zero additional writes. - Check the checkable subset of all of the above by running
backend/src/scripts/validateAgentTicketStandard.tsagainst this agent's realagentName(see that file's header for the exact invocation, both local/dev viats-nodeand production viadocker exec accelerator-backend node dist/scripts/validateAgentTicketStandard.js <agentName>). It is a read-only diagnostic, not a blocking gate — it reports PASS/FAIL/INFO per check; a FAIL means go fix the underlying thing, not silently ignore the output. H. (deploy + verify)tsc --noEmitboth stacks; unit tests (happy/failure/boundary/ idempotency per CLAUDE.md's Mandatory Test Types); deploy; confirm a real message exchange and a real linked ticket live, then confirm the Agent Detail page renders real (not empty) identity/prompt/tickets — the same close-out verification Reese Phase 1 used. If step G.5 applied, also runvalidateAgentTicketStandard.tsagainst the new agent live in production and attach its real output to this build'sdocs/sessions/CC-<id>.mdentry. Also confirm step E.5's wiring live, not just committed: query the realreports_to_type/reports_to_idand resolve it (resolveReportsToHuman()or an equivalent direct check) to a real human, confirm theAGENT_PERMISSIONSentry is actually being read (not silently falling toDEFAULT_PERMISSION), and if the agent talks to managers, send it one real message via the Talk tab and confirm the reply is grounded (not a generic refusal) — the same live verification pattern used for Reese's own recent-activity grounding (agentManagerConversationPrompt.ts, 2026-09-04). H.5. (deploy + verify, REQUIRED) Walk every realAgentDetailPagetab for the new agent — none of the steps above check this, and "does it actually work across the whole page" was an undocumented gap until this checkpoint (2026-09-10). Open/admin/agents/:idand click through all eight: At a Glance (real KPI tiles, no crash even with zero data everywhere), Live Status (operational state derives something real, even if "Unknown"), Overview (identity/system-prompt/ reports-to render, matching what steps E-F actually set), Work & Decisions (empty Manager Inbox renders honestly, not broken), Talk (send one real message — already covered above, but confirm the tab itself opens clean), Reports (subscribe form renders; the new Preview button, 2026-09-10, is a good extra check — click it with any section checked and confirm real content comes back, not an error), Performance (empty goals/1:1 lists render honestly), Trust & Control (Charter panel showsnull/empty honestly unless step E.5's charter-fill option was taken, in which case confirm the real written content renders). A tab that crashes or silently shows nothing where an honest empty state was expected is a real defect to fix before considering this agent built — not a follow-up. Also open the real Org Chart page and confirm the new agent appears in the correct position under itsreports_tochain (visual confirmation, not just the API-level check above).
If this agent needs to be proactive (initiates contact on its own)
Do not import Reese's autonomous-outreach code — it is deliberately domain-specific (student inactivity/completion/idle-event signals have no meaning for most other agents). Instead, treat these 6 files as the worked pattern to adapt, re-deriving each safety rail for the new domain rather than skipping any category:
| File (worked pattern) | What it shows |
|---|---|
reeseSignalService.ts |
How to define real, domain-grounded trigger conditions (not vague "check periodically") — re-derive your own signal(s) entirely. |
reeseEligibilityService.ts |
Eligible-population gate, fail-closed by design — isEligibleForAutonomousOutreach() never defaults to eligible on missing/ambiguous data (no pilot cohort configured → nobody eligible, checked BEFORE the enrollment lookup even runs). Re-derive your own gate; reuse the fail-closed principle, not the code. |
reeseAutonomousOutreachService.ts |
Cadence cap (CADENCE_DAYS) and daily send cap (DAILY_SEND_CAP) — both real, enforced, DB-checked constants. Also the dryRun parameter pattern (runs the full real decision pipeline, skips only the writes, honestly simulates shared caps) — the model for THIS skill's own preview mode. |
reeseOutreachFollowUpService.ts |
Follow-up/escalation cap (MAX_ATTEMPTS) — hits the cap → escalates to human review, never sends one more message past it and never silently gives up either. |
reeseOutreachMessageService.ts |
Grounding generated messages in real per-candidate data, never a fixed/templated string. |
reeseInitiateDmService.ts |
The thin wrapper pattern for agent-initiated contact, built on the platform's existing generic openDm()/sendDmMessage() — no new send plumbing needed. |
The 4 safety-rail categories every proactive agent must re-derive, not skip: cadence cap, daily send cap, an explicit eligible-population gate (fail-closed), a follow-up/escalation cap. Building proactive capability without all 4 is not a smaller version of this pattern — it's a different, unsafe thing. This is also the trigger point for the Governance checklist below.
Output (report back)
agentName · email · preview verdict (aiAgent.exists, what would be created) ·
draft persona block (full text) · draft system prompt (full text, persona-only since
no real conversation exists yet) · transparency-page preview (what Agent Detail would
show once real) · ticket-linkage shape (ticketType/entityType/title-description
templates) · reactive-only or proactive (and if proactive, the 4 safety-rail values
chosen) · the trust/hierarchy plan (proposed reports_to target and confirmation
it resolves to a real human, proposed permission tier and why, department if any,
confirmation autonomy_level is left at its inert default unless a reactivation is
explicitly also being proposed) · the tool-chest check (which existing
TOOL_CAPABILITIES entries are being reused vs. which are genuinely new, with the new
ones' draft reads/produces) · a ✅/⚠️ checklist (registry-entry-exists ·
identity-preview-clean · persona-drafted · prompt-drafted · ticket-shape-defined ·
transparency-page-confirmed-generic-no-change-needed · agent-ticket-standard-reviewed
(step G.5, if this agent creates tickets) · trust-hierarchy-planned (step E.5) ·
tool-chest-checked-before-inventing-new-tools · governance-checklist-reviewed ·
manager-intent-actions-confirmed-free-no-wiring-needed · role-charter-plan (write one
now, or confirm the honest-empty state is acceptable for launch) ·
all-eight-tabs-walked-live (step H.5)) · explicit confirmation nothing was actually
created (zero real writes) · the exact next step if the producer wants to proceed to
a real commit.
Governance checklist (mirrored in docs/PROOFDESK_STATUS.md)
Before ANY agent built this way goes live:
- Any communication capability (DM, email, outbound message) requires Ali's explicit
sign-off before
AiAgent.enabledis ever settruein production. - New agents seed with
AiAgent.enabled: falseby default. - Identity + ticket-linkage + the transparency page verified live (real exchange, real linked ticket, real page render) BEFORE any proactive capability is added.
- A pilot-cohort or equivalent eligible-population gate is mandatory before any autonomous outreach ships, fail-closed by design — no exceptions.
- Any agent that creates tickets satisfies
directives/register-ticket-creating-agent.md(see step G.5 above) — non-negotiable, not a "nice to have for high-volume agents only." The standard was codified specifically because all 6 of this platform's existing ticket-creating agents shipped without it and each needed a real bug fixed as a result (stale dedup keys, generic display-name collapse, no resolution mechanism at all, time-based fallback closures, non-idempotent bulk cleanups). Runbackend/src/scripts/validateAgentTicketStandard.tsagainst the new agent's real name before considering this checklist item done. reports_tois set and its chain genuinely resolves to a real human — a ticket-creating agent with no resolvable chain is not deployable (enforceReportsToGate()will reject its own tickets at write time). A non-ticket-creating agent should still be wired for the org chart to be honest, but isn't blocked on it the way a ticket creator is.- A permission tier was chosen deliberately, not silently defaulted — see step
E.5.2. Silently accepting
DEFAULT_PERMISSIONfor an agent that actually needs to write or communicate is exactly the "random agent doing things" pattern this checklist exists to prevent. - Every
tools_grantedentry either reuses an existingTOOL_CAPABILITIESentry or has a new one added with it, grounded in the real implementing code — never left as anundocumentedToolsgap at ship time (a temporary gap during preview/draft is fine; it is not fine at step H's live verification).
Worked example (CurriculumQA, preview only, done 2026-08-10)
Input: name "CurriculumQA", intent "reviews generated curriculum content for factual
and pedagogical quality before it reaches students." Full real preview output (real
previewAgentIdentity() return value, real buildAgentSystemPrompt() output, real
zero-write confirmation, real transparency-page description) is captured in
.loop-architect/runs/20260810-reese-phase3-agent-blueprint/worked-example-walkthrough.md.
Headline finding: aiAgent.exists: false — CurriculumQA has no AGENT_REGISTRY entry
yet, so step E (a real commit) would need to add one before any identity could be
seeded for real. No AiAgent/AdminUser/Enrollment/CommunityMember row named
"CurriculumQA" (or similar) was created anywhere — confirmed by grep across this
diff and every migration/seed file.
Worked example (ReesePresenceHeartbeat, real, 2026-09-04 — Step 0 in practice)
Ali asked to review the Reese agent family for sprawl ("I don't want random agents
doing things"). Step 0's checklist, applied for real: ReeseAutonomousOutreachSweep/
ReeseOutreachFollowUps/ReeseStudentSupportSupersessionResolver all answered "no" to
question 1 (not a new identity — no system_prompt/tools_granted/reports_to of
their own, all three write through Reese's own AdminUser) and "yes" to question 2
(each a real, independent, already-registered kill switch for one Reese behavior) —
left exactly as they were. ReesePresenceHeartbeat answered "yes" to question 3:
schedulerService.ts had been calling instrumentCronJob('ReesePresenceHeartbeat', ...) every minute since Reese Phase 1 with no matching row —
instrumentCronJob()'s own "agent not in registry, run untracked" branch had been
silently firing on every single run: no pause switch, no run_count/error_count, no
AiAgentActivityLog, invisible to cronHealthAlertService's missed-run alerting.
One AGENT_REGISTRY entry closed it — no identity, no persona, no ticket-linkage,
because this is a presence-touch cron, not a conversational agent. Deployed and
confirmed live: the row exists, enabled: true, and is accumulating real
run_count/last_run_at on its own per-minute schedule.
Separately, the same review closed a real Global Tool Chest gap: 13 of the 35 real
tool strings already in use across AGENT_REGISTRY had never been added to
TOOL_CAPABILITIES (agentToolCapabilities.ts) — AgentBehaviorMonitorAgent's 4
anomaly-detection tools and 4 ticket/case auto-resolvers' 2 tools each. All 13 were
documented from the registry's own already-grounded descriptions (real function
citations, not invented), closing the gap undocumentedTools had been honestly
flagging for them.
References
references/trust-and-hierarchy.md— the fullAiAgentschema, thereports_toresolution algorithm,AGENT_PERMISSIONS' 4 tiers and defaults, the autonomy ladder and ABAC shadow-mode mechanics, GOALS™ live/fixed scoring detail, the 5 manager-authored post-creation tables (AgentGoal/AgentOneOnOne/AgentReportSubscription/AgentMemoryProposal/ManagerDirective), and when (rarely) a newdocs/ai-governance/ai-systems-registry.csvrow is actually warranted.