Context

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 <keywords> 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.

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 <path> 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:

  node scripts/dev-detached.mjs /tmp/ade-dev-<lane>.log \
    npm run dev:desktop -- --socket /tmp/ade-runtime-<lane>.sock
  until grep -q 'dev isolation report' /tmp/ade-dev-<lane>.log; do sleep 2; done
  cat /tmp/ade-dev-<lane>.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:

pgrep -alf "cli.cjs serve|/bin/ade serve"
# then, for each pid:
ps eww -p <pid> | 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 <project>/.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 <home>/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 <project>/.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-<name> 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/<area>/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.