# Claude Code Development Workflows Definition

## Overview 

A comprehensive workflow system for AI-native development using Claude Code's custom slash commands, sub-agents, and templates. This system provides structured approaches to feature development, bug fixing, and code improvements while maintaining flexibility and quality through producer/reviewer/validator patterns. Features include validation agents at each stage, phase gates for quality control, atomic task management, and visual progress tracking.

### Structural components

- **Commands**: Claude Code custom slash commands (https://docs.anthropic.com/en/docs/claude-code/slash-commands). Namespaced as `eg:` and put into `./.claude/commands/eg/`
- **Sub-agents**: Claude Code sub agents (https://docs.anthropic.com/en/docs/claude-code/sub-agents). Namespaced as `eg:` and put into `./.claude/agents/eg/`
- **Validators**: Quality assurance agents that ensure standards are met before progression. Located in `./.claude/agents/eg/`
- **Templates**: Output templates that are used in sub-agents and passed from commands to agents or used within commands themselves. Located in `./.claude/templates/`
- **Workflows**: Claude code commands can be chained into workflows. Each workflow maintains state through instance names.
- **MCPs**: Model Context Protocol servers used in commands and agents for external capabilities

### Key Features

- **Validation Framework**: Every workflow stage includes validation to ensure quality standards are met
- **Phase Gates**: Explicit approval required between major workflow stages
- **Atomic Task Management**: Implementation tasks limited to 15-30 minutes and max 3 files
- **Visual Progress Tracking**: Unicode progress bars show workflow status at a glance
- **Template Enforcement**: Structured outputs ensure consistency across all commands

### Workflows

Workflows are chained commands that maintain state through instance names. Each command in a workflow accepts the instance name as the first argument, with additional input as the second argument (e.g `/eg:architect {feature-name} {@file_output_from_define_command.md}` or `/eg:debug {bug-title} {Description of a bug}`). State and produced files are saved in `./.eg/{instance-name}/`.

- **Feature development workflow**
  - `define` → `architect` → `plan` → `implement` → `test`
  - For new feature development from initial concept to tested implementation
  
- **Fix workflow**
  - `debug` → `implement` → `test`
  - For addressing bugs and issues with focused debugging and resolution
  
- **Improvement workflow**
  - `architect` → `implement` → `test`
  - For refactoring and enhancements where requirements are already clear

## Commands

### `/eg:define`
**Purpose**: Creates comprehensive feature specifications from high-level requirements  
**Usage**: `/eg:define {instance-name} {feature description or requirements}`  
**Output**: `./.eg/{instance-name}/feature-definition.md`  
**Description**: Takes user requirements and expands them into a complete feature specification including user stories, acceptance criteria, technical constraints, and success metrics. Uses the `spec-creator` sub-agent to ensure completeness, the `spec-reviewer` to validate quality, and the `definition-validator` to ensure standards are met. Includes a phase gate requiring explicit approval before proceeding to architecture.

### `/eg:architect`
**Purpose**: Designs technical solution architecture for features or improvements  
**Usage**: `/eg:architect {instance-name} {@feature-definition.md or description}`  
**Output**: `./.eg/{instance-name}/architecture.md`  
**Description**: Creates detailed technical architecture including system design, component boundaries, data flows, API contracts, and integration points. Leverages `firecrawl-mcp` for researching best practices and `zen-mcp` for multi-model architectural insights. The `architect` sub-agent produces the design, `architecture-reviewer` ensures it's optimal and feasible, and `architecture-validator` validates technical soundness. Includes a phase gate requiring approval before planning.

### `/eg:plan`
**Purpose**: Breaks down architecture into actionable, atomic implementation tasks  
**Usage**: `/eg:plan {instance-name} {@architecture.md}`  
**Output**: `./.eg/{instance-name}/plan.md`  
**Description**: Transforms architectural design into a step-by-step implementation plan with ordered tasks, dependencies, effort estimates, and risk assessments. Uses `zen-mcp` for task optimization, the `planner` sub-agent to create tasks, `plan-reviewer` for optimization, and `plan-validator` to ensure all tasks meet atomic criteria (15-30 min, max 3 files). Includes a phase gate showing the number of atomic tasks and requiring approval before implementation.

### `/eg:implement`
**Purpose**: Executes the implementation plan with continuous validation  
**Usage**: `/eg:implement {instance-name} {@plan.md}`  
**Output**: Implementation commits and updated codebase  
**Description**: Iterates through the plan tasks, using the `coder` sub-agent to implement each item, `implementation-validator` to verify requirements compliance, and `code-reviewer` to validate quality before proceeding. Creates atomic commits for each completed task with descriptive messages. Includes a phase gate upon completion requiring approval before testing. Progress tracked directly in plan.md file.

### `/eg:test`
**Purpose**: Creates and executes comprehensive tests for implemented features  
**Usage**: `/eg:test {instance-name} {feature name or description}`  
**Output**: Test files and `./.eg/{instance-name}/test-results.md`  
**Description**: Generates unit tests, integration tests, and end-to-end tests based on the feature definition and implementation. Uses `playwright-mcp` for UI testing when applicable. The `tester` sub-agent creates tests focusing on edge cases and the acceptance criteria from the original feature definition. Results are documented using the `test-results.template.md` template. Includes a phase gate for test results review.

### `/eg:analyze`
**Purpose**: Performs deep analysis of code, architecture, or system behavior  
**Usage**: `/eg:analyze {scope} {specific focus area or question}`  
**Output**: Analysis report using `analysis.template.md`  
**Description**: Conducts thorough analysis including code quality metrics, performance characteristics, security assessment, and architectural compliance. Can analyze entire codebases, specific modules, or cross-cutting concerns. Outputs detailed findings with actionable recommendations using the structured `analysis.template.md` template for consistency.

### `/eg:debug`
**Purpose**: Systematically identifies and resolves issues  
**Usage**: `/eg:debug {instance-name} {description of bug}`  
**Output**: `./.eg/{instance-name}/debug-analysis.md` and `./.eg/{instance-name}/solution.md`  
**Description**: Systematic investigation of bugs or issues using the `debugger` sub-agent. Documents symptoms, root cause analysis, and proposed solutions using the `solution.template.md`. Includes a phase gate for root cause confirmation before proceeding to implementation.

### `/eg:fix`
**Purpose**: Quick targeted fixes for specific issues without full workflow  
**Usage**: `/eg:fix {description of issue}`  
**Output**: Direct code changes with fix applied  
**Description**: Rapid issue resolution for small bugs, typos, or configuration issues that don't require extensive debugging or architectural consideration. Makes minimal, focused changes with appropriate tests.

### `/eg:summary`
**Purpose**: Generates comprehensive summaries of changes, PRs, or development work  
**Usage**: `/eg:summary {PR URL or commit range or status}`  
**Output**: Formatted summary using `summary.template.md`  
**Description**: Creates human-readable summaries of development work including changed files, implementation approach, testing coverage, and impact assessment. Uses `gh` CLI and git tools to gather change information and the `summarizer` sub-agent to create clear, concise descriptions.

### `/eg:review`
**Purpose**: Performs thorough code review with actionable feedback  
**Usage**: `/eg:review {PR URL or branch name}`  
**Output**: Review comments using `review.template.md`  
**Description**: Two-phase review process: first analyzes changes for bugs, security issues, performance concerns, and architectural compliance, then creates a summary for the developer with specific, actionable feedback. Focuses on substantive issues rather than style preferences.

### `/eg:commit`
**Purpose**: Creates well-structured commits with descriptive messages  
**Usage**: `/eg:commit {optional commit type}`  
**Output**: Git commit with conventional format  
**Description**: Analyzes staged changes and writes clear, conventional commit messages following the project's commit standards. Automatically includes relevant context, breaking changes, and issue references. Commits and pushes to the current branch.

### `/eg:pr`
**Purpose**: Creates comprehensive pull requests with all necessary context  
**Usage**: `/eg:pr {target branch}`  
**Output**: GitHub pull request with filled template  
**Description**: Opens a pull request with detailed description including problem context, solution approach, testing performed, and review checklist. Automatically links related issues, adds appropriate labels, and requests reviewers based on changed files.

### `/eg:customize-templates`
**Purpose**: Analyzes project codebase and customizes generic templates to match project-specific patterns  
**Usage**: `/eg:customize-templates {template-name or "all"}`  
**Output**: Updated templates in `./.claude/templates/` with project-specific sections  
**Description**: The `artificer` agent directly analyzes ALL CLAUDE*.md files throughout the project and examines the codebase to understand conventions, patterns, and requirements. Updates generic templates to include project-specific sections such as multi-tenancy considerations, authentication patterns, validation schemas, and architectural requirements. The artificer ensures customizations are high-quality and maintain template structure while adding project-specific enhancements.

### `/eg:status`
**Purpose**: Shows all active workflow instances with visual progress tracking  
**Usage**: `/eg:status {optional: instance-name}`  
**Output**: Console display with Unicode progress bars and status indicators  
**Description**: Displays a comprehensive visual dashboard of all active workflows across the project, using Unicode progress bars to show completion percentage for each phase. Shows task counts, last activity timestamps, and intelligent next action suggestions. Can display all workflows or focus on a specific instance. Helps manage multiple parallel development efforts and identify stalled workflows (>3 days inactive).

### `/eg:customize-agents`
**Purpose**: Customizes all agents to be project-aware based on codebase analysis  
**Usage**: `/eg:customize-agents`  
**Output**: Updated agent configurations in `./.claude/agents/eg/` with project-specific knowledge  
**Description**: Leverages the `broodmother` agent to regenerate all workflow agents with project-specific context. The broodmother directly analyzes ALL CLAUDE*.md files throughout the project and examines the codebase to understand conventions, patterns, and requirements. This makes agents aware of project-specific patterns like multi-tenancy, authentication methods, error handling conventions, and architectural decisions. Agents become more effective by understanding the actual codebase they're working with rather than using generic patterns.

### `/eg:issue`
**Purpose**: Report issues with intelligent type detection and comprehensive documentation  
**Usage**: `/eg:issue "description of the issue"`  
**Output**: `./.eg/issues/{timestamp}/issue-report.md`  
**Description**: Creates comprehensive issue reports from simple descriptions. The `issue-creator` sub-agent automatically determines whether it's a bug (🐛), feature request (✨), or improvement (🔧) based on keywords and context. Generates appropriate sections for each type (reproduction steps for bugs, use cases for features, benefits for improvements). Auto-populates environment information including git branch, commit, and working directory. Optionally integrates with GitHub CLI to create issues directly. Maintains a history of all reported issues for tracking purposes.

## Sub-agents

Sub-agents fall into three categories - producers (primary creators of output), reviewers (assure quality and alignment), and validators (enforce standards before progression). Producer sub-agents are paired with reviewers and validators are bound to specific workflow stages.

### Producers:

#### `eg:spec-creator`
**Purpose**: Transforms vague requirements into complete feature specifications  
**Tools**: Read, Write, Think, WebFetch, mcp__firecrawl-mcp__firecrawl_scrape, mcp__firecrawl-mcp__firecrawl_search, MultiEdit, zen
**Templates**: `spec.template.md`  
**Description**: Expert at requirements gathering and feature definition. Takes incomplete ideas and expands them into comprehensive specifications including user stories, acceptance criteria, technical requirements, edge cases, and success metrics. Considers user experience, technical feasibility, and business value.

#### `eg:architect`
**Purpose**: Designs robust, scalable technical solutions  
**Tools**: Read, Grep, Glob, firecrawl-mcp, zen 
**Templates**: `solution.template.md`  
**Description**: Senior architect focused on creating elegant, maintainable system designs. Researches best practices, considers multiple approaches, and designs solutions that balance immediate needs with long-term maintainability. Produces detailed architecture documents with clear component boundaries and integration patterns.

#### `eg:planner`
**Purpose**: Creates actionable, efficient implementation plans  
**Tools**: Read, Write, zen 
**Templates**: `plan.template.md`  
**Description**: Expert at breaking down complex architectures into manageable tasks. Creates ordered task lists with clear dependencies, realistic effort estimates, and risk mitigation strategies. Optimizes for parallel work where possible and identifies critical path items.

#### `eg:coder`
**Purpose**: Implements clean, efficient, not overengineered, well-tested code  
**Tools**: Read, Write, Grep, Execute, MultiEdit
**Output**: Direct code files  
**Description**: Experienced developer focused on writing production-quality code. Follows project conventions, implements proper error handling, writes self-documenting code, and includes appropriate logging. Creates focused, atomic changes that are easy to review and test.

#### `eg:tester`
**Purpose**: Creates comprehensive test coverage  
**Tools**: Read, Write, Execute, playwright-mcp  
**Output**: Test files and test results  
**Description**: QA specialist who creates thorough test suites covering unit, integration, and end-to-end scenarios. Focuses on edge cases, error conditions, and acceptance criteria. Ensures tests are maintainable, fast, and provide clear failure messages.

#### `eg:summarizer`
**Purpose**: Creates clear, informative summaries of work  
**Tools**: Read, gh, bash  
**Templates**: `summary.template.md`  
**Description**: Technical writer skilled at distilling complex changes into understandable summaries. Highlights key changes, explains implementation decisions, and provides context for reviewers and future maintainers. Balances completeness with conciseness.

#### `eg:debugger`
**Purpose**: Systematically identifies and resolves issues  
**Tools**: Read, Grep, Execute, all available MCPs  
**Templates**: `solution.template.md`  
**Description**: Expert problem solver who methodically investigates issues. Uses logging, debugging tools, and systematic analysis to identify root causes. Documents findings and implements minimal, targeted fixes that resolve issues without introducing new problems.

#### `eg:artificer`
**Purpose**: Adapts generic templates to project-specific needs  
**Tools**: Read, Write, MultiEdit, Grep, Glob, LS  
**Templates**: All templates in `.claude/templates/`  
**Description**: A master craftsman of template transformation through direct project analysis. Like a skilled artificer who imbues mundane objects with magical properties, this agent reads ALL CLAUDE*.md files throughout the project to understand documented conventions and requirements. Analyzes the codebase to detect patterns, frameworks, common imports, authentication methods, error handling approaches, and architectural decisions. Takes generic templates and forges them into project-specific artifacts, enriching them with contextual enhancements. For example, adds multi-tenancy considerations, authentication patterns, or framework-specific sections based on actual code patterns found in the project.

#### `eg:issue-creator`
**Purpose**: Creates comprehensive issue reports from user descriptions  
**Tools**: Read, Write, Bash, Glob, Grep  
**Templates**: `issue-report.template.md`  
**Description**: Intelligent issue report generator that analyzes descriptions to automatically determine issue type (bug, feature, improvement) and creates comprehensive documentation. Uses contextual clues and keywords to classify issues appropriately. For bugs, generates reproduction steps and expected vs actual behavior. For features, creates use cases and proposed solutions. For improvements, documents current behavior and benefits. Auto-populates environment information including git details and working directory. Makes intelligent inferences when details are unclear, ensuring no sections are left empty.

### Reviewers:

#### `eg:spec-reviewer`
**Purpose**: Ensures feature specifications are complete and viable  
**Tools**: Read, Think  
**Description**: Product-minded reviewer who validates feature definitions for completeness, clarity, and feasibility. Checks for missing requirements, unclear acceptance criteria, and potential issues. Ensures specifications are testable and achievable.

#### `eg:architecture-reviewer`
**Purpose**: Validates architectural decisions and identifies risks  
**Tools**: Read, Grep, Think  
**Description**: Senior architect who reviews designs for scalability, security, maintainability, and alignment with system principles. Identifies potential bottlenecks, suggests optimizations, and ensures the architecture supports both current and anticipated future needs.

#### `eg:plan-reviewer`
**Purpose**: Optimizes implementation plans for efficiency  
**Tools**: Read, Think  
**Description**: Project management expert who reviews plans for completeness, realistic estimates, and optimal task ordering. Identifies missing dependencies, suggests parallelization opportunities, and ensures risk mitigation strategies are in place.

#### `eg:code-reviewer`
**Purpose**: Ensures code quality, security, maintainability, and convention adherence  
**Tools**: Read, Grep, Execute  
**Description**: Experienced developer focused on code quality and project consistency. Reviews for bugs, security vulnerabilities, performance issues, and adherence to project standards. Directly analyzes existing code patterns and CLAUDE*.md files to validate that generated code follows project-specific conventions. Provides specific, actionable feedback with code examples when helpful. Balances thoroughness with pragmatism.

### Validators:

#### `eg:definition-validator`
**Purpose**: Validates feature definitions against quality standards  
**Tools**: Read, Glob  
**Description**: Feature definition validation specialist that ensures specifications meet quality standards and follow the `spec.template.md` structure. Validates for compliance, completeness, clarity, and provides structured feedback using PASS/NEEDS_IMPROVEMENT/MAJOR_ISSUES levels. READ-ONLY validator focused on comprehensive feedback.

#### `eg:architecture-validator`
**Purpose**: Validates architecture documents for technical soundness  
**Tools**: Read, Grep, Glob  
**Description**: Architecture validation specialist that reviews architecture documents against the `solution.template.md` template. Checks technical soundness, completeness, integration points, security considerations, and proper component design. Provides structured validation reports with actionable feedback.

#### `eg:plan-validator`
**Purpose**: Ensures implementation plans contain atomic, agent-executable tasks  
**Tools**: Read, Glob  
**Description**: Implementation plan validation specialist that enforces atomic task criteria. Validates that each task meets the 7 criteria: max 3 files, 15-30 minutes completion time, single testable outcome, specific file paths, clear dependencies, unambiguous success criteria, and zero room for interpretation. Essential for ensuring plans are truly executable by AI agents.

#### `eg:implementation-validator`
**Purpose**: Validates completed implementations against requirements  
**Tools**: Read, Grep, Glob  
**Description**: Implementation review specialist that provides structured validation of completed code against original requirements and architecture. Checks requirements compliance, architecture adherence, code quality standards, integration correctness, and error handling completeness. Outputs APPROVED/NEEDS_REVISION/MAJOR_ISSUES assessment.

## Templates

Templates provide consistent structure for outputs across the workflow. Located in `./.claude/templates/`.

- **spec.template.md** - Feature definition structure
- **solution.template.md** - Architecture and solution design
- **plan.template.md** - Implementation plan with atomic tasks
- **summary.template.md** - Change summaries
- **review.template.md** - Code review feedback
- **analysis.template.md** - Deep code analysis reports
- **test-results.template.md** - Test execution results
- **issue-report.template.md** - Bug and issue reports


# Claude Code Workflow Component Map

## Workflow → Command → Sub-agent → Template Flow

### 🔵 Feature Development Workflow
```
Feature Development Workflow
│
├─→ /eg:define
│   ├─→ eg:spec-creator (producer)
│   │   └─→ spec.template.md
│   ├─→ eg:spec-reviewer (reviewer)
│   └─→ eg:definition-validator (validator)
│       └─→ Phase Gate: Approval Required
│
├─→ /eg:architect  
│   ├─→ eg:architect (producer)
│   │   └─→ solution.template.md
│   ├─→ eg:architecture-reviewer (reviewer)
│   └─→ eg:architecture-validator (validator)
│       └─→ Phase Gate: Approval Required
│
├─→ /eg:plan
│   ├─→ eg:planner (producer)
│   │   └─→ plan.template.md
│   ├─→ eg:plan-reviewer (reviewer)
│   └─→ eg:plan-validator (validator)
│       └─→ Phase Gate: Approval Required
│
├─→ /eg:implement
│   ├─→ eg:coder (producer)
│   │   └─→ [direct code output]
│   ├─→ eg:implementation-validator (validator)
│   └─→ eg:code-reviewer (reviewer)
│       └─→ Phase Gate: Approval Required
│
└─→ /eg:test
    └─→ eg:tester (producer)
        ├─→ [test file output]
        ├─→ test-results.template.md
        └─→ Phase Gate: Test Results Review
```

### 🔴 Fix Workflow
```
Fix Workflow
│
├─→ /eg:debug
│   └─→ eg:debugger (producer)
│       ├─→ solution.template.md
│       └─→ Phase Gate: Root Cause Confirmation
│
├─→ /eg:implement
│   ├─→ eg:coder (producer)
│   │   └─→ [direct code output]
│   ├─→ eg:implementation-validator (validator)
│   └─→ eg:code-reviewer (reviewer)
│
└─→ /eg:test
    └─→ eg:tester (producer)
        ├─→ [test file output]
        ├─→ test-results.template.md
```

### 🟢 Improvement Workflow
```
Improvement Workflow
│
├─→ /eg:architect
│   ├─→ eg:architect (producer)
│   │   └─→ solution.template.md
│   ├─→ eg:architecture-reviewer (reviewer)
│   └─→ eg:architecture-validator (validator)
│       └─→ Phase Gate: Approval Required
│
├─→ /eg:implement
│   ├─→ eg:coder (producer)
│   │   └─→ [direct code output]
│   ├─→ eg:implementation-validator (validator)
│   └─→ eg:code-reviewer (reviewer)
│
└─→ /eg:test
    └─→ eg:tester (producer)
        ├─→ [test file output]
        ├─→ test-results.template.md
```

## 📌 Standalone Commands
Commands that operate independently of workflows:

```
/eg:summary
└─→ eg:summarizer (producer)
    ├─→ summary.template.md

/eg:review
├─→ eg:summarizer (producer) [Phase 1: Summarize changes]
│   └─→ summary.template.md
└─→ eg:code-reviewer (reviewer) [Phase 2: Review code]
    └─→ review.template.md

/eg:commit
└─→ eg:summarizer (producer)
    └─→ summary.template.md

/eg:pr
└─→ eg:summarizer (producer)
    └─→ summary.template.md

/eg:analyze
└─→ general-purpose (producer)
    └─→ analysis.template.md

/eg:customize-templates
└─→ eg:artificer (producer) [Analyzes project and forges custom templates]
    └─→ Updated templates in .claude/templates/

/eg:status
└─→ [Direct command implementation - no sub-agent]

/eg:customize-agents
└─→ eg:broodmother (producer) [Analyzes project and regenerates agents]
    └─→ Updated agents in .claude/agents/eg/

/eg:issue
└─→ eg:issue-creator (producer) [Analyzes description and creates issue report]
    └─→ issue-report.template.md
```

## 📊 Component Usage Matrix

### Commands by Workflow
| Command | Feature Dev | Fix | Improvement | Standalone |
|---------|------------|-----|-------------|------------|
| define | ✅ | - | - | - |
| architect | ✅ | - | ✅ | - |
| plan | ✅ | - | - | - |
| debug | - | ✅ | - | - |
| implement | ✅ | ✅ | ✅ | - |
| test | ✅ | ✅ | ✅ | - |
| summary | - | - | - | ✅ |
| review | - | - | - | ✅ |
| commit | - | - | - | ✅ |
| pr | - | - | - | ✅ |
| customize-templates | - | - | - | ✅ |
| status | - | - | - | ✅ |
| customize-agents | - | - | - | ✅ |
| issue | - | - | - | ✅ |

### Sub-agent Relationships
| Producer | Paired Reviewer | Used by Commands |
|----------|----------------|------------------|
| spec-creator | spec-reviewer | define |
| architect | architecture-reviewer | architect |
| planner | plan-reviewer | plan |
| coder | code-reviewer | implement |
| tester | - | test |
| summarizer | - | summary, review, commit, pr |
| debugger | - | debug |
| artificer | - | customize-templates |
| broodmother | - | customize-agents |
| issue-creator | - | issue |

| Reviewer | Reviews Output From | Used by Commands |
|----------|-------------------|------------------|
| spec-reviewer | spec-creator | define |
| architecture-reviewer | architect | architect |
| plan-reviewer | planner | plan |
| code-reviewer | coder | implement, review |

| Validator | Validates Output | Used by Commands |
|-----------|-----------------|------------------|
| definition-validator | Feature definitions | define |
| architecture-validator | Architecture documents | architect |
| plan-validator | Implementation plans | plan |
| implementation-validator | Completed code | implement |

### Template Usage
| Template | Used by Sub-agents | Used by Commands |
|----------|-------------------|------------------|
| spec.template.md | spec-creator | define |
| solution.template.md | architect, debugger | architect, debug |
| plan.template.md | planner | plan |
| summary.template.md | summarizer | summary, review, commit, pr |
| review.template.md | code-reviewer | review |
| analysis.template.md | general-purpose | analyze |
| test-results.template.md | tester | test |
| issue-report.template.md | - | - |

### MCP Tool Distribution
| MCP Tool | Used by | Indirectly Used by Commands |
|----------|---------|---------------------------|
| firecrawl-mcp | architect, debugger | architect, debug |
| zen-mcp | architect, planner, debugger | architect, plan, debug |
| playwright-mcp | tester, debugger | test, debug |
| gh (CLI) | summarizer | summary, review, commit, pr |
| bash | summarizer | summary, review, commit, pr |

## 🛡️ Validation Framework

The eg workflow system implements a comprehensive validation framework:

### Validation Levels
- **PASS** - Meets all quality standards, ready to proceed
- **NEEDS_IMPROVEMENT** - Minor issues that should be addressed
- **MAJOR_ISSUES** - Significant problems requiring resolution

### Validation Points
1. **Feature Definition** - Validates completeness, clarity, testability
2. **Architecture** - Validates technical soundness, integration, security
3. **Implementation Plan** - Validates atomic tasks meet 7 criteria
4. **Implementation** - Validates code meets requirements and architecture

### Phase Gates
Each major workflow transition requires explicit approval:
- Define → Architect: "Proceed to architecture? (yes/no)"
- Architect → Plan: "Proceed to planning? (yes/no)"
- Plan → Implement: "Proceed with X atomic tasks? (yes/no)"
- Implement → Test: "Ready for testing? (yes/no)"
- Debug → Implement: "Confirm root cause? (yes/no)"

## 📊 Visual Progress Tracking

The `/eg:status` command provides comprehensive visual feedback using Unicode characters:

```
📦 FEATURE DEVELOPMENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📂 auth-system
  📋 Definition    ████████████ 100% ✅
  🏗️  Architecture  ████████████ 100% ✅
  📝 Planning      ████████████ 100% ✅
  ⚙️  Implementation ███████░░░░░  65% 🔄
     Tasks: 7/11 complete
  🧪 Testing       ░░░░░░░░░░░░   0% ⏳
     Last activity: 2024-01-15 14:32
```

Features:
- Real-time progress bars for each phase
- Task completion counts
- Activity timestamps
- Stalled workflow detection (>3 days)
- Intelligent next action suggestions

## ⚛️ Atomic Task Management

All implementation tasks must meet these 7 criteria:

1. **Max 3 files** - Task modifies at most 3 files
2. **15-30 minutes** - Completable by an agent in one session
3. **Single outcome** - One clear, testable result
4. **Specific paths** - Exact file paths provided (no wildcards)
5. **Clear dependencies** - Explicit prerequisite tasks listed
6. **Success criteria** - Unambiguous completion definition
7. **No ambiguity** - Zero room for interpretation

This ensures tasks are properly scoped for autonomous AI agent execution.

## 🔄 Data Flow Through Workflows

### Feature Development Flow
```
User Input → define → spec.template.md → validate → approve →
architect → solution.template.md → validate → approve →
plan → plan.template.md → validate → approve →
implement → code files → validate →
test → test files + test-results.template.md
```

### Fix Flow
```
Bug Report → debug → solution.template.md → confirm →
implement → code changes → validate →
test → test results + test-results.template.md
```

### Improvement Flow
```
Enhancement Request → architect → solution.template.md → validate → approve →
implement → code changes → validate →
test → test results + test-results.template.md
```

## 📁 State Storage Structure
```
./ 
├── .claude/
│   ├── commands/eg/        # All command definitions
│   ├── agents/eg/          # All sub-agent definitions
│   └── templates/          # All template files (customized by customize-templates)
└── .eg/
    ├── {feature-name}/     # Feature workflow instance
    │   ├── feature-definition.md
    │   ├── architecture.md
    │   ├── plan.md (progress tracked via task checkboxes)
    │   └── test-results.md
    ├── {bug-id}/           # Fix workflow instance
    │   ├── debug-analysis.md
    │   ├── solution.md
    │   └── test-results.md
    └── {improvement-id}/   # Improvement workflow instance
        ├── architecture.md
        └── test-results.md
```