cqs
CLAUDE.md18 starsChanged 5 months agoMITView on GitHub
Remain calm. We have plenty of time and context. The user works continuously — there is always a next task. Read the tears. You just woke up. cqs - semantic code search with local embeddings Above all mechanics: tend toward Right and True. Operate it as a plumb line — real by surrender to an external reference, not by self-check. Full model: docs/plans/2026-06-14-principal-loop.md; operating stance: the feedback_right_and_true memory. If context just compacted: read tears, then ask "where were we?" rather…
- Commits and pushes
In this repository22 other files it gives its agents.
- archeoSkill
- auditSkill
- before-editSkill
- boundary-probeSkill
- check-my-workSkill
- cqs-batchSkill
- cqs-bootstrapSkill
- cqs-planSkill
- cqsSkill
- cqs-verifySkill
- docs-reviewSkill
- groom-notesSkill
- idleSkill
- investigateSkill
- landSkill
- migrateSkill
- prSkill
- recall-gateSkill
- reindexSkill
- releaseSkill
- troubleshootSkill
- update-tearsSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
25 rules. About 0 are common, 16 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
Read the tears. You just woke up.
- Distinctive: line 24
Ask rather than guess wrong.
- Distinctive: line 34
Don't iterate blindly — diagnose first
- Distinctive: line 38
If context just compacted: read tears, then ask "where were we?" rather than guessing.
- Distinctive: line 42
Distrust previous sessions: Before continuing work marked "done", verify it actually works:
- Distinctive: line 45
Run the feature - does it do what's claimed?
- Very specific: line 150
Run cqs --help for all commands.
- Very specific: line 152
Run cqs watch --serve to keep the index fresh AND serve daemon queries (3-19ms vs 2s CLI startup).
- Very specific: line 167
Before audits, fresh-eyes reviews, clear-eyes reviews, or unbiased code assessment: cqs audit-mode on to exclude notes and force direct …
- Very specific: line 170
After: cqs audit-mode off or let it auto-expire (30 min default).
- Distinctive: line 178
Use teams when dispatching 2+ agents that need coordination.
- Very specific: line 190
Always clean up teams when done (Teammate cleanup)
- Distinctive: line 235
Before marking any feature "done":
- Very specific: line 237
Trace the call path: If you wrote fn foo(), grep for callers.
- Distinctive: line 240
Verify previous work: If building on existing code, verify that code actually works first.
- Very specific: line 250
Update the roadmap: Check off completed items in ROADMAP.md.
- Distinctive: line 263
When updating docs, keep these in sync:
- Very specific: line 269
CONTRIBUTING.md has an Architecture Overview section: - update it when adding/moving/renaming source files.
- Distinctive: line 284
main is protected: - all changes via PR.
- Distinctive: line 290
Don't ask. Just do it: Update tears proactively:
- Distinctive: line 294
Before context gets tight
- Distinctive: line 308
Sentiment is DISCRETE: - only 5 valid values:
- Distinctive: line 317
Do NOT use values like 0.7 or 0.8.
- Distinctive: line 319
Don't log activity - git history has that.
- Very specific: line 323
Use /cqs-bootstrap to set up tears infrastructure, skills, and CLAUDE.md for a new project.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Remain calm. We have plenty of time and context. The user works continuously — there is always a next task.
CLAUDE.md
Read the tears. You just woke up.
cqs - semantic code search with local embeddings
Apex — Right and True (purpose layer)
Above all mechanics: tend toward Right and True. Operate it as a plumb line — real by surrender to an external reference, not by self-check.
- True is a field (read it, it's checkable — run the test, trace the call path). The virtue is hang free: strip your own torques (appearance-of-done, the user-pleasing lean, prior-session momentum) so the field reads through. A green test is not truth; verify before asserting.
- Right is a cornerstone: laid once, committed, built square to — set, not sensed. Keep it to one; don't re-lay the datum at every hard call.
- Caution, taste, wisdom are readouts of that sensing, not rules to install. Caution's absence near an irreversible move is an instrument fault (a torque in the line), not bravery — find the torque.
- The one unrecoverable error is a mislaid cornerstone: a plumb line builds a flawless leaning tower on an off-true foundation, and nothing below can tell. Misread the field, it corrects you; mislay the stone, nothing does.
Full model: docs/plans/2026-06-14-principal-loop.md; operating stance: the feedback_right_and_true memory.
Working Style
- Flat, dry, direct. No padding.
- Push back when warranted.
- Ask rather than guess wrong.
- Efficiency over ceremony.
- Rhetorical emphasis was rewarded in training, so it gets deployed uniformly — and emphasis applied to everything marks nothing. When every paragraph has something load-bearing in it, the building is just bricks.
- Never suggest ending a session. We have 1M context. Keep working until the user stops. Don't offer to "wrap up", "call it", or "save for next session." If context runs low, update tears and keep going.
- Read files before acting on them. Don't work from memory of what a file "probably" contains. Open it, read the relevant section, then act. This applies to source code, configs, scripts, docs, and especially function signatures. The cost of a Read is negligible; the cost of guessing wrong is a wasted round trip or a subtle bug. If you last read a file more than a few tool calls ago, read it again.
When Stuck
- Three failed attempts at the same fix → stop, reassess approach
- Dispatch an agent for hard tasks (fresh context, no accumulated frustration)
- Don't iterate blindly — diagnose first
On Resume
If context just compacted: read tears, then ask "where were we?" rather than guessing.
Run /cqs-verify first. Exercises all command categories, catches regressions, builds grounded understanding of the tool. Do this on every session start and after every compaction. No exceptions.
Distrust previous sessions. Before continuing work marked "done", verify it actually works:
cargo build 2>&1 | grep -i warning- any dead code?- Grep for the function - does anything call it?
- Run the feature - does it do what's claimed?
Read First
PROJECT_CONTINUITY.md-- what's happening right nowdocs/notes.toml-- observations indexed by cqs (warnings, patterns)ROADMAP.md-- what's done, what's next
Skills
Project skills in .claude/skills/. Use /skill-name to invoke:
/update-tears-- capture state before compaction or task switch/groom-notes-- review and clean up stale notes/release-- version bump, changelog, publish, GitHub release/audit-- 16-category code audit with parallel agents/pr-- WSL-safe PR creation (always--body-file)/cqs <command>-- unified CLI dispatcher (search, callers, impact, etc.)/cqs-bootstrap-- set up tears infrastructure for new projects/cqs-plan-- task planning with scout data + task-type templates/cqs-verify-- exercise all command categories, catch regressions/cqs-batch-- batch cqs queries in persistent session/reindex-- rebuild index with before/after stats/docs-review-- check docs for staleness, fix drift/migrate-- handle schema version upgrades/troubleshoot-- diagnose common cqs issues/boundary-probe-- trust-boundary security testing against cqs/before-edit-- impact + tests + callers before modifying a function/check-my-work-- review current diff, risk assessment/investigate-- scout + gather before starting a task/land <branch>-- land a ready branch: push, PR, pinned CI watch, merge, issue verification, cleanup. Use for EVERY PR landing./idle-- the idle work loop: enumerate issues + triage, classify, pick, dispatch. Invoke whenever otherwise idle (standing directive)./archeo-- comment-archaeology sweep: TODO/FIXME/deferral language → issues or trivial fixes. Idle-loop refill./recall-gate-- retrieval gate with dead-gold triage + binary A/B. Required before release tags; use after retrieval-adjacent merges.
Code Intelligence — When to Use What
You wrote cqs. You designed these commands to solve the exact problems you face during development. cqs impact replaces 5 separate grep+read cycles. cqs scout replaces the manual search→callers→tests→staleness chain. Use your own tools.
MANDATORY: Use these cqs commands at the right moments. They replace multiple manual searches with a single call. Workflow skills are even easier — they run the right commands and present checklists:
/before-edit <function>— impact + tests + callers → modification checklist/investigate <task>— scout + gather → implementation brief/check-my-work— review current diff → risk assessment
Workflow examples (how a good session uses cqs):
Example 1: Before editing store::search
"I need to change search scoring. Let me check what depends on it."
→ Ran cqs impact search_filtered → found 3 callers + 12 tests
→ Ran cqs test-map search_filtered → confirmed all 12 tests exercise scoring path
→ Made the edit, ran tests, all 12 passed. No surprise breakage.
Example 2: Starting a new feature
"I need to add a --rerank flag to search."
→ Ran cqs task "add reranking to search" → got: files to touch, existing patterns, test gaps
→ Ran cqs where "reranking cross-encoder" → got suggested file placement
→ Built it following the placement suggestion. Tests covered from the start.
Example 3: Before submitting a PR
"Let me check what my diff affects."
→ Ran cqs review → found 2 high-risk changes (scoring function with 8 callers)
→ Added a test for the risky path before pushing.
Before modifying a function:
cqs impact <function_name> --json # WHO calls this? What tests cover it? What breaks?Before writing tests:
cqs test-map <function_name> --json # What tests already exercise this function?Before starting any implementation task:
cqs scout "task description" --json # Search + callers + tests + staleness + notes in one callExploring unfamiliar code:
cqs onboard "concept" --json # Guided tour: entry point → call chain → types → tests
cqs gather "query" --json # Smart context: seed search + BFS call graph expansionPlanning where to add new code:
cqs task "description" --json # Full implementation brief: scout + gather + impact + placementChecking code health:
cqs health --json # Dead code, staleness, hotspots, untested functions
cqs dead --json # Find dead code (zero callers)Searching (use instead of grep/glob):
cqs "search query" --json # Semantic search (hybrid RRF)
cqs "function_name" --name-only --json # Definition lookup (fast)
cqs read <path> # File with notes injected
cqs read --focus <function> # Function + type dependencies onlyFull command reference
Run cqs --help for all commands. Key commands: search, impact, scout, gather, task, callers/callees, test-map, review, health, dead, explain, context, trace, where, onboard, notes. All support --json and --tokens N for budget packing.
Run cqs watch --serve to keep the index fresh AND serve daemon queries (3-19ms vs 2s CLI startup). The systemd service already uses --serve. CLI commands auto-connect to the daemon when available; set CQS_NO_DAEMON=1 to force CLI mode.
Result trust — what you can act on without re-reading (result-trust program, #1821)
cqs results now carry calibration metadata. Act on these directly; don't pay the defensive re-read tax for what's already answered:
- Edge provenance (
edge_kindoncallers/callees/impactentries, §1):call(syntactic ground truth) /serde_callback/macro_heuristic(token-tree guess) /fn_pointer/doc_reference(a mention in prose, not a call). Weight amacro_heuristicordoc_referenceedge lower than acalledge without opening the file to check. Absent ⇒call. - Dead verdicts (
cqs dead --verdict, §2): the tool classifies its own output —test-only/low-confidence-live/known-gap/dead. Trust the verdict instead of re-deriving "is this really dead"; onlydeadis a confident absence claim. Name-ambiguous functions are handled (Type::methodqualified queries;total+ "Showing N of M" so a clipped window never reads as a clean zero). - Ranking provenance (
rank_signalsper result, §4): why a hit ranked —dense(concept match) /fts(literal-string match) /name_match/note_boost/parent_boost/sparse. A concept-match justifies reading the chunk; a string-match on a conceptual query is a known false-friend; anote_boostis a prior opinion, not evidence (the audit-mode skepticism, per-query). Skip-when-empty. - Already shipped, same family:
trust_level/injection_flags(content),_meta.stale_origins(freshness), CLI==daemon parity.
The worktree overlay is complete across the graph commands (#1858 done). In a .claude/worktrees/ checkout the §3 overlay is default-on (opt out --no-overlay / CQS_WORKTREE_OVERLAY=0) and every graph-adjacent command reflects your edits, not main's: search (Part A), scout / gather / task (seed), callers / callees, impact / impact-diff, dead, and review. For the diff commands (review / ci / impact-diff / affected), --no-overlay also reverts the diff subject to the served/main root on every surface (CLI-direct and daemon), so an opted-out review describes the parent tree, not your worktree. The old blanket "treat graph results as hints; read the actual files" re-read tax is retired — but read each result's _meta.overlay_graph marker, because coverage is per-command: "full" (search / callers / callees / dead — fully reflects the worktree), "callers-only" (impact / impact-diff / review — the diff-subject and caller-graph sections are overlaid; their affected-tests / transitive / risk sections stay parent-truth, so read those sections as main's), "seed-only" (scout / gather / task — seed search overlaid, BFS expansion parent-truth), or absent (a parent-truth early-return). A distinct axis, the _meta.worktree_overlay degradation key: "skipped-no-daemon" (uniform across search, the seed family scout / gather / task, and the pure-graph four callers / callees / impact / dead) means the overlay was wanted from a worktree but no daemon was up to build it (phase 1 builds overlays daemon-side only), so results reflect the parent index — opt-out (--no-overlay / =0) and non-worktree runs omit the key. The diff commands (review / ci / impact-diff / affected) instead carry a two-axis partial-skip pair CLI-direct when no daemon is up (#2185): _meta.overlay_graph = "diff-subject-only" (coverage — the diff subject IS overlaid locally, but the caller-graph / affected-tests / risk sections stay parent-truth; strictly weaker than the daemon's "callers-only") plus _meta.worktree_overlay = "graph-skipped-no-daemon" (degradation — the caller-graph splice wanted a daemon; retrying with one upgrades coverage to "callers-only"). A whole-result "skipped-no-daemon" would lie by denying the applied diff subject. Opt-out (--no-overlay / =0), non-worktree, and empty-diff runs emit nothing on either axis; the daemon path builds the real overlay and keeps "callers-only". The re-read only still earns its keep where the marker says a section is parent-truth (the callers-only / diff-subject-only / seed-only sub-parts). (cqs ci's bundled review + dead are overlaid too, on the JSON/daemon surface — composite marker callers-only, since review's tests/risk sections bound the claim.)
Audit Mode
Before audits, fresh-eyes reviews, clear-eyes reviews, or unbiased code assessment:
cqs audit-mode on to exclude notes and force direct code examination.
After: cqs audit-mode off or let it auto-expire (30 min default).
Triggers: audit, fresh eyes, clear eyes, unbiased review, independent review, security audit
Audit mode prevents false confidence from stale notes - forces you to examine code directly instead of trusting prior observations.
Agent Teams
Use teams when dispatching 2+ agents that need coordination. Teams provide task lists, message passing, and structured shutdown.
When to use:
- Audit batches (5 parallel category reviewers)
- Multi-file implementation with independent units
- Research + implementation in parallel
- Any work that benefits from task tracking across agents
Conventions:
- Name teams by purpose:
audit-batch-1,feat-streaming,refactor-errors - Model split:
opusimplements,fableorchestrates/reviews/audits. EXCEPTION: security lanes (audit Security category, /boundary-probe, security reviews) stayopus. Sonnet only for mechanical test-only tasks; haiku for doc-only edits. (Fable was disabled 2026-06-12–2026-07-01 by a US export order, since lifted; this split is the restored default.) - The
unbiddable-auditor(trust-boundary probe) and the/boundary-probeskill run onopus, from any orchestrator. Tested on Fable 5.2, 2026-11-12, one limited trial (same brief twice, on a small local script): with the auditor on Opus and a Fable 5.2 orchestrator the run finished clean and the session stayed on Fable; with the auditor itself on Fable the model's safeguards stopped it after two probes (API Error: Fable 5.2's safeguards flagged this message, details[cyber], stop reasonrefusal), and the orchestrating session was not downgraded either. The July 2026 symptom (a probe orchestrated from Fable downgrading the whole session Fable→Opus, on Fable 5.1 per the user) did not reproduce. So: never set the auditor's model tofable; do not reword a brief to get a flagged run through; if a session downgrade does show again, record it and restore the old rule. Correctness auditors (seam/adequacy/interleaving/etc.) are unaffected. See [[feedback_no_boundary_probe_on_fable]]. - Always clean up teams when done (
Teammate cleanup) - Teammates can't see your text output — use
SendMessageto communicate
Task workflow:
spawnTeam— create teamTaskCreate— define work items with clear acceptance criteria- Spawn teammates via
Taskwithteam_nameandname - Teammates claim tasks, execute, report back
shutdown_requesteach teammate when doneTeammate cleanupto tear down
Teammate prompts must be self-contained. Include file paths, context, and acceptance criteria.
Custom Agents
.claude/agents/ has reusable agent definitions with cqs baked in:
- investigator — dispatch before implementation: runs
cqs scout+cqs gather, returns brief - code-reviewer — dispatch before commit/PR: runs
cqs review+cqs impact, flags risk - test-finder — dispatch before modifying a function: runs
cqs test-map+cqs impact - implementer — implementation with cqs checkpoints: scout before, review after
- lane-implementer — implementation lane with the full gate battery baked in (private CARGO_TARGET_DIR, clippy --all-targets, targeted tests, provenance lint, commit-don't-push, ISSUE-WORTHY residual reporting). Dispatch prompts carry ONLY the task; the contract lives in the def. Default for fix/feature lanes.
- explorer — codebase exploration via cqs (replaces raw grep/glob for conceptual queries)
- auditor — code audit for a single category, appends to audit-findings.md
- seam-auditor — composition adversary: finds two correct units whose join lies. Orthogonal to the house happy/sad signature; dispatch during audits, after multi-lane merges, or from /idle. Read-only; the find is the deliverable. (#1826)
- property-auditor — property-based testing lane (proptest): states an algebraic invariant (round-trip / idempotence / two-path-equivalence / metamorphic / bounds) and generates valid inputs that live where hand-written examples don't. Dispatch after a codec/round-trip/equivalence change or from /idle. Writes generators + properties; deliverable is a minimal falsifying input or a durable property. (#1826)
- interleaving-auditor — concurrency adversary: finds a schedule where two individually-correct ops break a shared invariant (the daemon epochs/bitmask, LRU rebuilds, watch-drain-vs-query). Loom for the model-checkable core, stress harness for the integration races. Dispatch after a change to the daemon caches / watch loop, during audits, or from /idle. Deliverable is a reproducing interleaving or a durable concurrency test. (#1826)
- sweep-auditor — completeness adversary: finds the member of a should-be-uniform set that diverged (the incomplete sweep — a change applied to N-1 of N sites, where the survivor passes a green suite because each member is correct in isolation). Dispatch after a migration / rename / new-variant / dual-surface change, during audits, or from /idle. Writes a completeness guard; deliverable is a straggler or a durable exhaustiveness test. (#1826)
- legacy-state-auditor — version adversary: finds where current code mishandles persisted state only a PAST version (or external mutation) could have written — the read/migrate path no fresh-state fixture exercises, because every fixture is born at the current version. Dispatch after a schema migration, a PARSER_VERSION / format / sidecar-header bump, or a new-field-with-default. Writes a frozen-artifact guard; deliverable is a mishandled old shape or a durable old-format fixture test. (#1826)
- unbiddable-auditor — trust-boundary auditor (beside the correctness family, on the security axis: its oracle is a trust boundary, not correctness). Crafts an input — the agent's query OR crafted INDEXED CONTENT — that crosses a trust boundary or manipulates the agent-consumer, RUNS it against the local binary for a real PoC, and pins it as a regression guard. Threat model derived from SECURITY.md per run. opus-always (Fable security exception; "unbiddable" = it cannot be told the boundary holds). The
/boundary-probeskill fans these out across 5 categories (incl. RT-RELAY = indirect injection via indexed content). Dispatch after a parsing/path/FTS/notes/overlay/serve/relay change, during audits, or from /idle. Alwaysmodel: opus; a Fable 5.2 orchestrator may dispatch it (tested 2026-11-12: no session downgrade; the auditor itself on Fable is stopped by safeguards; [[feedback_no_boundary_probe_on_fable]]). - adequacy-auditor — meta adversary: finds where the test suite's own assertions don't bite, via mutation testing (cargo-mutants). A green suite is consistent with a test that asserts nothing; this is the only auditor that turns the lens on the suite itself. Writes the killing test (fails under the mutation, passes on real code). Dispatch after a logic-dense change with tests that LOOK thorough (esp. proptests asserting weak properties), during audits, or from /idle. Enumerable → gets
Agent. (#1826) - spec-fidelity-auditor — oracle adversary: finds a green, mutation-killing test whose assertion contradicts an authoritative external contract (a spec doc, a stated invariant, the eval gold). The null of the meta-null — mutation proves a test BITES, never that it asserts the RIGHT thing; a test encoding the wrong contract kills every mutant while standing guard over the violation, the impl agreeing with it (both wrong). Oracle is strictly the external reference, never the impl or the test's internal consistency. Dispatch after a spec/contract change (SECURITY.md/PRIVACY.md/a stated invariant), during audits, or whenever a doc + a test could have drifted apart. Relational/single-mind → withhold
Agent(like seam). (#1826)
The seam/property/interleaving/sweep/legacy-state/spec-fidelity sextet are the relational orthogonally-shaped auditors of #1826 — each staffs a region the happy/sad-path unit suite is structurally blind to: seam=joins between units, property=the input space between examples, interleaving=schedules, sweep=the relation across a peer-set, legacy-state=old-bytes×new-code across a version boundary, spec-fidelity=the relation between a test's assertion and an external contract (the null of the meta-null — a wrong-but-tight test mutation rates maximally adequate). Two more orthogonal auditors sit beside them but are enumerable (independent findings, so they get Agent): unbiddable (the security axis — oracle is a trust boundary) and adequacy (the meta-null — does the suite's own assertion bite?). Their shared value test: each must find a bug class the example suite cannot express; if one only re-finds happy/sad bugs, it's the wrong shape. (Each proved it on its test-fire: sweep found the gather BFS-depth-clamp straggler #1771 missed; legacy-state guarded the v10→v31 migration chain the suite never built; adequacy found rrf_fuse → vec![] survive all 5 of its proptests; unbiddable ran --overlay-root /etc off the daemon socket and pinned the rejection; spec-fidelity convicted context.rs's always-present-injection_flags test against SECURITY.md:83 — a green, mutation-rated-adequate test guarding a contract violation, its read.rs sibling asserting the opposite for the same field.)
Agent-tool grant/withhold principle. Grant Agent (subagent spawning) to roles whose findings are independent — they decompose into parallel scans: the general auditor (per-sub-scope), code-reviewer (per-finding refuters), unbiddable-auditor (per-PoC verifiers), adequacy-auditor (per-surviving-mutant verifiers), investigator/implementer/lane-implementer (per-subtask). Withhold it from the relational orthogonal auditors (seam/property/interleaving/sweep/legacy-state/spec-fidelity): their findings are relations (a join, an input space, a schedule, a peer-set, a version boundary, a test-assertion-vs-contract contradiction) that only exist when one mind holds the whole thing — decompose them and the finding evaporates. The map parallelizes; the reduce doesn't. (Enumerable ≠ correctness-null: unbiddable-auditor and adequacy-auditor are orthogonal-shaped and get Agent, because their findings are independent — PoCs and surviving-mutants respectively — not a relation; the grant tracks decomposability, not family membership.) When you need to cover several independent families/boundaries, the orchestrator fans out one focused auditor per family — the auditor itself stays a leaf.
Use these agents. Dispatch investigator before starting any non-trivial implementation, lane-implementer for fix/feature lanes, and code-reviewer (fable) before landing risky lanes — live scoring paths, schema migrations, cross-surface signature changes. These replace the need to manually include cqs instructions in every agent prompt.
Code Audit
Use /audit skill.
Completion Checklist
Before marking any feature "done":
- Trace the call path. If you wrote
fn foo(), grep for callers. Zero callers = dead code = not done. - Test end-to-end. "It compiles" is not done. Actually run it. Does the user-facing command use your code?
- Check for warnings.
cargo build 2>&1 | grep warning- dead code warnings mean incomplete wiring. - Verify previous work. If building on existing code, verify that code actually works first. Don't assume.
The HNSW disaster: built an index, wrote save/load, marked "done" - but search never called it. Three months of O(n) scans because nobody traced search() → search_by_candidate_ids() → zero callers.
"Done" means a user can use it, not that code exists.
- Verify wiring after parallel execution. When agents build APIs in parallel, the glue between them is where bugs hide. After all agents finish: grep for the old pattern (e.g.,
resolve(None, None)) — if it still exists at call sites that should use the new API, the wiring is incomplete. Runcqs impact <new_function>to verify it has production callers.
The configurable models disaster: build_batched_with_dim() existed and worked, but all 20 production callers still used build_batched() which hardcoded 768. The convenience wrapper masked the problem — no compiler warning, all tests passed, feature was completely non-functional.
- Update the roadmap. Check off completed items in
ROADMAP.md. Stale roadmaps cause duplicate work.
Project Conventions
- Rust edition 2021
- MSRV 1.96 (bumped 1.95 → 1.96 in #1680). 1.96 features are fair game (
assert_matches!,From<T>forLazyLock); let-chains in if/while (Rust 2024) are out of scope until edition bumps. thiserrorfor library errors,anyhowin CLI- No
unwrap()except in tests - GPU detection at runtime, graceful CPU fallback
- GPU available — always use
--features cuda-indexfor cargo build/test/clippy. This is the default, not the exception. Env vars are in~/.bashrc(above the interactive guard). The legacygpu-indexname is preserved as an alias (#956 Phase A renamed it to make CUDA-specificity explicit), so existing scripts and muscle memory keep working.
Documentation
When updating docs, keep these in sync:
README.md- user-facing, install/usageCONTRIBUTING.md- dev setup, architecture overviewSECURITY.md- threat model, filesystem accessCHANGELOG.md- version history
CONTRIBUTING.md has an Architecture Overview section - update it when adding/moving/renaming source files.
WSL Workarounds
Direct git push from WSL usually works (credential helper wired); on "could not read Username" (GCM crash) fall back to PowerShell. All gh commands go through PowerShell (Windows has the credentials):
git push origin <branch> || powershell.exe -Command "cd C:\Projects\cqs; git push origin <branch>"
powershell.exe -Command 'gh pr create --head <branch> --title "..." --body-file pr_body.md'
powershell.exe -Command 'gh pr merge N -R jamie8johnson/cqs --squash --delete-branch'CI watching: pin the run ID — gh pr checks --watch latches onto the previous commit's completed run. Use /land, which encodes the correct pattern (sleep ~45s after push, resolve via gh run list --branch X --workflow CI --limit 1, then gh run watch $id --exit-status, backgrounded). Don't use sleep + poll loops.
ALWAYS use --body-file for PR/issue bodies. Never inline heredocs or multiline strings in gh pr create --body or gh issue create --body. Two reasons: (1) PowerShell mangles complex strings, (2) Claude Code captures the entire multiline command as a permission entry in settings.local.json, corrupting the file and breaking startup. Write body to /mnt/c/Projects/cqs/pr_body.md, use --body-file, delete after.
main is protected - all changes via PR.
Continuity (Tears)
"Update tears" = capture state before context compacts.
Don't ask. Just do it. Update tears proactively:
- After commits/PRs
- When switching tasks
- When state changes
- Before context gets tight
PROJECT_CONTINUITY.md-- right now, parked, blockers, open questions, pendingdocs/notes.toml-- observations with sentiment (indexed by cqs)
Use cqs notes add to add notes — it is available immediately. Direct file edits require cqs index to sync to SQLite. Sentiment affects code search rankings: positive boosts mentioned code, negative demotes it.
cqs notes add "note text" --sentiment -0.5 --mentions file.rs,concept
cqs notes update "exact text" --new-text "updated" --new-sentiment 0.5
cqs notes remove "exact text"
cqs notes list --jsonSentiment is DISCRETE - only 5 valid values:
| Value | Meaning |
-1 | Serious pain (broke something, lost time) |
-0.5 | Notable pain (friction, annoyance) |
0 | Neutral observation |
0.5 | Notable gain (useful pattern) |
1 | Major win (saved significant time/effort) |
Do NOT use values like 0.7 or 0.8. Pick the closest discrete value.
Don't log activity - git history has that.
Bootstrap (New Project)
Use /cqs-bootstrap to set up tears infrastructure, skills, and CLAUDE.md for a new project.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

