Skip to content

docs: add 3 missing agents to AGENTS.md and fix stale counts #1703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trek-e merged 1 commit into from
Apr 4, 2026
Merged

docs: add 3 missing agents to AGENTS.md and fix stale counts #1703

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 72 additions & 2 deletions docs/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).

---

Expand All @@ -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 |

---

Expand Down Expand Up @@ -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 |
Expand All @@ -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
Expand Down