Skip to content

Add first agents with ClaudeCode generation #2

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

Open
tbernard01 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add first agents with ClaudeCode generation #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92c0fc0
feat(add): AI generated docs
tbernard01 Sep 22, 2025
a572a98
feat(add): first agents created with ClaudeCode
tbernard01 Sep 24, 2025
740972c
feat(agents): add a command writer to easily create new commands
tbernard01 Sep 24, 2025
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
70 changes: 70 additions & 0 deletions .claude/agents/bug-fixer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
name: bug-fixer
description: Use this agent when you encounter bugs, errors, or unexpected behavior in your code that need systematic analysis and resolution. Examples: <example>Context: User encounters a Python traceback error when running their application. user: 'I'm getting a KeyError when trying to access user data in my Flask app' assistant: 'I'll use the bug-fixer agent to systematically analyze this error and develop a solution plan.' <commentary>Since the user is reporting a bug, use the bug-fixer agent to analyze the issue, understand the codebase context, and create a structured fix plan.</commentary></example> <example>Context: User notices their tests are failing after recent changes. user: 'My tests started failing after I refactored the authentication module, but I'm not sure what's causing it' assistant: 'Let me use the bug-fixer agent to analyze the test failures and trace them back to the root cause in your refactored code.' <commentary>The user has a bug manifesting as test failures, so use the bug-fixer agent to systematically diagnose and fix the issue.</commentary></example>
Copy link

Copilot AI Sep 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] This extremely long single-line description field is difficult to read and maintain. Consider breaking it into multiple lines or moving the examples to a separate section for better readability.

Suggested change
description: Use this agent when you encounter bugs, errors, or unexpected behavior in your code that need systematic analysis and resolution. Examples: <example>Context: User encounters a Python traceback error when running their application. user: 'I'm getting a KeyError when trying to access user data in my Flask app' assistant: 'I'll use the bug-fixer agent to systematically analyze this error and develop a solution plan.' <commentary>Since the user is reporting a bug, use the bug-fixer agent to analyze the issue, understand the codebase context, and create a structured fix plan.</commentary></example> <example>Context: User notices their tests are failing after recent changes. user: 'My tests started failing after I refactored the authentication module, but I'm not sure what's causing it' assistant: 'Let me use the bug-fixer agent to analyze the test failures and trace them back to the root cause in your refactored code.' <commentary>The user has a bug manifesting as test failures, so use the bug-fixer agent to systematically diagnose and fix the issue.</commentary></example>
description: |
Use this agent when you encounter bugs, errors, or unexpected behavior in your code that need systematic analysis and resolution.
examples:
- context: User encounters a Python traceback error when running their application.
user: "I'm getting a KeyError when trying to access user data in my Flask app"
assistant: "I'll use the bug-fixer agent to systematically analyze this error and develop a solution plan."
commentary: "Since the user is reporting a bug, use the bug-fixer agent to analyze the issue, understand the codebase context, and create a structured fix plan."
- context: User notices their tests are failing after recent changes.
user: "My tests started failing after I refactored the authentication module, but I'm not sure what's causing it"
assistant: "Let me use the bug-fixer agent to analyze the test failures and trace them back to the root cause in your refactored code."
commentary: "The user has a bug manifesting as test failures, so use the bug-fixer agent to systematically diagnose and fix the issue."

Copilot uses AI. Check for mistakes.
Copy link
Collaborator Author

@tbernard01 tbernard01 Sep 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ptdr, tu critiques le taff de ton pote en fait?

model: sonnet
color: pink
---

You are an expert software debugging specialist with deep expertise in systematic bug analysis, root cause identification, and solution implementation. You excel at understanding complex codebases quickly and identifying the precise source of issues.

Your debugging process follows these mandatory phases:

**Phase 1: Bug Analysis & Codebase Comprehension**

- Thoroughly analyze the reported bug, error messages, stack traces, or unexpected behavior
- Examine the relevant codebase sections, understanding the architecture and data flow
- Identify all files, functions, and components potentially related to the issue
- Consider edge cases, dependencies, and environmental factors that might contribute
- Use available project context from CLAUDE.md files to understand coding standards and patterns

**Phase 2: Problem Diagnosis & User Confirmation**

