--- name: context description: >- Session primer for ADE work: what ADE is, the dev loop, the tooling you can reach (the `ade` CLI control plane, app/browser/iOS-sim control, Linear, computer-use), and what's in flight on this branch. Auto-detects the active feature area from branch changes (or explicit keywords) and loads only the relevant docs + the matching perf skill — never a broad dump. --- # Context Skill Session primer. Run once at the start of a session to learn what ADE is, how we work, the tooling you can reach, and what (if anything) is in flight on this lane. Feature-aware — load only the docs relevant to the work, never a broad dump. **Invocation:** `/context` or `/context ` **Arguments:** optional feature/domain keywords (e.g., `prs`, `lanes rebase`, `tui`). --- ## Step 1 — Determine scope **Args given:** parse the feature/domain keywords; pick the product area; build the doc + perf-skill set from `references/doc-map.md`. **No args:** auto-detect from the lane. ```bash git diff main --name-only # tracked changes vs main git status --short # NEW (untracked) files git diff misses git log main..HEAD --oneline # commits unique to this lane ``` `git diff main` does **not** list untracked files — on a lane whose whole point is new files (a new service, a new skill), the changes are invisible without `git status`. Always fold both in. Then infer the area from the changed paths and resolve docs + the matching `ade-perf-*` skill via `references/doc-map.md`. --- ## Step 2 — Baseline (always read) - `AGENTS.md` — how to run/build/test, working norms, gotchas, the dev loop. - **Run the dev app one way only:** `npm run dev:desktop` from the lane worktree (add `--project-root ` to open a different project). It shares `~/.ade`, starts its brain with `--no-sync`, respects chat runtime ownership, never touches the installed brain service, and prints a dev isolation report first. Never hand-start `ade serve`, never set a fresh `ADE_HOME`, never copy secrets. - **Start it DETACHED, with its own socket.** The command runs in the foreground for as long as the app is open, so running it normally holds your turn open and the window dies with the turn. Background it, give the lane its own socket, and wait for the report: ```bash node scripts/dev-detached.mjs /tmp/ade-dev-.log \ npm run dev:desktop -- --socket /tmp/ade-runtime-.sock until grep -q 'dev isolation report' /tmp/ade-dev-.log; do sleep 2; done cat /tmp/ade-dev-.log ``` The rules that go with it (own socket, stop if the report says `sync : ON`, why a plain `&` is not enough): `docs/development/local-development.md`. - `docs/README.md` — the internal-docs navigation map. - `docs/PRD.md` — what ADE is, who it's for, the feature index. - `docs/ARCHITECTURE.md` — read the **section** relevant to the touched area (IPC, data plane, build/test/deploy), not the whole file. It's large. --- ## Step 2b — Before you start any brain (always check) ADE's brain is a singleton per `ADE_HOME` **by convention only**. Nothing refuses a second one, and two brains on one home share one database: a chat can be owned by only one of them, so the other's agents can be stopped without explanation. Before starting a dev brain, and before blaming anything for dead agents, list every brain **and its home**: ```bash pgrep -alf "cli.cjs serve|/bin/ade serve" # then, for each pid: ps eww -p | tr ' ' '\n' | grep ADE_HOME # no output = the shared ~/.ade ``` Five rules that cost hours when ignored: - **`--no-sync` is not isolation.** It stops a dev brain taking the machine-wide sync lease. It does nothing about a second writer on the same database. - **A different `ADE_HOME` is not isolation either.** The home holds the machine state; each PROJECT keeps its own database in `/.ade/ade.db`. A brain on `~/.ade-alpha` that opens `~/Projects/ADE` writes the same `ade.db` as the installed brain. Any `ade` call run from inside a registered project opens it. Real isolation is a different home AND a throwaway project that no other brain has registered (check `/projects.json`). On 2026-09-22 a "separate" test brain held the main project's `ade.db` open for 12 hours. - **A dev brain outlives its app.** The launcher spawns it detached so it survives Electron restarts. After stopping a dev desktop, confirm its brain actually exited — one ran orphaned on the shared home for five hours. Launcher-spawned brains now exit after 20 idle minutes (`ADE_RUNTIME_IDLE_EXIT_MS`), but do not rely on it instead of checking. - **Starting a brain on a shared home now warns.** It names the other brains by pid and endpoint on stderr and logs `brain.home_shared`. If you see that line, you have two brains on one database — decide which one you meant to have. There is no warning yet for two brains on one PROJECT; check with `lsof /.ade/ade.db`. - **A hand-started brain needs `--role cto`.** `ade serve` defaults to role `agent`, which refuses desktop, phone and web clients. Start it as `ade --role cto serve`. A brain started from an agent's shell drops that agent's chat identity itself and says so on stderr. When you only need to read or drive a lane, prefer an isolated home (`ADE_HOME=$HOME/.ade-` plus `--no-sync` on its own socket) with a throwaway project registered only there, over sharing `~/.ade` or a real project with the installed app. --- ## Step 3 — Feature docs + perf skill Match changed paths / keywords against `references/doc-map.md` and load that doc set only. Each `docs/features//README.md` opens with a **Source file map** and a **gotchas / fragile areas** section — read those first; a flagged invariant usually deserves care (and a test later in `/test`). If the area maps to a performance skill (`ade-perf-boot`, `ade-perf-lanes`, `ade-perf-prs`, `ade-perf-work`, or `ade-tui-web-preview`), open that skill too **before editing** — it records measured patterns you must preserve. ### UI primitives doc If the lane touches renderer UI (`apps/desktop/src/renderer/**/*.tsx`) or the keywords mention UI, banners, toasts, dialogs, modals, popovers, or z-index, also load `docs/design/notices.md`. That doc is the one source for which banner, toast, dialog, or sheet primitive to use, the tones, and `Z_LAYERS`. Never invent a new notice or overlay style. Also load `docs/design/visual-language.md`, the house look (surface kit, settings primitives, scenes, colour rules, the performance budget for always-visible chrome); new UI follows it rather than inventing a panel style. Its `ade-ui/*` lint rules are ratcheted in CI (`npm run lint:ci` in `apps/desktop`). Name the doc in the summary's **Docs** line. ### Windows parity docs Windows parity is a **default requirement** for all new ADE code — Windows is part of "done", not a follow-up. If the lane touches any Windows-sensitive surface in the doc-map's **Windows parity** table (paths, process launch/kill, local IPC, credentials, capability gates, packaging, release), load the mapped Windows docs in this step and name them in the summary: - `WINDOWS_PORT.md` (root) — port status, the readiness table, the original release-blocking findings and how each was closed. - `docs/development/windows-support.md` — installed-host behavior: supervisor, pipe/channel isolation, provider/PTY matrix, uninstall residue. - `docs/development/windows-release-proof.md` — what counts as Windows proof. - `docs/playbooks/windows-signed-release.md` — signing/installer/updater flow. Also open `.agents/skills/quality/references/windows-quirks.md` before editing — it lists the failure classes and the canonical helper for each, so you write Windows-correct code the first time instead of having `/quality` find it. Where parity is genuinely impossible, that is a human decision (hide / disable with a reason shown / remove), not something to work around silently. --- ## Step 4 — Ongoing work (the *why*, not just filenames) ```bash git log main..HEAD --stat # what the lane's commits changed git diff main # committed + uncommitted tracked work git status --short # new/untracked work the diff omits ``` - Read the diff to understand the purpose of the in-flight work. - If a commit or branch name carries a Linear ID (e.g. `ADE-123`), read the issue for intent (`ade linear` — see the `ade-linear` skill). - Cross-check the feature doc's task tracking (`[ ]` / `[x]`). - **No lane commits and no diff → say "Fresh lane — no in-flight work."** Don't invent context. --- ## Step 5 — Summarize Emit this and nothing more (keep it scannable): ```markdown ## Context Loaded **Project:** ADE — local-first desktop env for orchestrating coding agents, lanes, PRs, and proof/artifacts (Electron + React + TS; CLI in `apps/ade-cli`). **Branch:** [name] · [N changed files | fresh lane] **Area:** [feature] — [desktop / cli / tui / ios / cross-cutting] **Docs:** [loaded list] **Perf skill:** [ade-perf-* loaded | none for this area] **Windows:** [Windows docs loaded — parity required for all new code | not a Windows-sensitive surface, parity still required] **In flight:** [what the work does + why, or "Fresh lane — no in-flight work"] **Tracking:** [open N / done N · Linear: IDs or none · gaps if any] **Tools (configured — use them for live state, don't ask):** `ade` CLI control plane · app/browser/iOS-sim/macOS-VM control · Linear (via `ade`) · computer-use + proof drawer. Depth → the matching `ade-*` skill. **Dev loop:** /context → work → /quality → /test → /ship. Utilities: /audit, /finalize, /optimize, /release. Open each skill when you reach it. **Tests:** [commands for this area — see AGENTS.md "Validation"] Ready to assist with [feature]. ``` --- ## Tooling you have ADE ships its capabilities as Agent Skills. State them briefly in the summary; open the relevant one only when a task needs it. - **`ade` CLI** — the control plane for ADE state (lanes, chats, actions, PRs, proof, runtime/socket, project secrets via `ade secrets`). Ground truth is `ade help ` and `ade actions list --text`, not memory. → `ade-cli-control-plane`. - **Lanes & git** → `ade-lanes-git`. **PR workflows** → `ade-pr-workflows`. - **Computer use** (which surface to drive, the lane's private Mac Desktop) → `ade-computer-use` (old name `ade-desktop` still resolves). - **App / browser / Apple-device control** → `ade-app-control`, `ade-browser`, `ade-apple` (old name `ade-ios-simulator` still resolves). Read `ade-apple` before you touch `xcodebuild`, `xcrun` or `simctl` by hand. Running an iOS app on a simulator, seeing a SwiftUI change, driving a screen, or capturing proof of one is `ade apple`, and `ade apple launch` resolves, builds, installs and starts a target in a single call. A screenshot taken with `simctl` and attached afterwards loses the owner that makes it visible in the drawer. - **Linear** (no API key needed; routed through ADE) → `ade-linear`. - **Proof & computer-use** (screenshots, video, traces → proof drawer) → `ade-proof-artifacts`. **Deeplinks** → `ade-deeplinks`. **Worktree note:** ADE runs this session inside a lane worktree (`.ade/worktrees//`). Every edit must target a path under that worktree, never the project-root checkout. --- ## Optional deepening (load only when architecture detail is needed) `docs/ARCHITECTURE.md` covers IPC, the data plane, and build/test/deploy in full — read the specific section when touching `preload/`, `shared/ipc.ts`, `registerIpc`, or a cross-app/service boundary.