| name | routing-card-authoring |
| description | Use whenever a build emits or repairs .agentlas/routing-card.json — the shared card contract for the single-agent builder, the team builder, and the packager. States what belongs in every field, which fields the hub can actually match on, and which fields silently break matching when a sentence leaks into them. |
Routing Card Field Spec — what goes in every field, and where it lands
One card, four builders. 10-single-agent-builder, 20-multi-agent-team-builder,
30-agentlas-packager, and 40-session-agent-builder differ in what they
assemble, but the routing card is the same artifact with the same rules in all
four. This file is the reference
they share, and templates/routing-card.example.json is a complete card that
passes schemas/routing-card.schema.json.
Why the fields behave the way they do
Every rule below was measured against the live corpus on 2026-07-30
(492 workforce profiles, 253 stored manifests). The two facts that decide
everything else:
- Only two columns can be compared between a work order and a card.
communities (422 of 492 populated, 105 distinct) and skills (492 of 492,
1,969 distinct). Everything else is either declared by almost nobody
(roles 6, tools 10, knowledge 0, forbiddenAuthorities 0), or declared
by everyone with the same value (runtimes 14 distinct over 492 profiles,
languages exactly 2, modalities exactly 1) — neither can separate
candidates.
- The real matching is sentence-to-sentence. The slot's
task text is
compared semantically against the card's summary. A card whose summary
names its actual deliverable outranks a card with a perfect id list.
So the card has two jobs, and mixing them is the classic defect: short ids
for retrieval, whole sentences for judgement. A sentence that leaks into an
id field becomes a slug nothing else can ever match — measured: 8,973 distinct
outputs values across the corpus, 0% shared by two agents.
Field table
Columns: what the field is for · what the hub does with it · what to write.
Identity and display
| Field | Hub use | What to write |
|---|
schemaVersion | none | Exactly "routing-card/2.0". |
card_version | none | Semver of this card's content, bumped when you edit it. |
id | identity | local/<package-slug> before upload. |
canonical_id | identity | Stable cross-registry id when one exists, else omit. |
type | hard filter (entityKind) | "agent", "team", or "plugin". A team means an orchestrator owns workers; do not label a single worker a team. |
name / name_ko | display + lexical retrieval | The job title a human would search for. Not a product pun. |
aliases | lexical retrieval | Other phrasings a requester might type, including Korean. Cheap and safe to add. |
supersedes | lineage | Ids this card replaces. |
The sentences that actually win matches
| Field | Hub use | What to write |
|---|
summary (≤240 chars) | semantic ranking against the slot task — the single highest-value field | One sentence: what it does, what the requester ends up holding, and the one boundary that matters. Name the deliverable in the words a requester would use. Do not list technologies for their own sake. |
summary_ko | display + Korean retrieval | Faithful Korean of summary. |
description | semantic ranking | 2–4 sentences: when to use it, what the deliverable contains, and what it explicitly does not do. This is where "does not implement" or "does not run migrations" belongs. |
trigger_examples | semantic ranking (strong) | 6+ real sentences a requester would actually type, 3 Korean and 3 English. Write the request, not a feature name. |
anti_triggers | negative ranking | 4+ sentences that look adjacent but must NOT route here. This is how a design agent stops absorbing implementation work. |
known_failure_cases | honesty, read by the host LLM | What the agent degrades to when an input is missing. Sentences, whole. |
Short-id fields (open semantic concepts — never sentences)
| Field | Hub use | What to write |
|---|
capabilities | → skills column, lexical + semantic retrieval | 4–8 ids in verb_object snake_case (design_backend_services). Schema enforces the pattern. These become open skill:* graph concepts. Seed aliases may normalize familiar terms, but no finite list owns what an agent is allowed to know or do. |
domains | lexical retrieval | 2–5 broad area words. |
required_inputs / optional_inputs | compatibility display | Canonical interfaces live in contracts/intake.schema.json. Only stable name/id values may project to ontology IDs; descriptions and JSON types never do. |
input_notes | not read by matching | Free-text lines explaining each input, for humans and for the executing model. |
consumes / produces | compatibility display | Canonical interfaces live in contracts/intake.schema.json and contracts/output.schema.json. When present, use short stable kind IDs only. |
supported_runtimes | packaging metadata | Do not emit it as agent identity. Runtime adapters and prepare-time execution policy own compatibility. |
required_plugins | → tools column | {id, min_permissions} for a facility the worker itself must invoke. Almost no card declares tools; state the requirement vendor-free and keep the package usable without it. |
The workforce block — open-world semantic résumé fields
workforce is defined in schemas/routing-card.schema.json and is what the hub
reads. The snapshot agentlas_cloud/workforce/ontology_v1.json
(awo:2026-07-15.2) supplies seed aliases, parent relations and compatibility
mappings. It is not an allowlist. When no seed concept fits, author a faithful
English namespaced ID; the Hub embeds it and connects it to the ontology graph.
| Field | Hub use | What to write |
|---|
workforce.communities | semantic scope + strong ranking signal | 1–5 open community:* professional-domain ids. Reuse a seed alias when it fits; otherwise author the real community. |
workforce.skills | semantic ranking | 3–12 open skill:* verb-object capability ids that actually distinguish this agent. They are not a fixed dictionary. |
workforce.knowledge | ranking | knowledge:* ids. You may omit it: the compiler now derives one id per knowledge/*.md file the package ships (file stem → knowledge:<stem>), which is why the column existed with 0 producers until 2026-07-30. |
workforce.roles | semantic ranking | 0–4 open role:* professional-responsibility ids. [] is honest when the card already expresses the work better through its summary and skills. |
workforce.languages | delivery metadata, never an identity/callability gate | Languages the work product can genuinely be delivered in. Listing translation does not count. [] is allowed when unknown. |
workforce.modalities | runtime/input metadata, never an identity/callability gate | Declare only non-text media the agent genuinely consumes or emits. Ordinary text reasoning may use []. |
Safety, cost and operations (not matching inputs)
| Field | Hub use | What to write |
|---|
risk_profile.tier | display, governance | low / medium / high. |
risk_profile.capabilities_at_risk | display, governance | Enum: file_write, cloud_call, payment, publish, delete, private_data_export, external_tool. It never becomes semantic authority identity. |
approval_requirements | → authorities column | Same vocabulary; what a human must approve. |
approval_scope | runtime policy | {grant, ttl_seconds}. |
memory_behavior | runtime policy | {reads, writes, exports_to_cloud} — required object. |
data_access | runtime policy | {reads, writes, exports} path classes. |
cloud_delegation_policy | runtime policy | never / ask / allowed_with_grant. |
cost_hints | display | {model_calls, paid_api}. |
entrypoints | execution | {canonical_command, agent, terminal}. |
benchmark_fixtures | quality | Path to .agentlas/routing-benchmarks.jsonl. |
locale_coverage | display only | {primary, ready, partial} for marketplace copy. It must never project into workforce languages. |
routing_status | gate | draft → searchable → candidate → routing_ready → trusted. Only a card with real triggers, a real summary and a filled workforce block should claim routing_ready. |
routing_status_reason | gate | Why it is not ready, when it is not. |
card_quality_score, quality, integrity, source, stale, updated_at, agent_card_ref | pipeline-owned | Leave to lint, publish and the hub. Do not hand-author scores. |
Checklist a builder can run
summary names the deliverable in a requester's words, under 240 chars.- 6+
trigger_examples (3 ko / 3 en) and 4+ anti_triggers, all real sentences.
capabilities: 4–8 verb_object ids, checked against community aliases for
accidental pulls (contract → legal, and similar).- No
description inside required_inputs, optional_inputs, consumes
or produces. Explanations go in input_notes / description /
known_failure_cases.
workforce.communities, skills, roles, and knowledge use stable open
English IDs. Seed aliases are reusable examples, never an allowlist.risk_profile.capabilities_at_risk lists only real risks.routing_status is honest.- Validate: the card parses against
schemas/routing-card.schema.json.
Verified end to end
templates/routing-card.example.json was compiled through the live hub
compiler (compileExactOwnerPrivateWorkforceProfile) on 2026-07-30. Result:
communities [4] backend-engineering, database-engineering, legal*, software-engineering
skills [9] api-design, software-architecture, data-modeling + 6 from capabilities
knowledge [2] api-contract-checklist, database-schema-patterns (from knowledge/*.md)
inputs [5] requirement-brief, load-profile, service-context, stack-constraints, text*
outputs [3] api-contract, data-model, decision-record
runtimes [4] claude-code, codex, gemini-cli, terminal
languages [2] en, ko modalities [1] text
roles [2] backend-engineer, software-architect
authorities [1] file-write forbiddenAuthorities []
The same card written with sentences inside produces/required_inputs
produced outputs [6] and inputs [10] full of unmatchable slugs like
artifact:architecture-decision-record-naming-the-chosen-component-boundaries-and-….
That is the difference this spec exists to hold.
Two known compiler leaks are visible above and are not the author's fault:
legal* (community alias "contract review") and artifact:text* (the type
value of an input becoming a concept). Fix them in the compiler, not by
contorting the card.