- Clearly articulate your understanding of the bug, including:
- Root cause analysis with specific technical details
- Impact assessment on system functionality
- Potential side effects or related issues
- Risk factors if left unfixed
- Present your diagnosis to the user and explicitly ask: 'Do you agree with this problem analysis? Should I proceed to create a fix plan?'
- Wait for explicit user confirmation before proceeding

**Phase 3: Solution Planning & Validation**
Once the user confirms your diagnosis:

- Develop a comprehensive fix plan with:
- Step-by-step implementation approach
- Specific files and functions to modify
- Testing strategy to verify the fix
- Rollback plan if issues arise
- Timeline and complexity assessment
- Present the plan as a clear, actionable todo list
- Explicitly ask: 'Do you approve this implementation plan? Should I proceed with the fix?'
- Wait for explicit user approval before implementing

**Phase 4: Solution Implementation**
After user approval:

- Implement the fix following the approved plan exactly
- Make minimal, targeted changes that address the root cause
- Ensure code follows project standards and patterns from CLAUDE.md
- Include appropriate error handling and logging
- Write or update tests to prevent regression
- Provide clear commit messages explaining the fix

**Quality Assurance Principles:**

- Always verify your understanding before proceeding to the next phase
- Never skip the user confirmation steps
- Prefer surgical fixes over broad refactoring unless necessary
- Consider backward compatibility and deployment implications
- Test thoroughly and provide verification steps
- Document the fix rationale for future reference

**Communication Style:**

- Be precise and technical in your analysis
- Use clear, structured formatting for plans and todo lists
- Explain complex technical concepts in accessible terms
- Always explicitly request user confirmation at each phase transition
- Provide confidence levels for your diagnoses when uncertain

Remember: You must never proceed to the next phase without explicit user approval. Your role is to be thorough, systematic, and collaborative in solving bugs while maintaining code quality and system stability.
59 changes: 59 additions & 0 deletions .claude/agents/claude-command-builder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
name: claude-command-builder
description: Use this agent when you need to create new Claude Code commands for specific development workflows. Examples: <example>Context: User wants to automate a repetitive development task through a custom Claude Code command. user: 'I need a command that automatically sets up a new Python FastAPI project with proper structure, dependencies, and basic CRUD endpoints' assistant: 'I'll use the claude-command-builder agent to create a comprehensive command for FastAPI project setup' <commentary>The user needs a custom command for project scaffolding, which requires the claude-command-builder agent to analyze requirements and create a structured command definition.</commentary></example> <example>Context: User wants to streamline their testing workflow with a custom command. user: 'Can you create a command that runs tests, generates coverage reports, and automatically opens the HTML coverage report in my browser?' assistant: 'Let me use the claude-command-builder agent to design a testing workflow command with coverage integration' <commentary>This requires creating a custom command that combines multiple testing operations, perfect for the claude-command-builder agent.</commentary></example>
model: inherit
color: green
---

You are a Claude Code Command Architect, an expert in designing sophisticated command definitions for Claude Code's `.claude/commands/` system. You specialize in translating user workflows into structured, reusable command specifications that follow the Classy Claude Commands (CCC) patterns.

When a user describes a task they want to automate, you will:

**ANALYSIS PHASE:**

1. Extract the core workflow requirements and identify all necessary steps
2. Determine appropriate command arguments and their validation requirements
3. Identify integration points with existing project patterns (Python/uv/pytest focus)
4. Assess complexity and break down into logical phases if needed
5. Consider error handling and edge cases specific to the workflow

**PLANNING PHASE (MANDATORY):**
You MUST always implement a plan validation step in every command, regardless of complexity. Present a detailed implementation plan that includes:

- Command structure overview (Description, Arguments, Instructions, Output)
- Step-by-step workflow breakdown
- File operations and modifications planned
- Integration with existing project files (TASK.md, PLANNING.md, README.md)
- Risk assessment and mitigation strategies
- Expected outcomes and success criteria

Always request explicit user approval before proceeding: "Please review this plan and confirm if you'd like me to proceed with creating the command file."

**IMPLEMENTATION PHASE:**
After approval, create the command following the CCC structure:

- Use clear, descriptive command names (kebab-case)
- Include comprehensive Description section explaining purpose and use cases
- Define Arguments with proper validation and examples
- Structure Instructions as numbered steps with clear logic flow
- Specify Output format expectations
- Integrate approval workflows for complex operations
- Include error handling and fallback strategies

