agents-standards

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 — Skills loaded by an agent become part of the agent's context. If a skill assumes user interaction (e.g., "present options to the user", "let the user respond", "multi-turn conversation"), the agent inherits that assumption and will attempt to interact with a user it cannot reach. During audit, scan all skills referenced by each agent for user interaction patterns — not just the agent file itself.

BAD

## Workflow
1. Read the spec
2. Ask the user which components to implement
3. Confirm the approach with the user before proceeding

The agent cannot ask or confirm anything with the user. It has no user channel.

GOOD

## Workflow
1. Read the spec and plan
2. Identify components from the plan's phase details
3. Implement components as specified
4. Document any ambiguities in the output for caller review

The agent derives decisions from its inputs and flags issues in its output.

Skill References

Agents reference skills as instructional context — the skills define patterns and standards the agent must follow. This is a "load and apply" relationship, not input/output composition.

Format

## Skills

**CRITICAL: You MUST read and follow ALL patterns defined in these skills. They are mandatory, not optional reference material. ALL code you write or scaffold MUST adhere to these standards.**

- `typescript-standards` — Strict typing, immutability, arrow functions
- `backend-standards` — CMDO architecture, layer separation, telemetry

The bold CRITICAL line is mandatory. Without it, agents treat skills as optional reference material and ignore them in practice. The "ALL code you write or scaffold" clause ensures generated/scaffolded files also adhere to the standards.

Rules

1. Mandatory language required — The Skills section MUST include the CRITICAL preamble shown above. The phrase "for reference" or "for standards and patterns" alone is too passive — agents will not follow the skills.
2. Reinforce in Rules section — For each skill, add a corresponding "Follow all skill-name skill requirements" line in the agent's Rules section. Double reinforcement ensures compliance.
3. **Bri