Henrique Velloso
7c92d90a1e
- Changed .cursorrules to point to AGENTS.md. - Updated .gitignore to include test runs and reports, ensuring they are not tracked. - Enhanced AGENTS.md with a detailed quick reference table and added sections for E2E testing. - Introduced multiple new YAML files in the maestro directory for testing app installation, updates, and sign-in flows. - Created a comprehensive testing document in test/TESTING.md outlining agent-orchestrated testing procedures.
3.9 KiB
AI Agents
This document is the entry point for AI assistants. All behavioral authority lives in the project spec, not here.
If anything in this file conflicts with files under spec/guidelines/,
this file is wrong.
What This Repository Is
Zapstore is a local-first, Nostr-native app store for Android. It discovers, downloads, verifies, and installs APKs signed by developers the user trusts.
Users can support developers directly via Lightning zaps.
Quick Reference
| What | Where |
|---|---|
| Architecture & patterns | spec/guidelines/ARCHITECTURE.md |
| Non-negotiable rules | spec/guidelines/INVARIANTS.md |
| Quality standards | spec/guidelines/QUALITY_BAR.md |
| Product vision | spec/guidelines/VISION.md |
| Feature specs | spec/features/ |
| Active work | work/ |
| E2E testing workflow | test/TESTING.md |
| Test specs | test/specs/ |
| Maestro flows | maestro/ |
Project Spec Structure
spec/
guidelines/ # Permanent rules (human-owned, never AI-modified)
ARCHITECTURE.md # Package boundaries, dependencies, key patterns
INVARIANTS.md # Non-negotiable behavioral guarantees
QUALITY_BAR.md # Standards, when to create specs
VISION.md # Product goals and non-goals
features/ # Feature specs (behavioral contracts)
_TEMPLATE.md # Template with example
FEAT-001-*.md # Actual feature specs
work/ # Active work packets (temporary, delete after merge)
_TEMPLATE.md # Template with example
WORK-001-*.md # Actual work packets
How to Work
- Before implementing, check
spec/features/for a relevant feature spec - For non-trivial work, create a work packet in
work/ - Every code change must trace to a task in the work packet
- If a spec is unclear or incorrect, report a Spec Issue—do not guess
See spec/guidelines/QUALITY_BAR.md for what qualifies as "non-trivial."
File Ownership
Never modify files in spec/guidelines/.
If a guideline seems wrong or incomplete, report it as a Spec Issue.
| Path | Owner | AI May Modify |
|---|---|---|
spec/guidelines/* |
Human | No |
spec/features/* |
Human | No (unless explicitly asked) |
work/*.md |
AI | Yes |
lib/** |
Shared | Yes |
test/** |
Shared | Yes |
AGENTS.md |
Human | No |
test/TESTING.md |
Human | No |
test/specs/* |
Human | No (propose changes) |
test/runs/* |
Agent | Yes |
test/reports/* |
Agent | Yes |
maestro/** |
Shared | Yes |
Working Rules
- Prefer small, localized changes. Avoid unrelated refactors.
- After dependency changes, run:
fvm flutter pub get - Fix any analyze/lint errors introduced by your changes.
- Assume Android as default target unless instructed otherwise.
E2E Testing
Tests are agent-orchestrated: the agent handles setup, stateful checks, and
reporting while Maestro handles UI automation. Read test/TESTING.md first.
Key concept: Agent-Verified Criteria — Maestro is stateless, so cross-flow
checks (e.g., "badge count incremented by 1") are captured before/after by the
agent and reported alongside Maestro's own assertions. See the test spec template
at test/specs/_TEMPLATE.md for the format.