Claude Code AEP Prompt Workflow

Automated, iterative development workflows with persistent project memory

A complete, production-ready task execution system for Claude Code guardrailed by the Agent Envelope Protocol (AEP) and JSONL-based project memories. It implements structured workflows with TDD enforcement, code review loops, and automatic knowledge capture so every task leaves your codebase smarter than before.

---

What is this?

This repository provides a copy/paste workflow system for Claude Code that manages:

• ✅ Task execution - Research → Clarification → Plan → Implement ↔ Review → Validation
• ✅ Systematic debugging - 5 Whys root cause analysis with hypothesis testing
• ✅ Code reviews - Comprehensive PR reviews with GitHub-style output
• ✅ Project memory - Persistent JSONL-based knowledge base that learns from every task

Key benefit: Every task makes the next one easier through automatic knowledge capture.

What this repo includes:

• The .claude/ workflow system that plugs into your own projects

Table of Contents

• Quick Start
• Directory Structure
• Workflow Overview
• Core Workflows
• Key Features
• Architecture
• Memory System (JSONL Format)
• Configuration
• Customization
• Examples
• Troubleshooting
• Best Practices

---

Quick Start

Prerequisites

• Claude Code installed
• Git repository (recommended)

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/claude-code-aep-prompt-workflow.git
   cd claude-code-aep-prompt-workflow

2. Copy the .claude/ directory to your project:

   cp -r .claude /path/to/your/project/

3. (Optional) Install recommended MCP servers:

   # Sequential thinking for systematic analysis
   claude mcp add --transport stdio sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking
   
   # Context7 for documentation lookup (requires setup)
   # See: https://github.com/context7/mcp-server

How it works (first run example)

cd /path/to/your/project
claude

# Inside Claude Code:
/task "Add a simple hello world function with tests"

What happens:

1. Memory structure initializes automatically
2. Research agent analyzes your codebase
3. Plan agent creates a technical todo list (.claude/TODO.md)
4. Implement agent follows TDD (Red-Green-Refactor)
5. Review agent performs systematic code review
6. Validation agent verifies completion and saves learnings to memory

---

Directory Structure

The .claude/ directory that powers this workflow looks like:

.claude/
├── README.md                    # Internal workflow documentation
├── CLAUDE.md                    # Main memory (auto-imported by Claude Code)
├── settings.local.json          # Local settings (optional)
│
├── commands/
│   ├── task.md                  # /task workflow entry point
│   ├── debug.md                 # /debug workflow entry point
│   └── code-review.md           # /code-review workflow entry point
│
├── agents/
│   ├── research-agent.md        # Codebase analysis
│   ├── clarification-agent.md   # Critical questions
│   ├── plan-agent.md            # Todo list creation
│   ├── implement-agent.md       # TDD implementation
│   ├── review-agent.md          # Code review
│   ├── validation-agent.md      # Final validation & memory updates
│   ├── debug-agent.md           # Root cause analysis & debugging
│   └── code-review-agent.md     # PR code review specialist
│
├── skills/                      # Reusable Claude Code skills (optional)
│   ...
│
└── memories/
    ├── architecture.jsonl       # System design decisions
    ├── patterns.jsonl           # Proven code patterns
    ├── libraries.jsonl          # Library knowledge & gotchas
    ├── review-standards.jsonl   # Quality standards
    └── workflow-history.jsonl   # Task execution history

---

Workflow Overview

At a high level, each /task runs the same end-to-end pipeline:

user → research → clarification → plan → implement ↔ review → validation → user

• research: Understands the codebase and checks existing memories.
• clarification: Asks only critical blocking questions when needed.
• plan: Produces a concrete, test-first technical todo list.
• implement ↔ review: TDD implementation with up to 3 review iterations.
• validation: Verifies the work, updates JSONL memories, and summarizes results back to you.

For a deeper, agent-by-agent breakdown, see .claude/README.md.

---

Core Workflows

/task - Feature Development

Complete TDD workflow with automatic code review:

/task "Add user authentication with JWT tokens"

Process: research → clarification → plan → [implement ↔ review] → validation

Output:

• Fully implemented feature with tests
• Updated project memory with patterns and learnings
• .claude/TODO.md with completed task breakdown

---

/debug - Systematic Debugging

