---
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:

1. **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.
2. **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

1. `summary` names the deliverable in a requester's words, under 240 chars.
2. 6+ `trigger_examples` (3 ko / 3 en) and 4+ `anti_triggers`, all real sentences.
3. `capabilities`: 4–8 `verb_object` ids, checked against community aliases for
   accidental pulls (`contract` → legal, and similar).
4. **No `description` inside `required_inputs`, `optional_inputs`, `consumes`
   or `produces`.** Explanations go in `input_notes` / `description` /
   `known_failure_cases`.
5. `workforce.communities`, `skills`, `roles`, and `knowledge` use stable open
   English IDs. Seed aliases are reusable examples, never an allowlist.
6. `risk_profile.capabilities_at_risk` lists only real risks.
7. `routing_status` is honest.
8. 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.