erpaval

ERPAVal

Autonomous software development for Claude Code.

ERPAVal stands for Explore · Research · Plan · Act · Validate — the five-phase loop, plus a sixth Compound phase that writes durable lessons to disk so the next session inherits what this one learned.

Six phases, classifier-driven routing, and a compounding memory layer that makes every session smarter than the last.

A structured workflow for teams of Claude Code agents that build software the way a senior engineer would — if that engineer could run ten of themselves in parallel and actually remember what they learned yesterday.

[!NOTE] ERPAVal has only been tested with Claude Code. It relies on Claude Code's Agent tool, TaskCreate/TaskUpdate/TaskList task system, plugin hooks (SessionStart, PostToolUse, Stop), and ${CLAUDE_PLUGIN_ROOT} path resolution. It will not work with other AI coding tools or generic Claude API integrations.

[!IMPORTANT] Star → Fork → make it your own. ERPAVal is opinionated about coding workflow but agnostic about everything else. The bundle gives you a working flow on day one, but the workflow is designed to absorb your conventions, your team's writing style, your domain's vocabulary. Fork this repo, vendor in your own skills, swap out the ones that don't fit, rewrite the classifier prompts to match how you think. Re-syncing from upstream personal-plugins is intentionally manual — users who fork should diverge.

---

Install

ERPAVal is a Claude Code plugin. There are two ways to install it.

Option A — Claude Code plugin marketplace (recommended)

Ships everything: skills, agents, hooks, and MCP server config.

In a Claude Code session, run:

/plugin marketplace add theagenticguy/erpaval
/plugin install erpaval@erpaval

Adding a marketplace is lazy — nothing loads until you install. The plugin installs to your user scope (available in every project) by default. To scope it to one project instead, use /plugin install erpaval@erpaval --scope project.

Then enable the plugin and reload so its skills, agents, and hooks activate:

/plugin            # → Installed tab → erpaval → Enable
/reload-plugins

Verify by listing skills:

/help              # /erpaval:* should appear in the namespace

To uninstall:

/plugin uninstall erpaval
/plugin marketplace remove theagenticguy/erpaval

[!NOTE] If /plugin marketplace add reports "not found", update Claude Code to a recent version (v2.1.x or later) and retry.

Option B — skills.sh CLI (skills only, multi-agent)

skills.sh is the open agent-skills directory. Its CLI installs the skills to whichever coding agents you have locally — Claude Code, Cursor, Codex, Windsurf, and ~50 others. It does not install the hooks, agents, or MCP server config that the plugin marketplace ships.

npx skills add theagenticguy/erpaval

Use this path if you want ERPAVal's skills available across multiple agents. Use Option A if you want the full Claude Code experience (compounding lessons, validation hooks, the Compound-phase nudge).

Option C — Local development install

To hack on the plugin without going through either:

git clone https://github.com/theagenticguy/erpaval
claude --plugin-dir ./erpaval

---

The problem

For single-file changes, the basic loop works: give Claude a task, get working code back, ship it. The loop breaks when a task touches multiple modules, depends on unfamiliar APIs, or requires coordinating work across files that reference each other.

It breaks in a second, quieter way: the next session starts from scratch — even though the previous one just spent two hours learning the codebase's peculiarities.

[!IMPORTANT] The failure mode of unstructured AI coding is not broken code. It is plausible code that does not belong, written by an agent that forgot last week's lessons.

ERPAVal fixes both: it front-loads understanding, crystallizes intent into a per-task context packet, hands each implementing subagent a curated briefing, and closes the loop by writing what was learned to disk so future sessions inherit it.

---

The flow

The high-level shape is a six-phase pipeline gated by mechanical dependency checks, with one deliberate human review at Gate 1.

flowchart LR
  IN([User request]) --> CL[Classifiers]
  CL --> ER[Explore +<br/>Research]
  ER -->|Gate 0| PLAN[Plan]
  PLAN -->|Gate 1<br/>human review| ACT[Act · waves]
  ACT --> VAL[Validate]
  VAL -.->|fail| ACT
  VAL -->|Gate 2| COMP[Compound]
  COMP --> DONE([Done])

Phase	Purpose	Parallelizable with
Explore	Build a mental model of the codebase	Research
Research	Fetch live API docs, version pins, patterns	Explore
Plan	Decompose into a dependency-wired task graph	—
Act	Delegate to parallel subagents per task	Per dependency graph
Validate	3-layer static + quality + security check	Partially
Compound	Extract durable lessons to .erpaval/solutions/	—

Gates are mechanical dependency blockers, not approval queues. addBlockedBy wires every phase to its predecessors — the orchestrator reads TaskList and advances the moment predecessors flip to completed. The one exception is Gate 1 (Plan → Act), which is a deliberate human design-review checkpoint. Catching a wrong abstraction here saves hours of agent rework.

---

