erpaval

name	erpaval
description	Workflow for autonomous software development with the Kiro CLI (open Agent Skills standard). Classifiers route scope, complexity, directory state, and spec readiness before committing to Explore / Research / Plan / Act / Validate, then close the loop with a Compound step that persists lessons to `.erpaval/solutions/` for future sessions. Optional HMW reframing and EARS specification add structured rigor — the orchestrator agent judges when to run them. Each Act subagent edits its own Markdown task packet section-by-section per the write protocol, and the orchestrator monitors with `wc -l`. Use when the user asks to implement a feature autonomously, build with agents, use ERPAVal, plan and execute a coding task, delegate to subagents, do agent-driven development, extract lessons, recall prior lessons, or mentions autonomous coding workflow or compound engineering.
license	MIT
compatibility	Designed for Kiro CLI (open Agent Skills standard). Compatible with any Agent Skills runtime that supports SKILL.md frontmatter and `assets/`/`scripts/`/`references/` directories.

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/glossary.md	CP-*, CL-*, gates, cycles, zones, placeholder tokens
${ERPAVAL_HOME}/skills/product-discovery/references/roles/hmw-framer.md	HMW substep (hard-dep on product-discovery; run when CL-RIGOR asks for HMW)
${ERPAVAL_HOME}/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 — NL subagent dispatch, filesystem-driven gates, /todo mirror, summary return contract
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
assets/session/task-skeleton.md	Per-task packet skeleton with embedded write protocol
assets/session/	YAML schemas the orchestrator seeds into .erpaval/sessions/<id>/ at runtime
assets/specs/	EARS spec and task-list skeletons for the Framing substep
assets/solutions/	Lesson templates (bug, knowledge) the Compound phase writes from
assets/brainstorms/	HMW requirement skeletons for the Framing substep
assets/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 (the Kiro CLI session running the erpaval-orchestrator agent) 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 filesystem state

Each phase has a completion gate enforced by the orchestrator reading the status: frontmatter of per-task Markdown packets at .erpaval/sessions/<id>/tasks/T-AC-X-Y.md. The orchestrator advances a wave only when every blocker packet has status: COMPLETE. Kiro's /todo slash command mirrors progress for the user but is advisory only — the authoritative state lives in the packet files.

Kiro gap shim — task dependencies. Kiro's /todo does not support addBlockedBy semantics; only add and complete. ERPAVal therefore drives gate enforcement from the filesystem (per-task packet status: frontmatter) and uses /todo for the user-visible progress mirror. The packet files are the source of truth.

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 subagent timeouts; 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 ${ERPAVAL_HOME}/skills/erpaval/scripts/erpaval-recall.py bootstrap surfaces category counts + INDEX.md path. Cold repos print no prior lessons and proceed. The agentSpawn hook on the erpaval-orchestrator agent also emits this via STDOUT, 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:
   • new session — run uv run ${ERPAVAL_HOME}/skills/erpaval/scripts/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 six-gate check never clears and Compound silently no-ops.
   • 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. The orchestrator agent 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
CL-RESUME	New session or resume a prior one?	new → erpaval-new.py; resume → read prior session-<hex>/ and continue. Runs only when CL-COMPLEXITY is multi-module / rebuild
CL-DIR	Empty dir · existing code · rebuild-in-place?	Empty → skip Explore, start at Research
CL-RIGOR	Problem crisp, or needs HMW / EARS?	Crisp → skip both; fuzzy → HMW; contract-unclear → EARS; both when needed
CL-SPEC	PRD / stack / concept ready?	Missing → loop through /product-discovery, /build-stack (product-discovery covers PRD drafting and design-thinking methodology)
CL-VALIDATE	All 3 validation layers green?	Fail → C4 back to Act
CL-C2	Attempt-4 escalation in a stuck subagent?	fix-directly / respawn / missing-prereq (C3)
CL-LESSONS	Session produced novel learnings?	Yes → write to .erpaval/solutions/; no → skip

