Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (72 loc) · 4.52 KB

AGENTS.md

File metadata and controls

82 lines (72 loc) · 4.52 KB

AGENTS.md — Setlist

Working With Mike

Mike is not a coder by trade, but understands the principles. Explain things plainly and clearly without dumbing them down. When making product or architecture choices, be direct about tradeoffs and prefer practical, low-maintenance systems over clever machinery.

Product Direction

Setlist is becoming a local, agent-readable project/workspace intelligence registry that can work across multiple LLM and agent clients. Do not narrow the public product to code repositories only. Code projects should get richer adapters, but non-code workspaces must remain first-class.

Architecture And Coding Guidelines

  • Keep Setlist library-first. Core behavior belongs in @setlist/core; MCP, CLI, and app surfaces should stay thin adapters over shared logic.
  • Avoid monoliths. Prefer small, named modules with clear ownership: detection, install planning, config read/write, backup, safety classification, UI state, and similar boundaries.
  • Keep public contracts explicit. Shared types, tool schemas, config shapes, and install-plan shapes should live in one place and be reused across CLI, MCP, and app surfaces instead of copied.
  • Prefer plan/apply flows for risky operations. Anything that writes external client config, edits project files, runs bootstrap steps, or changes registry state should have a dry-run or preview path first.
  • Preserve user data by default. Never overwrite unmanaged config entries, never casually delete user content, and create backups before writing external client config files.
  • Make behavior easy to inspect. Return structured results with clear statuses such as detected, installed, not_installed, would_write, backed_up, skipped, and error.
  • Keep adapters separate from policy. Client-specific paths and formats belong in client adapters; product decisions like which clients to offer during onboarding belong in orchestration code.
  • DRY the important contracts, not every line. Avoid duplicate schemas, paths, safety tiers, and config-writing logic. Do not create clever abstractions just to remove harmless repetition.
  • Keep tests close to risk. Add focused tests for config preservation, backup behavior, detection rules, dry-run plans, schema outputs, and safety-tier classification.
  • Design for multi-client portability. Do not bake Claude, Codex, or any one host into the core model. Host-specific install logic should be additive adapters.
  • Keep code readable for future agents. Clear names, narrow files, explicit result types, and plain comments at tricky boundaries are more valuable than dense cleverness.
  • Do not let the Electron app become the business-logic owner. The app should display state and trigger core/CLI-equivalent operations, not reimplement registry or install logic in renderer code.

Native Bindings And The MCP Launcher

  • The setlist MCP server runs through scripts/launch-mcp.sh, not node …/mcp/dist/index.js directly. The hoisted better-sqlite3 binary is shared mutable state across four tenants (Claude Desktop MCP, Codex MCP, Electron packages/app dev/build, tests) with no single ABI that satisfies all of them, so the launcher probes the binding before exec and copies the matching cached binary from packages/app/native-cache/ into place when dlopen fails.
  • Never hardcode a node path in an MCP config. The launcher resolves it via SETLIST_MCP_NODE (default: Volta Node 24).
  • On JSON-RPC -32000 from the MCP server, the launcher self-heals on next spawn — restart the host (Codex / Claude Desktop) first. If it still fails, the cache file for the calling node's ABI is missing: run npm run repair:mcp-abi, and/or cd packages/app && npx electron-rebuild -f -w better-sqlite3.
  • Don't touch packages/app/scripts/with-electron-abi.sh or the native-cache/*.node files without understanding the four-tenant contract. The swap protocol and the cache together make the problem solvable; either alone makes it worse.
  • After any work that touches packages/app/** or native deps, run npm run verify:mcp-abi.

Development Notes

  • Inspect the existing code shape before changing architecture.
  • Use rg/rg --files for repo searches.
  • Use apply_patch for manual edits.
  • Keep Setlist and codebase memory fresh. When meaningful project facts, capabilities, workflows, or decisions change, update the Setlist registry and the relevant codebase memory before calling the work complete.
  • Do not revert unrelated work in this repo. Other agents may be active in the same worktree.