quickadd Agent Skills & AI Rules

# Repository Guidelines

## Project Overview
QuickAdd is an Obsidian community plugin that provides four choice types:
templates, captures, macros, and multis.

## Project Structure & Module Organization
QuickAdd is an Obsidian community plugin. Source code lives in `src/`: core logic under `engine/`, `services/`, and `utils/`; Svelte UI in `src/gui`; shared types in `src/types`; settings entry in `src/quickAddSettingsTab.ts`. Bundled artifacts `main.js` and `styles.css` stay at the repo root and should be generated, not hand-edited. Place tests and stubs in `tests/`, and keep user-facing docs in `docs/`.

## Tooling & GitHub
- Use `pnpm` for package management and scripts. Avoid npm/yarn/bun.
- Use the GitHub CLI (`gh`) for issues, PRs, and releases.
- When resolving a GitHub issue, use `gh issue develop <issue-number>` to
  create/link the working branch before implementation.
- GitHub does not allow approving your own PR from the same account; do not
  block merge waiting for self-approval.
- Never merge a `release/*` PR from `quickadd-release-bot`; chhoumann
  squash-merges those himself. After any other merge, the release workflow
  refuses to publish, so `master` advertises a version with no GitHub release.
  Obsidian then fails to install QuickAdd and drops it from Community plugins
  (#1763).

## Build, Test, and Development Commands
- `pnpm run dev`: watch-mode bundle via `esbuild.config.mjs`, regenerating `main.js` as you edit.
- `pnpm run build`: run `tsc --noEmit` then produce the production bundle.
- `pnpm run build-with-lint`: run `pnpm lint`, then produce the production build; use for release packaging.
- `pnpm run lint`: run Oxlint, Svelte template policies, a tsconfig check, and `pnpm run check` in parallel. The first failure stops the others. Never add `--no-bail`, because pnpm 10 then exits 0 when a script fails.
- `pnpm run check`: strict Svelte compiler checks plus native TypeScript checks of every `.ts` and `.svelte` file. It passes when the tsconfig matches no files, which `lint` catches.
- `pnpm run test`: execute Vitest with `--passWithNoTests` for fast local verification.

## Coding Style & Naming Conventions
The project uses tab indentation and LF endings (see `.editorconfig`); align editor settings. Use camelCase for variables and functions, PascalCase for classes and Svelte components, and kebab-case for directories and utilities. Preserve the hand-ordered imports in `src/main.ts`; disable auto-sorting there. Prefer type-only imports and route logging through the `logger` utilities for consistent output.

## Testing Guidelines
Vitest (configured in `vitest.config.mts`) runs in Node and cannot load real Obsidian modules. A test file that needs a DOM or loads Svelte code starts with `// @vitest-environment jsdom`; leave it off otherwise, because jsdom setup is the suite's largest cost. A Node test that loads Svelte code or reads `document` fails with that hint. Structure production code so Obsidian dependencies are injected behind interfaces; unit tests target pure logic and swap in adapters or `tests/obsidian-stub.ts`. Co-locate specs with their source or group them under `tests/feature-name`. Add regression coverage for bug fixes, and ensure `pnpm run test` passes before pushing.

## Commit & Pull Request Guidelines
Follow Conventional Commits (`feat:`, `fix:`, `test:`, ...) so the shared release pipeline can determine versions from history. Keep generated files in the same commit as the changes that produced them. Pull requests must include a concise summary, reproduction steps or screenshots for UI changes, linked issues when relevant, and explicit notes on release or migration impact. Request review from maintainers closest to the touched area.

## Documentation
Docs live in `docs/` (Astro Starlight) and are single-version: pages in `docs/src/content/docs/docs/` serve at `/docs/` on quickadd.obsidian.guide, and edits go live when they land on `master` (deployed by Cloudflare Pages; only pushes touching `docs/` trigger a build, and the Cloudflare check is informational, not required for merge). Every page pins its URL with a `slug:` frontmatter field; keep slugs stable, and add a 301 in `docs/public/_redirects` if one must change.

## Agent Playbook
Automation or scripted work should surface disruptive operations in the PR description and rerun `pnpm run build-with-lint` to keep `main.js`, `manifest.json`, and `versions.json` synchronized. Treat unexpected diffs in those artifacts as blockers until a maintainer approves.

## Obsidian Runtime Workflow
Agents with the `verify-in-obsidian` skill get the generic workflow there:
vault-mode choice, the runner script quartet, `--print-env`, instance
teardown, and the dev-tools loop. This section is the QuickAdd-specific
brief that a skill-less agent still needs.

- Plugin id `quickadd`; the runner's ready probe is `quickadd:list`. Run a
  choice with `pnpm run obsidian:e2e -- quickadd:run choice=<name>` - note that
  `ok:true` means the run finished, not that it did what you wanted. Drive
  anything else through `pnpm run obsidian:e2e -- eval code=<javascript>`;
  top-level `await` is not allowed there, so wrap async work in an IIFE the
  eval can await.
- The four runner scripts - `provision:e2e-vault`, `start:e2e-obsidian`,
  `stop:e2e-obsidian`, `obsidian:e2e` - run the shared `obsidian-e2e` bin,
  configured by `obsidian-e2e.config.mjs` at the repo root (plugin id, the
  symlinked artifacts, the `data.json` seed, and the `quickadd:list` ready
  probe).
- Worktrees use the isolated vault (`.obsidian-e2e-vaults/quickadd-<worktree>`)
  and must not race the shared `dev` vault. The main
  `/Users/christian/Developer/quickadd` checkout uses the shared `dev` vault
  (root `/Users/christian/Developer/dev_vault/dev`, plugin folder
  `.obsidian/plugins/quickadd` symlinked to this checkout's `main.js`); only one
  checkout can own those symlinks at a time. Run `pnpm run dev` to rebuild.
- Always pass the `vault=` selector as a **prefix** argument, never a suffix -
  suffix form can resolve to the wrong vault.
- `pnpm run obsidian:e2e -- <cmd>` attaches to a running instance without
  reloading QuickAdd, so plugin state, open modals and settings tabs, and a
  plugin you disabled all persist between separate commands. After a rebuild,
  load the new `main.js` with `pnpm run obsidian:e2e -- --reload <cmd>` (or
  `start:e2e-obsidian`, which always reloads and verifies). If no instance is
  running, `obsidian:e2e` launches one first.
- Specs that need Templater run only with `OBSIDIAN_E2E_TEMPLATER=1
  .agents/run-e2e`, which installs a pinned Templater into the isolated vault.
  A change that touches a Templater path must also pass that run: CI runs no
  native specs, so a Templater expectation can otherwise go stale unnoticed.
- Toggle desktop mobile emulation with `pnpm run obsidian:e2e -- dev:mobile on`
  (or `off`). The command returns only after the reloaded app reports the new
  mode, so the next command can run straight away with no sleep. The switch
  reloads the whole app, so reopen any UI afterwards.

```bash
pnpm run dev                                # or: pnpm run build
pnpm run obsidian:e2e -- --reload quickadd:list   # load the rebuilt main.js
pnpm run obsidian:e2e -- quickadd:list
pnpm run obsidian:e2e -- eval code='Boolean(app.plugins.plugins.quickadd)'
pnpm run obsidian:e2e -- dev:errors

# point the Vitest tests/e2e suite at the isolated instance:
eval "$(pnpm run --silent start:e2e-obsidian -- --print-env)"
pnpm run test:e2e

pnpm run stop:e2e-obsidian                  # stop this worktree's instance on wrap-up
```

The runner emits canonical `OBSIDIAN_E2E_*` env names, plus legacy
`QUICKADD_E2E_*` aliases during the migration (`tests/e2e/e2eVault.ts` reads
canonical first). `dev:console`/`dev:errors` are most reliable while debugger
capture is attached (`pnpm run obsidian:e2e -- dev:debug on`, which stays on this
worktree's isolated instance); for non-trivial `eval`,
pass code via `code=...` from a heredoc/file to avoid shell-quoting corruption.

## Evidence-First Bug Triage
- Default bug workflow: reproduce in Obsidian first, then implement fix, then
  verify in Obsidian again, then add/adjust unit tests for regression coverage.
- Do not assume a reported bug still exists. Issues may already be fixed by
  unrelated changes; confirm current behavior before changing code.
- For reproduction, prefer real user conditions over synthetic tests
  (hotkeys, choice settings, workspace/tab layout, and platform specifics).
- When debugging command-triggered behavior, test both paths:
  hotkey execution and direct command execution (`obsidian command ...`).
- Record evidence from `tabs`, `workspace`, `dev:console`, and `dev:errors`
  before and after the action being tested.
- For pane/tab diagnostics, treat `workspace ... ids` as authoritative layout
  evidence and use `tabs` as a quick summary.
- If not reproducible after solid evidence gathering, respond with exact tested
  setup and ask for a fresh issue with versions, config, and repro artifacts.

## CLI-Verifiable Development
- Verifiability is required: work is not complete until behavior can be checked
  through the Obsidian CLI in the `dev` vault.
- If a flow is UI-only (for example forms/modals), add a CLI-native verification
  seam first (command/API entrypoint, inspectable state, and deterministic logs).
- Prefer verification paths that can run both manually and scripted:
  command execution, `eval`, `dev:console`, `dev:errors`, `tabs`, and
  `workspace`.
- Add or update automated tests around the new seam so regressions are caught
  without depending on manual modal interaction.