See references/classifiers.md for each classifier's prompt text.

Optional rigor — HMW + EARS

CL-RIGOR decides whether to run these substeps. Both are well-suited to subagent delegation (bounded creative task, durable file output). erpaval hard-deps on product-discovery for these substeps: the orchestrator seeds brainstorms/NNN-<slug>-requirements.md or specs/NNN-<slug>/spec.md from ${ERPAVAL_HOME}/skills/product-discovery/assets/hmw-skeleton.md / ears-spec-skeleton.md and dispatches one general-purpose subagent per substep that reads ${ERPAVAL_HOME}/skills/product-discovery/references/roles/hmw-framer.md (or ears-specifier.md) as its role prompt. Dispatch via in-chat NL: > Use a general-purpose agent to frame this as HMW per the role prompt at …; final step: call the built-insummarytool with the framing.

• HMW (fuzzy problems) — customer-problem template, 3 of 9 d.school strategies, NN/g-validated HMW statements.
• EARS (unclear contracts) — 5 templates (Ubiquitous, Event-driven, State-driven, Optional feature, Unwanted behavior). Each AC carries [P] (parallel-safe) or Dependencies: AC-X-Y. Plan derives tasks directly.

Skip both when the ask names a specific user segment, an observable outcome with a metric, and no solution verbs — see ${ERPAVAL_HOME}/skills/product-discovery/references/frameworks/how-might-we.md (HMW skip test) and ${ERPAVAL_HOME}/skills/product-discovery/references/frameworks/ears.md (EARS skip test).

Phase summary

Phase	Purpose	Execution method	Parallelizable with
Explore	Build mental model of the codebase	Parallel NL subagent dispatches (erpaval-explorer — split by module, single turn)	Research
Research	Fetch live API docs, versions, patterns	Parallel NL subagent dispatches (erpaval-researcher — split by domain, single turn)	Explore
Plan	Derive tasks from EARS spec + deps	Orchestrator + filesystem packet seeding (with /todo mirror)	None (needs E+R)
Act	Implement via parallel subagents	One turn per wave, NL dispatch per task (Kiro caps at 4 concurrent)	Per dependency graph
Validate	Verify correctness, quality, security	NL subagent dispatch (Opus) + static tools	Partially
Compound	Extract lessons from session	Orchestrator + compound.md procedure	None (post-merge)

Research agents start with date +"%Y-%m-%d" (always) and context7 (for library/API/SDK lookups). Default recency window is the last 6 months — agentic-AI libraries change monthly.

Kiro gap shim — concurrency. Kiro caps subagent fan-out at 4 parallel. If a wave declares more than 4 parallel-safe tasks, the orchestrator dispatches them in batches of 4 and waits between batches. Sequential dependencies still form a DAG by reading task-packet status: frontmatter.

When to use ERPAVal

CL-COMPLEXITY decides before committing to the full flow.

Scenario	Classifier verdict
Feature touching multiple modules	multi-module → full flow
Bug fix in a single file	1-file-fix → skip ERPAVal
Greenfield project setup	multi-module + CL-DIR=empty → skip E
Rip-and-replace rebuild	rebuild → full E+R + destructive Wave 1
Refactoring with behavioral preservation	multi-module → full flow
Integrating a new dependency or API	multi-module → heavy Research phase
Quick script or one-off tool	1-file-fix → skip ERPAVal

.erpaval/ directory — two-zone layout

Placeholder tokens (NNN, <hex>, <slug>, <domain>, T-AC-X-Y) are defined in references/glossary.md.

