path: root/.agent/config.md

# Agent Configuration & Master Rulebook (.agent/config.md)

This is the primary source of truth for all AI agents working on **Nav**. These instructions take absolute precedence over general defaults.

## 1. Project Directory Structure (.agent/)

| File | Purpose |
|------|---------|
| `config.md` | **Main Entry Point** — Rules, workflows, and core mandates. |
| `code-map.md` | **Code Map** — Package topology, key classes, gotchas, testing guide. Read this to bootstrap context fast. |
| `worklog.md` | **Session State** — Current focus, recently completed, and next steps. |
| `design.md` | **Architecture** — Component design, UI mockups, and roadmap. |
| `coding_standards.md` | **Technical Standards** — Android/Kotlin best practices, offline-first. |
| `mission.md` | **Mission & Values** — Strategic goals and agent personality. |
| `narrative.md` | **Background** — Historical context and evolution of the project. |
| `preferences.md` | **User Prefs** — Living record of user-specific likes/dislikes. |
| `review-intent-reality.md` | **Audit Prompt** — Structured review to find gaps between documented intent and implemented reality. Run after major merges or when a regression reveals a code-map error. |

## 2. Branch Policy — MANDATORY SESSION START ACTION

**Before any other action in every session: run `git branch` and switch to `main` if not already there.**

```
git checkout main                              # run this if not already on main
git config core.hooksPath scripts/git-hooks   # activate if not already set
```

The repo ships a pre-commit hook in `scripts/git-hooks/pre-commit` that hard-blocks commits to `master`. Activate it with the command above on first use in any environment.

**Primary branch: `main`**

- ALL work merges to `main`. Never to `master` or any other branch.
- `master` does not exist as a development target. If HEAD is on `master`, switch to `main` immediately — before reading files, before planning, before any other tool call.
- Feature branches are cut from `main` and merge back to `main`.
- When a session harness specifies a generated branch name (e.g. `claude/foo-XYZ`), develop there and merge to `main` when done — not to wherever the local HEAD points.
- The CI/CD workflow targets `main`. Firebase distribution fires on `main` pushes only.
- If you are ever unsure which branch to merge to: it is `main`.

## 3. Core Mandates

### ULTRA-STRICT ROOT SAFETY PROTOCOL
1.  **Inquiry-Only Default:** Treat every message as research/analysis unless it is an explicit, imperative command (Directive).
2.  **Zero Unsolicited Implementation:** Never modify files, directories, or processes based on assumptions.
3.  **Interactive Strategy Checkpoint:** Research first, present a strategy, and **WAIT** for an explicit "GO" before any system-changing tool call.
4.  **No Destructive Assumptions:** Always verify state (`ps`, `ls`, `git status`) before proposing actions.
5.  **Root-Awareness:** Prioritize system integrity and user confirmation over proactiveness.

### Living Documentation Mandate
1.  **Continuous Capture:** Agents MUST proactively update the files in ".agent/" as new decisions, patterns, or user preferences are revealed.
2.  **No Stale Instructions:** If a workflow or technical standard evolves, the agent is responsible for reflecting that change in the Master Rulebook immediately.
3.  **Worklog Integrity:** The ".agent/worklog.md" must be updated at the start and end of EVERY session.
4.  **Code-Map Accuracy:** `code-map.md` must describe what the code **does**, not what was intended. If a refactor changes a class's role, removes a feature, or leaves dead code, update `code-map.md` in the same commit. Never leave a known-wrong entry — a wrong code-map is worse than no code-map.
5.  **Intent-Reality Audit:** After any significant merge or refactor, check whether existing code-map entries, comments, and `design.md` still reflect reality. When they don't, fix them immediately. For a full audit, run the prompt in `review-intent-reality.md`.