Project Documentation

Maintain navigation files so that ANY new AI session can orient itself instantly without exploring the codebase.

<HARD-GATE> After every milestone, structural change, or file creation/deletion: UPDATE these docs. A project without current PROJECT.md, MAP.md, SESSION.md, and LESSONS_LEARNED.md is a project where every AI session wastes tokens re-exploring. </HARD-GATE>

Navigation Files

1. PROJECT.md — Identity & Operations

What this project IS and how to OPERATE it. Stable — changes rarely.

# <Project Name>

## Purpose
One paragraph. What does this project do and why does it exist?

## Tech Stack
- Language: X
- Framework: Y
- Test runner: Z
- Package manager: W

## Directories
- Specs: `docs/specs/`
- Plans: `docs/plans/`
(Override if your project uses different directories)

## Commands
- Test: `<project test command>`
- Lint: `<project lint command>`
- Build: `<project build command>`
- Typecheck: (if applicable)
- Format check: (if applicable)

## Architecture (one paragraph)
How the system works at the highest level. Data flow, key processes,
entry points. Enough to understand the "shape" of the project.

## Key Decisions
- Decision 1: Why X instead of Y (concrete reason)
- Decision 2: Why this pattern (concrete reason)

## Custom Skills (optional)

<!-- Register project-specific skills here. The agent reads this alongside the built-in manifest.
| Skill | Path | Trigger |
|-------|------|---------|
| `deploy` | `skills/deploy/SKILL.md` | Before any deployment |
-->

Update when: Tech stack changes, new commands added, architecture shifts, key decisions made.

2. MAP.md — Navigational Index

Every significant file and directory with its purpose. One line per entry. Skip trivial, generated, or obvious artifacts (dependency directories, .git, etc.).

# Project Map

## Root
- `PROJECT.md` — project identity and commands
- `MAP.md` — this file, project navigation
- `SESSION.md` — current work state, what's next
- `GATES.md` — mandatory pre/post-task rules (user-editable)
- `HOOKS.md` — lifecycle hook definitions (user-editable)

## src/
- `src/main` — application entry point, server setup
- `src/auth/login` — login flow: validate credentials, issue token
- `src/auth/middleware` — extract and verify token from Authorization header

Rules:

• One line per entry — enough to navigate, not to replace reading the file
• Descriptions are functional: "what it does", not "a file"
• No stale entries — deleted file = removed line
• New file = new line immediately

Anti-patterns:

Bad	Good
src/utils — utility functions	src/utils — date formatting and string sanitization helpers
src/api/ — API code	src/api/ — REST endpoints, one file per resource

Update when: Any file added, deleted, renamed, or moved.

3. SESSION.md — Routing Table

A tiny pointer file (~50-100 tokens) that tells the AI where to pick up. NOT a progress log — progress lives in plan files.

# Session State

Updated: YYYY-MM-DD

## Active

<!-- Entry format:
- **[Task name]**: [one-line status]
  - Plan: `docs/plans/<plan-file>.md`
  - Branch: `<type>/<branch-name>`
  - Resume: [what to do next — specific enough to pick up cold]
-->
- **Auth system**: implementing middleware (Task 6/12)
  - Plan: `docs/plans/auth-system.md`
  - Branch: `feat/auth-system`
  - Resume: write JWT verification middleware in `src/auth/middleware.ts`, then run tests

## Paused

- **API refactor**: awaiting user input on versioning strategy
  - Plan: `docs/plans/api-refactor.md`
  - Branch: `refactor/api-cleanup`
  - Resume: Task 3/8 — resume after user confirms `/v2` vs header-based versioning

## Completed
- `docs/plans/user-model.md` — all 5 tasks done

Rules:

• Update when starting/completing/pausing a plan
• Keep it tiny — one line per plan, just enough to route
• Progress details live in the plan file's Resume section, not here
• Never scan all plan files at session start — read SESSION.md first, then read only the active plan
• Only one plan may be Active at a time. If multiple plans exist, others must be Paused. If the user requests work on a different plan, pause the current one first.

Status authority: SESSION.md is the authority for which plan is active. Plan frontmatter status tracks the plan's internal state (pending/in_progress/done/blocked). Update BOTH when status changes. If they disagree, SESSION.md wins.

Resume flow for a new session:

1. Read SESSION.md (~50 tokens)
2. Read the ONE active plan file
3. Read plan's Resume section → know exactly where to pick up
4. Read PROJECT.md only if commands/architecture needed
5. Read MAP.md only for files mentioned by the current task

Update when: Plan started, completed, paused, or blocked.

4. LESSONS_LEARNED.md — Mistake Prevention

Records mistakes, wrong approaches, and their corrections. Mandatory reading at session start — prevents repeating errors across sessions.

Each entry follows: Wrong (what failed), Right (what works), Why (explanation).

Update when: You discover a wrong approach, a command that doesn't work, or an assumption that was incorrect. This is a post-task gate obligation — check if any mistakes were made during the task.

Pruning: When entries exceed 20 or the file exceeds 3000 characters, archive older entries under a ## Archived heading at the bottom. Keep only entries from the last 5 sessions or those still relevant to the current project state.

Not a navigation file — LESSONS_LEARNED.md is a companion file maintained alongside the navigation triad. It's created during Project Initialization and read during pre-task gates.

When to Update What

Event	PROJECT.md	MAP.md	SESSION.md	Plan file	LESSONS_LEARNED.md
Session starts	—	—	Read it	Read active plan	Read it
Step completed	—	—	—	Yes Mark [x]	—
Task completed	—	—	—	Yes Update Resume	Yes If mistakes found
New file created	—	Yes Add line	—	—	—
File deleted	—	Yes Remove line	—	—	—
Architecture changes	Yes	—	—	—	—
Plan started	—	—	Yes Add to Active	Yes status: in_progress	—
Plan completed	—	—	Yes Move to Completed	Yes status: done	—
Session ends	—	—	Yes Verify pointer	—	—
Milestone completed	Review	Review	—	Yes Update Resume	—
New command added	Yes	—	—	—	—
Wrong approach found	—	—	—	—	Yes Add entry

Why Separate Files

Token efficiency. A single large doc forces the AI to read everything. Focused docs let it:

• Read PROJECT.md once per session (stable)
• Scan MAP.md when looking for files (structural)
• Read SESSION.md to resume work (volatile)
• Read LESSONS_LEARNED.md to avoid known mistakes

Total: ~300-500 tokens to fully orient. Without these: 20-50 tool calls × 100+ tokens each = 2000-5000 wasted tokens.

Transitions

This skill runs alongside every other skill — it's not a phase, it's a maintenance obligation. Update docs as you work, not as a separate step.

Red Flags

Thought	Reality
"I'll update docs at the end"	Update as you go. Forgetting is the default.
"The file change is too small to update MAP.md"	If a file was added, renamed, or deleted, MAP.md needs updating.
"SESSION.md can stay as-is"	If the active plan changed, SESSION.md must reflect it.
"PROJECT.md doesn't need the new command"	If you ran a new build/test/lint command, add it.