13 — Cursor Handoff

From the Burrow™ specification set.

13 — Cursor Handoff

Objective

Build Burrow™ according to the repository specifications. Cursor has access to the development Mac and can run the application locally, but that access must be treated conservatively.

Start Here

Read in order:

  1. AGENTS.md
  2. README.md
  3. docs/00-PRODUCT-VISION.md
  4. docs/03-SAFETY-MODEL.md
  5. docs/01-ARCHITECTURE.md
  6. docs/09-CANONICAL-DATA-MODEL.md
  7. docs/10-IMPLEMENTATION-PLAN.md
  8. the specification for the feature being implemented.

Critical Constraint

Phase 1 is read-only.

Do not add or invoke code that deletes, moves, renames, archives, backs up, evicts, downloads, synchronizes, or modifies user files.

Do not "clean up" anything on the owner's Mac as part of development.

First Task

Produce an implementation proposal for Milestone 0 and Milestone 1 before writing substantial feature code.

The proposal should include:

  • repository structure;
  • Swift engine structure;
  • Next.js app structure;
  • API/IPC contract strategy;
  • SQLite library/migration choice;
  • testing approach;
  • development commands;
  • risks/questions.

Do not replace documented architectural decisions without identifying the proposed change and reason.

Suggested Repository Shape

/
├── AGENTS.md
├── README.md
├── mkdocs.yml
├── vercel.json
├── docs/
├── brand/                   # Official Burrow brand kit
├── apps/
│   └── web/                 # Next.js management UI (local)
├── engine/
│   └── Burrow/              # Swift package/app/service
├── contracts/               # API schemas/types
├── fixtures/                # generated/safe test fixtures
├── scripts/                 # dev/build commands only
└── migrations/              # SQLite migrations

Public documentation and the app UI are the Next.js site on Vercel (burrow.jasonkoch.io). MkDocs Material remains the local strict docs build. Do not host the engine or grant the public site filesystem access.

Adjust if Swift tooling strongly favors a different layout, but keep boundaries clear.

Root quality commands are make lint, make typecheck, make test, and make build. They pass on the empty skeleton and invoke Next.js/Swift tools when those packages exist.

Working Against Real Drives

Before any real scan:

  1. show which roots will be scanned;
  2. verify the operation is Level 0/read-only;
  3. use explicit roots rather than /;
  4. respect exclusions;
  5. make scanning cancellable;
  6. do not intentionally hydrate cloud-only files;
  7. log errors rather than changing permissions.

Reporting Back

At the end of each milestone provide:

  • what was implemented;
  • commands to run;
  • tests executed/results;
  • known limitations;
  • screenshots or summarized UI verification where useful;
  • any deviations from the specifications;
  • next recommended work item.

Forbidden Shortcuts

  • shelling out to rm, mv, or cleanup tools;
  • using the owner's files as mutation fixtures;
  • assuming iCloud/OneDrive files are backups;
  • deleting "obvious duplicates";
  • force-downloading cloud content to hash it;
  • adding external SaaS/telemetry;
  • hiding errors or incomplete scan coverage.