From 30a877762395beb7a071f257d8deba050780e059 Mon Sep 17 00:00:00 2001
From: Jeremy McSpadden <jeremy@fluxlabs.net>
Date: Sat, 4 Apr 2026 15:17:05 -0500
Subject: [PATCH] docs: add 3 missing agents to AGENTS.md and fix stale counts
 (#1703)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #1702

- Title: 18 → 21 agents
- Categories table: added Doc Writers (2), Profilers (1), bumped
  Auditors from 2 → 3 (security-auditor)
- Added full detail sections for gsd-doc-writer, gsd-doc-verifier,
  gsd-security-auditor with roles, tools, spawn patterns, and
  key behaviors
- Added 3 agents to tool permissions summary table
---
 docs/AGENTS.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 72 insertions(+), 2 deletions(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 600db46be..e8b945347 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -1,6 +1,6 @@
 # GSD Agent Reference
 
-> All 18 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md).
+> All 21 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md).
 
 ---
 
@@ -20,9 +20,11 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | Executors | 1 | executor |
 | Checkers | 3 | plan-checker, integration-checker, ui-checker |
 | Verifiers | 1 | verifier |
-| Auditors | 2 | nyquist-auditor, ui-auditor |
+| Auditors | 3 | nyquist-auditor, ui-auditor, security-auditor |
 | Mappers | 1 | codebase-mapper |
 | Debuggers | 1 | debugger |
+| Doc Writers | 2 | doc-writer, doc-verifier |
+| Profilers | 1 | user-profiler |
 
 ---
 
@@ -401,6 +403,71 @@ Communication style, decision patterns, debugging approach, UX preferences, vend
 
 ---
 
+### gsd-doc-writer
+
+**Role:** Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode, and project context.
+
+| Property | Value |
+|----------|-------|
+| **Spawned by** | `/gsd-docs-update` |
+| **Parallelism** | Multiple instances (one per doc type) |
+| **Tools** | Read, Write, Bash, Grep, Glob |
+| **Model (balanced)** | Sonnet |
+| **Color** | Purple |
+| **Produces** | Project documentation files (README, architecture, API docs, etc.) |
+
+**Key behaviors:**
+- Supports modes: create, update, supplement, fix
+- Handles doc types: readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing, custom
+- Monorepo-aware: can generate per-package READMEs
+- Fix mode accepts failure objects from gsd-doc-verifier for targeted corrections
+- Writes directly to disk — does not return content to orchestrator
+
+---
+
+### gsd-doc-verifier
+
+**Role:** Verifies factual claims in generated documentation against the live codebase.
+
+| Property | Value |
+|----------|-------|
+| **Spawned by** | `/gsd-docs-update` (after doc-writer completes) |
+| **Parallelism** | Multiple instances (one per doc file) |
+| **Tools** | Read, Write, Bash, Grep, Glob |
+| **Model (balanced)** | Sonnet |
+| **Color** | Orange |
+| **Produces** | Structured JSON verification results per doc |
+
+**Key behaviors:**
+- Extracts checkable claims (file paths, function names, CLI commands, config keys)
+- Verifies each claim against filesystem using tools only — no assumptions
+- Writes structured JSON result file for orchestrator to process
+- Failed claims feed back to doc-writer in fix mode
+
+---
+
+### gsd-security-auditor
+
+**Role:** Verifies threat mitigations from PLAN.md threat model exist in implemented code.
+
+| Property | Value |
+|----------|-------|
+| **Spawned by** | `/gsd-secure-phase` |
+| **Parallelism** | Single instance |
+| **Tools** | Read, Write, Edit, Bash, Glob, Grep |
+| **Model (balanced)** | Sonnet |
+| **Color** | `#EF4444` (red) |
+| **Produces** | `{phase}-SECURITY.md` |
+
+**Key behaviors:**
+- Verifies each threat by its declared disposition (mitigate / accept / transfer)
+- Does NOT scan blindly for new vulnerabilities — verifies declared mitigations only
+- Implementation files are read-only — never patches implementation code
+- Unmitigated threats reported as OPEN_THREATS or ESCALATE
+- Supports ASVS levels 1/2/3 for verification depth
+
+---
+
 ## Agent Tool Permissions Summary
 
 | Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |
@@ -423,6 +490,9 @@ Communication style, decision patterns, debugging approach, UX preferences, vend
 | codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |
 | user-profiler | ✓ | | | | | | | | |
+| doc-writer | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
+| doc-verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
+| security-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
 
 **Principle of Least Privilege:**
 - Checkers are read-only (no Write/Edit) — they evaluate, never modify