ERPAVal, a Gated Six-Phase Workflow for Claude Code Agents

0. Session 0, the mandatory intake scaffold #

Two tool calls run before any classifier except SCOPE and COMPLEXITY. Running erpaval-recall.py bootstrap comes first and always; it surfaces the category counts and index path from .erpaval/solutions/. Cold repos print "no prior lessons" and proceed; warm repos start the session already aware of what the codebase has taught previous sessions.

The second, for multi-module and rebuild tasks only, is either erpaval-new.py, which creates .erpaval/sessions/session-<hex>/intake.yaml and ensures the .gitignore entry, or a read of the prior session's session.yaml if CL-RESUME picked resume. This step exists for exactly one reason: without a session directory on disk, the Compound phase at the end of the flow cannot recognize the session and will silently skip writing lessons. Making the scaffold mandatory at intake removes the most common way the compounding loop fails to close.

1. Explore #

The Explore phase answers: what does this codebase look like, and where do my changes land?

A dedicated exploration agent, or several in parallel across different areas, reads the project structure, traces module boundaries, and catalogs patterns for error handling, logging, dependency injection, and testing. It identifies the build toolchain, linting configuration, and test conventions. The output is a structured summary: architecture patterns, file locations, naming conventions, test infrastructure. This becomes the conventions section that every implementing agent receives later.

Explore is read-only: no files are created or modified, and the agent is building understanding rather than artifacts. That constraint prevents the common failure mode where an agent starts exploring and then quietly begins implementing before it has the full picture.

2. Research #

Research addresses the staleness problem. An agent's training data has a cutoff. The library you are integrating shipped a breaking change last month. The API you are calling deprecated an endpoint. The framework version in your lockfile has different patterns than what the model learned.

A code-researcher agent fetches current documentation via Context7, DeepWiki, or web search. It checks package versions against what is in your lockfile, pulls API signatures, usage examples, and migration guides. The output is a dependency inventory with version pins and concrete code patterns.

Research runs in parallel with Explore. They answer different questions: Explore asks what our code looks like, Research asks what the external tools expect. Launching both simultaneously halves the pre-coding phase without sacrificing either dimension.

3. Plan #

The Plan is the single most consequential artifact in the entire flow. A good plan means Act executes cleanly; a bad plan means agents step on each other, duplicate work, or produce incompatible interfaces.

Planning decomposes the implementation into atomic tasks, each completable by a single agent in isolation. Tasks are grouped into waves that can run in parallel within the wave, with explicit dependency edges between waves. When the intake included an EARS specification from the rigor substep, the plan derives one implementation task per acceptance criterion, carrying the AC's parallel-safe flag forward so the orchestrator can launch safe tasks concurrently.

Wave 1 (parallel):
  Task A: Create data models       → blocks C, D
  Task B: Add API route stubs      → blocks D

Wave 2 (parallel):
  Task C: Implement service layer  → blocks E
  Task D: Implement API handlers   → blocks E

Wave 3:
  Task E: Integration tests

Each task includes success criteria: what tests must pass, what type checks must clear, what lint rules must hold. These criteria are mechanical, so a subagent can verify them without human judgment.

The plan is also the first review gate. A senior engineer reviews the task graph (about 50 lines of structured YAML) and approves the architecture before any code is written. Catching a wrong abstraction boundary here saves hours of agent rework later, which is why Gate 1 is the one place a human stays in the loop. Expect two to four revision rounds before it clears; the gate is a design-review checkpoint rather than a rubber stamp.

4. Act #

Each task in the plan becomes a delegation to a subagent. The context packet is the complete briefing each implementing agent receives, and it is also the agent's work log, a single Markdown file that the agent edits section-by-section as it works, following a write protocol that sets status, summary, and a running log in place. The orchestrator never polls the agent's output stream. It watches the packet files with wc -l, and a task whose line count is identical across two consecutive check-ins is flagged as stuck.

Each subagent is an expert developer with zero context. It can write excellent code, but it knows nothing about your codebase, your conventions, or your architecture. The context packet is what transforms a general-purpose coding agent into a specialist for your system. The Prior lessons section is what transforms a specialist into a specialist who has already seen this class of problem before.

Tasks within a wave launch in parallel. When all of Wave 1 completes, Wave 2 begins. The orchestrator also does eager unblocking: after each completion, it scans the dependency graph for any downstream work whose blockers have all cleared, and launches immediately rather than waiting for its sibling tasks. On a 26-task run this saves about 30 to 40 percent of wall-clock time compared to strict wave-by-wave execution.

When a task gets stuck, the recovery path is defined. The first three in-task fix attempts happen via SendMessage to the same worker. On attempt four, the orchestrator runs the CL-C2 classifier against the packet and the last error, and dispositions the situation as one of: apply a one-to-two-line fix inline, respawn a fresh worker with the same packet, or route to a missing-prereq replan that inserts a new task and re-wires the dependency graph. None of these recovery paths involves a human picking from a menu.

5. Validate #

Layer 1, static checks. The project's existing toolchain: ruff check plus ruff format plus pytest for Python, pnpm lint plus pnpm typecheck plus pnpm test for TypeScript, and so on. Fast and automated, sub-second lint and sub-minute type checking. The closed-loop toolchain is designed for this: Rust-based tools like ruff (about 100x faster than pylint) and biome (about 50 to 100x faster than eslint) give agents a tight feedback loop.

Layer 2, code quality review. A dedicated Opus agent analyzes the complete diff for tech debt creep, DRY violations, dead code, convention drift, and API surface bloat. This catches the things static tools miss: a function that compiles but does not match the codebase's patterns, duplicated logic across files, unnecessary complexity.

Layer 3, security scanning. Semgrep with OWASP Top 10 rules, language-specific tools (bandit for Python, npm audit for Node), dependency vulnerability checks, and an Opus-powered security review for logic flaws that static tools miss.

If any layer fails, the cycle loops back to Act with scoped fix packets on just the failing tasks. The fix-to-validate loop is fast because all checks are local and deterministic. The agent writes a fix, re-runs lint in about 300 milliseconds, re-runs type checking in about 800 milliseconds, re-runs module tests in about 2 seconds. The full cycle takes under 4 seconds, against 60 to 300 seconds for a CI roundtrip.

6. Compound #

Compound is the phase most methodologies forget. It runs after Gate 2 clears and the work merges. The CL-LESSONS classifier reads the trace from first tool call through final validation and identifies candidate learnings along two tracks: bug-track lessons are root causes uncovered during fix cycles (the C2 and C4 loops), and knowledge-track lessons are architectural or API patterns surfaced during Explore and Research that a later run would not infer on its own. Each candidate is filtered on two criteria: novel (no existing entry in .erpaval/solutions/ already covers it) and reusable (likely to apply elsewhere, rather than a one-off hack).

Surviving lessons are written to .erpaval/solutions/<category>/<slug>.md with YAML frontmatter carrying tags and module scope. The next session's recall step greps this directory with a path-boundary match on module and a tag-overlap score, and the top-scoring lessons are pasted directly into the Prior Lessons section of each task's context packet.

That is the compounding loop. A lesson learned in March shows up in an Act packet in May without anybody having to remember it was there.