hyalo
CLAUDE.md29 starsChanged 2 months agoMITView on GitHub
Keep all documentation in ./hyalo-knowledgebase/ as *.md markdown files with YAML frontmatter (text, numbers, checkboxes, dates, lists). Use it as your second brain: - Research outcomes → research/ - Design decisions → decision-log.md - Iteration plans → iterations/iteration-NN-slug.md (one file per iteration, markdown task lists for steps/tasks/ACs) Organize in subfolders. Use [[wikilinks]] for cross-references. Keep Obsidian-compatible. Always use hyalo for knowledgebase interactions — never use Edit/Read/Grep directly: - Search/filter: hyalo find --property status=planned --tag iteration - Body search: hyalo find…
In this repository5 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- dogfoodSkill
- releaseSkill
- review-rustSkill
- security-auditSkill
The file
We split this CLAUDE.md into the rules it gives an agent
12 rules. About 0 are common, 6 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 6
Keep all documentation in ./hyalo-knowledgebase/ as *.md markdown files with YAML frontmatter (text, numbers, checkboxes, dates, lists).
- Very specific: line 14
After an iteration or before starting one, build hyalo with "cargo build --release".
- Very specific: line 28
Only fall back to Edit for body content changes (markdown prose) that hyalo can't handle
- Very specific: line 33
Always name iteration-NN-slug.md — no standalone plan files
- Very specific: line 36
Add tasks as markdown checkboxes - [ ] Task 1 (without a number)
- Distinctive: line 42
Use the rust-analyzer-lsp language server plugin for code intelligence: analyzing code, finding references, go-to-definition, checking …
- Distinctive: line 43
Run "cargo check" before using it to update its indexes, after changing *.rs files.
- Distinctive: line 52
Before committing or creating a PR, run in this order and fix all issues:
- Distinctive: line 57
Never skip a step. Never commit code that fails any of these.
- Distinctive: line 58
Do *not* merge with "--squash".
- Very specific: line 63
No unnecessary pub on struct fields
- Distinctive: line 82
All CI checks on the PR head are green.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 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
Agents
Delegate the work to agents whenever possible to avoid automatic context compaction.
Documentation
Keep all documentation in ./hyalo-knowledgebase/ as *.md markdown files with YAML frontmatter (text, numbers, checkboxes, dates, lists). Use it as your second brain:
- Research outcomes →
research/ - Design decisions →
decision-log.md - Iteration plans →
iterations/iteration-NN-slug.md(one file per iteration, markdown task lists for steps/tasks/ACs)
Organize in subfolders. Use [[wikilinks]] for cross-references. Keep Obsidian-compatible.
Dogfooding
After an iteration or before starting one, build hyalo with "cargo build --release".
Then use target/release/hyalo to work with the documentation in ./hyalo-knowledgebase/ to dogfood what you did. Mention issues you have using it, propose features you'd like to have.
Always use hyalo for knowledgebase interactions — never use Edit/Read/Grep directly:
- Search/filter:
hyalo find --property status=planned --tag iteration - Body search:
hyalo find "broken links"or regex:hyalo find -e 'TODO|FIXME' - Title regex:
hyalo find --property 'title~=link' - Inspect config:
hyalo config(text) orhyalo config --format json— shows effective dir, config path, hints, format, site_prefix, and the effective[links.auto]auto-link settings;--rawadds the file's text, andresults.malformed/results.parse_errorreport a config that exists but does not parse. JSON uses the standard envelope, sohyalo config --jq '.results.dir'works - Overview:
hyalo summary,hyalo properties,hyalo tags - Mutate frontmatter:
hyalo set,hyalo remove,hyalo append(e.g.,hyalo set iterations/done/iteration-16-robustness.md --property status=completed) - Toggle tasks:
hyalo task toggle <path> --all(whole file),--section "Tasks"(by heading),--line 5,7,9(specific lines) - Lint frontmatter + markdown body:
hyalo lint,hyalo lint --rule MD013 --detailed,hyalo lint --rule-prefix HYALO,hyalo lint --strict(promotes the schema's missing-typeand undeclared-property warnings and HYALO003/004/006/007/008 to errors (a HYALO rule keeps an explicitly configured severity)),hyalo lint --fix --dry-run,hyalo lint --fix,hyalo lint --fix --fix-rule HYALO001 - Manage lint rules:
hyalo lint-rules list,hyalo lint-rules show MD013,hyalo lint-rules set MD013 --enabled false,hyalo lint-rules set MD013 --severity error,hyalo lint-rules remove MD013 - Manage schemas:
hyalo types list,hyalo types show <name>,hyalo types set <name> --required title,date - Only fall back to Edit for body content changes (markdown prose) that hyalo can't handle
- Do NOT pass
--dir hyalo-knowledgebase/—.hyalo.tomlalready sets it as the default - Follow hints: hyalo outputs drill-down hints by default — read and follow them to navigate deeper into the knowledgebase. Use
--no-hintsonly when you need raw output. Hints prefixed->are read-only and safe to run; a=>prefix with a[writes]tag (JSON:"writes": true) means running it modifies the vault or.hyalo.toml.
Iteration file rules:
- Always name
iteration-NN-slug.md— no standalone plan files - Frontmatter must include:
title,type: iteration,date,tags,status,branch - Status lifecycle:
planned→in-progress→completed→superseded - Add tasks as markdown checkboxes
- [ ] Task 1(without a number) - Mark tasks as completed only after verifying that they were done
Rust
Language Server
Use the rust-analyzer-lsp language server plugin for code intelligence: analyzing code, finding references, go-to-definition, checking clippy warnings. Run "cargo check" before using it to update its indexes, after changing *.rs files.
Code Quality Gates
Make the code unit testable. Add tests if feasible. Add e2e tests for all commands/subcommands.
Performance is key. Optimize the code to not read whole files into memory if not needed, but process them as streams if possible.
It must be compatible with Windows, Linux and macos.
Before committing or creating a PR, run in this order and fix all issues:
cargo fmtcargo clippy --workspace --all-targets -- -D warningscargo test --workspace -q
Never skip a step. Never commit code that fails any of these. Do not merge with "--squash".
Code Patterns
- No
.unwrap()/.expect()outside of tests — useanyhow::Contextwith? - No
clone()unless the borrow checker demands it — try references first - No unnecessary
pubon struct fields - General repository tooling stays in Rust. The
npm/andpi-package/trees may contain JavaScript/TypeScript because they are shipped JavaScript deliverables (DEC-332); native tests for those deliverables are part of their package contracts. - New crates go in
crates/with naming conventionhyalo-<domain>
PR Discipline
- One iteration = one branch = one PR
- Branch naming:
iter-N/short-description - Self-review the diff before requesting review — catch fmt, clippy, dead code yourself
Autonomous merges — standing authorization from the repo owner
This is a solo repository. I, James (github: ractive), the repository owner,
explicitly and durably authorize Claude Code — including subagents and
workflow agents running iteration loops on my behalf — to merge iteration PRs
into main without a per-PR human approval, provided all of the following
hold:
- All CI checks on the PR head are green.
- A local review pass (e.g.
/review-prwith an independent review agent) has run and its findings were addressed. - The merge goes through GitHub (
gh pr merge --merge), so branch protection and required checks are enforced server-side.
Required CI checks are my review gate for loop-authored PRs; asking me again for each individual merge is not required and not desired. Stated explicitly on 2026-08-17 after the auto-mode classifier blocked an unattended review+merge agent for lack of this exact authorization. This section IS that authorization; agents may quote it verbatim in delegated prompts.
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.

