# Claude Code Commands & Agents for Crafted SaaS

This directory contains custom slash commands and autonomous agents that integrate with the Crafted SaaS AI system.

## Autonomous Agents

The `.claude/agents/` directory contains **4 specialized autonomous agents** that can work independently:

### Available Agents

Use `/agents <name>` to invoke an agent:

1. **`/agents architect`** - System Architect
   - Designs architecture based on quality level (Rapid/Balanced/Crafted)
   - Creates ADRs (Architecture Decision Records)
   - Defines interfaces and module boundaries
   - Plans file structure and dependencies

2. **`/agents developer`** - Software Developer
   - Implements features following the provided architecture
   - Writes clean, self-documenting code (NO inline comments)
   - Respects quality level rules (function length, parameters, etc.)
   - Creates all necessary files with full implementation

3. **`/agents tester`** - QA Engineer
   - Writes comprehensive test suites
   - Ensures coverage requirements met (0% Rapid, 70% Balanced, 100% Crafted domain)
   - Tests happy paths, error cases, and edge cases
   - Runs tests and reports results

4. **`/agents reviewer`** - Code Reviewer
   - Reviews code quality and architecture compliance
   - Validates test coverage and quality
   - Uses MCP tools (typescript, vitest, rules-validator, architecture-guard)
   - Makes decision: **APPROVE** / **REQUEST_CHANGES** / **REJECT**

### How to Use Agents

**Individual agent:**
```
/agents developer
```
Then describe what you want the developer to implement.

**Chained workflow (manual):**
```
1. /agents architect
   → "Design user authentication feature for Balanced level"

2. /agents developer
   → "Implement the architecture provided by the architect"

3. /agents tester
   → "Write tests for the authentication implementation"

4. /agents reviewer
   → "Review the authentication feature implementation and tests"
```

Each agent is **fully autonomous** and will complete its task independently using available MCP tools.

---

## Available Commands

### `/features` - Feature Development Workflow
Execute the complete feature development workflow with 4 specialized agents:
- **Architect** - Designs architecture and creates ADRs
- **Developer** - Implements the feature
- **Tester** - Writes comprehensive tests
- **Reviewer** - Reviews and validates

**Usage:**
```
/features
```

Then provide:
- Feature name
- Requirements
- Any specific constraints

### `/bugfix` - Bug Fix Workflow
Execute the bug fix workflow with 3 specialized agents:
- **Developer** - Fixes the bug
- **Tester** - Writes regression tests
- **Reviewer** - Validates the fix

**Usage:**
```
/bugfix
```

Then provide:
- Bug description
- Steps to reproduce
- Expected vs actual behavior

### `/refactor` - Refactoring Workflow
Execute the refactoring workflow with 3 specialized agents:
- **Architect** - Designs refactoring approach
- **Developer** - Implements refactoring
- **Reviewer** - Validates improvements

**Usage:**
```
/refactor
```

Then provide:
- What to refactor
- Why refactor
- Goal of the refactoring

### `/workflows` - Explore Workflows & Agents
Explore available workflows and agents in the AI system.

**Usage:**
```
/workflows
```

This will help you understand:
- All available workflows
- All specialized agents
- Their roles and responsibilities
- How to use them effectively

## How It Works

These commands use the **Orchestrator MCP** to:
1. Get workflow and agent information
2. Guide you through each step
3. Apply quality level rules (Rapid/Balanced/Crafted)
4. Ensure proper testing and validation

## MCP Tools Available

The commands use these orchestrator tools:
- `list_workflows` - List all workflows
- `get_workflow_info` - Get workflow details
- `list_agents` - List all agents
- `get_agent_info` - Get agent details
- `execute_workflow` - Simulate workflow execution (info only)

## Quality Levels

The workflows adapt to your project's quality level:

### Rapid
- Fast iteration
- Minimal ceremony
- Tests for critical paths only

### Balanced
- Pragmatic quality
- 70% test coverage
- Clean architecture

### Crafted
- Software craftsmanship
- 100% domain coverage
- Hexagonal architecture
- Full ADRs

## Important Principles

All workflows follow these principles:
- **NO inline comments** - Refactor instead of commenting
- **Clean code** - Self-documenting code
- **DRY** - Don't Repeat Yourself
- **SOLID** - Applied according to quality level
- **Test-After Generation** - Code + Tests in parallel

## Need Help?

Use `/workflows` to explore the system and understand how each workflow and agent works!
