Files

T

jpmschweitzerandClaude Opus 4.7 a782511470 carry forward ADRs, Claude Code config, and changelog discipline

Ports the patterns that crystallized during the short-lived claudian
plugin project (discarded in favour of this Flutter rebuild):

- ADRs 0001-0004 capture decisions that survive the host change —
  CLI-first over MCP, Go for the sidecar, pql as a supporter tool
  that becomes a clide-managed subsystem when present, and the
  ignore-file strategy that wires all file-enumerating surfaces
  through one knob in .pql/config.yaml.
- .claude/settings.json and the git-commit and skill-create skills
  come over with naming updated for clide. The git-commit skill's
  "no Conventional Commits" convention supersedes the Python-era
  clide style under legacy/; the Keep-a-Changelog discipline and
  the project.yaml-version-and-changelog-bumped-together rule
  apply going forward.
- CHANGELOG.md starts fresh at the repo root to track the Flutter
  rebuild. The Python changelog is preserved under legacy/.

.gitignore narrows from `.claude/` to just `.claude/settings.local.json`
so project-level config and skills travel with the repo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-20 20:38:49 +02:00

2.3 KiB

Raw Blame History

ADR 0003 — pql as supporter tool; Clide wraps, never duplicates

Status: accepted Date: 2026-04-20 (ported from the claudian lineage)

Context

pql is a pre-existing Go CLI that indexes a markdown-bearing directory tree into SQLite and exposes its semantics (frontmatter, wikilinks, tags, headings, bases) through a query surface. Clide needs those capabilities for its Query panel, canvas drivers, graph view, and any feature that needs to know structure.

Decision

Two complementary rules.

1. Wrap, don't duplicate.

Clide never re-implements backlinks, ranking, frontmatter parsing, or wikilink resolution for query purposes. If a capability is missing in pql, it is added upstream in pql's repo and Clide bumps the dependency.

The only place Clide contains pql logic is sidecar/internal/pql/ — pure shell-outs to the pql binary, no logic beyond invocation and result rendering.

2. pql is a Clide subsystem when Clide is present in the repo.

Broader than "wrap, don't duplicate." When Clide is loaded in a repo, it owns pql's lifecycle and the config keys it cares about. On load, Clide writes its current state into .pql/config.yaml — no conditional sync, no "did anything change" logic.

Clide only stomps the keys it manages (starting with ignore_files: — see ADR 0004). Other pql config keys are left alone so pql's config surface can grow independently.

Clide does not touch pql's index/cache data under <repo>/.pql/ — that stays pql's private store. Only the config file is Clide's to edit.

In repos without Clide, pql works standalone, unaffected. The rule: direct-pql users get vanilla pql; Clide users get pql managed by Clide.

Consequences

One source of truth for markdown semantics (pql).
Clide's sidecar/internal/pql/ package is deliberately thin.
Any new query capability the UI wants goes through a pql upstream PR, not a local workaround.
User never has to learn pql's config file to get consistent behavior — Clide manages it.
The arrow Clide → pql is never inverted: pql stays ignorant of its wrapper, never hardcodes Clide filenames.
pql is also the only query engine. Obsidian-style inline "bases" (YAML query tables embedded in markdown) are explicitly not supported; queries live at the repo level where they belong.

2.3 KiB Raw Blame History