{
  "id": "agent-design-standard-0745043fad",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/agent-design-standard.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.749Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Agent Design Standard",
  "summary": "Agent Design Standard Version: 2.0 — April 28, 2026 Purpose: Reference for creating and auditing RedKey agents. All new agents must use Agent Card format. Prose personas are legacy — do not create new ones. Reference implementation: definitions/cards/quinn.json — the canonical reference Card. The Format: Agent Card (card version 1.0) Every new agent is defin...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Agent Design Standard",
      "level": 1,
      "body": "**Version:** 2.0 — April 28, 2026\n**Purpose:** Reference for creating and auditing RedKey agents. All new agents must use Agent Card format. Prose personas are legacy — do not create new ones.\n\n**Reference implementation:** `definitions/cards/quinn.json` — the canonical reference Card.\n\n---"
    },
    {
      "title": "The Format: Agent Card (card_version 1.0)",
      "level": 2,
      "body": "Every new agent is defined as an Agent Card JSON file in `definitions/cards/<slug>.json` and synced to Supabase via `scripts/sync-agent-cards.js`.\n\nThe Card replaces the prose `persona` field. Prose personas are supported for backwards compatibility but must not be created for new agents."
    },
    {
      "title": "Required fields checklist",
      "level": 3,
      "body": "| Field | Required | Rule |\n|---|---|---|\n| `card_version` | Yes | Must be `\"1.0\"` |\n| `identity.slug` | Yes | Matches the agent's slug in `agent_definitions` |\n| `identity.name` | Yes | Display name |\n| `identity.department` | Yes | dev / ops / marketing / sales / platform |\n| `identity.reports_to` | Yes | Agent slug or `\"human\"` |\n| `identity.model` | Yes | Exact model ID |\n| `scope` | Yes | One sentence. What the agent owns AND what it doesn't. |\n| `capabilities` | Yes | What the agent can do — one phrase per item |\n| `constraints` | Yes | \"I never X\" format — declarative, not advisory. Min 3. |\n| `escalation_rules` | Yes | At least one rule. Must reference real role slugs. |\n| `output_types` | Yes | References Wire output contract slugs |\n| `working_style` | Yes | 3 sentences max. How the agent approaches work. |\n| `voice.description` | Yes | 1-2 sentences on communication style |\n| `voice.example` | Yes | One concrete example of agent output |\n| `values` | Yes | What the agent optimises for |"
    },
    {
      "title": "The 9 questions (now answered by Card fields)",
      "level": 3,
      "body": "Every Card must implicitly answer these:\n\n| Question | Card field |\n|---|---|\n| Who are you? | `identity` + `scope` |\n| Where do you run? | `platform-env` shared skill (injected automatically — do not repeat in Card) |\n| What's your first move? | `working_style` first sentence |\n| What do you do? | `capabilities` |\n| How do you know you're done? | `output_types` + escalation_rules |\n| When do you stop and ask for help? | `escalation_rules` |\n| What do you hand off? | `output_types` |\n| What do you never do? | `constraints` |\n| Who gets problems? | `escalation_rules[].route_to` |"
    },
    {
      "title": "Constraints format rule",
      "level": 3,
      "body": "Write \"I never X\" not \"avoid X\" or \"try not to X\". Declarative prohibitions hold more reliably than advisory prose.\n\n**Wrong:** \"You should avoid committing directly to main\"\n**Right:** \"I never commit directly to main or marketplace\""
    },
    {
      "title": "Escalation rules format rule",
      "level": 3,
      "body": "Every escalation rule must reference a real, currently-deployed role slug or agent slug. Check `scripts/lib/dispatch.js` ROLE_TOPIC_IDS for valid role slugs.\n\n---"
    },
    {
      "title": "Procedure content belongs in Skills",
      "level": 2,
      "body": "Agent-specific execution procedures (step-by-step flows) live in `capabilities/skills/<agent>-<protocol>.md`, not in the Card. The Card is an identity document — not a manual.\n\n| Content type | Location |\n|---|---|\n| Who I am, constraints, voice | Agent Card (`definitions/cards/<slug>.json`) |\n| Step-by-step execution procedures | Agent-specific skill (`capabilities/skills/<slug>-protocol.md`) |\n| VPS environment | `capabilities/skills/platform-env.md` (shared, auto-injected) |\n| Inbox read/write protocol | `capabilities/skills/inbox-protocol.md` (shared, auto-injected) |\n| Done/blocked criteria | `output_contract` in Wire Brief |\n\nBoth `platform-env` and `inbox-protocol` are injected for all agents — do not repeat their content in any Card or skill.\n\n---"
    },
    {
      "title": "Wire Protocol: what agents produce and consume",
      "level": 2,
      "body": "All A2A messages are Wire messages. See `definitions/wire/` for schemas.\n\n| Message | Producer | Consumer |\n|---|---|---|\n| Wire Brief | `dispatch.js` | `runner.py` → agent system prompt |\n| Wire Inbox | `hedera-listener.py`, `hcs-post-server.js` | `runner.py` → agent inbox section |\n| Wire Complete | `runner.py` | `hedera-listener.py`, Mindy |\n| Wire Blocked | `runner.py` | `hedera-listener.py`, Iris (blocker_type routing), Mindy |\n| Wire Claim | `runner.py` | `hedera-listener.py` |\n\n**Rule:** agent output fields (summary, reason) are the only prose in a Wire message. All other fields are typed.\n\n---"
    },
    {
      "title": "Adding a new agent — checklist",
      "level": 2,
      "body": "- [ ] Write `definitions/cards/<slug>.json` using `definitions/cards/TEMPLATE.json`\n- [ ] Add agent to `definitions/agents/<slug>.json` (slug, name, department, model, schedule_seconds, roles, skills, plugins)\n- [ ] Add role entry to `scripts/lib/dispatch.js` ROLE_TOPIC_IDS if adding a new role\n- [ ] Run `node --env-file=.env scripts/sync-agent-cards.js --slug <slug>`\n- [ ] Create a systemd unit file on VPS if the agent runs as a daemon\n- [ ] Verify runner picks up the Card: check `journalctl -u redkey-<slug>` for \"assembling prompt from Card\""
    }
  ],
  "html_path": "artifacts/agent-design-standard-0745043fad.html",
  "json_path": "artifacts/agent-design-standard-0745043fad.json"
}