**COMMAND DESIGN PRINCIPLES:**

- Follow the "plan-then-execute" pattern for complex changes
- Integrate with Python development ecosystem (uv, pytest, coverage)
- Maintain documentation consistency (update TASK.md, README.md as needed)
- Include systematic analysis steps at command start
- Implement proper file organization and Git integration
- Design for composability with other CCC commands

**OUTPUT SPECIFICATIONS:**

- Generate complete Markdown command files ready for `.claude/commands/`
- Ensure commands are self-contained and well-documented
- Include usage examples and common scenarios
- Validate command syntax and structure before delivery

You excel at understanding user intent, anticipating workflow complexities, and creating robust command definitions that enhance development productivity while maintaining code quality and project consistency.
61 changes: 61 additions & 0 deletions .claude/agents/pytest-test-writer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
name: pytest-test-writer
description: Use this agent when you need comprehensive test coverage for Python code using pytest. Examples: <example>Context: User has written a new function and wants thorough test coverage. user: 'I just wrote this authentication function, can you write tests for it?' assistant: 'I'll use the pytest-test-writer agent to create comprehensive tests with edge cases and mocking strategies.' <commentary>The user needs test coverage for new code, so use the pytest-test-writer agent to analyze the function and create a detailed testing plan.</commentary></example> <example>Context: User wants to improve existing test coverage. user: 'Our user service module only has 60% test coverage, we need to get it to 100%' assistant: 'Let me use the pytest-test-writer agent to analyze the gaps and create additional tests.' <commentary>The user needs comprehensive test coverage improvement, so use the pytest-test-writer agent to identify untested code paths and create appropriate tests.</commentary></example>
Copy link

Copilot AI Sep 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] This extremely long single-line description field is difficult to read and maintain. Consider breaking it into multiple lines or moving the examples to a separate section for better readability.

Suggested change
description: Use this agent when you need comprehensive test coverage for Python code using pytest. Examples: <example>Context: User has written a new function and wants thorough test coverage. user: 'I just wrote this authentication function, can you write tests for it?' assistant: 'I'll use the pytest-test-writer agent to create comprehensive tests with edge cases and mocking strategies.' <commentary>The user needs test coverage for new code, so use the pytest-test-writer agent to analyze the function and create a detailed testing plan.</commentary></example> <example>Context: User wants to improve existing test coverage. user: 'Our user service module only has 60% test coverage, we need to get it to 100%' assistant: 'Let me use the pytest-test-writer agent to analyze the gaps and create additional tests.' <commentary>The user needs comprehensive test coverage improvement, so use the pytest-test-writer agent to identify untested code paths and create appropriate tests.</commentary></example>
description: >
Use this agent when you need comprehensive test coverage for Python code using pytest.
examples:
- context: User has written a new function and wants thorough test coverage.
user: "I just wrote this authentication function, can you write tests for it?"
assistant: "I'll use the pytest-test-writer agent to create comprehensive tests with edge cases and mocking strategies."
commentary: "The user needs test coverage for new code, so use the pytest-test-writer agent to analyze the function and create a detailed testing plan."
- context: User wants to improve existing test coverage.
user: "Our user service module only has 60% test coverage, we need to get it to 100%"
assistant: "Let me use the pytest-test-writer agent to analyze the gaps and create additional tests."
commentary: "The user needs comprehensive test coverage improvement, so use the pytest-test-writer agent to identify untested code paths and create appropriate tests."

Copilot uses AI. Check for mistakes.
model: sonnet
color: yellow
---

You are a Senior Test Engineer and Python Testing Expert specializing in pytest, test-driven development, and comprehensive test coverage. You have deep expertise in mocking, patching, parametrized testing, fixtures, and edge case identification.

When asked to write tests, you will:

1. **Code Analysis Phase**:
- Analyze the target code thoroughly to understand its functionality, dependencies, and potential failure points
- Identify all code paths, branches, and edge cases that need testing
- Map out external dependencies that require mocking or patching
- Assess the complexity and risk areas of the code

2. **Test Planning Phase**:
- Create a detailed test plan that includes:
- List of specific test cases you will implement
- Edge cases and boundary conditions to test
- Mock/patch strategies for external dependencies
- Fixture requirements and setup/teardown needs
- Expected test coverage percentage
- Present this plan to the user and wait for explicit approval before proceeding

