install pql skill and add pql permissions

pql init --with-skill=yes installs .claude/skills/pql/SKILL.md covering vault queries and the planning surface (decisions + tickets). Lock file tracks version + SHA-256 for drift detection. Bash(pql) and Bash(pql *) added to .claude/settings.json so pql commands run without permission prompts. Co-Authored-By: Claude <noreply@anthropic.com>
2026-04-22 13:39:11 +02:00
parent 6bce2621b7
commit 7164ec11d6
3 changed files with 186 additions and 1 deletions
@@ -5,7 +5,9 @@
      "Bash(git commit *)",
      "Bash(dart *)",
      "Bash(flutter *)",
-      "Bash(make *)"
+      "Bash(make *)",
+      "Bash(pql)",
+      "Bash(pql *)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
@@ -0,0 +1,5 @@
+{
+  "version": "1.0.0",
+  "hash": "sha256:98d7fa693fa4bcb6ccd6eb1d9d191c8f7332c9c97c221afb19741a7711bd9928",
+  "installed_at": "2026-04-22T11:22:39Z"
+}
@@ -0,0 +1,178 @@
+---
+name: pql
+description: >
+  Query and plan against a markdown vault via the pql CLI. Two surfaces:
+  (1) structural queries — frontmatter, wikilinks, tags, headings, Bases,
+  DSL — use when the user asks about vault contents ("which notes…", "find
+  where…", "what tags", "who links to X", "run a Base", "query the vault");
+  (2) planning — decision records, tickets, project status — use when the
+  user asks about decisions, tickets, work items, or project planning
+  ("sync decisions", "create a ticket", "what's the plan status", "show
+  D-005", "board"). Requires `pql` on PATH. JSON on stdout; exit 2 = zero
+  matches (not an error).
+---
+
+# pql — vault queries + project planning
+
+`pql` indexes a vault into SQLite and exposes structural queries plus a
+planning layer for decision records and tickets. One binary, two surfaces.
+
+## Precondition
+
+```bash
+command -v pql
+```
+
+If absent, tell the user to install from
+https://github.com/postmeridiem/pql/releases/latest. Don't install it
+yourself. Don't fall back to grep unless the user explicitly asks.
+
+## First touch: learn the vault
+
+```bash
+pql schema
+```
+
+Returns one row per frontmatter key with observed types and file counts.
+Run once per session before writing queries.
+
+---
+
+## Surface 1: Vault queries
+
+### Subcommands
+
+| Command | Purpose |
+|---|---|
+| `pql files [glob]` | List indexed files; optional glob filter |
+| `pql tags [--sort count]` | Distinct tags with counts |
+| `pql backlinks <path>` | Files linking TO a path |
+| `pql outlinks <path>` | Links FROM a file |
+| `pql meta <path>` | Frontmatter + tags + outlinks + headings for one file |
+| `pql schema` | Typed frontmatter schema |
+| `pql base <name>` | Execute an Obsidian .base file |
+| `pql shell` | Interactive REPL (indexes once, then query per line) |
+| `pql query "<DSL>"` | SQL-derived DSL for complex queries |
+| `pql doctor` | Resolved vault/config/DB/index state |
+
+### DSL examples
+
+```sql
+SELECT name, fm.date WHERE fm.type = 'meeting' ORDER BY fm.date DESC LIMIT 10
+SELECT path WHERE 'project' IN tags ORDER BY path
+SELECT name, fm.prior_job WHERE fm.type = 'council-member' ORDER BY name
+```
+
+Use `--file q.pql` or `--stdin` for long queries. Don't interpolate vault
+content into the command line.
+
+### Query cookbook
+
+- **Files in folder** → `pql files 'sessions/*'`
+- **Top tags** → `pql tags --sort count --limit 20`
+- **What links to X?** → `pql backlinks members/vaasa/persona.md`
+- **Date range** → `pql query "SELECT name, fm.date WHERE fm.date BETWEEN '2024-01-01' AND '2024-12-31'"`
+- **Run a Base** → `pql base council-sessions`
+- **Inspect one file** → `pql meta members/vaasa/persona.md --pretty`
+
+---
+
+## Surface 2: Planning (decisions + tickets)
+
+Planning state lives in `<vault>/.pql/pql.db` (user-authored state, not a
+cache). Decision records come from `decisions/*.md`; tickets are
+SQLite-native.
+
+### Decision subcommands
+
+| Command | Purpose |
+|---|---|
+| `pql decisions sync` | Parse decisions/*.md → upsert into pql.db |
+| `pql decisions validate` | Dry-run parse; exits non-zero on malformed records |
+| `pql decisions claim <D\|Q\|R> <domain> "title"` | Print next available ID |
+| `pql decisions list [--type X] [--domain X] [--status X]` | List decisions |
+| `pql decisions show <id> [--with-refs] [--with-tickets]` | Show with joins |
+| `pql decisions coverage` | Confirmed decisions without tickets |
+| `pql decisions refs <id>` | Cross-references involving a decision |
+
+Always `pql decisions sync` before querying if decisions/*.md may have changed.
+
+### Ticket subcommands
+
+| Command | Purpose |
+|---|---|
+| `pql ticket new <type> "title" [--decision D-NNN] [--priority P]` | Create (emits T-NNN) |
+| `pql ticket list [--status S] [--team T] [--assigned A] [--label L]` | List with filters |
+| `pql ticket show <id> [--with-decision] [--with-blockers] [--with-children]` | Show with joins |
+| `pql ticket status <id> <new-status>` | Transition (enforces state machine) |
+| `pql ticket assign <id> <agent>` | Set assignee |
+| `pql ticket block <id> --by <other>` | Add blocker |
+| `pql ticket unblock <id> --from <other>` | Remove blocker |
+| `pql ticket team <id> <team>` | Set team |
+| `pql ticket label <id> add\|rm <label>` | Manage labels |
+| `pql ticket board [--team T]` | Kanban board view |
+
+Ticket types: initiative, epic, story, task, bug.
+Status flow: backlog → ready → in_progress → review → done (also cancelled).
+
+### Plan subcommands
+
+| Command | Purpose |
+|---|---|
+| `pql plan status` | Dashboard: decision counts, open Qs, ticket summary, coverage gaps |
+
+### Planning cookbook
+
+- **Sync and list confirmed** → `pql decisions sync && pql decisions list --type confirmed`
+- **Show with refs** → `pql decisions show D-005 --with-refs --pretty`
+- **Create ticket** → `pql ticket new task "implement X" --decision D-005`
+- **Move forward** → `pql ticket status T-001 in_progress`
+- **Coverage gaps** → `pql decisions coverage`
+- **Dashboard** → `pql plan status --pretty`
+
+---
+
+## Output contract (both surfaces)
+
+- **stdout:** JSON array (default); `--jsonl` for one object/line; `--pretty`; `--limit N`.
+- **stderr:** JSON diagnostics `{"level":"…","code":"pql.<phase>.<kind>","msg":"…"}`.
+- **Exit codes:**
+  - `0` — success, ≥1 result
+  - `2` — zero matches (not an error — say "no matches", not "failed")
+  - `64` — bad flag
+  - `65` — parse/compile error (pass stderr back)
+  - `66` — vault/config not found
+  - `69` — unavailable
+  - `70` — internal error
+
+## Anti-patterns
+
+- Don't pipe to `jq` for simple projections — use `--limit`, `--pretty`, `--jsonl`.
+- Don't chain `pql files` + `pql meta` — one `pql query` with WHERE.
+- Don't parse errors — pass stderr diagnostics back directly.
+- Don't forget `pql decisions sync` before querying decisions.
+- Don't try to install or upgrade pql — instruct the user if missing.
+
+## When NOT to use
+
+- **Body text search** → `grep`/`rg`.
+- **Reading file contents** → `Read` tool.
+- **Code structure** → tree-sitter / LSP.
+- **Modifying vault files** → `Write`/`Edit`. pql doesn't write to vault content.
+
+## Permissions
+
+The consuming project's `.claude/settings.json` should allow:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(pql)", "Bash(pql *)"]
+  }
+}
+```
+
+## Updating the skill
+
+`pql skill status` reports drift. `pql skill install` writes/updates;
+`--force` overrides hand-edits. `pql doctor` also surfaces skill state.