Imported from UBC-FRESH/fieldatlas (AGENTS.md). Install upstream with npx skills add UBC-FRESH/fieldatlas. Copyright stays with the author.

AGENTS.md

This file is the working contract for AI coding agents in this repository.

Project Purpose

fieldatlas exists to build a free iPhone app for offline, georeferenced field maps and reproducible public map packages.

The goal is not to copy the internals, branding, or proprietary behavior of any commercial map application. The goal is to provide an open, auditable field map experience where package metadata, georeferencing assumptions, source provenance, and offline behavior are explicit.

Current Repo State

This repository has completed Phase 1 iOS app-shell work. It contains:

• README.md: concise public overview and current status.
• ROADMAP.md: phase/task roadmap and issue tracker map.
• CHANGE_LOG.md: append-only project narrative.
• planning/: focused planning notes and design records.
• Package.swift: Swift Package Manager manifest for core and app-shell targets.
• src/fieldatlas_core/: importable Swift core library code.
• app/fieldatlas_ios/sources/: package-compiled SwiftUI app-shell code.
• app/fieldatlas_ios/app/: native SwiftUI app entrypoint for a future Xcode target.
• tests/: package-backed tests.
• docs/: lightweight project documentation.
• .github/workflows/: CI checks.
• tmp/, runtime/, local/, and outputs/: ignored local working areas.

Do not claim that FieldAtlas currently implements a production iOS app, real map renderer, geospatial PDF parser, offline tile engine, user-selected package import, or location privacy model until a roadmap phase records that evidence.

Working Principles

• Read AGENTS.md, ROADMAP.md, and CHANGE_LOG.md before making project-shaping changes.
• Keep UI code thin over testable Swift package APIs.
• Keep map package metadata explicit and Codable.
• Prefer structured records over ad hoc strings for package manifests, provenance, validation diagnostics, and map layer descriptions.
• Keep public repo content clean of private, unpublished, credentialed, or machine-specific material.
• Use public-safe synthetic fixtures in tests.
• Keep changes scoped to the active roadmap phase and issue.

Planning Workflow

This repo follows the UBC-FRESH phase/task/subtask workflow:

• ROADMAP.md is the current plan and issue tracker map.
• One roadmap phase maps to one GitHub parent issue and one feature branch.
• One roadmap task maps to one child issue linked from the parent issue body.
• Subtasks usually stay as checklist items inside the child issue body.
• Use at most three issue levels: phase, task, implementation subtask.
• Record issue numbers beside roadmap phases and tasks once created.
• Keep ROADMAP.md, CHANGE_LOG.md, planning notes, issue bodies, and PR descriptions synchronized.
• Open a PR from the phase branch to main only after phase tasks, tests, docs, and closeout notes are complete or explicitly deferred.

Strict Development Workflow

• Create or activate the GitHub parent issue before starting a roadmap phase.
• Create the feature branch from current main for that parent issue.
• Create child issues for roadmap tasks under the parent issue.
• Work child issues one at a time where practical.
• Before closing a child issue, update checklist items or explain superseded scope in the issue body.
• Keep ROADMAP.md, CHANGE_LOG.md, and issue comments synchronized as task state changes.
• Close the parent issue only after the PR has merged back to main.

Verification

Default local check:

swift test

Before claiming iOS app behavior, verify on a real simulator or device using the active Xcode project/workspace for the phase.