[1/6] docs: set up agent-skill conventions and domain glossaries

[freshtonic]

📚 eql-v3 PR  ·  1 of 6

Part of a queue. The PRs merge in FIFO order — the numbered order below, #1 first. Merging one supersedes the PRs after it until the author runs git queue sync (rebases the rest onto the merged base) and git queue submit (retargets their PRs).

✅🟢 #422 queue/eql-v3/setup-skills → main  👈 this PR
✅🟢 #423 queue/eql-v3/upgrade-deps → queue/eql-v3/setup-skills
♻️🟢 #424 queue/eql-v3/typecheck → queue/eql-v3/upgrade-deps
✅🟢 #428 queue/eql-v3/transform → queue/eql-v3/typecheck
✅🟢 #426 queue/eql-v3/showcase → queue/eql-v3/transform
⏳🟢 #427 queue/eql-v3/integration → queue/eql-v3/showcase

_{✅ approved · ♻️ changes requested · ⏳ review pending  |  🟣 merged · 🟢 open · ⚫ closed  —  status as of the last git queue submit.
🥞 Managed by git-queue — do not edit this list by hand.}

About this queue

Migrates CipherStash Proxy from EQL v2 to EQL v3 (cipherstash-client 0.34.1-alpha.4 → 0.42.0, EQL 2.3.0-pre.3 → 3.0.2), replacing the opaque eql_v2_encrypted composite type with 53 typed jsonb domains that encode both scalar type and searchable capability in the column type itself.

About this branch

Set up the Matt Pocock skills which will we use to drive the subsequent changes.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds agent guidance for Linear issue management and triage, plus a context map and package glossaries covering Proxy, EQL Mapper, shared terminology, ADR usage, and a documented capability-model gap.

Changes

Agent and Domain Documentation

Layer / File(s)	Summary
Agent workflow guidance CLAUDE.md, docs/agents/issue-tracker.md, docs/agents/triage-labels.md	Documents Linear workflows, issue linking, status handling, triage labels, and agent-skill references.
Domain documentation map CONTEXT-MAP.md, docs/agents/domain.md	Defines workspace contexts, shared vocabulary, cross-context relationships, ADR lookup rules, and terminology handling.
Package context glossaries packages/cipherstash-proxy/CONTEXT.md, packages/eql-mapper/CONTEXT.md	Defines Proxy and EQL Mapper concepts, type and transformation terminology, naming conventions, and the known trait-bound enforcement gap.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• cipherstash/proxy#415: Adds overlapping Agent skills, context-map, and agent documentation.
• cipherstash/proxy#420: Adds the same multi-context documentation and Proxy/EQL Mapper glossary content.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the documentation-focused changes adding agent-skill conventions and domain glossaries.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch queue/eql-v3/setup-skills

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/agents/domain.md`:
- Around line 28-39: Specify the text language on the fenced directory-tree
block in the documentation by changing its fence to text, preserving the
existing tree content unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a4e1f88e-d3dd-4bbe-9428-ba13993aa6b9

📥 Commits

Reviewing files that changed from the base of the PR and between 43da7e4 and ad36391.

📒 Files selected for processing (7)

• CLAUDE.md
• CONTEXT-MAP.md
• docs/agents/domain.md
• docs/agents/issue-tracker.md
• docs/agents/triage-labels.md
• packages/cipherstash-proxy/CONTEXT.md
• packages/eql-mapper/CONTEXT.md

[tobyhede]

Docs-only. Verified: code references are accurate (manager.rs:146 is exactly EqlTraits::all() in SchemaManager; satisfy_bounds/UnsatisfiedBounds exist). The "capability seam broken" / "known model gap" callouts correctly describe a real bug. Good, precise glossaries. Safe to merge as queue base.

Minor, non-blocking:

• CLAUDE.md no trailing newline — pre-existing; add one while touching the file.
• Hardcoded manager.rs:146 in CONTEXT-MAP.md and eql-mapper/CONTEXT.md — line-precise refs will rot once this queue churns that file. Anchor to EqlTraits::all() in SchemaManager instead.
• Template artifacts — docs/agents/domain.md uses ADR-0007 (event-sourced orders) (no ADRs exist; wrong domain). triage-labels.md has a reader-instruction line ("Edit the right-hand column…"). Both look copied from upstream skills template.
• v2 type names baked in — eql_v2_encrypted + two "EQL v2 operations" descriptions in CONTEXT-MAP.md/eql-mapper/CONTEXT.md become the first thing PR TLS configuration and connection #4+ must revise. (Localized to a few entries, not the whole glossary.)

[coderabbitai]

🧹 Nitpick comments (1)

CONTEXT-MAP.md (1)

29-36: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Replace brittle line-number references with stable source anchors.

Both glossaries should reference the SchemaManager/EqlTraits::all() symbol instead of manager.rs:146; otherwise the documentation will become incorrect after routine source edits.

• CONTEXT-MAP.md#L29-L36: update the capability-gap reference.
• packages/eql-mapper/CONTEXT.md#L95-L102: update the known-model-gap reference.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTEXT-MAP.md` around lines 29 - 36, Replace the brittle manager.rs:146
reference in the capability-gap entry of CONTEXT-MAP.md with stable anchors
naming SchemaManager and EqlTraits::all(). Apply the same reference update in
packages/eql-mapper/CONTEXT.md’s known-model-gap entry; both documentation sites
require direct changes.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@CONTEXT-MAP.md`:
- Around line 29-36: Replace the brittle manager.rs:146 reference in the
capability-gap entry of CONTEXT-MAP.md with stable anchors naming SchemaManager
and EqlTraits::all(). Apply the same reference update in
packages/eql-mapper/CONTEXT.md’s known-model-gap entry; both documentation sites
require direct changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 487f02d4-fb8a-45cb-a6fb-44db6ae2af22

📥 Commits

Reviewing files that changed from the base of the PR and between ad36391 and 874be05.

📒 Files selected for processing (6)

• CLAUDE.md
• CONTEXT-MAP.md
• docs/agents/domain.md
• docs/agents/triage-labels.md
• packages/cipherstash-proxy/CONTEXT.md
• packages/eql-mapper/CONTEXT.md

💤 Files with no reviewable changes (1)

• docs/agents/triage-labels.md

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/cipherstash-proxy/CONTEXT.md
• CLAUDE.md

[freshtonic]

Addressed the review nits (all pushed) → docs(agents): address setup-skills review nits:

• Languaged the directory-tree fence as ```text (markdownlint MD040).
• Replaced the copied-in ADR-0007 (event-sourced orders) example (no such ADR, wrong domain) with a neutral placeholder.
• Dropped the leftover reader-instruction line in triage-labels.md.
• Added the missing trailing newline in CLAUDE.md.

Left as-is, on purpose:

• The manager.rs:146 line-ref in CONTEXT-MAP.md / eql-mapper/CONTEXT.md — downstream commits in this stack rewrite those exact "capability seam" passages (the v3 work closes that gap), so anchoring them here just collides with those rewrites. The volatile line-ref lives in the rewritten passage on [3/6] feat: EQL v3 type checker driven by per-column domain capability #424/[6/6] feat: infer v3 encrypt config and convert the integration suite #427 if it's worth anchoring there.
• The v2 type-name entries (eql_v2_encrypted, "EQL v2 operations") — already updated by the later docs: sweep remaining EQL v2 references to v3 commit on [6/6] feat: infer v3 encrypt config and convert the integration suite #427.