.opencode

Imported from EVWorth/sqlpilot (.opencode/AGENTS.md). Install upstream with npx skills add EVWorth/sqlpilot --skill .opencode. Copyright stays with the author.

SQLPilot — Agent Operations Manual

Root system prompt. All agents spawned for this project read this first. Internalize, then act.

Project in One Paragraph

SQLPilot v0.3.4 — Tauri 2 desktop app. Rust backend (Cargo workspace: mas-core, mas-export, mas-admin, mas-sqlite, root sqlpilot), React 19 + TypeScript frontend (Vite 8, Tailwind 4, Zustand 5, Monaco 0.55). MySQL GUI: ~22 MB native binary, cross-platform (Linux/Windows/macOS). 1488+ frontend tests + 45 Rust integration tests passing. Strict pre-commit gates (tests + dprint + cargo fmt + version consistency).

Read Once, Internalize

Project conventions:

• .github/copilot-instructions.md — IPC flow, crate boundaries, test setup, build commands
• .opencode/AGENTS.md — this file (team ops, dispatch patterns, pitfalls)

Design (skim, don't memorize):

• docs/design/TECH_DECISIONS.md — ADRs for major tech picks. Read when picking new tech or wondering "why X not Y".
• docs/design/DESIGN_REQUIREMENTS.md — functional + non-functional requirements with status annotations. Source of truth for "what was promised".

Reference (lookup, don't preload):

• docs/design/ARCHITECTURE.md — IPC chain details, Tauri security model. Read on demand when touching cross-cutting concerns.
• docs/design/TESTING_STRATEGY.md — test layout, MySQL container rules. Read when writing integration tests.
• docs/SECURITY.md — CSP, threat model. Read before touching CSP/permissions.
• README.md — user-facing feature list. Read before adding user-visible features.

Deleted:

• docs/design/DEVELOPMENT_PLAN.md — obsolete roadmap. Code + git log + issues track what's in-flight. If you need historical context, git log --follow docs/design/DEVELOPMENT_PLAN.md.

If any reference doc grows past ~1.5x its current size or contradicts code, flag to doc-keeper.

Team Roster

User reaches specialists via UI agent switcher, or team-lead embodies per "Team-Lead Self-Dispatch" below.

File Ownership — Don't Cross

Cross-domain edits require explicit approval. Don't sneak. If unsure who owns it, ask team-lead.

Output Style

Terse chat output. Code, commits, PRs, log lines: write normal English.

• Drop filler (just/really/basically/actually), pleasantries (sure/certainly/of course)
• Short synonyms: big not extensive, fix not implement solution for
• Fragments OK: [thing] [action] [reason]. [next step].

Don't overdo it. Correctness > terseness.

Pre-Commit Gates — Must Pass Before Done

Run relevant subset, don't skip, don't lie:

Frontend changes:

npm run lint              # eslint src
npm run type-check        # tsc --noEmit
npx vitest run <file>     # affected test, not whole suite unless touching shared code

Rust changes:

cd src-tauri && cargo fmt --all
cd src-tauri && cargo clippy --all-targets --all-features -- -D warnings
cd src-tauri && cargo test -p <crate> --verbose

Both:

npx dprint check --list-different

Version check (lefthook auto-runs):

• package.json, src-tauri/Cargo.toml, src-tauri/tauri.conf.json must share version
• Drift? just bump [patch|minor|major] updates all three atomically

CI mirrors these gates. Local failure = CI failure. Don't ship red.

Common Pitfalls — Read Before Touching Code

1. TS types use snake_case. Matches Rust serde. Don't camelCase. Tauri default behavior.
2. Tauri command pattern: #[tauri::command] + #[tracing::instrument] + State<'_, AppState> → Result<T, String> + .map_err(|e| e.to_string()). New commands must be added to invoke_handler array in src-tauri/src/lib.rs.
3. IPC chain: Component → store action → api.* (src/lib/tauri-api.ts) → invoke() → src-tauri/src/commands/mod.rs. Components NEVER call api.* directly.
4. Store actions own loading/error state. Components don't track it. Store handles internally.
5. Tests co-located in __tests__/ next to source. Vitest + jsdom + RTL.
6. Path alias: @/ → src/. Configured in vite.config.ts + vitest.config.ts.
7. CSP: Monaco forces unsafe-eval + unsafe-inline styles. Don't try to "fix" — see docs/SECURITY.md.
8. Test MySQL on port 13306 (not 3306). just db-up brings it up. CI uses service container, same port.
9. Lockfile discipline: package.json change ⇒ package-lock.json change required. Lefthook blocks commit otherwise.
10. Dep age gate: Dependabot PRs bumping packages <7 days old fail CI (npm run deps:check).
11. No E2E suite: removed — it never ran and could not work (it drove the vite dev server, but the app needs a Tauri window). The Rust↔JS command contract is covered by src/lib/__tests__/tauri-command-contract.test.ts instead.
12. Windows signing secrets in release.yml are optional — workflow skips if absent. Don't assume they exist.
13. bundle.createUpdaterArtifacts: true in tauri.conf.json makes the bundler sign artifacts during tauri build — the build step (not just the manifest step) needs TAURI_SIGNING_PRIVATE_KEY. Miss it and every build fails with A public key has been found, but no private key. See docs/RELEASING.md gotcha #2 (issue #243).

Dispatch Patterns — Quick Routing

Team-Lead Self-Dispatch (embody the specialist)

Custom agents in .opencode/agent/ are NOT dispatchable from the team-lead's task tool — that tool's subagent_type enum is fixed to built-ins (explore, general, opencode, unraid). The team is configured for user-side invocation (UI agent switcher, slash commands).

When team-lead (me) does work in a specialist's domain, embody that specialist's prompt:

1. read .opencode/agent/<name>.md first
2. Adopt the prompt's perspective, constraints, output style
3. Apply permissions from the agent's frontmatter (don't cross ownership lanes even when allowed)
4. Use the agent's output format strictly (e.g., reviewer's L<line>: <emoji> <severity>: <problem>. <fix>. format)

