routing-card-authoring

# 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