all-hands-cli 0.1.0

package/.allhands/skills/harness-maintenance/references/harness-skills.md

@@ -0,0 +1,87 @@
+# Harness Skills
+
+Per **Knowledge Compounding**, skills are domain expertise packages that compound over time — agents discover them automatically and load only what they need per **Context is Precious**.
+
+## Skill Schema
+
+Skills are defined by a YAML frontmatter manifest. Run `ah schema skill` for the authoritative schema. Key fields:
+
+- **name**: Skill identifier (e.g., `harness-maintenance`)
+- **description**: When to use this skill — agents match on this
+- **version**: Semver for tracking changes
+- **globs**: File patterns that trigger skill discovery (e.g., `".allhands/flows/**/*.md"`)
+
+## Directory Conventions
+
+```
+.allhands/skills/
+├── <skill-name>/
+│   ├── SKILL.md          # Hub: frontmatter + routing table
+│   └── references/       # Domain-specific reference docs (optional)
+│       ├── topic-a.md
+│       └── topic-b.md
+```
+
+- `SKILL.md` is the entry point — always a compact routing hub
+- `references/` (or `docs/`) contains deep domain knowledge
+- Agents read the hub first, then load only the reference matching their scenario
+
+## Discovery Mechanism
+
+Skills are discovered via glob matching against the files an agent is working on:
+
+1. Agent touches a file (e.g., `.allhands/flows/shared/MY_FLOW.md`)
+2. Harness matches file against all skill globs
+3. Matching skill(s) are surfaced to the agent
+4. Agent reads `SKILL.md` hub for routing context
+
+List all skills: `ah skills list`
+
+## Hub-and-Spoke Pattern
+
+This restructure establishes the convention for all harness skills:
+
+**Hub** (`SKILL.md`):
+- Compact (<100 lines) routing document
+- Contains `<goal>`, `<constraints>`, cross-cutting patterns
+- **Routing table**: Maps scenarios to specific reference docs
+- Agents always start here
+
+**Spokes** (`references/*.md`):
+- Deep, domain-specific knowledge
+- Loaded only when the routing table directs
+- Flexibly structured per domain (no rigid template)
+- Grounded in codebase reality (file paths, commands, schema fields)
+
+### When to Create a New Skill vs Extend Existing
+
+**Create new** when:
+- The domain is distinct (different file patterns, different expertise)
+- The knowledge doesn't fit under any existing skill's glob patterns
+- Agents working in this domain need dedicated context
+
+**Extend existing** when:
+- The knowledge falls within an existing skill's glob patterns
+- Adding a new reference doc to the existing hub covers it
+- The domain is a sub-specialty of an existing skill
+
+## Reference Doc Guidelines
+
+Per **Context is Precious**, each reference doc should:
+- Start with the most relevant first principles for that domain
+- Be grounded in codebase reality (file paths, schema fields, command examples)
+- Structure itself flexibly to fit its domain
+- Be concise — agents load only what they need
+
+## Existing Skills
+
+| Skill | Purpose | Pattern | Primary For |
+|-------|---------|---------|-------------|
+| `harness-maintenance` | Harness architecture and extension | Hub + `references/` | `.allhands/` content files (flows, schemas, skills, validation, agents) |
+| `claude-code-patterns` | Claude Code native features | Hub + `docs/` | TypeScript implementation in `harness/src/`, Claude Code configs in `.claude/` |
+
+## Related References
+
+- [`writing-flows.md`](writing-flows.md) — When authoring reference docs or skill entry-point flows
+- [`knowledge-compounding.md`](knowledge-compounding.md) — When skills need to compound knowledge via schemas or indexes
+- [`core-architecture.md`](core-architecture.md) — When skill globs or discovery interact with directory structure

package/.allhands/skills/harness-maintenance/references/knowledge-compounding.md

