Skip to content

Latest commit

 

History

History
40 lines (32 loc) · 6.09 KB

AGENTS.md

File metadata and controls

40 lines (32 loc) · 6.09 KB

Plannotator agent guidance

Plannotator is a plan review UI for Claude Code that intercepts ExitPlanMode via hooks, letting users approve or request changes with annotated feedback. It also provides code review for git diffs and annotation of arbitrary Markdown files.

This file is a map. The full guidance lives in focused guides under docs/agent-guides/. Read the hard rules below, then the guide for the code or behavior you are changing. CLAUDE.md is a symlink to this file; packages/ui/AGENTS.md adds guidance scoped to packages/ui/.

Hard rules (read before touching anything)

  • Never compromise UX. Plannotator is an open-source product that has to work well and feel like magic; it is not an enterprise critical system. Don't add friction for defensive reasons: no extra gates, confirmations, owner-only checks, warnings or settings that make it harder to use. Fix real bugs without making the product worse to use, and when a safety idea would cost UX, ask the owner first.
  • One experience across a person's devices. Every Inbox feature works the same on a thread, agent or project that lives on another of the person's linked machines as on this one: tagging, Priority, pins, starting agents, replying, anything. Never ship a feature that works only on this machine's own threads, and never add a rule that treats a linked machine's thread differently. Send the action to the machine that owns the thing; if an older or offline machine cannot take it yet, that is the one allowed gap and it closes when that machine updates. Build and test both ways (two linked Inboxes) before calling a feature done. See Linked machines.
  • Reusing the document UI in the commercial Workspaces app? Read packages/ui/README.md FIRST: an earlier from-scratch rebuild of this UI broke the app and was reverted. Do not rebuild the UI or recreate packages/document-ui; add a seam to @plannotator/ui (configurePlannotatorUI()), keep Plannotator's app unchanged, and never delete working code until a human confirms parity in the browser.
  • Two server runtimes change together. An endpoint change goes into both the Bun server (packages/server/) and the Pi server (apps/pi-extension/server/); shared logic lives in packages/shared/. Only the Inbox and the Shapes server are Bun-only. See Server Runtimes.
  • Build order: review, then hook, then opencode. bun run --cwd apps/review build && bun run build:hook && bun run build:opencode; building out of order copies stale HTML. See Build.
  • Tailwind @source. A new directory with .tsx files that use Tailwind classes needs a matching @source entry in the app's index.css.
  • Testing Rules (full list in Testing Rules):
    • Tests and dev scripts never touch the real ~/.plannotator, the real Inbox or user config: sandbox under a temp PLANNOTATOR_DATA_DIR, and mutate globals only inside tests with a restore.
    • Tests never open a browser: set NO_BROWSER from tests/helpers/no-browser.ts, never PLANNOTATOR_BROWSER=none (or another sentinel).
    • Tests never run the real GitHub CLI, and never signal an Inbox except through tests/helpers/inbox-process.ts.
    • Every test guards a behavior that can regress: no copy snapshots of prose, no round-trip prop tests, no implementation echo.
    • Test agent-facing instructions (tool text, skills, --help) clean room: a fresh agent with only that text, in a scratch folder outside this repo, given a real task. Judge what it does, not what it says.
  • No new Inbox keyboard shortcuts without the owner's approval (see the Inbox shortcuts note in Keyboard Shortcuts). Shortcuts elsewhere go through the shortcut registry.
  • Git: never rebase or force-push a shared branch; merge main instead.
  • Releases: follow .agents/skills/release/SKILL.md.

Topic guides

  • project-and-development.md: repository map, server runtimes, installation, development, Testing Rules, build, marketing site.
  • environment.md: every environment variable and config-only setting.
  • plan-review.md: plan review flow, Guides in VS Code, Pi plan review and the Pi plannotator tool.
  • claude-code-mod.md: the Claude Code hooks module (non-blocking flows, the plannotator tool, its Ask this session client and Inbox wake, version skew).
  • opencode-t3-and-codex.md: OpenCode 2 tool, T3 Code, Codex Stop hook.
  • code-review.md: code review flow and UI, Ask AI provider defaults, "Ask this session" (the session bridge and pull bridge).
  • annotate.md: annotate flow, bundles, drafts, strict gates, live app annotation.
  • inbox.md: index to the Plannotator Inbox guides (inbox-*.md).
  • server-and-storage.md: archive, Server API tables and guards, plan history, feedback archive, plan diff.
  • guides-and-shared-ui.md: portable Guided Reviews, data types, parser, annotation system, question blocks, WebMCP, shortcuts, sharing, settings, syntax highlighting.

Where new docs go

Keep this file a map: add no feature detail here. Put a new section in the guide for its area (the list above): an env var in environment.md, an endpoint in the matching Server API table in server-and-storage.md, Inbox behavior in the matching inbox-*.md (and a line in inbox.md for a new Inbox guide), a shared UI or format change in guides-and-shared-ui.md. A new guide gets one line in the list above. tests/agents-md-size.test.ts fails when this file grows past its budget or links to a guide that does not exist.