Architecture and design principles

Architecture

src/
  parser/        .feature → scenarios (outline expansion, step kinds, AST line lookup)
  cache/         schema, store, proposals, propagation
  replay/        the replayer: cache actions performed on Playwright's browser engine (locators, retries, tabs, capture vars)
  agent/         AgentProvider abstraction; Claude provider, recorder, prompts, MCP tools
  orchestrator/  per-scenario state machine: replay ⇄ agent, assertion guard, proposals
  report/        HTML + JSON generation
  cli/           run / accept / reject / report

Key boundaries:

• AgentProvider is an interface; the Claude implementation is one provider. Multi-provider support (OpenAI) slots in without touching the orchestrator.
• The replayer knows nothing about AI; the agent knows nothing about caching. The orchestrator owns the escalation policy and the assertion guard: trust decisions live in exactly one place.
• One browser, two drivers. The orchestrator launches Chromium with a CDP port; the replayer drives it via the Playwright library, the agent via Playwright MCP attached to the same endpoint.

Design principles

1. A test tool that masks regressions is worse than none. Everything about assertions follows from this.
2. Adaptation is a proposal, not a decision. Humans accept caches, like snapshot updates.
3. Determinism is the product; AI is the maintenance crew. Tokens are spent only when reality changed.
4. Exact identity over clever inference. Propagation matches identical queries; no entity-resolution heuristics rewrite your suite.

The full design rationale, competitor research, and decision log live in the design log. For hands-on usage, continue to How to Use; for pending work, milestones, and decision gates, see the Roadmap.