> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useharmonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# ADK agent platform
> Coordinator, specialists, sequential drafting team, skills, managed sessions, and authority boundaries.
Harmonia uses Google ADK for bounded judgment inside a deterministic asynchronous workflow. Agent Engine hosts cognition; it does not own durable workflow state or external-effect authority.
Routes one bounded task to the appropriate specialist.
Produce grounded analysis, strategy, and content plans.
Agentically operationalizes an approved Ryan strategy; deterministic code persists the plan and selects one item.
Deterministic code runs separate typed Noni and Dara calls for the selected item.
## Team topology
```mermaid theme={"system"}
flowchart LR
W[Deterministic worker] --> H[Harmonia coordinator]
H --> R[Ryan strategist]
H --> S[Nimi analyst]
H --> T[Temi editorial planner]
T --> FS[Firestore plan + selected item]
FS --> F[Deterministic writing/review loop]
F --> N[Noni copywriter]
N --> D[Dara editor]
D --> N
W --> M[Maya presenter]
W --> V[Nova liaison]
D --> P[Reviewed drafts]
P --> G[Deterministic policy + human gate]
```
| Role | Responsibility | Allowed context | Prohibited authority |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Harmonia | exact specialist routing | typed invocation state | answer the specialist task, approve, publish |
| Nimi | source evidence analysis: exact moments and qualified source/context/performance/memory angles | typed transcript/frame evidence, verified performance, eligible Memory Bank facts, one bounded method skill, and optional request-bound grounded context | use skill prose as evidence, invent evidence or trends, define strategy, write final copy, approve, schedule, publish, or treat memory/search as authority |
| Ryan | agentic strategy and source-grounded content briefs | typed Nimi analysis, company/campaign context, verified performance, eligible Memory Bank facts | write final copy, mutate calendars, approve, publish |
| Temi | agentic editorial operationalization: sequencing, cadence, supported channels/formats, windows, deadlines, dependencies, and priorities | exact human-approved Ryan strategy, Nimi evidence, one immutable Firestore planning snapshot, local method skill, and request-bound read views | invent strategy/evidence, search, read outside the snapshot, write final copy, approve, mutate external calendars, schedule externally, publish |
| Noni | platform-native writing and revision | one selected Temi item, its exact Ryan brief, referenced Nimi evidence, local writing guidance, verified prior publications, and brief-scoped public sources | redefine strategy, search trend feeds, access Memory Bank, inspect the rest of the plan, create facts, approve, publish |
| Maya | reference-only interface composition | exact typed job/entity catalog; deterministic host hydration from Firestore | invent IDs or state, emit lifecycle placeholders, expose payloads, approve, publish, verify, or mutate workflow |
| Dara | complete seven-dimension assessment and bounded correction issues | exact Noni draft, immutable production input, and allow-listed editing-method guidance | cite skill prose as evidence, author workflow metadata, rewrite copy, replace evidence, request a third pass, or create authority |
| Maya | A2UI layout selection | typed entity references and UI context | emit executable UI or mutate records |
| Nova | read-only operational answers | allow-listed tools and skills | write Firestore, retry jobs, approve, publish |
## Managed invocation lifecycle
The worker reads authoritative Firestore state and creates a serializable invocation seed.
Agent Engine receives a session keyed by workspace, user, and job. The retrieved session object is treated as read-only.
ADK `output_key` values and event `state_delta` records carry specialist handoffs. Required keys are validated before use.
Deterministic routes write accepted results to Firestore. Session state alone cannot advance the workflow.
The ephemeral managed session is removed after success or failure.
Agent state, chat history, and Memory Bank are context—not authorization. Only durable policy, approval, claim, receipt, and verification records control effects.
Invalid specialist output crosses the coordinator boundary as a structured `AgentContractError` with a role, stable code, safe operator message, and optional schema path. The failure pipeline retains these fields in its typed envelope and durable activity event; model output and validation payloads never become operator-facing error text.
## Activity and telemetry
Every specialist invocation emits a strict metadata-only log, trace, and metric projection with tenant, job, operation, agent, stage, model, timing, usage counts, outcome, and real W3C trace/span IDs. Tool activity is projected only when ADK supplies real trace context. Unknown fields fail validation, and the schema cannot carry prompts, model responses, transcripts, drafts, credentials, or provider bodies.
The projection powers **Monitoring → Agent activity**. Native ADK OpenTelemetry signals continue to Cloud Logging, Cloud Monitoring, and Cloud Trace; the projection is a bounded operator view, not a replacement for those backends and never an authority source.
## Versioned ADK skills
Nimi loads exactly one `nimi-analysis-skills` skill and at least one relevant allow-listed analysis
reference. This filesystem skill contains method guidance only.
Dara loads exactly one `dara-editing-skills` skill and at least one approved editing reference before
review. The seven references route editorial triage, grounding and claims, structure and clarity,
brief/voice/audience fit, platform/CTA usability, safety and inclusion, and bounded feedback. Dara
has no search, Memory Bank, workflow, approval, or effect tool. Runtime callbacks record the actual
loader sequence and deterministic validation rejects missing, duplicate, out-of-order, or
unapproved resources. The guidance can shape editorial judgment but cannot serve as factual
evidence, a brand constraint, or authority.
Noni loads exactly one `noni-writing-skills` skill and at least one approved writing reference before
drafting.
Temi loads exactly one `temi-editorial-planning-skills` skill and at least one of six allow-listed
planning references. Its separate read-only tools expose commitments, capacity, asset readiness,
verified posting-window observations, calendar projection state, and blocked dependencies from the
exact immutable planning snapshot. The trace must load references before data reads and every read
must match the request's snapshot ID. Skill prose is methodology and never evidence.
## Runtime research tools
Search and internal-data reads are tools, not skills. Nimi's optional native Google Search and
Vertex AI Search tools run in isolated request-bound child agents. The runtime validates a separate
research trace and native grounding metadata before persistence.
Noni has two separate read capabilities:
`search_verified_publications` for tenant-scoped posts with applied receipts and successful
verification, and native ADK `google_search` through an isolated brief-bound research agent.
It has no trend-feed, Memory Bank, approval, or effect tool. The ten references cover thought leadership,
hooks and introductions, MECE structure, case studies, storytelling, bad-content diagnosis,
persuasion, outlining, titles and headlines, and convincing content. Skill guidance shapes writing
but never counts as evidence for a factual claim. Research-derived claims and URLs must cite the
live tool evidence ID recorded in the actual trace.
Nova loads exactly one skill before any data tool. The runtime records the real
skill/tool envelopes in managed ADK state and rejects answers whose selected
skill, tool sequence, retry behavior, status, errors, claims, or evidence IDs
do not match that trace. Skill prose guides reasoning; deterministic validation
enforces the boundary.
| Skill | Purpose | Allowed tools |
| --------------------- | ------------------------------------------ | --------------------------------------------------- |
| `trend-scan` | find grounded public topics | trend signal fetch/search |
| `signal-watch` | explain current signals and operator feed | trend signals and operator feed |
| `engagement-insights` | summarize measured post performance | engagement insights |
| `posting-schedule` | suggest evidence-based UTC windows | engagement insights, operator feed, posting windows |
| `job-status` | answer scoped operational status questions | job status |
See [Agent tool contracts](/tool-contracts) for the exact envelope and permission model.