karvey-browse — Give the agent eyes
Purpose
A cross-cutting skill of the Karvey Method: a support layer, NOT a phase. It does not advance the method nor change spec.json:phase. It can be invoked from any phase when the agent needs to see with its own eyes what is happening in the target's real runtime.
Its role is simple: give it eyes. The agent stops reasoning blindly about the code and starts observing the real behavior — open, click, screenshot and inspect state. Inspired by gstack /browse + /setup-browser-cookies.
Stack-agnostic
It operates on the real runtime of the target declared in project.json:targets (see karvey/rules/targets.md). It does not assume a fixed stack:
| Target |
Real runtime |
How it is observed |
web |
Headless browser (e.g. Playwright) |
navigate, click, screenshot, read DOM/console |
ios / android |
Simulator / device |
open the app, interact, screenshot, read logs |
cli |
Process / terminal |
run, capture stdout/stderr, inspect state |
api |
HTTP client |
send requests, capture responses and headers |
Capabilities
- Navigate / open the target in its real runtime.
- Click / interact (forms, buttons, gestures depending on the target).
- Capture screenshots as visual evidence.
- Read state / console (DOM, logs, process output, responses).
Findings (feed the iteration loop)
When browsing surfaces a defect or a gap (something looks wrong, behaves wrong, or contradicts/exceeds the spec), and a change-id is in context, append it to docs/spec/changes/{change-id}/findings.md classified as bug / spec-gap / emergent (see karvey/rules/iteration-loop.md). Browse only observes and classifies — routing is karvey-iterate's job. This is how "I saw it break with my own eyes" becomes tracked work instead of a passing comment.
Session handling (web target)
When the target is web, it can import cookies/session from a real browser to test authenticated views without manual re-login. This makes it possible to inspect screens behind login using the user's already-active session.
Steps
- Determine the target. Read
project.json:targets (and karvey/rules/targets.md). If the user passed --target, use that; if not, infer it from the destination or from the project's main target.
- Bring up the corresponding runtime. Headless browser for web, simulator/device for mobile, process/terminal for CLI, HTTP client for API. If it is authenticated web, import the real browser's cookies/session before navigating.
- Execute the requested actions. Navigate/open, click/interact, capture and read state as requested.
- Return evidence. Screenshots, DOM/state, console logs or process output — everything that backs up what was observed.
Reminders
- Close the runtime/browser when finished. Do not leave processes or browsers hanging.
- It does not advance the phase. This skill is cross-cutting support; it never modifies
spec.json:phase nor makes method transitions.
Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see karvey/LICENSE and karvey/TRADEMARK.md.
1---2name: karvey-browse3description: karvey-browse — Give the agent eyes4---56# karvey-browse — Give the agent eyes78## Purpose910A **cross-cutting** skill of the Karvey Method: a **support layer, NOT a phase**. It does not advance the method nor change `spec.json:phase`. It can be invoked from any phase when the agent needs to **see with its own eyes** what is happening in the target's real runtime.1112Its role is simple: **give it eyes**. The agent stops reasoning blindly about the code and starts observing the real behavior — open, click, screenshot and inspect state. Inspired by `gstack /browse` + `/setup-browser-cookies`.1314### Stack-agnostic1516It operates on the real runtime of the target declared in `project.json:targets` (see `karvey/rules/targets.md`). It does not assume a fixed stack:1718| Target | Real runtime | How it is observed |19|--------|--------------|-----------------|20| `web` | Headless browser (e.g. Playwright) | navigate, click, screenshot, read DOM/console |21| `ios` / `android` | Simulator / device | open the app, interact, screenshot, read logs |22| `cli` | Process / terminal | run, capture stdout/stderr, inspect state |23| `api` | HTTP client | send requests, capture responses and headers |2425### Capabilities2627- **Navigate / open** the target in its real runtime.28- **Click / interact** (forms, buttons, gestures depending on the target).29- **Capture screenshots** as visual evidence.30- **Read state / console** (DOM, logs, process output, responses).3132### Findings (feed the iteration loop)3334When browsing surfaces a defect or a gap (something looks wrong, behaves wrong, or contradicts/exceeds the spec), and a `change-id` is in context, **append it to `docs/spec/changes/{change-id}/findings.md`** classified as `bug` / `spec-gap` / `emergent` (see `karvey/rules/iteration-loop.md`). Browse only **observes and classifies** — routing is `karvey-iterate`'s job. This is how "I saw it break with my own eyes" becomes tracked work instead of a passing comment.3536### Session handling (web target)3738When the target is web, it can **import cookies/session from a real browser** to test authenticated views without manual re-login. This makes it possible to inspect screens behind login using the user's already-active session.3940## Steps41421. **Determine the target.** Read `project.json:targets` (and `karvey/rules/targets.md`). If the user passed `--target`, use that; if not, infer it from the destination or from the project's main target.432. **Bring up the corresponding runtime.** Headless browser for web, simulator/device for mobile, process/terminal for CLI, HTTP client for API. If it is authenticated web, import the real browser's cookies/session before navigating.443. **Execute the requested actions.** Navigate/open, click/interact, capture and read state as requested.454. **Return evidence.** Screenshots, DOM/state, console logs or process output — everything that backs up what was observed.4647## Reminders4849- **Close the runtime/browser when finished.** Do not leave processes or browsers hanging.50- **It does not advance the phase.** This skill is cross-cutting support; it never modifies `spec.json:phase` nor makes method transitions.5152---53*Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see `karvey/LICENSE` and `karvey/TRADEMARK.md`.*
MauricioQuezadaHaintech