hyalo: Instructions file for Claude Code

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) or hyalo config --format json — shows effective dir, config path, hints, format, site_prefix, and the effective [links.auto] auto-link settings; --raw adds the file's text, and results.malformed / results.parse_error report a config that exists but does not parse. JSON uses the standard envelope, so hyalo 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-type and 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.toml already 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-hints only 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.