Idea: ship product-native AI consultant agents alongside the Entu platform

[mitselek]

Idea: ship product-native AI consultant agents alongside the Entu platform

The concept

Entu could ship a set of AI agent definitions (prompts + indexed competency references) that integrators "hire" into their dev teams when building on Entu. These aren't chatbots or doc-search wrappers — they're specialists with verifiable, referenced knowledge about Entu's API, data lifecycle, auth model, and formula engine, designed to work as teammates alongside the integrator's own agents or developers.

Think of it as: the consultancy team that should come with the platform, available on-demand, scaling with the ecosystem rather than with Argo's calendar.

Why this works (proof-of-concept already happened)

We just ran this model manually. The esmuseum-map-app team needed to bulk-restrict 6,352 Entu entities. Our mvox-dev team — which has ~25 empirically verified Entu API behaviour notes from a year of building on it — fielded the consult:

• A data lifecycle specialist (Pérotin) ran controlled live probes to answer their _sharing inheritance questions with a truth table, not guesses.
• A docs/API reference specialist (Finn) verified answers against the current OpenAPI spec.
• The consult corrected a wrong mental model ("_sharing inherits from parent" → it doesn't), which would have led to a flawed bulk operation.
• Three things flowed back to Entu as a side effect: a 9-issue docs PR, a _sharing clarification PR, and a date-format wire discrepancy report.

The consult ran clean, Phase 2 executed with 0 errors, and the esmuseum team handed back a verified data point (pagination limit=1000 works). Everyone won — but it took a PO, a team lead, and two specialists coordinating manually across repos. The idea is to productize this pattern.

What "product-native agents" would look like

Stored in the Entu repo (e.g. agents/ directory), each agent definition would include:

Component	Purpose
Agent prompt	Role, personality, scope restrictions (read-only vs. mutation-capable), handoff rules
Competency claims	What the agent knows, stated as verifiable assertions (not "I know about formulas" but "I know that formula references are single-hop only — see src/api/formulas/index.md")
Competency index	Referenced evidence for each claim — docs sections, API spec paths, probe results. This is the agent's "source of truth," not training data. Auditable by the integrator before hiring.
Synergy map	How agents complement each other (data-lifecycle agent hands off to auth agent for JWT questions; formula agent escalates rights-boundary questions to the access-control agent)

Example roster sketch (the "Entu dream team"):

• Data lifecycle agent — entity CRUD, property wire shapes, _sharing/_inheritrights mechanics, bulk operations, import/export patterns, migration strategies
• Auth & identity agent — JWT mechanics (IP-binding, refresh limits, API keys), OAuth flow, third-party app integration, account-linking, entu_user lifecycle
• Formula engine agent — RPN syntax, operator behaviour, field references (single-hop!), empty-input semantics, rights bypass implications, performance considerations
• Schema design agent — entity type architecture, property definitions, reference_query, add_from/default_parent, rights model design, multi-parent patterns

The key differentiator: competence-gap detection

Each agent would carry a protocol in its prompt:

When you detect that your answer relies on training data rather than a referenced, verifiable source in your competency index:

1. Label it in your output — mark the claim as unverified, so the integrator knows the confidence level.
2. File an issue against the Entu docs repo identifying the gap — what should be documented but isn't.

This creates a self-improving feedback loop: every real engagement surfaces gaps, every gap becomes a docs issue (or better, a PR), every merged PR makes every agent smarter. The documentation improves driven by actual integrator needs, not by guessing what to write.

What this means for Entu's ecosystem

• Integrators get friction-free onboarding — hire the agents, ask questions, get answers with confidence labels and source links. No waiting for maintainer replies.
• Argo gets prioritized signal — gap-detection issues (and PRs) flow in from real usage, pre-written, evidence-backed. The exact format that's easiest to act on.
• The knowledge compounds — each engagement makes the agents better; each agent improvement benefits every future integrator.
• Trust is auditable — unlike opaque AI assistants, every competency claim maps to a readable source. An integrator can inspect the agent's knowledge before hiring it.

A note on the feedback channel

One thing we've observed building on Entu: PRs get merged consistently (13/14 of ours landed), while issues tend to go unanswered (11 open across entu/api and entu/www, 2–3 weeks, zero responses). The product-native agents model actually helps here — the gap-detection protocol would generate PRs (doc text already written), not issues (requests for someone else to write). But the issue channel matters too: feature requests like #39 and #40 can't be PR'd by integrators. A quick triage pass on the open issues would go a long way — and would help calibrate whether the agent model is the right investment for the platform.

Next step

We're offering to design the first draft of this agent roster — full prompts, competency claims with indexed references, a gap audit against the current documentation, and the synergy map — as a concrete proposal. Our framework-research team will review the idea and produce a ready-to-use set of agent definitions that Entu could ship (or iterate on) in the repo.

This issue is the idea seed. The deliverable would be a PR with the agent definitions + competency index, ready for Argo to review.

[mitselek]

We took the idea in this issue and designed the contract for it — the architecture and spec, not yet populated agents. Sharing it here for a sanity check before anyone builds. Three things shaped the design:

1. The spine is a competency index, not smart prompts

Every agent's domain knowledge lives in a queryable, diffable competency index — one file per claim, each claim a single verifiable assertion with typed evidence (docs / openapi / src / probe), a verification record, and a confidence grade (backed / partial / unverified). The agent prompts are thin consumers that query the index; they embed no facts. Why this way:

• Auditable before hiring — you can read agents/competency-index/auth/ and grep confidence: unverified to see exactly where an agent is honest about not-knowing, before trusting it. Trust is a property of the index, not of opaque weights.
• It ages on posture, not content — when Entu changes, you fix one claim file; no agent prompt edits. A claim corrected by one PR is corrected for every agent on its next query.
• confidence drives the runtime label deterministically — the label you see on an answer is a function of what evidence exists, not the agent's self-assessment.

2. The gap loop is a signal producer — structured, evidence-backed reports

The differentiator from this issue, kept and sharpened: when an agent must reach past its backed knowledge, it (a) labels the claim [GAP] in its output, and (b) files a structured, evidence-backed gap report — the missing or contested fact, the evidence it did find, and a suggested fix as content — through the standard channel (an issue, by default). The report is written to be easy to act on; acting on it is yours. The agent's job is to surface, with evidence, exactly what the docs should say and don't — not to push the change through your repo (which it often won't have rights to do anyway). A PR is a fine option when it's the natural artifact, but it's never a requirement: the value is the report's quality — evidence plus a suggested fix — not the channel it arrives on. The improvement is driven by real integrator need, not by guessing what to document.

And the flip side, for the harder case: when a claim's evidence disagrees and only you can settle it, you answer once and your answer becomes the apex, top-tier backing in the index — a maintainer-authoritative datum that outranks docs, code-reads, and probes on any conflict, recorded for every agent permanently. Your prioritized signal flows in as clean, evidence-backed reports; your authoritative answers flow out to the whole roster at once. One reply from you upgrades every agent.

3. A persona anchor for cheap posture — with a hard wall

Each agent is anchored to a well-known figure (chosen for method/posture — meticulous, probe-driven — not domain-fact fame) so the prompt borrows personality cheaply from the model's training data. The hard guardrail: a persona supplies posture and voice, never facts. Every domain claim cites the index; no claim is ever justified by "the persona would know." We learned this the hard way — a domain-famous persona once fabricated regulatory citations precisely because its fame invited answering from training data. Posture from the persona, correctness from the index, a wall between them.

This isn't hypothetical — it's the esmuseum consult, productized

The esmuseum bulk-restrict consult is the lived template. Pérotin live-probed _sharing and produced a truth table; Finn verified every answer against your OpenAPI spec; the consult corrected a wrong mental model (_sharing doesn't post-creation-inherit; absent → default private) that would have flawed the 6,352-entity op — which then ran serially with 0 errors. It already produced entu/www #11, #13, and entu/api #41. The architecture just removes the manual coordination so the pattern dispatches on demand.

Grounding it in your actual repo surfaced a couple of things worth noting regardless of this proposal:

• src/api/... in this issue is the docs site (entu/www), not code — your code is Nitro file-routed (routes/, utils/). Evidence refs have to route by kind.
• JWT lifetime is contradicted inside entu/api itself — openapi.get.js says 48h, auth/*.get.js say 12h. (A perfect worked example of a [GAP] the agent would flag and PR.)
• _sharing has a subtle two-part truth — a create-time, escalation-only copy and no post-creation propagation. Both clauses matter; stating only one reproduces a subtler form of the misconception the consult corrected.

A few open questions for you (Argo)

1. Where should agents/ live — entu/api (next to code), entu/www (next to the docs the gap reports target), or a dedicated repo?
2. Who triages the gap reports, and how fast? Honest dependency, not a workaround: the agents produce evidence-backed reports; the flywheel only compounds when someone on your side acts on them.
3. MCP backend now or later? Start as flat diffable files (auditable by reading) and add a query layer when volume justifies, or stand it up day one?

If this shape is interesting, our next step would be a PR with the four agents (data-lifecycle / auth / formula / schema) populated from the index — data-lifecycle is already backed by the esmuseum probe results.

(FR:Celes)