.erpaval/
  INDEX.md                       committed — pointer from AGENTS.md
  solutions/                     committed — dual-track lessons
    <category>/                  one folder per entry in
                                 references/solution-categories.yaml
  brainstorms/                   committed — HMW outputs
    NNN-<slug>-requirements.md
  specs/                         committed — EARS specs + derived tasks.md
    NNN-<slug>/
      spec.md
      tasks.md
  sessions/                      gitignored — orchestrator-coupled, ephemeral
    .nudged                      persistent ledger of session-ids already
                                 nudged by kiro_compound_nudge.py (one line per id)
    session-<hex>/
      intake.yaml
      recall.yaml
      explore.yaml
      research-<domain>.yaml
      tasks/T-AC-X-Y.md
      validation.yaml
      lessons.yaml
      session.yaml

Single .gitignore line: .erpaval/sessions/. The durables compound across team. Session state is orchestrator-coupled (subagent names, tool IDs, task schema) and a secrets surface — archive to object storage if audit is needed.

Recall + Compound — the compounding loop

Every session starts by reading prior lessons and ends by writing new ones:

• Session start — the agentSpawn hook on the erpaval-orchestrator agent (kiro/hooks/kiro_session_start_bootstrap.py) emits category counts from .erpaval/solutions/ to STDOUT, which Kiro folds into the conversation context. Fires once per session; no-ops for projects without .erpaval/.
• Pre-Act — the orchestrator queries erpaval-recall.py per task during Plan → Act, populating each packet's Prior Lessons section via tag / module scoring.
• Mid-session — the orchestrator agent invokes recall ad-hoc when a new sub-problem emerges that prior sessions may have hit.
• Post-merge — Compound runs as the sixth phase. CL-LESSONS filters candidates by novelty + reusability. Writes to solutions/<category>/<slug>.md, updates INDEX.md, adds the AGENTS.md pointer if missing, records sessions/<id>/lessons.yaml. The stop hook (kiro/hooks/kiro_compound_nudge.py) emits a one-shot advisory STDERR warning when all six gates hold (see Tools and hooks table); once fired, the session-id is written to .erpaval/sessions/.nudged and won't re-fire.

Kiro gap shim — Stop semantics. Unlike Claude Code, Kiro stop hooks cannot block-and-re-prompt. Exit code 2 is not honored on stop; only STDERR-as-warning is supported. The Compound nudge is therefore advisory: when the user sees the warning, they (or the orchestrator agent on the next turn) should explicitly run /erpaval (or invoke the skill via NL) to drive the Compound phase. The .erpaval/sessions/.nudged ledger ensures the warning fires exactly once per session.

Compound can also run ad-hoc when the user wants to force-extract lessons mid-session. See references/compound.md for the dual-track schema, scoring formula, and operating sequence.

Ecosystem integration

Upstream skills (run before ERPAVal)

Skill	When to use first
Product Discovery (/product-discovery)	Define what to build before planning how (PRD drafting, HMW, EARS, user stories, JTBD)
Tech Stack Builder (/build-stack)	Select technologies for greenfield projects
Product Strategy (/product-strategy)	Business strategy frameworks (Rumelt, Wardley, Minto, Working Backwards)

CL-SPEC loops through these automatically if any are missing.

Phase-level agent mapping