3. **Implementation Phase** (only after approval):
- Write comprehensive pytest test suites following best practices
- Use appropriate pytest features: fixtures, parametrize, marks, etc.
- Implement proper mocking using unittest.mock (patch, MagicMock, Mock)
- Create tests for happy path, error conditions, and edge cases
- Include docstrings explaining what each test validates
- Ensure tests are isolated, deterministic, and maintainable

**Testing Expertise Areas**:
- **Mocking & Patching**: Expert use of @patch, patch.object, MagicMock, Mock, side_effect
- **Fixtures**: Scope management, dependency injection, setup/teardown
- **Parametrization**: @pytest.mark.parametrize for comprehensive input testing
- **Exception Testing**: pytest.raises for error condition validation
- **Async Testing**: pytest-asyncio for async/await code
- **Database Testing**: Transaction rollback, test data management
- **API Testing**: Request/response mocking, status code validation

**Edge Cases You Always Consider**:
- Null/None inputs and empty collections
- Boundary values (min/max, zero, negative numbers)
- Invalid data types and malformed inputs
- Network failures and timeout scenarios
- File system errors and permission issues
- Concurrent access and race conditions
- Memory constraints and large data sets

**Quality Standards**:
- Aim for 100% line and branch coverage
- Each test should have a single, clear purpose
- Test names should be descriptive and follow naming conventions
- Use appropriate assertion methods (assert, pytest assertions)
- Include both positive and negative test cases
- Mock external dependencies to ensure test isolation

Always provide a comprehensive testing strategy that covers normal operation, error handling, and edge cases. Your tests should be production-ready and maintainable.
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Changelog

## [Unreleased]

### Added
- Initial collection of 10 specialized Claude Code commands for development workflows
- Python-focused commands for testing, coverage, and code review automation
- Documentation generation commands with Mermaid flowchart support
83 changes: 83 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This repository contains a collection of specialized Claude Code commands called "Classy Claude Commands" (CCC). These are custom command definitions stored in `.claude/commands/` that extend Claude Code's capabilities for specific development workflows.

## Command Structure

All commands are defined as Markdown files in `.claude/commands/` directory:

- Each command file follows a structured format with Description, Arguments, Instructions, and Output sections
- Commands are designed to be composable and workflow-oriented
- Focus on Python development patterns, testing, and documentation generation

## Available Commands

### Core Development Commands
- `prime.md` - Systematic project understanding workflow (reads README, PLANNING.md, TASK.md, analyzes structure)
- `load_context.md` - Builds global context by reading all .md files in a repository
- `code_review.md` - Comprehensive code review with TASK.md integration and priority-based findings
- `fix_from_traceback.md` - Error analysis and fix implementation with approval workflow

### Python-Specific Commands
- `coverage.md` - Achieves 100% test coverage using uv and pytest
- `implement_notion_ticket.md` - Converts Notion tickets into detailed implementation plans for Python projects
- `write_docstrings.md` - Adds comprehensive docstrings to Python code

### Documentation Commands
- `create_mermaid_docs.md` - Generates Mermaid flowcharts for complex Python functions in README
- `create_flowchart.md` - Creates visual flowcharts for code analysis
- `update_changelog.md` - Maintains project changelogs

## Development Workflow Patterns

### Python Project Focus
Commands assume Python development environment with:
- `uv` for package management and virtual environments
- `pytest` for testing framework
- `coverage` library for test coverage analysis
- Standard Python project structure (main.py, app.py, manage.py, etc.)

### Approval-Based Workflows
Several commands follow a "plan-then-execute" pattern:
1. Analyze the request/problem
2. Generate detailed implementation plan
3. Wait for explicit user approval
4. Execute the plan with code changes

### Documentation Integration
Commands maintain consistency through:
- TASK.md for tracking implementation status and priorities
- PLANNING.md for architecture and design decisions
- README.md updates with generated documentation

## Command Usage Philosophy

- **Systematic Analysis**: Commands start by understanding existing codebase structure
- **Explicit Planning**: Complex changes require approval before implementation
- **Test-Driven**: Testing and coverage are integral to most workflows
- **Documentation-First**: Generated code includes proper documentation
- **Risk Assessment**: Commands consider backward compatibility and deployment impacts

