Competency Manifest Field Rationale

Date: 2026-07-08 (revised — verified against CompetencyManifest in crates/platform/hoziron-core-types/src/types.rs and crates/platform/hoziron-core/src/competency/{manifest,equip}.rs) Related: ADR-028, ADR-050, ADR-051, ADR-056, Issue #243

What Is a Competency?

A competency is a professional certification, not a job description. It grants domain knowledge, tools, and constraints to an agent — but doesn't act independently. An agent's character emerges from the combination of its equipped competencies and their ordering.

Competencies are composable building blocks:

• claims-data-extraction + client-facing-communication → empathetic intake agent
• claims-data-extraction + investigative-analysis → skeptical verification agent

Same domain knowledge, different character by composition.

Manifest Fields: What They Do and Why

Operational (wired to agent state at equip time)

contracts and integrations are actively wired into the agent's MCP server list at equip time, and contracts additionally gates whether the agent can activate at all.

Stored but not enforced at runtime (future value)

Cosmetic / organizational

There is no category field on the competency manifest. Domain taxonomy (categories) is declared one layer up, at the package level (MANIFEST.toml's [package.metadata]), not on CompetencyManifest/COMPETENCY.toml. The two manifests are easy to conflate since a competency is usually packaged 1:1 with its own MANIFEST.toml, but they are distinct schemas parsed by distinct code paths.

There is no metrics field on the competency manifest.

The package manifest schema (MANIFEST.toml) has no [optional-dependencies]/[peer-dependencies] section — only [dependencies] is ever walked for transitive fetching by the catalog resolver. The competency manifest this document covers has never had those fields either.

Where Things Live: Competency vs. Agent vs. Binding

The key insight: what you know lives on the competency, what you are lives on the agent, and how you're configured lives on the equip binding.

There is no triggers field or concept on the agent or competency manifest — see invocation-model.md for how invocation sources are actually gated.

Schedule Design

Cron is a platform-level resource, not owned by the competency or agent:

1. Competency manifest declares schedule = "0 */6 * * *" (a default suggestion) and, optionally, schedule_action (the instruction sent on each fire)
2. On equip, a CronJob is created in the kernel's CronScheduler
3. The cron job sends periodic messages to the already-running agent (CronAction::AgentTurn), using schedule_action if set or "Execute scheduled competency task" otherwise
4. The operator can independently pause/delete/override cron jobs without unequipping
5. On unequip, the cron job is cleaned up (ignore if already deleted)
6. hoziron-cli competency check-schedules reports drift between declared and actual schedules
7. POST /agents/{id}/competencies/{cid}/reset-schedule recreates a deleted job from manifest defaults

Agents don't self-schedule. The kernel's cron loop fires messages TO agents on a timer. If an operator accidentally deletes a competency's cron job, the competency remains equipped and functional for on-demand use — it just stops receiving periodic triggers.

Settings Design

Settings are the runtime configuration surface for enterprise deployments:

• The schema is authored in COMPETENCY.md (Vec<SettingDef> with key, type, default, options)
• The values are provided per-agent at equip time or updated via API
• Resolved settings are injected as a prompt block after the competency's system prompt
• Settings are scoped per-binding — two agents with the same competency can have different values

Example: FNOL intake competency has settings for cost_cap, language, policy_admin_url. Different carriers deploy with different values. No code change, no prompt surgery, no repackaging.

Multi-Competency Ordering

Order determines prompt priority. Earlier in the stack = earlier in the system prompt = more weight in LLM attention.

fnol-intake-agent:
  1. claims-data-extraction       → "You extract structured FNOL data..."
  2. client-facing-communication  → "You communicate with empathy..."
  3. regulatory-compliance        → "You never disclose PII..."

The agent's identity is "claims specialist" first, "communicator" second, "compliant" third. Swap 1 and 2 and you get a subtly different agent — primarily a communicator who knows claims.

This gives non-technical operators a tunable knob: "this agent is too formal — move client-communication above claims-extraction." Config change, not code change.

Important caveat: Prompt ordering influences behavior but doesn't strictly override. LLMs don't have deterministic priority parsing. Hard constraints (permissions, tool access, contract resolution, PII egress) are mechanically enforced. Soft behavior (tone, approach) is influenced by position.

Competency Tiers (Library Design)

With multi-competency, the package library shifts from "job roles" to "composable certifications":

Existing monolithic competencies (100+ insurance job roles) remain valid as single-equip packages. The new composable tier is additive — it enables differentiation without invalidating the existing library.