/routing-card-authoring

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.commun