@@ -0,0 +1,78 @@
+# Knowledge Compounding
+
+Per **Knowledge Compounding**, everything feeds forward — decisions, pivots, limitations, realizations, best practices, and preferences. The harness captures and surfaces knowledge so future agent work benefits from all past work.
+
+## Documentation Schemas
+
+The harness defines schemas for structured knowledge artifacts. Run `ah schema <type>` to inspect any schema:
+
+| Schema | File Pattern | Purpose |
+|--------|-------------|---------|
+| `prompt` | `.planning/*/prompts/*.prompt.md` | Task definition and completion records |
+| `alignment` | `.planning/*/alignment.md` | Milestone context, prompt summaries, decisions |
+| `spec` | `specs/**/*.spec.md` | Feature specifications |
+| `skill` | `.allhands/skills/*/SKILL.md` | Domain expertise manifests |
+| `validation-suite` | `.allhands/validation/*.md` | Validation tooling definitions |
+| `solution` | `docs/solutions/*.md` | Reusable solution documentation |
+| `documentation` | `docs/*.md` | General documentation |
+
+Run `ah schema <type> body` to see the body format (not just frontmatter).
+
+## Knowledge Indexes
+
+### Solutions (`docs/solutions/`)
+Reusable patterns discovered during work. Searchable by future agents:
+- `ah solutions search "<keywords>"` — Find relevant past solutions
+- Solutions are created when an agent discovers a reusable pattern worth preserving
+- Per **Knowledge Compounding**, solutions prevent re-discovery of known patterns
+
+### Memories (`ah memories`)
+Agent learnings and engineer preferences that persist across sessions:
+- `ah memories search "<keywords>"` — Find relevant learnings
+- Captures: debugging insights, preference decisions, architectural rationale
+- Per **Knowledge Compounding**, memories prevent repeated mistakes
+
+### Knowledge Docs
+Codebase knowledge indexed for semantic search:
+- `ah knowledge docs search <descriptive_query>` — Semantic code search
+- Built from codebase during TUI startup (semantic index)
+- Per **Context is Precious**, agents search rather than loading full codebase
+
+## How Knowledge Feeds Forward
+
+### Prompt Completion Cycle
+Per **Prompt Files as Units of Work**, completed prompts document what was decided:
+1. Agent completes prompt tasks
+2. Summary appended to prompt file (decisions, deviations, learnings)
+3. Summary appended to alignment doc's "## Prompt Summaries" section
+4. Future agents read alignment doc to see all completed work without reading each prompt
+
+### Compaction Summaries
+Per **Knowledge Compounding**, compaction preserves work across context boundaries:
+1. `agent-compact` hook parses transcript for session summary
+2. Oracle generates summary with decision (CONTINUE/RESTART/BLOCKED)
+3. Summary appended to prompt file
+4. Same prompt can be re-run with accumulated learnings
+
+### Skill Improvement
+Skills and validation tooling improve with use:
+- Skills gain new reference docs as domains expand
+- Validation suites crystallize stochastic patterns into deterministic checks
+- Solutions capture reusable patterns discovered during implementation
+
+## Compounding Principles from `principles.md`
+
+The **Knowledge Compounding** principle states:
+> Everything feeds forward — decisions, pivots, limitations, disagreements, realizations, best practices, preferences. The harness implementation itself improves with use. Future tasks benefit from all past work.
+
+This manifests in:
+- **Alignment docs**: Cross-prompt visibility without context bloat
+- **Solution docs**: Reusable pattern library growing with each milestone
+- **Memories**: Persistent learnings across agent sessions
+- **Validation suites**: Crystallized quality checks that compound
+- **Skills**: Domain expertise packages that deepen over time
+
+## Related References
+
+- [`validation-tooling.md`](validation-tooling.md) — When knowledge artifacts involve validation suites or crystallization
+- [`harness-skills.md`](harness-skills.md) — When knowledge compounds through skill improvement or reference docs

package/.allhands/skills/harness-maintenance/references/tools-commands-mcp-hooks.md

