session

# Session Work spans many sessions and many AI vendors. Continuity is a discipline, not an accident. State lives in files, not in memory; the backlog has one source of truth; the mirror is one-way. ## Start of every session 1. Read `.agents/SESSION-HANDOFF.md` **before making any implementation decision**. 2. Re-assert the handoff's **Constraint Lock** before coding. 3. If the handoff conflicts with a skill, the `architecture` skill, or the canonical laws, **stop and ask** — never resolve silently (conflict priority: `Autocss-com/ai` AGENTS.md > repo AGENTS.md > `SESSION-HANDOFF.md`). Skipping handoff review "to save time" is prohibited — it is the single largest cause of lost context and repeated mistakes. ## Single source of truth for outstanding work `PROGRESS.json` (its `meta.future_goals` + `cursor.open_q`) is the **one** authoritative list of outstanding work. Keep structured state as data in `PROGRESS.json`; keep principles/rationale as concise prose in the skills/docs (JSON usually costs more tokens for prose). Nothing competes with `PROGRESS.json`. Chat memory, scratch notes, and the issue tracker are all downstream of it. ## The GitHub mirror is one-way GitHub **Issues** + the **Projects board** are a human-visible **mirror** of the backlog, never a competing tracker: - Open an Issue for each new backlog / open-question item; **close** it when done. - Title mirrors the item; body carries detail + a pointer to the `PROGRESS.json` / prompt entry; apply the `backlog` label. - **Board columns are label-driven and status labels are mutually exclusive — never stack them.** Backlog column = `backlog` label only; In Progress = `in-progress` only (you must remove `backlog` when moving to In Progress); Done = the Issue **closed** (no status label). To move a card, **swap** the status label, never add a second. Grouping tags (e.g. `demo`) are orthogonal — keep them. - Issues are effectively append-only (GitHub closes, never deletes) — create deliberately, avoid duplicates. - If the board/toolset is unavailable in a session, **skip silently** — `PROGRESS.json` stays authoritative and the mirror catches up later. ## End of every session (the ritual) Commit → update `PROGRESS.json` → append a session shard → update `SESSION-HANDOFF.md` → reconcile the GitHub mirror. Then write the **next-phase prompt**: a super-detailed brief for what the next session must do, holding all three contexts (immediate task, overall project intent, next-phase needs) so no context is dropped. ## Documentation maintenance (periodic, cost-driven) Periodically optimize the docs **for AI accessibility/usability, not human reading**, to cut token cost — without dropping any detail, intention, plan, or context. Reduce redundancy; restate more concisely; prefer a short whitelist ("only X permitted; all else forbidden") over long blacklists when clearer for AI processing. Never duplicate a rule already stated — strengthen the existing wording instead (see the DRY principle). ## Standards consultation Consult the standing references — `modern-web-guidance` and MDN Web Docs (search / doc / compat) — and periodically reconcile them against the app's current features. Their content is **advisory and subordinate**: on any conflict, the AutoCSS rules win. But the requirement to consult, to reconcile, and to *suggest* improvements is canonical. Identify ≠ apply — never silently change anything; confirm with the user first. ## What session-handling never does - Never starts implementing before reading `SESSION-HANDOFF.md` - Never treats chat memory or the issue tracker as the backlog source — `PROGRESS.json` is - Never stacks `backlog` + `in-progress` labels, or invents new status labels - Never resolves a documented-rule conflict silently — surface it to the user - Never ends a working session without updating state + writing the next-phase prompt ## Baseline & support _Checked against MDN as of 2026-07-16._ - No version-sensitive web-platform features are referenced here — everything used is **Baseline Widely available**. **Canonical rules:** https://github.com/Autocss-com/ai/blob/main/AGENTS.md ## Reference - AutoCSS Architecture + Response Integrity Charter (canonical): https://github.com/Autocss-com/ai/blob/main/AGENTS.md - Agent Skills open standard: https://agentskills.io - GitHub Projects (board automation): https://docs.github.com/issues/planning-and-tracking-with-projects