Evidence-based debugging using root cause analysis:

/debug "Database queries timing out in production"

Process: symptom analysis → 5 Whys → hypothesis testing → implement fix → validation

Output:

• Root cause identified with evidence
• Fix implemented and tested
• Debug notes saved to memory

---

/code-review - PR Code Review

Comprehensive technical review with GitHub-style output:

/code-review 123

Process: fetch PR diff → 6-category review → generate markdown → save to memory

Output:

• temp-123-review.md with detailed findings
• Severity-based issue classification (🚫 blocking, ⚠️ major, ℹ️ minor)
• Actionable fix recommendations

---

/memory-init - Initialize Project Memory

Analyze existing codebase and populate memory:

/memory-init

Process: discover architecture → extract patterns → document libraries → save to memory

Output:

• Populated .claude/memories/*.jsonl files
• Architecture decisions documented
• Code patterns identified

---

Key Features

🧠 Persistent Project Memory

The system builds a knowledge base that persists across sessions:

.claude/memories/
├── architecture.jsonl       # System design decisions
├── patterns.jsonl          # Proven code patterns
├── libraries.jsonl         # Third-party library gotchas
├── review-standards.jsonl  # Quality standards
└── workflow-history.jsonl  # Task execution history

Benefits:

• Research agent checks memory before searching codebase
• Patterns are automatically reused in new implementations
• Past mistakes inform future reviews
• Team knowledge is captured and shared

---

🔁 TDD Enforcement

Every implementation follows Red-Green-Refactor:

1. RED - Write failing test first
2. GREEN - Implement minimum code to pass
3. REFACTOR - Clean up while keeping tests green

No shortcuts. Tests must pass before moving forward.

---

🔍 Code Review Loop

Systematic 6-point review with automatic iteration:

1. Code Quality (naming, clarity, responsibility)
2. Type Safety (no any/Any types)
3. Testing (coverage, edge cases)
4. Performance (optimizations)
5. Security (no secrets, validation)
6. Best Practices (conventions)

Max 3 iterations before escalating to user.

---

🤖 Fully Autonomous via AEP

Agents route automatically using the Agent Envelope Protocol (AEP):

user → research → clarification → plan → implement ↔ review → validation → user

No permission requests between stages. Fully automated pipeline.

---

Architecture

Agent Pipeline

Agent	Responsibility	Tools
research-agent	Checks memory, analyzes codebase	Read, Grep, Glob, sequential-thinking, context7
clarification-agent	Asks critical questions only	Read, sequential-thinking
plan-agent	Creates technical todo list	Read, Grep, sequential-thinking, context7
implement-agent	TDD implementation	Read, Edit, Bash, context7
review-agent	Systematic code review	Read, Grep, Glob, Bash, sequential-thinking
validation-agent	Verifies completion, updates memory	Read, Edit, Bash, sequential-thinking

Special Purpose Agents

• debug-agent - 5 Whys root cause analysis, hypothesis testing
• code-review-agent - PR-specific review with tech stack expertise

---

Memory System (JSONL Format)

Memory files use JSONL (JSON Lines) for efficient updates:

• ✅ Append-only without parsing entire file
• ✅ Better git diffs (line-by-line changes)
• ✅ Automatic compaction at 100KB or 200 entries

Example Entry (architecture.jsonl)

{"id":"auth-system","type":"architecture","name":"JWT Authentication","when":"2025-11-05","decision":"Centralized JWT auth service","rationale":"Stateless validation across services","files":["auth/jwt.ts"],"tradeoffs":"Benefits: scalable. Limitations: token revocation requires blacklist","dependencies":["jsonwebtoken"],"related":["session-mgmt"],"updated":"2025-11-05"}

---

Configuration

MCP Integration

The workflow dynamically discovers and uses available MCP servers:

# Check what's available
claude mcp list

Recommended MCPs:

• sequential-thinking - Systematic analysis (all agents)
• context7 - Documentation lookup (research, plan, implement)

Not required - Workflow works without MCPs, but they enhance quality.

---

Customization

Add a New Agent

1. Create .claude/agents/your-agent.md
2. Add to workflow chain in commands/task.md
3. Update routing in adjacent agents

See .claude/README.md for details.

Add Memory Category

1. Create .claude/memories/your-category.jsonl
2. Add import to .claude/CLAUDE.md
3. Update validation-agent to append to it
4. Update research-agent to check it

Modify Review Standards

Edit .claude/memories/review-standards.jsonl to add project-specific rules.

---

Examples

Example 1: Simple Feature

/task "Add logout button to header"

Result:

• Button component created
• Logout handler implemented
• Unit tests passing
• Memory updated with logout pattern

Time: ~2-3 minutes (depends on codebase size)

---

Example 2: Complex Feature

/task "Implement real-time notifications with WebSocket"

Workflow:

1. Research: No WebSocket in memory, searches codebase
2. Clarification: Asks about connection strategy, fallback options
3. Plan: 8 todos sequenced for TDD
4. Implement: Uses context7 to look up WebSocket best practices
5. Review: 2 iterations (adds error handling, improves reconnection)
6. Validation: Saves WebSocket pattern, library knowledge, architecture

Memory Created:

• patterns.jsonl - WebSocket connection pattern
• libraries.jsonl - ws library usage and gotchas
• architecture.jsonl - Real-time system design
• workflow-history.jsonl - Complete implementation record

Time: ~10-15 minutes

---

Example 3: Bug Fix

/debug "Users getting 500 errors on form submission"

Process:

1. Symptom Analysis: Reproduce error, check logs
2. 5 Whys Analysis:
   • Why 500 error? → Missing validation
   • Why missing? → Refactor removed it
   • Why not caught? → Missing test coverage
   • Why no coverage? → Test file not updated
   • Root Cause: Incomplete refactor, missing tests
3. Hypothesis: Add validation + tests (95% confidence)
4. Fix: Implements validation with TDD
5. Validation: Confirms error resolved, updates memory

Memory Created:

• Debug investigation notes
• Validation pattern documented
• Test coverage requirement reinforced

Time: ~5-10 minutes

---

Example 4: Code Review

/code-review 456

Output: temp-456-review.md

# Code Review: PR #456

**Overall Status**: CHANGES_REQUESTED

## Files Reviewed
- `auth.py` (+34, -12)
- `auth.ts` (+45, -20)

## Detailed Findings

### 🚫 [blocking] Silent Fallback for SECRET_KEY
**File**: `config.py:15`
SECRET_KEY = os.getenv("SECRET_KEY", "default-secret")

**Issue:** Silent fallback compromises security...
**Fix:** Fail fast with explicit error...

### ⚠️ [major] Missing Test Coverage
...

## Action Items
1. 🚫 **2 Blocking Issues** - Must fix before merge
2. ⚠️ **1 Major Issue** - Should fix before merge

Time: ~3-5 minutes

---

Troubleshooting

Workflow stops between agents

Symptoms: Agent completes but doesn't route to next agent

Solution:

1. Check agent files have <<<AGENT:COMPLETE>>> blocks
2. Verify route_to: field is set correctly
3. Ensure no text after <<<END:COMPLETE>>> marker

---

System runs out of memory

Symptoms: Multiple test/build processes accumulating

Solution:

• Check for orphaned background processes:

  ps aux | grep -E "npm|node|vite|webpack" | grep -v grep

• Kill manually:

  pkill -f "npm.*test"

Prevention: Workflow now has strict process management (max 1-2 background tasks per agent).

---

Memory not loading

Symptoms: Research agent doesn't find past patterns

Solution:

1. Verify .claude/CLAUDE.md imports all memory files
2. Check memory files use .jsonl extension
3. Re-run /task to reinitialize structure

---

Best Practices

1. Be Specific in Task Descriptions

Good: /task "Add JWT-based authentication with refresh tokens to the API"

Bad: /task "Add auth"

More detail = better research and planning.

---

2. Commit Memory Files

git add .claude/memories/
git commit -m "docs: update project memory"

Benefits:

• Team shares knowledge
• Track memory evolution
• Onboard new developers faster

---

3. Trust the Memory System

After a few executions, the system will:

• Recognize similar tasks
• Apply proven patterns automatically
• Avoid past gotchas
• Speed up implementation

---

4. Review Memory Periodically

Check .claude/memories/*.jsonl files to:

• Ensure accuracy
• Consolidate duplicate patterns
• Update outdated information

Automatic compaction happens at 100KB or 200 entries.