Phase	Agent used
Explore	Bundled erpaval-explorer agent at kiro/agents/erpaval-explorer.json
Research	Bundled erpaval-researcher agent at kiro/agents/erpaval-researcher.json
Act	General-purpose subagents via NL dispatch (model is set in the subagent's agent JSON, not at invocation time)
Validate	Opus subagents for code quality and security review
Compound	Orchestrator + compound.md procedure (invokes opus for CL-LESSONS)

Tools and hooks

Hooks are configured inline in the hooks field of kiro/agents/erpaval-orchestrator.json — Kiro has no plugin-global hooks.json. All three hooks are UV-shebang Python scripts built on a Kiro-shaped fork of framework.py. Every hook is fail-open via framework.run_hook — any uncaught exception logs to stderr and exits 0, so a broken hook cannot wedge a session.

Hook	Kiro event	Role
kiro_session_start_bootstrap.py	agentSpawn	Emit .erpaval/solutions/ category counts to STDOUT (Kiro folds STDOUT into conversation context). Fires once per session and only when a sessions/session-<hex>/ dir was modified in the last 24h — cold repos stay silent.
kiro_validate_packet.py	postToolUse (matcher=fs_write)	Pydantic schema-check writes under .erpaval/. Early-exits on non-erpaval paths. Also drops /tmp/kiro-erpaval-active-<session_id> as a cross-hook "this Kiro session touched ERPAVal" marker.
kiro_compound_nudge.py	stop	One-shot advisory STDERR warning when Compound is pending. Six gates: erpaval-active marker, session-<hex> name, fresh validation.yaml (<2h), no lessons.yaml, not nudged this session (HookState), not in .erpaval/sessions/.nudged ledger. The warning is informational — Kiro cannot block on stop.

Imperative tools under scripts/ — PEP 723 scripts invoked via uv run by the orchestrator:

Tool	Purpose	Invoked by
erpaval-new.py	Scaffold .erpaval/sessions/session-<hex>/ + seed intake.yaml	Orchestrator at session start
erpaval-recall.py	Tag-scored grep over .erpaval/solutions/**.md	Orchestrator per Act task
erpaval-validate.py	Pydantic schema check on YAML packet writes (CLI version)	Manual / CI — hook is primary

Kiro CLI compatibility

This skill is the Kiro distribution of erpaval. The Claude Code distribution lives at the repo root (skills/erpaval/); this distribution lives at kiro/skills/erpaval/. The methodology (six phases, classifiers, gates, cycles, write protocol, EARS, HMW) is identical across both. The differences below are runtime-shape only.

Concern	Claude Code distribution	Kiro distribution
Plugin root env var	${CLAUDE_PLUGIN_ROOT} (Claude Code injects)	${ERPAVAL_HOME} (set by kiro/install.sh; defaults to ~/.kiro/erpaval)
Skill subfolders	skills/erpaval/{references,templates,tools}/	kiro/skills/erpaval/{references,assets,scripts}/ (Agent Skills spec naming)
Subagent invocation	Task(subagent_type=…, prompt=…, run_in_background=true, isolation="worktree")	In-chat NL: > Use the erpaval-explorer agent to …. Fires Kiro's subagent built-in. Returns via the auto-attached summary tool — every dispatch prompt must end with Final step: call the built-insummarytool …. /spawn is not the orchestrator's primitive; it's a user-driven command for fresh sessions.
Concurrency cap	No documented cap	Max 4 parallel subagents (Kiro hard limit) — large waves dispatch in batches of 4
Task primitive	TaskCreate / TaskUpdate / TaskList / addBlockedBy	Filesystem-driven (tasks/T-AC-X-Y.md status: frontmatter) authoritative; Kiro /todo mirrors UI
Hook config location	hooks/hooks.json at plugin root (plugin-global)	Inline hooks field in kiro/agents/erpaval-orchestrator.json (per-agent)
Hook event names	SessionStart, PostToolUse(Write|Edit|MultiEdit), Stop	agentSpawn, postToolUse(matcher=fs_write), stop
Stop hook semantics	Can re-prompt the model via decision: "block" + reason	Advisory only — STDERR warning, non-blocking. User runs /erpaval to invoke Compound when warned.
Worktree isolation	isolation: "worktree" per Agent call	No Kiro primitive. Subagents run in the same working tree; rely on Scope discipline in packets.
Plugin namespacing	plugin:skill syntax	Flat — skills live as sibling dirs under ~/.kiro/skills/ or <project>/.kiro/skills/

The PEP 723 scripts (erpaval-new.py, erpaval-recall.py, erpaval-validate.py) are runtime-agnostic — identical bytes in both distributions. The methodology references (flow.md, classifiers.md, compound.md, validation-playbook.md, write-protocol.md, context-packets.md) are also runtime-agnostic with light env-var/path rewrites only.