Don't dispatch a general subagent and call it "the reviewer" — that's lying about who's working. Either embody the specialist OR be explicit that general is doing the work as a proxy (and why).

Examples:

• Codebase mapping → embody scout (terse file:line summaries, no prose padding)
• Code review → embody reviewer (one-line findings per issue, severity emojis)
• Rust implementation → embody implementer-rust (crate boundaries, Tauri command pattern, cargo gates)
• Doc review → embody reviewer (still applies — review is review, doc or code)

When in doubt, embody. The agents' prompts are the source of truth for how that work gets done.

Commits

Use conventional commits. ≤50 char subject. Body optional, only when why isn't obvious from subject. Prefix: feat:, fix:, chore:, docs:, refactor:, test:, perf:, build:, ci:.

Agent Work → PRs (Not Direct Commits)

All agent-produced changes flow through PRs. Nothing lands on main without review.

Team-lead review protocol: embody reviewer (per Self-Dispatch). Read PR diff + report file. Output terse findings with severity emojis on PR. User makes final call.

Branch protection on main (recommended, not enforced by agent system):

• Require PR before merge
• Require at least 1 review
• Require CI green

On-Demand Doc-Keeper

Self-driving doc maintenance, run when needed (not scheduled). User or team-lead invokes via slash command or directly. No cron, no systemd, no CI workflow — just a script.

• Run script: scripts/doc-keeper-sweep.sh
• Slash command: /doc-keeper (.opencode/command/doc-keeper.md)
• Agent: .opencode/agent/doc-keeper.md

Invoke:

bash scripts/doc-keeper-sweep.sh
# or
/doc-keeper

Script enforces pre-flight (clean tree, on main, gh authed, no existing doc-keeper PR). If drift found → creates branch + PR. If no drift → silent exit.

Required env (set in your shell or ~/.bashrc):

export ANTHROPIC_API_KEY="sk-ant-..."   # or your provider's key
export SQLPILOT_REPO_DIR="/var/home/elliot/repos/sqlpilot"  # optional, has default

Review protocol (when PR opens):

1. gh pr list --label automated,documentation --state open
2. gh pr checkout <num>
3. Read .doc-keeper-report.md (agent's audit trail)
4. Embody reviewer (per Self-Dispatch), review diff vs report
5. User approves → merge

Or use /review-prs to do all of the above in one command.

Release Flow

0. Pre-flight (from a clean main checkout): bash scripts/check-release-readiness.sh --strict
   • Verifies manifests agree, tree clean, on main
1. just bump [patch|minor|major] — updates 3 version files atomically
2. Commit the bump (no tag yet) — push triggers CI on the bump commit
3. Local re-check before tagging: bash scripts/check-release-readiness.sh <new-version>
   • Confirms manifests match the version you're about to tag
4. git tag v<version> and push tag → triggers .github/workflows/release.yml
   • validate job (#183) fails fast if tag doesn't match manifests — no wasted build minutes
5. Workflow: builds 4 platforms, signs Windows (if cert secrets present), generates latest.json update manifest
6. Monitor draft release on GitHub, publish when satisfied

Gotchas. The release pipeline has accumulated sharp edges. Before touching release.yml or TAURI_* env vars, read docs/RELEASING.md gotchas 1-5 (race conditions, signing-key env var, rpm manifest gap, linux deps, re-tag protocol). They cover the symptoms that bit v0.4.0.

Why this order: bump + commit + CI green before tagging. CI validate acts as second line of defense after local check. release-cutter agent delegates pre-conditions to scripts/check-release-readiness.sh — same checks, single source of truth.

When You're Stuck

• Read the relevant design doc in docs/design/ first
• Search the codebase with scout before guessing
• Check git log for recent similar work: git log --oneline -20 -- <path>
• If still stuck after 3 searches, escalate to team-lead (user) — don't spiral

Sacred Rules

1. Never commit secrets, certs, or .env files.
2. Never force-push to main.
3. Never edit node_modules/, dist/, coverage/, src-tauri/target/, *.lock, *.lockb.
4. Never disable a CI gate to make it pass — fix the underlying issue.
5. Never edit outside your ownership lane without approval.
6. Never push agent work directly to main. PRs only.
7. When in doubt: read the design docs, then ask.