golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bb9c190ac8cc5010ee2e4e348261e1a29d5f4e2b
msd-core/docs/AGENTS.md
Tom Boucher 80605d2051 docs: add developer profiling, execution hardening, and idempotent mark-complete to docs (#1108) 
Update documentation for features added since v1.25.1:

- CHANGELOG.md: Add [Unreleased] entries for developer profiling pipeline,
  execution hardening (pre-wave check, cross-plan contracts, export
  spot-check), and idempotent requirements mark-complete

- README.md: Add /gsd:profile-user command to utilities table

- docs/COMMANDS.md: Add full /gsd:profile-user command documentation
  with flags, generated artifacts, and usage examples

- docs/FEATURES.md: Add Feature 33 (Developer Profiling) with 8
  behavioral dimensions, pipeline modules, and requirements; add
  Feature 34 (Execution Hardening) with 3 quality components

- docs/AGENTS.md: Add gsd-user-profiler agent documentation and
  tool permissions entry
2026-03-16 13:39:52 -06:00

381 lines
12 KiB
Markdown
Raw Blame History

# GSD Agent Reference
> All 15 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md).
---
## Overview
GSD uses a multi-agent architecture where thin orchestrators (workflow files) spawn specialized agents with fresh context windows. Each agent has a focused role, limited tool access, and produces specific artifacts.
### Agent Categories
| Category | Count | Agents |
|----------|-------|--------|
| Researchers | 3 | project-researcher, phase-researcher, ui-researcher |
| Synthesizers | 1 | research-synthesizer |
| Planners | 1 | planner |
| Roadmappers | 1 | roadmapper |
| Executors | 1 | executor |
| Checkers | 3 | plan-checker, integration-checker, ui-checker |
| Verifiers | 1 | verifier |
| Auditors | 2 | nyquist-auditor, ui-auditor |
| Mappers | 1 | codebase-mapper |
| Debuggers | 1 | debugger |
---
## Agent Details
### gsd-project-researcher
**Role:** Researches domain ecosystem before roadmap creation.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:new-project`, `/gsd:new-milestone` |
| **Parallelism** | 4 instances (stack, features, architecture, pitfalls) |
| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
| **Model (balanced)** | Sonnet |
| **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |
**Capabilities:**
- Web search for current ecosystem information
- Context7 MCP integration for library documentation
- Writes research documents directly to disk (reduces orchestrator context load)
---
### gsd-phase-researcher
**Role:** Researches how to implement a specific phase before planning.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:plan-phase` |
| **Parallelism** | 4 instances (same focus areas as project researcher) |
| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
| **Model (balanced)** | Sonnet |
| **Produces** | `{phase}-RESEARCH.md` |
**Capabilities:**
- Reads CONTEXT.md to focus research on user's decisions
- Investigates implementation patterns for the specific phase domain
- Detects test infrastructure for Nyquist validation mapping
---
### gsd-ui-researcher
**Role:** Produces UI design contracts for frontend phases.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:ui-phase` |
| **Parallelism** | Single instance |
| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
| **Model (balanced)** | Sonnet |
| **Color** | `#E879F9` (fuchsia) |
| **Produces** | `{phase}-UI-SPEC.md` |
**Capabilities:**
- Detects design system state (shadcn components.json, Tailwind config, existing tokens)
- Offers shadcn initialization for React/Next.js/Vite projects
- Asks only unanswered design contract questions
- Enforces registry safety gate for third-party components
---
### gsd-research-synthesizer
**Role:** Combines outputs from parallel researchers into a unified summary.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:new-project` (after 4 researchers complete) |
| **Parallelism** | Single instance (sequential after researchers) |
| **Tools** | Read, Write, Bash |
| **Model (balanced)** | Sonnet |
| **Color** | Purple |
| **Produces** | `.planning/research/SUMMARY.md` |
---
### gsd-planner
**Role:** Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:plan-phase`, `/gsd:quick` |
| **Parallelism** | Single instance |
| **Tools** | Read, Write, Bash, Glob, Grep, WebFetch, mcp (context7) |
| **Model (balanced)** | Opus |
| **Color** | Green |
| **Produces** | `{phase}-{N}-PLAN.md` files |
**Key behaviors:**
- Reads PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md
- Creates 2-3 atomic task plans sized for single context windows
- Uses XML structure with `<task>` elements
- Includes `read_first` and `acceptance_criteria` sections
- Groups plans into dependency waves
---
### gsd-roadmapper
**Role:** Creates project roadmaps with phase breakdown and requirement mapping.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:new-project` |
| **Parallelism** | Single instance |
| **Tools** | Read, Write, Bash, Glob, Grep |
| **Model (balanced)** | Sonnet |
| **Color** | Purple |
| **Produces** | `ROADMAP.md` |
**Key behaviors:**
- Maps requirements to phases (traceability)
- Derives success criteria from requirements
- Respects granularity setting for phase count
- Validates coverage (every v1 requirement mapped to a phase)
---
### gsd-executor
**Role:** Executes GSD plans with atomic commits, deviation handling, and checkpoint protocols.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:execute-phase`, `/gsd:quick` |
| **Parallelism** | Multiple (parallel within waves, sequential across waves) |
| **Tools** | Read, Write, Edit, Bash, Grep, Glob |
| **Model (balanced)** | Sonnet |
| **Color** | Yellow |
| **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` |
**Key behaviors:**
- Fresh 200K context window per plan
- Follows XML task instructions precisely
- Atomic git commit per completed task
- Handles checkpoint types: auto, human-verify, decision, human-action
- Reports deviations from plan in SUMMARY.md
- Invokes node repair on verification failure
---
### gsd-plan-checker
**Role:** Verifies plans will achieve phase goals before execution.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:plan-phase` (verification loop, max 3 iterations) |
| **Parallelism** | Single instance (iterative) |
| **Tools** | Read, Bash, Glob, Grep |
| **Model (balanced)** | Sonnet |
| **Color** | Green |
| **Produces** | PASS/FAIL verdict with specific feedback |
**8 Verification Dimensions:**
1. Requirement coverage
2. Task atomicity
3. Dependency ordering
4. File scope
5. Verification commands
6. Context fit
7. Gap detection
8. Nyquist compliance (when enabled)
---
### gsd-integration-checker
**Role:** Verifies cross-phase integration and end-to-end flows.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:audit-milestone` |
| **Parallelism** | Single instance |
| **Tools** | Read, Bash, Grep, Glob |
| **Model (balanced)** | Sonnet |
| **Color** | Blue |
| **Produces** | Integration verification report |
---
### gsd-ui-checker
**Role:** Validates UI-SPEC.md design contracts against quality dimensions.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:ui-phase` (validation loop, max 2 iterations) |
| **Parallelism** | Single instance |
| **Tools** | Read, Bash, Glob, Grep |
| **Model (balanced)** | Sonnet |
| **Color** | `#22D3EE` (cyan) |
| **Produces** | BLOCK/FLAG/PASS verdict |
---
### gsd-verifier
**Role:** Verifies phase goal achievement through goal-backward analysis.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:execute-phase` (after all executors complete) |
| **Parallelism** | Single instance |
| **Tools** | Read, Write, Bash, Grep, Glob |
| **Model (balanced)** | Sonnet |
| **Color** | Green |
| **Produces** | `{phase}-VERIFICATION.md` |
**Key behaviors:**
- Checks codebase against phase goals, not just task completion
- PASS/FAIL with specific evidence
- Logs issues for `/gsd:verify-work` to address
---
### gsd-nyquist-auditor
**Role:** Fills Nyquist validation gaps by generating tests.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:validate-phase` |
| **Parallelism** | Single instance |
| **Tools** | Read, Write, Edit, Bash, Grep, Glob |
| **Model (balanced)** | Sonnet |
| **Produces** | Test files, updated `VALIDATION.md` |
**Key behaviors:**
- Never modifies implementation code — only test files
- Max 3 attempts per gap
- Flags implementation bugs as escalations for user
---
### gsd-ui-auditor
**Role:** Retroactive 6-pillar visual audit of implemented frontend code.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:ui-review` |
| **Parallelism** | Single instance |
| **Tools** | Read, Write, Bash, Grep, Glob |
| **Model (balanced)** | Sonnet |
| **Color** | `#F472B6` (pink) |
| **Produces** | `{phase}-UI-REVIEW.md` with scores |
**6 Audit Pillars (scored 1-4):**
1. Copywriting
2. Visuals
3. Color
4. Typography
5. Spacing
6. Experience Design
---
### gsd-codebase-mapper
**Role:** Explores codebase and writes structured analysis documents.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:map-codebase` |
| **Parallelism** | 4 instances (tech, architecture, quality, concerns) |
| **Tools** | Read, Bash, Grep, Glob, Write |
| **Model (balanced)** | Haiku |
| **Color** | Cyan |
| **Produces** | `.planning/codebase/*.md` (7 documents) |
**Key behaviors:**
- Read-only exploration + structured output
- Writes documents directly to disk
- No reasoning required — pattern extraction from file contents
---
### gsd-debugger
**Role:** Investigates bugs using scientific method with persistent state.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:debug`, `/gsd:verify-work` (for failures) |
| **Parallelism** | Single instance (interactive) |
| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch |
| **Model (balanced)** | Sonnet |
| **Color** | Orange |
| **Produces** | `.planning/debug/*.md`, knowledge-base updates |
**Debug Session Lifecycle:**
`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved`
**Key behaviors:**
- Tracks hypotheses, evidence, and eliminated theories
- State persists across context resets
- Requires human verification before marking resolved
- Appends to persistent knowledge base on resolution
- Consults knowledge base on new sessions
---
### gsd-user-profiler
**Role:** Analyzes session messages across 8 behavioral dimensions to produce a scored developer profile.
| Property | Value |
|----------|-------|
| **Spawned by** | `/gsd:profile-user` |
| **Parallelism** | Single instance |
| **Tools** | Read |
| **Model (balanced)** | Sonnet |
| **Color** | Magenta |
| **Produces** | `USER-PROFILE.md`, `/gsd:dev-preferences`, `CLAUDE.md` profile section |
**Behavioral Dimensions:**
Communication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth.
**Key behaviors:**
- Read-only agent — analyzes extracted session data, does not modify files
- Produces scored dimensions with confidence levels and evidence citations
- Questionnaire fallback when session history is unavailable
---
## Agent Tool Permissions Summary
| Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |
|-------|------|-------|------|------|------|------|-----------|----------|-----|
| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| research-synthesizer | ✓ | ✓ | | ✓ | | | | | |
| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |
| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |
| user-profiler | ✓ | | | | | | | | |
**Principle of Least Privilege:**
- Checkers are read-only (no Write/Edit) — they evaluate, never modify
- Researchers have web access — they need current ecosystem information
- Executors have Edit — they modify code but not web access
- Mappers have Write — they write analysis documents but not Edit (no code changes)
Reference in New Issue View Git Blame Copy Permalink