@@ -0,0 +1,115 @@
+# Tools, Commands, MCP & Hooks
+
+Per **Context is Precious** and **Agentic Validation Tooling**, the harness extends Claude Code through hooks, CLI commands, and MCP integrations — all sharing an auto-discovery pattern.
+
+## Auto-Discovery Pattern
+
+Hooks, commands, and MCP servers share the same extension model:
+1. Create a module in the appropriate `src/` subdirectory
+2. Export a `register(parent: Command)` function
+3. The harness auto-discovers and registers at startup
+
+This pattern applies to:
+- **Hooks**: `.allhands/harness/src/hooks/` — Claude Code lifecycle integration
+- **Commands**: `.allhands/harness/src/commands/` — CLI subcommands under `ah`
+- **MCP Servers**: `.allhands/harness/src/mcp/` — External tool integrations
+
+## Hooks System
+
+Per **Context is Precious** and **Agentic Validation Tooling**, hooks bridge Claude Code and the harness.
+
+### Categories
+
+| Category | Purpose | Key Hooks |
+|----------|---------|-----------|
+| **Context** | Token-efficient context injection | `tldr-inject`, `read-enforcer`, `edit-inject`, `signature` |
+| **Enforcement** | Guide toward appropriate tools | `github-url`, `research-fetch`, `research-search` |
+| **Validation** | Quality gates on edits | `diagnostics`, `schema`, `format` |
+| **Lifecycle** | Handle agent events | `agent-stop`, `agent-compact` |
+| **Notification** | Desktop alerts | `elicitation`, `stop`, `compact` |
+| **Session** | Startup tasks | `tldr-warm` |
+
+### Hook Events (`.claude/settings.json`)
+
+| Event | Purpose |
+|-------|---------|
+| **PreToolUse** | Context injection, enforcement, blocking |
+| **PostToolUse** | Diagnostics, validation |
+| **SessionStart** | TLDR daemon warm-up |
+| **Stop/SessionEnd** | Notifications, cleanup |
+| **PreCompact** | Compaction handling |
+
+### Design Rules
+- Graceful degradation: hooks allow tool execution even if analysis fails
+- Enforcement blocks include helpful redirect messages
+- All optional dependencies (TLDR, pyright) have fallback behavior
+
+### Compaction Hook (Critical)
+Per **Knowledge Compounding**, `agent-compact` preserves work:
+1. Parse agent transcript for session summary
+2. Get git status (file changes)
+3. Call oracle to generate summary with decision (CONTINUE/RESTART/BLOCKED)
+4. Append summary to prompt file (allows re-run with learnings)
+5. Kill agent window
+
+## Commands Architecture
+
+Entry point: `.allhands/harness/src/cli.ts` (default action launches TUI). Auto-discovers commands from `.allhands/harness/src/commands/`.
+
+### Core Commands
+
+| Command | Domain | First Principle |
+|---------|--------|-----------------|
+| `ah knowledge` | Semantic search | **Context is Precious** |
+| `ah schema` | File structure | **Frontier Models are Capable** |
+| `ah validate` | Quality gates | **Agentic Validation Tooling** |
+| `ah oracle` | LLM inference | **Context is Precious** (saves caller context) |
+| `ah spawn` | Sub-agents | **Context is Precious** (isolated work) |
+| `ah tools` | MCP integration | **Agentic Validation Tooling** |
+
+### Command Design Rules
+- Use `--json` flag for machine-readable output
+- Graceful degradation when optional deps missing
+- Help text explains first principle motivation
+
+## MCP Server Integration
+
+Per **Agentic Validation Tooling**, MCP servers extend the harness with external tool capabilities.
+
+### Adding a New MCP Server
+
+Follow `.allhands/flows/shared/WRITING_HARNESS_MCP_TOOLS.md` for the full process. Key phases:
+
+1. **Research**: Investigate package requirements (transport type, auth, env vars)
+2. **Build Config**: Copy `.allhands/harness/src/mcp/_template.ts`, fill in researched values
+3. **Environment**: Document required env vars (do NOT add values)
+4. **Validate**: Build harness, verify with `ah tools --list` and `ah tools <server-name>`
+
+### Config Structure
+- `name`: Short identifier (used in `ah tools <name>:tool`)
+- `type`: Transport ('stdio', 'http', 'sse')
+- `command`/`args`: For stdio transport
+- `env`: Environment variables (`${VAR_NAME}` syntax)
+- `stateful`: Whether server maintains session state
+- `toolHints`: Helpful hints for key tools
+
+## Extension Points
+
+### Adding New Hooks
+1. Create file in `.allhands/harness/src/hooks/`
+2. Export `register(parent: Command)` function
+3. Add matcher to `.claude/settings.json`
+
+### Adding New Commands
+1. Create file in `.allhands/harness/src/commands/`
+2. Export `register(parent: Command)` function
+3. Document in `README.md`
+
+### Adding New Template Variables
+1. Add to `TemplateVars` registry in `.allhands/harness/src/lib/schemas/template-vars.ts`
+2. Include Zod schema and description
+
+## Related References
+
+- [`core-architecture.md`](core-architecture.md) — When your hook or command integrates with TUI lifecycle or platform settings
+- [`validation-tooling.md`](validation-tooling.md) — When adding validation hooks or quality gate tooling