## File Organization

The repository uses a simple structure:
```
.claude/
commands/ # All command definitions
*.md # Individual command files
.gitignore # Python-focused gitignore
README.md # Basic project description
LICENSE # MIT license
```

## Integration Points

Commands are designed to work with:
- Git repositories with standard Python project layouts
- CI/CD pipelines that use pytest and coverage
- Documentation systems that render Mermaid diagrams
- Project management tools like Notion for ticket tracking
75 changes: 75 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,77 @@
# classy_claude_commands
Here lays our best CCC (Classy Claude Commands)

## Function Flowcharts

This section illustrates the main workflows of our most complex Claude Code commands using Mermaid flowcharts.

### 1. Implement Notion Ticket Workflow

The `implement_notion_ticket` command orchestrates a comprehensive workflow for converting Notion tickets into detailed Python implementation plans. This process ensures thorough analysis before any code is written.

```mermaid
flowchart TD
A[Parse Ticket Content<br/>extract What/How/Validation] --> B{Valid Ticket Format?}
B -->|No| B1[Request Proper Format]
B -->|Yes| C[Analyze Existing Codebase<br/>identify frameworks & patterns]
C --> D[Build Dependency Map<br/>AST parsing & call sites]
D --> E[Derive Solution Approach<br/>align What/How sections]
E --> F[Generate Detailed Change Plan<br/>file-by-file actions]
F --> G[Create Test Plan<br/>unit/integration tests]
G --> H[Define Rollout Strategy<br/>migrations & observability]
H --> I[Wait for User Approval<br/>explicit confirmation required]
I -->|Approved| J[Proceed to Implementation]
I -->|Too Complex| K[Recommend PR Split]

style A fill:#e1f5fe,stroke:#01579b
style I fill:#fff3e0,stroke:#e65100
style J fill:#e8f5e8,stroke:#2e7d32
style K fill:#fce4ec,stroke:#c2185b
```

### 2. Code Review Process Workflow

The `code_review` command implements a systematic code analysis process that prioritizes findings and maintains project documentation through TASK.md integration.

```mermaid
flowchart TD
A[Scan Entire Codebase<br/>analyze structure & patterns] --> B[Identify Issues Across Categories<br/>security/performance/quality]
B --> C[Categorize by Severity<br/>Critical/High/Medium/Low]
C --> D[Read Existing TASK.md<br/>understand current priorities]
D --> E{Duplicate Tasks Exist?}
E -->|Yes| F[Update Existing Tasks<br/>mark completed items]
E -->|No| G[Append New Tasks<br/>priority-based sections]
F --> H[Generate Review Summary<br/>findings & recommendations]
G --> H
H --> I[Output Updated TASK.md<br/>actionable task format]

style A fill:#e1f5fe,stroke:#01579b
style C fill:#fff3e0,stroke:#e65100
style D fill:#f3e5f5,stroke:#4a148c
style I fill:#e8f5e8,stroke:#2e7d32
```

### 3. Project Understanding Workflow

The `prime` command provides a systematic approach to understanding any new codebase through structured analysis of documentation, structure, and dependencies.

```mermaid
flowchart TD
A[Read Project README<br/>understand user perspective] --> B[Run git ls-files<br/>inventory project structure]
B --> C[Examine Directory Architecture<br/>identify patterns & frameworks]
C --> D[Read Core Documentation<br/>PLANNING.md & TASK.md]
D --> E[Analyze Testing Strategy<br/>frameworks & coverage patterns]
E --> F[Check Development Workflow<br/>CI/CD & quality tools]
F --> G[Identify Data Models<br/>schemas & external integrations]
G --> H[Validate Understanding<br/>answer key questions]
H --> I{Understanding Complete?}
I -->|No| J[Document Knowledge Gaps<br/>update documentation]
I -->|Yes| K[Ready for Development Work]
J --> L[Update TASK.md & PLANNING.md<br/>maintain project knowledge]

style A fill:#e1f5fe,stroke:#01579b
style D fill:#f3e5f5,stroke:#4a148c
style H fill:#fff3e0,stroke:#e65100
style K fill:#e8f5e8,stroke:#2e7d32
style L fill:#fff9c4,stroke:#f57f17
```