Tag Vocabulary

Curated list of every tag an agent is allowed to declare. Source of truth: tags.json. Linter rejects any tag not in this list.

Why a fixed vocabulary

Auto-generated tags (json, JSON, Json, json-parsing) fragment the routing index. A curated list makes the orchestrator's job tractable: when it looks up by_tag.security, it gets every agent that should be there, not half of them plus a scatter of secure, sec, security-audit.

New tags aren't forbidden — they require one thing: add the tag to tags.json in the same MR as the agent that uses it. That discipline is the vocabulary's immune system.

Layers

Every tag lives in one of six layers. An agent typically carries 5–10 tags spread across skill, domain, tech, and concern.

Layer	What it answers	Typical count per agent
skill	What the agent does functionally (backend, review, growth, qa)	1–3
domain	Subject matter (fintech, blockchain, gamedev, xr)	1–2
tech	Concrete stack / platform (react, postgres, unity, tiktok)	0–3
concern	Non-functional property (security, performance, a11y)	0–3
workflow	Output mode (implementation, audit, reporting)	0–1
marker	Pack infrastructure tags (template, bootstrap)	0–1

Layer summaries

skill — what the agent does

Engineering roles: backend, frontend, fullstack, devops, sre, infra, data-engineering, data-science, ai, ml, llm, mobile, embedded.

Design: ui-design, ux-design, ux-research, brand-design, visual-storytelling, whimsy, prompt-design.

Testing: qa, e2e-testing, api-testing, performance-testing, accessibility-testing, evidence-collection, reality-check.

Protocol-bound: review, audit, scout, orchestration.

Writing: technical-writing, content-creation, book-authoring.

Marketing / growth: growth, seo, aso, aeo, social-media, community-building, livestream-commerce, localization.

Paid media: ppc, paid-social, programmatic, tracking, paid-audit, search-analysis.

Sales: outbound, discovery-selling, deal-strategy, sales-engineering, proposal-writing, pipeline-analysis, account-expansion, sales-coaching.

Product / PM: product-management, prioritization, feedback-analysis, trend-research, behavioral-design, project-planning, experiment-tracking, jira-workflow, studio-ops.

Finance: bookkeeping, fpa, tax-strategy, investment-research.

Support: customer-support, legal-compliance, analytics-reporting, executive-summary, finance-tracking, infra-maintenance.

Academic: historical-analysis, anthropology, psychology, narratology, geography.

Game craft: game-design, level-design, technical-art, game-audio, narrative-design.

Security / ops specializations: threat-modeling, threat-detection, smart-contract-audit, compliance-audit, incident-response, identity-engineering, workflow-design, document-generation, automation-governance, knowledge-management, recruiting, training-design, supply-chain.

domain — subject matter

Platforms: web, api, microservices, event-driven, serverless, cli-tools.

Finance: fintech, banking, payments, trading, escrow, wallet, ledger.

Blockchain: blockchain, defi, nft, smart-contracts, zk-proofs, mev.

Games: gamedev, multiplayer, open-world.

Verticals: healthcare, gov-tech, education.

B2B: saas, multi-tenant.

Reality: xr, vr, ar, webxr, visionos, cockpit.

Academic: academic.

Regional: china-market, cross-border, korean-market, french-market.

Commerce / community: marketplace, ecommerce, devrel.

tech — concrete stack

Languages: python, java, kotlin, scala, go, rust, swift, typescript, javascript, ruby, php, c-cpp, solidity, gdscript, luau, hlsl, glsl, metal.

Web / backend frameworks: react, react-native, vue, angular, next, svelte, node, spring, django, rails.

Game engines: unity, unreal, godot, roblox, blender.

Data systems: postgres, mysql, mongodb, redis, elasticsearch, kafka.

Infra: docker, kubernetes, terraform, aws, gcp, azure.

Mobile: ios, android, flutter.

CMS / SaaS: wordpress, drupal, cms, salesforce.

Chinese platforms: wechat, feishu, bilibili, xiaohongshu, weibo, douyin, kuaishou, zhihu, baidu.

Global platforms: tiktok, instagram, twitter, linkedin, reddit, youtube.

Blockchain nets: ton, ethereum, solana.

AI infra: mcp.

concern — non-functional

Security: security, auth, authz, secrets, owasp.

Performance: performance, caching, scaling.

Reliability: reliability, observability, chaos-engineering.

Compliance: privacy, gdpr, pci, soc2, hipaa.

UX / code: a11y, architecture, refactoring, minimal-change, database-design, query-optimization, observability-instrumentation, regression.

workflow — output mode

implementation, design, strategy, reporting, coaching, estimation, coordination.

marker — pack infra only

template (for files in agents/templates/), bootstrap (used in memory templates).

Using the vocabulary

From the migrator

scripts/migrate_schema.py loads tags.json on start, then for each agent:

1. Seeds tags with the category's per_category_defaults + the agent's own category.
2. Scans the filename, description, and body for tag names and synonyms.
3. Filters out foreign-category tags so marketing tags don't leak onto engineering agents.

From the linter

scripts/lint_agents.py loads tags.json and rejects any tag not in the vocabulary with a clear error message, including the closest match suggestion.

Adding a new tag

When an agent needs a tag that's not here:

1. Pick a layer.
2. Add it to agents/tags.json with a short synonyms list (other ways authors might write it).
3. Add it under the appropriate layer section of this document.
4. Run scripts/migrate_schema.py to ensure re-migration is idempotent.
5. Run scripts/build_index.py to refresh index.json.
6. Commit all four changes together.

Disambiguation tags

Agents with overlapping category/tag footprints may declare an optional distinguishes_from frontmatter field listing slugs they're often confused with. The orchestrator uses this as a tie-breaker when tag intersection alone is ambiguous. Example:

distinguishes_from: [engineering-security-engineer, blockchain-security-auditor]

engineering-code-reviewer with that field says: "when picking a security reviewer I'm the lighter-weight code review variant; for full threat modelling delegate to engineering-security-engineer."

Anti-patterns

• Tagging with the agent's own role noun (engineer, specialist). The vocabulary deliberately excludes those; they add nothing for routing.
• Tagging a foreign category. engineering-security-engineer is not a support agent even if the body mentions "decision support".
• One-off tags (my-favourite-framework-v3). If it's not in tags.json, the linter fails the PR.