erpaval

Contents

| Reference | When to load | | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | references/flow.md | The graph — intake, build loop, validate/compound, cycles | | references/classifiers.md | Prompt text for each CL- classifier | | references/fan-out.md | Per-phase subagent counts + the one-message parallel-launch rule | | references/glossary.md | CP-, CL-*, gates, cycles, zones, placeholder tokens | | ${CLAUDE_PLUGIN_ROOT}/skills/product-discovery/references/roles/hmw-framer.md | HMW substep (hard-dep on product-discovery; run when CL-RIGOR asks for HMW) | | ${CLAUDE_PLUGIN_ROOT}/skills/product-discovery/references/roles/ears-specifier.md | EARS substep (hard-dep on product-discovery; run when CL-RIGOR asks for EARS) | | references/orchestrator.md | Per-phase runbook — Task-tool lifecycle, Agent patterns | | references/context-packets.md | Per-packet YAML schemas + two-gate review + auto-merge rules | | references/write-protocol.md | Canonical write-protocol block (copied into every Act prompt) | | references/validation-playbook.md | 3-layer validation + closed-loop toolchain | | references/compound.md | Dual-track lesson schema + recall retrieval algorithm | | templates/session/worklog-skeleton.md | Per-task packet skeleton with embedded write protocol | | templates/session/ | YAML schemas the orchestrator seeds into .erpaval/sessions/<id>/ at runtime | | templates/specs/ | EARS spec and task-list skeletons for the Framing substep | | templates/solutions/ | Lesson templates (bug, knowledge) the Compound phase writes from | | templates/brainstorms/ | HMW requirement skeletons for the Framing substep | | templates/INDEX.md | Recall-phase index of lessons by category, read at session start |

ERPAVal — adaptive autonomous software development

A six-phase workflow with two framing substeps and a compounding tail. The orchestrator (main Claude Code session) runs classifiers to decide which phases apply, delegates implementation to subagents, and persists Markdown + YAML packets under .erpaval/ so future sessions start smarter than this one.

The graph at a glance

flowchart LR
  IN[Intake + Recall bootstrap] --> SCOPE{Scope?}
  SCOPE -->|coding| COMPLEX{Complexity?}
  SCOPE -->|non-coding| ROUTE[Upstream skill]
  COMPLEX -->|1-file fix| DIRECT[Direct fix]
  COMPLEX -->|multi-module or rebuild| RESUME{New or resume?}
  RESUME -->|new| NEW[erpaval-new.py]
  RESUME -->|resume| PRIOR[Load prior session]
  NEW --> DIR{Dir state?}
  PRIOR --> DIR
  DIR --> RIGOR{Rigor?}
  RIGOR -.->|fuzzy| HMW[HMW frame]
  RIGOR -.->|contract unclear| EARS[EARS spec]
  HMW --> EARS
  EARS --> ER[Explore + Research]
  RIGOR -->|crisp| ER
  ER --> PLAN[Plan]
  PLAN --> G1{Gate 1}
  G1 -.->|revise| PLAN
  G1 -->|approved| ACT[Act · waves]
  ACT --> VAL[Validate]
  VAL -.->|fail| ACT
  VAL -->|pass| G2{Gate 2}
  G2 --> MERGE[Merge]
  MERGE --> COMP[Compound · extract lessons]
  COMP --> DONE([Done])

Full three-view graph with every cycle is in references/flow.md. Dashed edges are named cycles.

Strict phase gating via TaskCreate / TaskUpdate / TaskList

Each phase has a completion gate enforced by the TaskCreate / TaskUpdate / TaskList todo-list tool family (distinct from the Agent subagent-launcher). Every implementation task is wired with addBlockedBy so the task system itself prevents out-of-order execution. No skipping, no parallel execution across gates, no early starts.

The todo-list tools hold authoritative state. YAML packets under .erpaval/sessions/ are read-only hints that inform which tasks to create and what goes in their prompt. Per-task Markdown packets at .erpaval/sessions/<id>/tasks/T-AC-X-Y.md double as subagent work logs — the agent edits them section-by-section per write-protocol.md, and the orchestrator monitors with wc -l. Partial progress on disk survives timeouts and SendMessage interrupts; state held in working memory does not.

See references/orchestrator.md for the per-phase runbook.

Session 0 — mandatory intake scaffolding

Two steps the orchestrator always runs before Explore, so Compound can actually fire at the end of the session.

1. Recall first (always). uv run ${CLAUDE_PLUGIN_ROOT}/skills/erpaval/tools/erpaval-recall.py bootstrap surfaces category counts + INDEX.md path. Cold repos print no prior lessons and proceed. The SessionStart hook also emits this via additionalContext, but the tool call is the authoritative record — run it.
2. Decide new vs resume (after CL-COMPLEXITY returns multi-module / rebuild). CL-RESUME reads the request, ls .erpaval/sessions/session-*/ (sorted by mtime), and the top-5 prior session.yaml files, then emits one of:
3. new session — run uv run ${CLAUDE_PLUGIN_ROOT}/skills/erpaval/tools/erpaval-new.py --request "<raw_request>". Creates .erpaval/sessions/session-<hex>/intake.yaml, ensures .gitignore and INDEX.md. Required — without a session-<hex>/ dir, the Stop hook's six-gate check never clears and Compound silently no-ops.
4. resume session — read the prior session.yaml + latest tasks/*.md, append the new ask to intake.yaml.raw_request, continue from the last completed gate. Do not scaffold a new session-<hex>/.

For 1-file fixes, CL-COMPLEXITY exits the flow before Session 0 step 2 — recall-only is correct; no session dir needed.

See references/classifiers.md for the CL-RESUME prompt and references/orchestrator.md for the runbook.

Pre-phase classifiers — where adaptation lives

Before Explore starts, the orchestrator runs classifiers to decide which phases to run. Claude judges — the user never picks from a menu.

| Classifier | Question | Skips / routes | | ----------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | CL-SCOPE | Is this a coding task? | Non-coding → route to /research, /product-discovery, /product-strategy, /working-backwards, /customer-research, etc. | | CL-COMPLEXITY | 1-file fix · multi-module · rip-and-replace? | 1-file → skip ERPAVal, just fix