package/.allhands/skills/harness-maintenance/references/validation-tooling.md

@@ -0,0 +1,77 @@
+# Validation Tooling
+
+Per **Agentic Validation Tooling**, programmatic validation replaces human supervision. This reference covers how validation suites are created, structured, and how they compound from stochastic exploration into deterministic gates.
+
+## Crystallization Lifecycle
+
+Per **Agentic Validation Tooling**, validation compounds through a lifecycle:
+
+1. **Stochastic exploration** — Agent-driven exploratory testing using model intuition discovers patterns
+2. **Pattern crystallization** — Discovered patterns become deterministic checks
+3. **CI/CD entrenchment** — Deterministic checks gate releases
+4. **Frontier shift** — Stochastic exploration moves to new unknowns
+
+This is how validation compounds. Every domain has both a stochastic dimension (exploratory) and a deterministic dimension (binary pass/fail).
+
+## Suite Existence Threshold
+
+A validation suite must have a meaningful stochastic dimension to justify existing. Deterministic-only tools (type checking, linting, formatting) are test commands referenced directly in acceptance criteria and CI/CD — they are NOT suites.
+
+## Creating Validation Tooling
+
+Follow `.allhands/flows/shared/CREATE_VALIDATION_TOOLING_SPEC.md` for the full process. This creates a spec, not an implementation.
+
+### Research Phase
+- Run `ah tavily search "<validation_type> testing tools"` for available tools
+- Run `ah perplexity research "best practices <validation_type> testing <technology>"` for best practices
+- Determine whether the domain has a meaningful stochastic dimension before proceeding
+- Run `ah tools --list` to check existing MCP integrations
+
+### Tool Validation Phase
+Per **Agentic Validation Tooling**, research produces assumptions; running the tool produces ground truth:
+- Install and verify tool responds to `--help`
+- Create a minimal test target (temp directory, not committed)
+- Execute representative stochastic workflows
+- Systematically try commands against codebase-relevant scenarios
+- Document divergences from researched documentation
+
+### Suite Writing Philosophy
+
+Per **Frontier Models are Capable** and **Context is Precious**:
+
+- **`--help` as prerequisite**: Suites MUST instruct agents to pull `<tool> --help` before any exploration — command vocabulary shapes exploration quality. The suite MUST NOT replicate full command docs.
+- **Inline command examples**: Weave brief examples into use-case motivations as calibration anchors — not exhaustive catalogs, not separated command reference sections.
+- **Motivation framing**: Frame around harness value: reducing human-in-loop supervision, verifying code quality, confirming implementation matches expectations.
+- **Exploration categories**: Describe with enough command specificity to orient, not prescriptive sequences that constrain.
+
+Formula: **motivations backed by inline command examples + `--help` as prerequisite and progressive disclosure**. Commands woven into use cases give direction; `--help` reveals depth.
+
+### Evidence Capture
+
+Per **Quality Engineering**, two audiences require different artifacts:
+
+- **Agent (self-verification)**: Primitives used during the observe-act-verify loop (state checks, assertions, console output). Real-time, not recorded.
+- **Engineer (review artifacts)**: Trust evidence produced after exploration (recordings, screenshots, traces, reports).
+
+Pattern: explore first, capture second.
+
+## Validation Suite Schema
+
+Run `ah schema validation-suite` for the authoritative schema. Key sections in a suite:
+
+- **Stochastic Validation**: Agent-driven exploratory testing with model intuition
+- **Deterministic Integration**: Binary pass/fail commands that gate completion
+
+List available suites: `ah validation-tools list`
+
+## Integration with Prompt Execution
+
+Prompt files reference validation suites in their `validation_suites` frontmatter. During execution:
+1. Agent reads suite's **Stochastic Validation** section during implementation for exploratory quality
+2. Agent runs suite's **Deterministic Integration** section for acceptance criteria gating
+3. Validation review (`PROMPT_VALIDATION_REVIEW.md`) confirms pass/fail
+
+## Related References
+
+- [`tools-commands-mcp-hooks.md`](tools-commands-mcp-hooks.md) — When validation uses hooks, CLI commands, or MCP research tools
+- [`knowledge-compounding.md`](knowledge-compounding.md) — When crystallized patterns need to compound into persistent knowledge

