AGENTS.md

This repo dogfoods the packaged minimap app. Minimap exposes two capabilities, each shipped as a self-contained skill with its own bundled runtime and lifecycle scripts:

• For roadmap planning, roadmap file updates, and pickup, resume, investigation, testing, or completion of assigned roadmap work in this repo, follow package/minimap/skills/minimap-roadmap/SKILL.md. Treat the roadmap files as canonical and keep behavior aligned with the minimap roadmap contract in package/minimap/CONTRACT.md.
• For spec/design review on a specific file, follow package/minimap/skills/minimap-spec-review/SKILL.md. The skill works from any repo.

Server lifecycle — use the packaged scripts only

All server interaction goes through scripts in <skill>/scripts/:

• start-server.cjs — start (or detect + reuse a running instance)
• status.mjs — print status; exit 0 running, 1 stale, 3 not running
• stop-server.mjs — graceful shutdown via POST /api/shutdown; cleans stale registry
• restart-server.mjs — compose stop + start

When a user service is installed, these scripts manage its stable runtime. Restart does not deploy checkout or skill changes: run node <new-skill>/scripts/service.mjs update explicitly to deploy that skill's bundled runtime. Copying a skill refreshes its files, including its bundled runtime, without deploying them to the service. Refresh older skill copies before using managed lifecycle commands; they may reuse a compatible healthy service but do not understand service ownership. Service installation/update requires explicit environment-change approval; follow the migration guide.

The canonical start-server.cjs bootstrap defaults UV_THREADPOOL_SIZE to 8 only when absent, before importing the existing launcher in the same process. Restart applies the same default to its new child. Explicit overrides are retained; reused servers are unchanged. The legacy start-server.mjs entrypoint remains supported without this bootstrap default.

Do not curl the server directly, send signals to it (process.kill, taskkill), poke $MINIMAP_HOME/server.json by hand, or invoke node package/minimap/server.js directly. The scripts handle every state (running, stale registry, port busy, race with another launcher) and stay correct on Windows where signal-based stop is unreliable.

A single running server transparently serves both modes for any number of repos. The launchers detect an already-running instance via $MINIMAP_HOME/server.json + /health and reuse it.

Tri-tree sync

Top-level package/minimap/ is the source of truth. After any change to server, CLI, API, UI, or scripts, run:

node scripts/sync-mirrors.mjs

It rewrites both runtime trees (package/minimap/skills/minimap-roadmap/runtime/ and package/minimap/skills/minimap-spec-review/runtime/) from the top-level files. The unit test test/sync-mirrors.test.js runs the script and re-verifies byte-identity in CI; test/roadmap.test.js's portability test additionally guards against any runtime/ tree introducing install-time dependencies (skills install via copy, never npm install).

Do not hand-edit files under package/minimap/skills/*/runtime/ — they are derived. Edit the top-level copy and run the sync script.

Skill-doc drift check — after every behavior change

Behavior changes ship in code + tests, but the prose docs under package/minimap/skills/*/SKILL.md and package/minimap/skills/*/references/*.md describe that same behavior to agents. Tri-tree sync only handles runtime/ byte-identity; skill docs are not auto-synced and silently rot. Caught real drift twice in one session: the apply-cascade was widened from exact-quote to range-overlap (commit e0456c6) but references/http.md still claimed exact-quote; --json-stdin made the CLI multi-line-capable but references/http.md still framed CLI as "single-line text only."

Before declaring a behavior change done, grep the skill docs for the OLD behavior's keywords:

# After changing the cascade, anchor logic, status semantics, etc.:
grep -rn "<old-behavior-phrase>" package/minimap/skills/*/SKILL.md package/minimap/skills/*/references/

# Sanity sweeps that catch most drift:
grep -rn "exact quote\|same quote\|same old quote" package/minimap/skills/
grep -rn "single-line\|short.*--text\|--text-file\|--quote-file" package/minimap/skills/

If the grep finds anything, fix it in the same change set as the behavior. The drift is invisible until a future agent reads the doc and follows the wrong rule, which makes it the kind of bug that survives review (the doc lives in a different file than the code) but stings every agent reading the contract.

This applies to changes in: anchor cascades, comment/suggestion shapes, CLI flag semantics, HTTP route bodies/responses, error codes, server lifecycle. It does NOT apply to UI-only changes that don't reach the documented surface (DOM rendering, layout, etc.).

Frontend module map

ui/index.html loads app.js as a native ES module. App.js imports leaf modules directly; the static server serves whatever path the import asks for, so no bundler.

DOM-touching modules are exercised end-to-end via Playwright (playwright/roadmap-ui.spec.js). Pure-logic modules have node --test units that run in milliseconds.

Backend module map

UI conventions

• Every void api.foo(...) call MUST be followed by .catch(...). Wrappers like persistGroupOrder / loadWorkspace / saveCurrentItem already do try { await api.foo() } catch (e) { setBanner(e.message, "error") } internally, so void persistGroupOrder() is fine — the wrapper has the catch. The lint test test/ui-lint-promises.test.js enforces this for bare api.* call sites.
• Spec subsystem extension: add new render functions to ui/spec/render.js and new composer/form functions to ui/spec/composer.js. Use the captured DOM, STATE, API, HELPERS bindings rather than re-querying. New DOM elements need an entry in the dom: {...} object passed to initSpec in app.js.

agent-workflow

This repository uses agent-workflow with agent-redline risk classification.

Start: invoke /agent-workflow or the runtime's native command. If unavailable, read .claude/skills/agent-workflow/SKILL.md or .agents/skills/agent-workflow/SKILL.md.

Plan mode: for every non-exempt task, the plan's first implementation step must be "Invoke the /agent-workflow skill to create the Work Record and classify risk, before any code edit." Do that first on approval. The hook checks plans that touch configured hooks.guardedPaths (default src/) as supplemental enforcement; it is a nudge, not the applicability decision or CI gate.

Local check before pushing: POSIX: bash scripts/agent-workflow-runtime.sh codex check --repo-root . --slug <slug>. PowerShell: & scripts/agent-workflow-runtime.ps1 codex check --repo-root . --slug <slug>.

The adapter tries PYTHON, .venv, then platform fallbacks. Missing prerequisites block with guidance. Exit codes: 0 clean, 1 advisory, 2 blocking. CI posts it.

Native mutation coverage is version/surface/tool-specific: verified requires a denied operation with unchanged target; installation, trust, or a direct evaluator pass is insufficient. Record every other combination as degraded. Shell mutations bypass the guard; CI validates final artifacts/applicability, not pre-edit ordering or direct pushes. Evaluator failure returns deny; native prevention requires that evidence.