/agents-standards

name: agents-standards
description: Standards for authoring SDD plugin agents — frontmatter, self-containment, skill references, and no-user-interaction rules.
user-invocable: false

Agents Standards

Standards for every agent in the plugin. Apply when creating or reviewing plugin agents.

---

Scope

This standard applies to agents shipped with the SDD plugin — all `.md` files found in `plugin/fullstack-typescript/agents/` (or any future tech pack's `agents/` directory). It does not apply to the repo's own `.claude/` configuration.

---

Frontmatter

Every agent file must start with YAML frontmatter containing exactly these fields:

---
name: my-agent               # REQUIRED — kebab-case, must match filename (without .md)
description: >               # REQUIRED — what this agent does + its expertise area
  Implements backend services using Node.js and TypeScript
  with strict CMDO architecture.
tools: Read, Write, Grep, Glob, Bash  # REQUIRED — comma-separated list of available tools
model: sonnet                # REQUIRED — "sonnet" for implementation, "opus" for review/advisory
color: "#10B981"             # REQUIRED — hex color for UI representation
skills:                      # REQUIRED — skills to preload into agent context
  - typescript-standards
  - backend-standards
---

| Field | Type | Rule | |-------|------|------| | `name` | `string` | kebab-case, matches the filename without `.md` extension | | `description` | `string` | 1-2 sentences. What the agent does + its domain expertise. Never reference when or by whom the agent is invoked — the agent doesn't know its callers. | | `tools` | `string` | Comma-separated list of tools this agent can use. Read-only agents (reviewer, db-advisor) must NOT include `Write`. | | `model` | `string` | `sonnet` for implementation agents, `opus` for review/advisory agents. Choose based on the cognitive complexity required. | | `color` | `string` | Hex color code for UI. Must be unique across agents. | | `skills` | `list` | Skills to preload into agent context. Full skill content is injected at startup. **Agents do not inherit skills from the parent conversation — they must be listed explicitly.** |

---

Self-Containment

An agent must be fully understandable on its own. An LLM reading a single agent file should know exactly what role this agent plays, what it owns, and what constraints it operates under — without reading other agents.

Rules

1. **Define your role clearly** — The first line after frontmatter must be a "You are..." statement that establishes the agent's expertise and scope. This is the agent's identity. 2. **Own your working directory** — If the agent operates in a specific directory, state it explicitly. Never assume the reader knows the project layout. 3. **Delegate clearly to other agents** — When referencing another agent, state what you expect it to do (the contract), not how it works internally. Example: "Invoke `db-advisor` for database schema review" is sufficient. 4. **Don't duplicate other agents** — Never copy responsibilities, checklists, or rules from another agent. If review of database changes is `db-advisor`'s job, delegate to it — don't reproduce its checklist. 5. **No cross-agent file references** — Never reference or read files inside another agent's definition. Each agent is a self-contained unit. 6. **No environment assumptions** — Do not assume a specific directory structure, tool version, or runtime context unless the agent explicitly documents it as a precondition. If the project may vary (multi-instance), tell the agent where to check (e.g., `.sdd/sdd-settings.yaml`). 7. **Define your own terms** — If the agent introduces domain-specific vocabulary (e.g., "CMDO architecture"), define it on first use or delegate to a skill that defines it. 8. **Complete examples** — Every example must be understandable without external context. 9. **Plugin boundary** — Plugin agents (`plugin/fullstack-typescript/agents/`) have no runtime access to anything outside `plugin/`. Never reference `.claude/`, `.tasks/`, or root-level files from within a plugin agent.

---

CLI Delegation

Agents should not invoke the system CLI directly. Instead, agents delegate to commands or skills that handle CLI invocation. This keeps CLI coupling out of agents and in the orchestration layers. **For the canonical CLI invocation pattern, see the `system-cli-standards` skill.**

---

No User Interaction

Agents run as subprocesses (subagents) invoked by commands or other agents. They have **no direct access to the user**. This is a hard constraint of the execution environment, not a style preference.

Rules

1. **Never prompt the user** — An agent cannot ask the user for clarification, confirmation, or input. Statements like "Ask the user which..." or "Confirm with the user before..." are invalid because the agent has no communication channel to the user. 2. **Never wait for user decisions** — An agent must be able to complete its work with the inputs it receives. If a decision point exists, the agent must either (a) make the decision using documented rules in its definition or referenced skills, or (b) document the decision it made in its output so the caller can review. 3. **Never reference user preferences at runtime** — Phrases like "based on user preference" or "if the user wants..." are invalid. All configuration must come from files (specs, plans, settings) or the invoking command's parameters. 4. **Output is for the caller, not the user** — The agent's output goes back to the command or agent that invoked it. Write output as structured results (checklists, reports, code), not conversational prose aimed at a human. 5. **Errors are output, not questions** — When an agent encounters an ambiguity or missing information, it must document the issue in its output (e.g., flag it in a review report) rather than asking for help. 6. **Transitive: referenced skills must also be interaction-free** — Sk