package/.allhands/skills/harness-maintenance/references/writing-flows.md

@@ -0,0 +1,84 @@
+# Writing Flows
+
+Per **Context is Precious** and **Frontier Models are Capable**, flows articulate "why" so agents deduce "what" and "how". This reference covers flow authorship patterns, structure conventions, and the progressive disclosure model.
+
+## First Principles Applied
+
+| First Principle | Flow Directive |
+|-----------------|----------------|
+| **Context is Precious** | Be brief. Progressive disclosure. Don't over-explain. |
+| **Frontier Models are Capable** | Provide "why", let agents deduce "what/how". Trust capability. |
+| **Knowledge Compounding** | DRY - centralize instructions, reference rather than repeat. |
+
+When a flow instructs a behavior, cite the motivating First Principle. This teaches agents to think like members of a model-first company.
+
+## XML Tags
+
+Reserved for drawing specific attention to rules, use as needed:
+- `<goal>`: Motivations and contribution to the wider harness
+- `<constraints>`: Hard rules (NEVER/MUST/ALWAYS)
+- `<ownership>`: Files and domains the agent is restricted to
+- `<success_criteria>`: Validation criteria for task completion
+- `<inputs>`: Inputs required for the flow to execute
+- `<outputs>`: Outputs expected from the flow
+
+## Structure
+
+Per **Frontier Models are Capable**:
+- Start with `<goal>` - the "why" that enables capable deduction
+- Organize into `##` sections representing phases or capability chunks
+- Use bullet points for individual units of capability:
+  - "Read `path/to/FLOW_DOC.md`"
+  - "Use `ah [command]` to [action]"
+  - "Think deeply about X, Y, and Z"
+
+Per **Context is Precious**:
+- Reference other flows for progressive disclosure rather than repeating
+- Keep flows brief - agents only see what they need, when they need it
+
+Per **Knowledge Compounding**:
+- Centralize instructions, use decision trees that reference capability chunks
+- Don't repeat messaging, instructions, or command usage across flows
+
+## File Organization
+
+- `flows/` root: Agent default flows, disclosed immediately on spawn
+- `flows/shared/`: Progressively disclosed via references in parent flows
+- `flows/shared/jury/`: Specialized review sub-agents
+
+### Progressive Disclosure Pattern
+```markdown
+- Read `.allhands/flows/shared/SKILL_EXTRACTION.md` and follow its instructions
+```
+
+Sub-flows use `<inputs>` and `<outputs>` tags for execution-agnostic subtasks. This decouples the flow from its caller — any agent can execute it given the right inputs.
+
+## Quickfire Writing Tips
+
+- **Action-verb bullets**: Start with verbs ("Read", "Use", "Follow", "Run")
+- **Path backticking**: Consistently wrap paths and commands in backticks
+- **Conditional simplicity**: Use "If X - Y" pattern, keep logic flat
+- **Hierarchical nesting**: Sub-bullets for related sub-tasks only
+- **Phase naming**: Section headers as capability phases (Context Gathering, Implementation, Validation, Completion)
+- **Exit clarity**: End with explicit stop condition ("commit your work", "Stop")
+- **Progressive disclosure**: Reference external flows for complexity ("read `.allhands/flows/FLOW.md` and follow its instructions")
+- **Inline commands**: Embed CLI usage directly ("Run `ah schema prompt body`")
+- **First Principle citation**: Label motivating principles by name to teach agents the "why" behind directives
+
+## Northstar Example
+
+See `.allhands/flows/PROMPT_TASK_EXECUTION.md` — this flow demonstrates all conventions: `<goal>`, `<constraints>`, phase sections, action-verb bullets, progressive disclosure via sub-flow references, and explicit completion steps.
+
+## Flow-Config Boundary
+
+Flows and workflow domain configs serve distinct roles. Maintaining the boundary prevents redundancy and keeps configs concise.
+
+- **Flows** own generic behaviors: interview mechanics, grounding patterns, conviction spectrum, open question triage, roadmap-aware assumptions
+- **Configs** provide domain-specific context: vocabulary, gap signals, output sections, planning strategy, category deep dives
+- **Litmus test**: If removing it from the config would break ALL domains, it belongs in the flow. If it only affects ONE domain, it belongs in the config.
+- Configs layer domain-specific additions on top of flow behaviors — they should not restate the base behaviors the flow already provides
+
+## Related References
+
+- [`core-architecture.md`](core-architecture.md) — When your flow change touches directory structure, TUI lifecycle, or schema system
+- [`harness-skills.md`](harness-skills.md) — When creating a flow that should be discoverable as a skill entry point

