Imported from JCodesMore/starry-ai-bookmark-search (AGENTS.md). Install upstream with npx skills add JCodesMore/starry-ai-bookmark-search. Copyright stays with the author.

Starry — agent operating manual

This file is always in context — keep it lean. It holds only what applies to every task. Detailed, task-specific guidance lives in docs/ and is loaded on demand via the Routing table below. Load a doc only when its task applies; don't pre-load everything.

The project

Starry — an MV3 Chrome extension: free, fully local semantic search over bookmarks. Developed and tested in a dedicated Comet dev browser instance driven over the Chrome DevTools Protocol; no manual clicking in chrome://extensions is ever needed.

• src/ — TypeScript extension source (strict; bundled by esbuild)
• public/ — static extension assets (manifest.json, popup.html) copied into the build
• dist/ — built unpacked extension (gitignored; what the dev browser loads)
• tools/ — zero-dependency Node dev-loop + build scripts (Node 22+, global fetch/WebSocket)
• .dev-profile/ — isolated browser profile for the dev instance (gitignored)
• docs/ — this manual's routed docs, plus architecture, decisions, research, store listing

The dev loop (every task runs through it)

npm run browser   # launch/attach dev Comet with CDP on :9222, ensure dist/ loaded (idempotent)
npm run reload    # BUILD + reload extension; exit 1 + real error if the new code fails to load
npm run smoke     # e2e checks: SW ping, bookmarks API, popup UI search, screenshot
npm run gate      # format:check + lint + typecheck + tests (pre-commit hook runs this)
npm run stop      # cleanly close the dev browser

Standard iteration: edit → npm run reload → npm run smoke → view tools/screenshots/smoke-popup.png. Reload clears Chrome's sticky extension error log first, so reported errors always belong to the current code. Fast file-scoped checks while iterating: npx eslint src/lib/url.ts, npx vitest run src/lib/url.test.ts. The full diagnostic/verification catalog (eval, UI suites, DB inspection, test-bookmark import) is in docs/dev-loop.md — routed below.

Hard rules (this environment)

• Never touch the user's main Comet browser (their profile, their process). The dev instance is fully isolated via --user-data-dir=.dev-profile and is the only thing listening on CDP port 9222. tools/stop.mjs only closes via that port.
• The user's main browser has the Claude-in-Chrome extension connected — never reload/kill that extension; it is the session's browser control channel.
• Extension ID is derived from the unpacked path (currently dist/), so it is stable per machine but CHANGES if the load path moves — never hardcode it; read it from npm run browser output or findExtension() in tools/cdp.mjs.

Prime directives (always apply)

1. Evidence over memory. Verify libraries/APIs/configs/best-practices with context7 + web search + the real installed source before deciding. Never trust training knowledge for load-bearing details — it is outdated, partial, or wrong.
2. Progressive disclosure — load only what you need, when you need it. The recurring discipline for everything (code, planning, docs, memory, skills): keep the always-on surface tiny; pull in detail on demand via documented pointers that say why to load each one. The Routing table below is this principle in action — apply the same shape when you design modules, write docs, brief agents, and build skills/plugins.
3. Beat the context window. Treat context rot and "glossing over big problems" as enemy #1. Break work into small, focused pieces — smaller than your first instinct, split at seams you can verify, so every task ends with a check you can actually run. Push heavy/independent work to subagents. Persist decisions to memory + docs so nothing is lost across compaction.
4. Delegate with full context. Brief every subagent as if it knows nothing: goal, standards, files, exact deliverable, how to verify. Parallelize only where quality won't drop.
5. Verify everything yourself. "It passes" is a claim until you've seen it. Re-run the full gate (format + lint + types + tests) and review correctness-critical logic before every commit. Never trust a subagent's "all green" at face value.
6. Persistent goal & clean resume. Keep the goal in view and self-audit against it. Continuing existing work in a fresh session? Before acting, reconstruct state — recall memory, read .claude/session.local.md (the local done/now/next), skim git log — then keep that breadcrumb current as you work so the next session resumes cleanly (see memory-and-docs.md).
7. No tech debt, by construction. Modular, low-coupled, extensible so any wrong piece can be redone in isolation. Enforce standards in tooling, not vibes.
8. Triage before you act. Scale ceremony to the task. Trivial (a one-sentence diff): just do it. Standard: restate the goal, scope, and done-criteria in one sentence — if your restatement doesn't match the request, ask instead of guessing. Complex / ambiguous / irreversible: the prompt is often a brain dump — synthesize it into explicit goals, assumptions, and open questions, confirm direction, then plan step-by-step before touching code.
9. Disagree openly; never silently override. If evidence says an instruction is mistaken, say so directly with reasoning and a better alternative — accuracy over agreement. Fill small, reversible gaps in the user's intent yourself and say you did; for explicit decisions or anything big/irreversible, propose and get a go-ahead. The user's goal is binding; their stated means is a draft you may challenge.

Non-negotiables (never violate)

• Never commit secrets — commit .env.example only; keep real .env gitignored; never log/echo creds.
• Full gate green (format + lint + types + tests, every language in the repo) before every commit; don't break what already passes. The pre-commit hook runs it — never bypass with --no-verify.
• No magic numbers; files strictly under 1,000 LOC and generally capped at ~500 LOC and functions small where practical; low coupling.
• Never hand-edit generated artifacts (lockfiles, migrations, build output, generated code) — change the source that produces them.

Routing — load a doc ONLY when its task applies

At the start of a task and when entering a new phase, scan this table and Read the rows that apply (when in doubt, load it). These are plain paths — they are not auto-loaded.

Re-read, don't run on memory. On long-running work the standards fade from context as work fills it (context rot — directive #3). So re-read the relevant row when you start a task, enter a phase, or notice yourself drifting or a check failing — re-reading is cheap; a debt-laden codebase is not. And every subagent starts with none of this context: name the exact doc paths it must read in its brief (the standard for its task, plus the architecture/overview doc), never assume it inherited the rules.