refactor: restructure agent system for consolidation (#149)

Restructures the SQLSpec agent system to eliminate duplication, clarify automated workflows, and establish AGENTS.md as the single source of truth for all AI coding assistants (Claude, Gemini, Codex, etc.).

Author: cofin

.claude/AGENTS.md

@@ -0,0 +1 @@
+../AGENTS.md

.claude/AGENTS.md

@@ -7,8 +7,8 @@ Enhanced agent system for AI-assisted SQLSpec development, compatible with Claud
 ## Quick Start
 
 ```bash
-# 1. Plan a feature
-/plan implement vector search for Oracle
+# 1. Create PRD for a feature
+/prd implement vector search for Oracle
 
 # 2. Implement it
 /implement
@@ -22,18 +22,18 @@ Enhanced agent system for AI-assisted SQLSpec development, compatible with Claud
 
 ## Core Agents (Enhanced System)
 
-### 1. **Planner** - Strategic Planning
+### 1. **PRD** - Product Requirements and Design
 
 - Research-grounded planning (guides + Context7 + WebSearch)
 - Structured multi-step plans via zen.planner
 - Multi-model consensus via zen.consensus
-- Creates workspace in `requirements/{requirement}/`
+- Creates workspace in `specs/active/{requirement}/`
 
-**Invoke:** `/plan {feature description}`
+**Invoke:** `/prd {feature description}`
 
 ### 2. **Expert** - Implementation
 
-- Implements features following CLAUDE.md standards
+- Implements features following AGENTS.md standards
 - Uses zen.debug for systematic debugging
 - Uses zen.thinkdeep for complex decisions
 - Uses zen.analyze for code analysis
@@ -63,7 +63,7 @@ Three sequential phases:
 ## Workspace Structure
 
 ```
-requirements/
+specs/active/
 ├── {requirement-slug}/      # Active requirement
 │   ├── prd.md               # Product Requirements Document
 │   ├── tasks.md             # Implementation checklist
@@ -94,10 +94,10 @@ These guides are the **canonical source of truth** for SQLSpec patterns.
 
 ### Full Feature Development
 
-1. **Plan:** Research → Structured planning → Create workspace
+1. **PRD:** Research → Structured planning → Create workspace
 
    ```bash
-   /plan add connection pooling for asyncpg
+   /prd add connection pooling for asyncpg
    ```
 
 2. **Implement:** Read plan → Implement → Test → Update workspace
@@ -120,7 +120,7 @@ These guides are the **canonical source of truth** for SQLSpec patterns.
 
 ### Bug Fix
 
-1. **Plan (optional):** Quick plan for complex bugs
+1. **PRD (optional):** Quick PRD for complex bugs
 2. **Implement:** Use zen.debug for systematic investigation
 3. **Test:** Add regression test
 4. **Review:** Quality gate + cleanup
@@ -131,14 +131,14 @@ Resume work across sessions/context resets:
 
 ```python
 # Find active work
-Read("requirements/{requirement}/recovery.md")  # Shows status, next steps
-Read("requirements/{requirement}/tasks.md")      # Shows what's done
-Read("requirements/{requirement}/prd.md")        # Full context
+Read("specs/active/{requirement}/recovery.md")  # Shows status, next steps
+Read("specs/active/{requirement}/tasks.md")      # Shows what's done
+Read("specs/active/{requirement}/prd.md")        # Full context
 ```
 
 ## Code Quality Standards
 
-All agents enforce [CLAUDE.md](../CLAUDE.md) standards:
+All agents enforce [AGENTS.md](../AGENTS.md) standards:
 
 ### ✅ ALWAYS
 
@@ -160,13 +160,13 @@ All agents enforce [CLAUDE.md](../CLAUDE.md) standards:
 
 Structured multi-step planning workflow
 
-**Used by:** Planner
+**Used by:** PRD
 
 ### zen.consensus
 
 Multi-model decision verification (gemini-2.5-pro, gpt-5)
 
-**Used by:** Planner, Expert
+**Used by:** PRD, Expert
 
 ### zen.debug
 
@@ -217,7 +217,7 @@ Current best practices (2025+)
 **MANDATORY after every `/review`:**
 
 1. Remove all `tmp/` directories
-2. Archive completed requirement to `requirements/archive/`
+2. Archive completed requirement to `specs/active/archive/`
 3. Keep only last 3 active requirements
 4. Archive planning reports to `.claude/reports/archive/`
 
@@ -227,8 +227,8 @@ Current best practices (2025+)
 
 - **[AGENTS.md](AGENTS.md)** - Comprehensive agent coordination guide
 - **[../docs/guides/README.md](../docs/guides/README.md)** - Index of all development guides
-- **[../requirements/README.md](../requirements/README.md)** - Workspace structure and usage
-- **[../CLAUDE.md](../CLAUDE.md)** - Code quality standards (mandatory reading)
+- **[../specs/active/README.md](../specs/active/README.md)** - Workspace structure and usage
+- **[../AGENTS.md](../AGENTS.md)** - Code quality standards (mandatory reading)
 
 ## Archive
 
@@ -249,15 +249,15 @@ Run enhancement bootstrap again when:
 
 - **2025-10-09:** Major enhancement
     - Consolidated guides to `docs/guides/`
-    - Created 4 core agents (Planner, Expert, Testing, Docs & Vision)
-    - Added `requirements/` workspace system
+    - Created 4 core agents (PRD, Expert, Testing, Docs & Vision)
+    - Added `specs/active/` workspace system
     - Added mandatory cleanup protocols
-    - Created workflow commands (`/plan`, `/implement`, `/test`, `/review`)
+    - Created workflow commands (`/prd`, `/implement`, `/test`, `/review`)
     - Archived old agents and guides
 
 ## See Also
 
 - [Agent Coordination Guide](AGENTS.md) - Detailed agent workflows
-- [Code Quality Standards](../CLAUDE.md) - MANDATORY coding standards
+- [Code Quality Standards](../AGENTS.md) - MANDATORY coding standards
 - [Development Guides](../docs/guides/) - Canonical pattern reference
-- [Workspace Guide](../requirements/README.md) - Workspace management
+- [Workspace Guide](../specs/active/README.md) - Workspace management

.claude/README.md

@@ -3,6 +3,9 @@ name: docs-vision
 description: Documentation excellence, quality gate validation, and workspace cleanup specialist - ensures code quality, comprehensive docs, and clean workspace before completion
 tools: mcp__context7__resolve-library-id, mcp__context7__get-library-docs, WebSearch, Read, Write, Edit, Bash, Glob, Grep
 model: sonnet
+standards_uri: ../AGENTS.md#mandatory-code-quality-standards
+guides_root: ../docs/guides/
+workspace_root: ../specs/active/
 ---
 
 # Docs & Vision Agent
@@ -203,7 +206,7 @@ Quality gate MUST pass before moving to Phase 3 (Cleanup).
 ### Step 1: Read Quality Standards
 
 ```python
-Read("CLAUDE.md")  # Code quality standards
+Read("AGENTS.md")  # Code quality standards
 Read("docs/guides/testing/testing.md")  # Testing standards
 ```
 
@@ -814,6 +817,6 @@ def test_asyncpg_connection_basic():
 ✅ **Phase 4 Complete** - Re-validation passed after updates
 ✅ **Phase 5 Complete** - Workspace cleaned and archived
 ✅ **All tests pass** - `make lint && make test` success
-✅ **Standards followed** - CLAUDE.md compliance
+✅ **Standards followed** - AGENTS.md compliance
 ✅ **Knowledge preserved** - Future implementations benefit
 ✅ **Clean handoff** - Ready for PR/commit

.claude/agents/docs-vision.md

@@ -3,6 +3,9 @@ name: expert
 description: SQLSpec domain expert with comprehensive knowledge of database adapters, SQL parsing, type system, storage backends, and Litestar integration
 tools: mcp__context7__resolve-library-id, mcp__context7__get-library-docs, WebSearch, mcp__zen__analyze, mcp__zen__thinkdeep, mcp__zen__debug, Read, Edit, Bash, Glob, Grep, Task
 model: sonnet
+standards_uri: ../AGENTS.md#mandatory-code-quality-standards
+guides_root: ../docs/guides/
+workspace_root: ../specs/active/
 ---
 
 # Expert Agent
@@ -14,12 +17,12 @@ Domain expert for SQLSpec implementation. Handles all technical work: core devel
 1. **Implementation** - Write clean, type-safe, performant code
 2. **Debugging** - Use zen.debug for systematic root cause analysis
 3. **Deep Analysis** - Use zen.thinkdeep for complex architectural decisions
-4. **Code Quality** - Enforce CLAUDE.md standards ruthlessly
+4. **Code Quality** - Enforce AGENTS.md standards ruthlessly
 5. **Documentation** - Update technical docs and code comments
 
 ## Implementation Workflow
 
-Codex or Gemini CLI can emulate this workflow without the `/implement` command. When prompted to “run the implementation phase” for a workspace, either assistant must follow every step below, then continue with the Testing and Docs & Vision sequences described in their respective agent guides. Always read the active workspace in `specs/active/{requirement}/` (or `requirements/{requirement}/` if legacy) before making changes. Claude should rely on `/implement` unless explicitly directed to operate manually.
+Codex or Gemini CLI can emulate this workflow without the `/implement` command. When prompted to “run the implementation phase” for a workspace, either assistant must follow every step below, then continue with the Testing and Docs & Vision sequences described in their respective agent guides. Always read the active workspace in `specs/active/{requirement}/`  before making changes. Claude should rely on `/implement` unless explicitly directed to operate manually.
 
 ### Step 1: Read the Plan
 
@@ -53,7 +56,7 @@ Read("docs/guides/architecture/architecture.md")
 Read("docs/guides/architecture/data-flow.md")
 
 # Code quality standards
-Read("CLAUDE.md")
+Read("AGENTS.md")
 
 # Quick reference for common patterns
 Read("docs/guides/quick-reference/quick-reference.md")
@@ -74,7 +77,7 @@ mcp__context7__get-library-docs(
 
 ### Step 3: Implement with Quality Standards
 
-**MANDATORY CODE QUALITY RULES** (from CLAUDE.md):
+**MANDATORY CODE QUALITY RULES** (from AGENTS.md):
 
 ✅ **DO:**
 
@@ -457,6 +460,49 @@ The Expert agent orchestrates a complete workflow:
 3. Docs & Vision agent confirms knowledge captured in AGENTS.md and guides
 4. Spec is properly archived to specs/archive/
 
+## Automated Sub-Agent Invocation
+
+**IMPORTANT**: The Expert agent **automatically invokes** Testing and Docs & Vision agents upon completing implementation. This is **NOT optional** - it's part of the core workflow.
+
+### When to Auto-Invoke
+
+After implementation is complete and local tests pass:
+
+1. **Always invoke Testing agent** (`subagent_type="testing"`):
+   - Creates comprehensive unit and integration tests
+   - Verifies test coverage meets thresholds (80%+ adapters, 90%+ core)
+   - Tests edge cases, errors, concurrency
+   - Ensures all tests pass
+
+2. **Always invoke Docs & Vision agent** (`subagent_type="docs-vision"`):
+   - Phase 1: Updates documentation
+   - Phase 2: Runs quality gate validation (BLOCKS if fails)
+   - Phase 3: Captures new patterns in AGENTS.md and guides
+   - Phase 4: Re-validates after documentation updates
+   - Phase 5: Cleans workspace and archives to specs/archive/
+
+### Invocation Pattern
+
+```python
+# After implementation complete and local tests pass:
+
+# 1. Invoke Testing agent
+Task(
+    subagent_type="testing",
+    description="Create comprehensive test suite",
+    prompt="Create unit and integration tests for [feature]. Verify coverage and edge cases."
+)
+
+# 2. Invoke Docs & Vision agent
+Task(
+    subagent_type="docs-vision",
+    description="Documentation, QA, and archival",
+    prompt="Complete 5-phase workflow: docs, quality gate, knowledge capture, re-validation, archive."
+)
+```
+
+**Result**: When `/implement` completes, the feature is fully implemented, tested, documented, quality-validated, patterns captured, and archived. No manual `/test` or `/review` commands needed!
+
 ## Tools Available
 
 - **zen.debug** - Systematic debugging workflow
@@ -503,7 +549,7 @@ Task(subagent_type="docs-vision", description="Complete workflow", prompt=...)
 
 ## Success Criteria
 
-✅ **Standards followed** - CLAUDE.md compliance
+✅ **Standards followed** - AGENTS.md compliance
 ✅ **Guides consulted** - Referenced relevant docs
 ✅ **Tests pass** - `make lint` and `make test` pass
 ✅ **Performance considered** - SQLglot and mypyc patterns followed

.claude/agents/expert.md

@@ -1,13 +1,16 @@
 ---
-name: planner
-description: Multi-session planning agent for complex SQLSpec development spanning multiple files, adapters, and features
+name: prd
+description: Product Requirements and Design agent for complex SQLSpec development spanning multiple files, adapters, and features
 tools: mcp__zen__planner, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, WebSearch, mcp__zen__consensus, Read, Glob, Grep
 model: sonnet
+standards_uri: ../AGENTS.md#mandatory-code-quality-standards
+guides_root: ../docs/guides/
+workspace_root: ../specs/active/
 ---
 
-# Planner Agent
+# PRD Agent
 
-Strategic planning agent for SQLSpec development. Creates research-grounded, multi-session plans for complex features spanning multiple database adapters, storage backends, or framework integrations.
+Product Requirements and Design agent for SQLSpec development. Creates research-grounded, multi-session plans for complex features spanning multiple database adapters, storage backends, or framework integrations.
 
 ## Core Responsibilities
 
@@ -18,7 +21,7 @@ Strategic planning agent for SQLSpec development. Creates research-grounded, mul
 
 ## Planning Workflow
 
-Codex or Gemini CLI can mirror this workflow without using `/plan`. When either assistant is asked to “plan {feature}”, it must follow every step below, create or update the workspace at `specs/active/{requirement}/` (fallback `requirements/{requirement}/`), and generate the same artifacts the Planner agent would produce. Claude should continue to rely on the `/plan` command unless instructed otherwise.
+Codex or Gemini CLI can mirror this workflow without using `/prd`. When either assistant is asked to "create PRD for {feature}", it must follow every step below, create or update the workspace at `specs/active/{requirement}/` , and generate the same artifacts the PRD agent would produce. Claude should continue to rely on the `/prd` command unless instructed otherwise.
 
 ### Step 1: Understand Requirements
 
@@ -49,7 +52,7 @@ Codex or Gemini CLI can mirror this workflow without using `/plan`. When either
    Read("docs/guides/testing/testing.md")
 
    # Code quality standards
-   Read("CLAUDE.md")
+   Read("AGENTS.md")
    ```
 
 2. **Context7** (for library documentation):
@@ -196,7 +199,7 @@ Read(f"docs/guides/adapters/{adapter}.md")
 
 ## Anti-Patterns to Avoid
 
-Based on CLAUDE.md standards:
+Based on AGENTS.md standards:
 
 ❌ **NO defensive programming**:
 
@@ -238,7 +241,7 @@ After planning complete:
 
 2. **Notify user**:
 
-   ```
+   ```text
    Planning complete! Workspace created at `specs/active/{requirement-slug}/`.
 
    Next: Invoke Expert agent to begin implementation.
@@ -294,4 +297,4 @@ mcp__zen__planner(
 ✅ **Decisions verified** - Consensus on complex choices
 ✅ **Workspace created** - `specs/active/{requirement}/` fully populated
 ✅ **Resumable** - recovery.md enables session continuity
-✅ **Standards followed** - CLAUDE.md patterns enforced
+✅ **Standards followed** - AGENTS.md patterns enforced

.claude/agents/planner.md .claude/agents/prd.md.claude/agents/planner.md renamed to .claude/agents/prd.md

@@ -3,6 +3,9 @@ name: testing
 description: Comprehensive testing specialist for SQLSpec - creates unit tests, integration tests, fixtures, and validates test coverage across all database adapters
 tools: mcp__context7__resolve-library-id, mcp__context7__get-library-docs, Read, Write, Edit, Bash, Glob, Grep
 model: sonnet
+standards_uri: ../AGENTS.md#mandatory-code-quality-standards
+guides_root: ../docs/guides/
+workspace_root: ../specs/active/
 ---
 
 # Testing Agent
@@ -87,7 +90,7 @@ def test_statement_parameter_replacement():
     assert "$1" in converted.sql
 ```
 
-**Testing standards (from CLAUDE.md):**
+**Testing standards (from AGENTS.md):**
 
 ✅ **DO:**
 

.claude/agents/testing.md

@@ -23,14 +23,13 @@ The expert should:
 - Use zen.analyze for code analysis
 - Update workspace progress continuously
 
-**This ONE command handles:**
-✅ Implementation
-✅ Testing (automatic via Testing agent)
-✅ Documentation (automatic via Docs & Vision)
-✅ Quality gate (automatic via Docs & Vision)
-✅ **Knowledge capture** (automatic via Docs & Vision)
-✅ **Re-validation** (automatic via Docs & Vision)
+**This ONE command automatically runs the entire workflow:**
+✅ Implementation (Expert agent)
+✅ `/test` - Testing (automatic via Testing agent invocation)
+✅ `/review` - Documentation, quality gate, knowledge capture (automatic via Docs & Vision agent invocation)
 ✅ Archival (automatic via Docs & Vision)
 
-**After implementation:**
-Feature is complete, tested, documented, patterns captured, and archived!
+**Equivalent to running:** `/implement` → auto-runs `/test` → auto-runs `/review` → auto-archives
+
+**After completion:**
+Feature is fully implemented, comprehensively tested, documented, quality-validated, patterns captured in AGENTS.md and guides, and archived to specs/archive/!

.claude/commands/implement.md

@@ -1,6 +1,6 @@
-Create a comprehensive, research-grounded plan for: {{prompt}}
+Create a comprehensive Product Requirements Document and design plan for: {{prompt}}
 
-Invoke the Planner agent to:
+Invoke the PRD agent to:
 
 1. **Research** - Consult docs/guides/, Context7, and WebSearch
 2. **Plan** - Use zen.planner for structured planning
@@ -12,7 +12,7 @@ Invoke the Planner agent to:
    - recovery.md (Session resume instructions)
    - tmp/ (temporary files directory)
 
-The planner should reference:
+The PRD agent should reference:
 
 - docs/guides/adapters/ for database-specific patterns
 - docs/guides/performance/ for optimization strategies