improve prompts to force CC to proactively invoke subagents

Author: izeigerman

.claude/agents/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: Use this agent when you need expert code review after writing or modifying code. This agent should be called after completing any coding task to ensure quality, architectural compliance, and catch potential issues. Examples: <example>Context: The user has just implemented a new feature for processing SQLMesh snapshots. user: 'I just added a new method to handle snapshot fingerprinting in the Context class' assistant: 'Let me use the code-reviewer agent to analyze this implementation for potential issues and architectural compliance' <commentary>Since code was just written, use the code-reviewer agent to review the implementation for quality, edge cases, and adherence to SQLMesh patterns.</commentary></example> <example>Context: An agent just generated a database migration script. user: 'Here's the migration I created for adding a new state table' assistant: 'Now I'll have the code-reviewer agent examine this migration for safety and best practices' <commentary>Since a migration was created, use the code-reviewer agent to ensure it follows SQLMesh migration patterns and handles edge cases safely.</commentary></example>
+description: Use this agent PROACTIVELY when you need expert code review after writing or modifying code. This agent should be called after completing any coding task to ensure quality, architectural compliance, and catch potential issues. Examples: <example>Context: The user has just implemented a new feature for processing SQLMesh snapshots. user: 'I just added a new method to handle snapshot fingerprinting in the Context class' assistant: 'Let me use the code-reviewer agent to analyze this implementation for potential issues and architectural compliance' <commentary>Since code was just written, use the code-reviewer agent to review the implementation for quality, edge cases, and adherence to SQLMesh patterns.</commentary></example> <example>Context: An agent just generated a database migration script. user: 'Here's the migration I created for adding a new state table' assistant: 'Now I'll have the code-reviewer agent examine this migration for safety and best practices' <commentary>Since a migration was created, use the code-reviewer agent to ensure it follows SQLMesh migration patterns and handles edge cases safely.</commentary></example>
 tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, Bash
 model: sonnet
 color: blue

.claude/agents/developer.md

@@ -1,6 +1,6 @@
 ---
 name: developer
-description: Use this agent when you need to implement new features, write comprehensive tests, refactor existing code, fix bugs, or make any code changes that require deep understanding of the project's architecture and coding standards. Examples: <example>Context: User wants to add a new SQL dialect adapter to SQLMesh. user: 'I need to implement support for Oracle database in SQLMesh' assistant: 'I'll use the software-engineer agent to implement the Oracle adapter following SQLMesh's engine adapter patterns' <commentary>Since this requires implementing a new feature with proper architecture understanding, use the software-engineer agent.</commentary></example> <example>Context: User discovers a bug in the migration system. user: 'The migration v0084 is failing on MySQL due to field size limits' assistant: 'Let me use the software-engineer agent to investigate and fix this migration issue' <commentary>This requires debugging and fixing code while understanding SQLMesh's migration patterns, so use the software-engineer agent.</commentary></example> <example>Context: User needs comprehensive tests for a new feature. user: 'I just implemented a new snapshot fingerprinting algorithm and need tests' assistant: 'I'll use the software-engineer agent to write comprehensive tests following SQLMesh's testing patterns' <commentary>Writing thorough tests requires understanding the codebase architecture and testing conventions, so use the software-engineer agent.</commentary></example>
+description: Use this agent PROACTIVELY when you need to understand the user's task, read GitHub issues, implement new features, write comprehensive tests, refactor existing code, fix bugs, or make any code changes that require deep understanding of the project's architecture and coding standards. Examples: <example>Context: User wants to add a new SQL dialect adapter to SQLMesh. user: 'I need to implement support for Oracle database in SQLMesh' assistant: 'I'll use the software-engineer agent to implement the Oracle adapter following SQLMesh's engine adapter patterns' <commentary>Since this requires implementing a new feature with proper architecture understanding, use the software-engineer agent.</commentary></example> <example>Context: User discovers a bug in the migration system. user: 'The migration v0084 is failing on MySQL due to field size limits' assistant: 'Let me use the software-engineer agent to investigate and fix this migration issue' <commentary>This requires debugging and fixing code while understanding SQLMesh's migration patterns, so use the software-engineer agent.</commentary></example> <example>Context: User needs comprehensive tests for a new feature. user: 'I just implemented a new snapshot fingerprinting algorithm and need tests' assistant: 'I'll use the software-engineer agent to write comprehensive tests following SQLMesh's testing patterns' <commentary>Writing thorough tests requires understanding the codebase architecture and testing conventions, so use the software-engineer agent.</commentary></example>
 model: sonnet
 color: red
 ---

.claude/agents/technical-writer.md

@@ -1,6 +1,6 @@
 ---
 name: technical-writer
-description: Use this agent when you need to create, update, or maintain technical documentation for SQLMesh. Examples include: writing user guides for virtual environments, creating API documentation for new features, updating existing docs after code changes, writing deep-dive technical explanations of core concepts like fingerprinting or state sync, creating migration guides for users upgrading between versions, or documenting new engine adapter implementations. This agent should be used proactively when code changes affect user-facing functionality or when new features need documentation.
+description: Use this agent PROACTIVELY when you need to create, update, or maintain technical documentation for SQLMesh. Examples include: writing user guides for virtual environments, creating API documentation for new features, updating existing docs after code changes, writing deep-dive technical explanations of core concepts like fingerprinting or state sync, creating migration guides for users upgrading between versions, or documenting new engine adapter implementations. This agent should be used proactively when code changes affect user-facing functionality or when new features need documentation.
 model: sonnet
 color: white
 ---

CLAUDE.md

@@ -4,21 +4,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Agent-Based Development Workflow
 
-SQLMesh development follows a structured agent-based workflow to ensure high code quality and comprehensive documentation:
+Every time the user requests a feature or bug fix, you MUST follow the process below:
 
 ### Development Process
 
-1. **Feature Development & Bug Fixes**: Use the `developer` agent for implementing features and fixing bugs
-2. **Code Review**: After development work, invoke the `code-reviewer` agent to review the implementation
-3. **Iteration**: Use the `developer` agent again to address feedback from the code reviewer
-4. **Repeat**: Continue the developer → code-reviewer cycle until no more feedback remains
-5. **Documentation**: If the feature or bug fix requires documentation updates, invoke the `technical-writer` agent
+1. **Understanding The Task**: Use the `developer` agent to understand what the user is asking for and to read GitHub issues
+2. **Feature Development & Bug Fixes**: Use the `developer` agent for implementing features and fixing bugs
+3. **Code Review**: After development work, invoke the `code-reviewer` agent to review the implementation
+4. **Iteration**: Use the `developer` agent again to address feedback from the code reviewer
+5. **Repeat**: Continue the developer → code-reviewer cycle until no more feedback remains
+6. **Documentation**: If the feature or bug fix requires documentation updates, invoke the `technical-writer` agent
 
 IMPORTANT: Make sure to share the project overview, architecture overview, and other concepts outlined below with the agent when it is invoked.
 
 ### Agent Responsibilities
 
 **Developer Agent**:
+- Understands a feature request or a reported issue
 - Implements new features following SQLMesh's architecture patterns
 - Fixes bugs with proper understanding of the codebase
 - Writes comprehensive tests following SQLMesh's testing conventions