action-topology-engine/AGENTS.md

AGENTS.md

This project is a focused deterministic website action topology engine.

Scope

Build and maintain only the topology engine:

• Capture page states.
• Extract actionable elements.
• Generate and verify locator candidates.
• Record action edges and observable effects.
• Emit graph artifacts that other projects can consume.

Do not turn this repository into a general browser agent platform. LLM planning, natural-language task execution, orchestration, and product UI belong in separate projects.

Commands

• npm install — install dependencies.
• npm run typecheck — TypeScript type check.
• npm run build — compile to dist/.
• npm run scan -- --url ./examples/simple.html --out artifacts/simple-scan.json — static scan.
• npm run example — low-risk exploration of the local example page.

Implementation Notes

• Prefer Playwright user-facing locator strategies first: role, label, placeholder, text, test id.
• Keep CSS locators as fallback candidates, not the primary source of truth.
• Bind elements to states. Do not treat a DOM node as globally meaningful outside its page state.
• Preserve risk gating. High-risk terms such as delete, submit, pay, confirm, and authorize must not be clicked by the default explorer.
• Keep source discussions under docs/source/ when they drive design decisions.