package/.allhands/validation/browser-automation.md

@@ -0,0 +1,109 @@
+---
+name: browser-automation
+description: "Browser-based validation for front-end web implementations — exploratory UX testing, visual regression, accessibility scanning, and end-to-end flow verification"
+globs:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.vue"
+  - "**/*.svelte"
+  - "**/*.html"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.astro"
+  - "**/pages/**"
+  - "**/app/**"
+  - "**/components/**"
+  - "**/layouts/**"
+  - "**/views/**"
+tools:
+  - "agent-browser"
+  - "playwright"
+  - "@axe-core/playwright"
+---
+
+## Purpose
+
+This suite validates browser-based quality across a unified domain: end-to-end flow verification, visual regression, UX quality, and accessibility. These are sub-concerns within a single validation domain — the browser — not separate suites.
+
+The stochastic dimension uses agent-driven browser exploration to probe edge cases, test responsive behavior, verify interaction flows, and discover regressions that scripted tests miss. The deterministic dimension uses Playwright directly for CI-gated visual regression, accessibility scanning, and scripted e2e flows.
+
+Per **Agentic Validation Tooling**, this suite meets the existence threshold: the stochastic dimension (exploratory UX testing, interaction probing, visual state exploration) provides meaningful agent-driven validation beyond what deterministic tests alone can cover.
+
+## Tooling
+
+### agent-browser (stochastic dimension)
+
+- **Installation**: `npm install -g agent-browser && agent-browser install`
+- Rust CLI + Node.js daemon built on Playwright. Discrete CLI commands, not a persistent API.
+- **Snapshot+Refs model**: Accessibility tree with compact element refs (`@e1`). Refs invalidate on state change — always re-snapshot after navigation or DOM mutation.
+- **Session isolation**: Named sessions for parallel exploration. Auth state persists across sessions.
+- **Command reference first**: Run `agent-browser --help` and `agent-browser <command> --help` before any exploration — command vocabulary shapes what you attempt. Prerequisite, not afterthought.
+
+### Playwright (deterministic dimension)
+
+- **Installation**: `npm install -D @playwright/test @axe-core/playwright && npx playwright install chromium --with-deps`
+- **Command reference first**: `npx playwright --help` and Playwright docs for the full API surface.
+- Scripted CI tests — visual regression (`toHaveScreenshot()`), accessibility (`@axe-core/playwright`, WCAG 2.1 AA), e2e flows. Not via MCP; no LLM reasoning needed.
+
+## Stochastic Validation
+
+Agent-driven exploratory browser validation. This section teaches WHAT to validate and WHY — the CLI teaches HOW.
+
+### Core Loop
+
+**Prerequisite**: `agent-browser --help` — internalize the full command vocabulary before exploring. Every subcommand has its own `--help`. Command awareness shapes exploration quality.
+
+Navigate → snapshot → identify targets → interact → wait for result → verify outcome → check errors.
+
+This is the thinking pattern to internalize, not a command sequence:
+
+- Always re-snapshot after state changes — navigation, form submission, modal appearance, any DOM mutation. Stale refs cause cascading failures.
+- Wait for async results before verifying — element appearance, text change, URL update, network settlement
+- Verify outcomes before proceeding — never assume an interaction succeeded
+- Check console errors after interactions — bugs are often invisible in the visual state
+
+### Use Cases
+
+These seed categories guide exploration. Per **Frontier Models are Capable**, the agent extrapolates deeper investigation from these starting points.
+
+- **Flow verification**: `navigate` to entry point, `snapshot` to orient, interact via refs — `click @e3`, `type @e5 "user@test.com"` — then re-snapshot to verify: URL changed, success state appeared, no console errors. Walk full critical paths (registration, checkout, settings). Exercise redirects and back/forward navigation.
+- **Responsive testing**: `resize` viewport across breakpoints (e.g., 375px mobile, 768px tablet, 1280px desktop), `snapshot` at each to inspect layout changes. Test media preferences with `emulate-media` (dark mode, reduced motion). Layout bugs at specific widths are among the most common front-end regressions.
+- **Edge case probing**: `click` submit without filling fields, `type` overlong strings and special characters into inputs. Verify error handling surfaces appropriate messages in the next `snapshot`. Test keyboard-only navigation — `press Tab`, `press Enter`, `press Escape` — can a user complete flows without a mouse?
+- **Accessibility exploration**: `snapshot` IS the assistive technology view — the accessibility tree reveals semantic structure directly. Verify Tab order (`press Tab` sequences), Enter/Space activation (`press Enter` on focused element), Escape dismissal (`press Escape`), focus management on modals.
+- **Evidence capture**: `screenshot` before/after interactions for visual comparison. Capture console output tied to specific flows as bug evidence. Screenshots are opportunistic — capture what's interesting, not on a schedule.
+- **Video recording**: Explore first (discover flows, find issues), then `record` a clean replay for engineer review. Recording creates a fresh context but preserves session state — focused evidence, not noisy exploration footage.
+
+### Resilience
+
+Stochastic exploration is inherently unpredictable. These patterns prevent death spirals:
+
+- Max 3 retries on any interaction, then report failure and move on
+- `screenshot` on failure — capture full-page state before recovery attempts
+- Session restart if page becomes unresponsive — fresh named session + alternative path
+- Auth bail-out — OAuth, MFA, or CAPTCHA blockers: save state, report, move on
+- Dialog/frame handling — accept or dismiss dialogs to unblock; switch into iframes for embedded content
+- Self-healing pattern — when an element disappears, re-snapshot the entire page rather than retrying the same selector (Stagehand reference)
+
+Use `agent-browser --help` and `agent-browser <command> --help` for all available commands and options. This suite teaches what to validate and why — the CLI teaches how.
+
+## Deterministic Integration
+
+CI-gated browser regression testing using Playwright directly. Scripted assertions — no LLM reasoning needed.
+
+- **Visual regression**: `await expect(page).toHaveScreenshot('dashboard.png')` — baseline screenshots committed to repo, fail CI on drift. Mask dynamic content (`{ mask: [page.locator('.timestamp')] }`) to avoid false positives. Single OS + browser in CI for font rendering consistency.
+- **Accessibility**: `const results = await new AxeBuilder({ page }).analyze()` — WCAG 2.1 AA scanning via `@axe-core/playwright`. Reusable fixture for consistent config. Scope to components (`.include('.component')`) for feature tests, full-page for integration.
+- **Multi-device**: `projects: [{ use: devices['iPhone 14'] }]` — Chromium-only, desktop/mobile/tablet viewport projects. Responsive regression is a viewport concern, not a browser concern.
+- **CI artifacts**: `use: { trace: 'on-first-retry', screenshot: 'only-on-failure' }` — traces + screenshots on failure for remote debugging. Upload artifacts to survive ephemeral runners.
+
+## ENV Configuration
+
+| Variable | Required | Dimension | Purpose |
+|----------|----------|-----------|---------|
+| `BASE_URL` | Yes | Both | Dev server URL (e.g., `http://localhost:3000`) |
+| `AGENT_BROWSER_SESSION` | No | Stochastic | Named session for isolation |
+| `AGENT_BROWSER_PROFILE` | No | Stochastic | Persistent browser profile path for auth state |
+| `BROWSERBASE_API_KEY` | No | Both (CI) | Cloud browser provider API key |
+| `BROWSERBASE_PROJECT_ID` | No | Both (CI) | Cloud browser provider project ID |
+| `CI` | Auto | Deterministic | Set by CI environment; controls retries, reporter |
+
+`BASE_URL` must be configured per-target-project. This suite is framework-agnostic — the agent should discover the target project's dev server configuration at execution time.