Before the phases: adaptive classifiers

ERPAVal never runs its full machinery on a one-line bug fix. Before Explore starts, a chain of classifiers — labelled CL-* so they're easy to grep in the session trace — decides which phases apply.

flowchart LR
  IN([User request]) --> SCOPE{CL-SCOPE}
  SCOPE -->|knowledge work| ROUTE[Upstream skill]
  SCOPE -->|coding| COMPLEX{CL-COMPLEXITY}
  COMPLEX -->|1-file fix| DIRECT[Direct fix]
  COMPLEX -->|multi-module<br/>or rebuild| RESUME{CL-RESUME}
  RESUME -->|new| NEW[erpaval-new.py]
  RESUME -->|resume| LOAD[Load prior session]
  NEW & LOAD --> DIR{CL-DIR}
  DIR --> RIGOR{CL-RIGOR}
  RIGOR -.->|fuzzy| HMW[How Might We<br/>HMW substep]
  RIGOR -.->|contract<br/>unclear| EARS[Easy Approach to<br/>Requirements Syntax<br/>EARS substep]
  HMW --> EARS
  EARS --> ER([Explore + Research])
  RIGOR -->|crisp| ER

Classifier	Decision	Effect
CL-SCOPE	Coding or knowledge work?	Knowledge work routes to an upstream skill (research, Product Requirements Doc (PRD), strategy, …)
CL-COMPLEXITY	1-file fix, multi-module, or rip-and-replace?	1-file skips ERPAVal entirely
CL-RESUME	New session or resume a prior one?	New scaffolds session-<hex>/; resume reads prior state and continues
CL-DIR	Empty dir, existing code, or rebuild-in-place?	Empty skips Explore; rebuild explores both existing and target patterns
CL-RIGOR	Crisp problem, or needs HMW / EARS framing?	Fuzzy → HMW substep; contract-unclear → EARS substep; crisp → skip both
CL-SPEC	PRD, stack, and concept ready?	Missing prerequisites loop through product-discovery and build-stack
CL-VALIDATE	All 3 validation layers green?	Failure routes back to Act with scoped fix packets
CL-LESSONS	Novel, reusable learnings this session?	Yes → write to .erpaval/solutions/; no → skip

Every verdict appends to classifier_trace in the session YAML — routing decisions are auditable after the fact. Claude judges; the user never picks from a menu.

---

Phases in detail

Session 0 — mandatory intake

Two tool calls run before any phase.

1. Recall first (always): erpaval-recall.py bootstrap surfaces category counts from .erpaval/solutions/. Cold repos print "no prior lessons" and proceed. Warm repos start the session already aware of what previous sessions learned.

2. New or resume: CL-RESUME checks for a prior session within 72 hours on the same module. New → erpaval-new.py creates .erpaval/sessions/session-<hex>/intake.yaml. Resume → reads the prior session.yaml and continues from the last completed gate. Without a session directory on disk, the Compound phase at the end silently no-ops — making the scaffold mandatory at intake is what keeps the compounding loop closed.

---

Explore + Research (parallel)

flowchart LR
  START([Intake done]) --> FORK{ }
  FORK --> EXP[Explore agent<br/>structure · patterns · DI]
  FORK --> RES[Research agent<br/>Context7 · DeepWiki · web]
  EXP --> JOIN{Gate 0}
  RES --> JOIN
  JOIN --> PLAN([Plan])

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

A dedicated exploration agent reads project structure, traces module boundaries, and catalogs patterns — error handling, dependency injection (DI), logging, test style, build toolchain, lint config. Output is a structured summary that becomes the conventions section every implementing agent receives.

Research fixes the staleness problem. A code-researcher agent fetches current documentation via Context7, DeepWiki, or web search. It checks package versions, pulls API signatures, usage examples, and migration guides. The result is a dependency inventory with version pins and concrete patterns.

Both run in parallel — different questions, no data dependency on each other.

---

Plan

flowchart LR
  G0([Gate 0]) --> DRAFT[Draft task graph<br/>1 task per acceptance<br/>criterion AC]
  DRAFT --> WAVES[Group into waves<br/>wire dependencies]
  WAVES --> CRIT[Mechanical success<br/>criteria per task]
  CRIT --> G1{Gate 1<br/>human review}
  G1 -.->|revise| DRAFT
  G1 --> ACT([Act])

The single most consequential artifact in the flow.

Planning decomposes the implementation into atomic tasks, each completable by a single agent in isolation, grouped into waves with explicit dependency edges. When intake included an EARS spec, the plan derives one task per acceptance criterion (AC) — the AC's [P] parallel-safe flag carries 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 carries mechanical success criteria — exact tests, type checks, lint rules. Gate 1 is a human design-review checkpoint. Expect 2–4 revision rounds; the plan is a senior engineer's architecture review, not a rubber stamp.

---

Act