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/`

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

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.

2.5 KiB Raw Blame History