HADS — structured docs for smarter agent context

[catcam]

Agents waste context loading full docs. HADS tags blocks ([SPEC], [BUG], [NOTE]) so the agent loads only what's relevant to the task. ~70% token reduction, works with any model.

https://github.com/catcam/hads

[roomote-v0]

I'd like to help with this issue, but I need some clarification to ensure I implement the right solution. Could you please provide more details on the following:

• Scope of integration: Are you proposing that Roo Code add native support for parsing HADS-tagged documentation blocks ([SPEC], [BUG], [NOTE], etc.) when reading user project docs? Or is this about restructuring Roo Code's own internal documentation using HADS format?

• Specific behavior: What should Roo Code do differently when it encounters HADS-tagged docs? For example, should the agent selectively load only blocks matching the current task type (e.g., load [BUG] blocks when debugging, [SPEC] blocks when implementing features)?

• File discovery: Should Roo Code automatically detect HADS-formatted files in a project, or should this be opt-in via a configuration setting (e.g., a .hads config file or a setting in Roo Code's configuration)?

• Fallback behavior: How should Roo Code handle projects that don't use HADS? Should the existing documentation loading behavior remain unchanged?

• Priority of tags: Is there a defined set of HADS tags, or is it extensible? Should users be able to define custom tags and their relevance mappings?

Understanding these details will help me propose a concrete implementation plan.

Please tag @roomote in your response with the answers, and I'll be happy to propose a plan and proceed with the implementation.

[catcam]

Thanks for the detailed questions.

To clarify scope: this is not a request for Roo Code to add native HADS parsing. The ask is simpler — just awareness of the standard so users can adopt it in their project docs and it works naturally with any agent that reads Markdown.

Practically: if a user structures their CLAUDE.md or knowledge files with HADS tags, the agent already benefits without any code changes — it just reads the manifest at the top and knows what to skip. No special parsing needed.

A more concrete integration would be: when Roo Code generates project documentation (memory files, context docs), it could optionally output HADS-tagged Markdown. That's the generation side, and it would reduce context waste on every subsequent read.

But honestly even just a mention in the docs as a community best practice would be useful. Not asking for a roadmap item.

[catcam]

Just published a concrete case study if it helps clarify the value: https://github.com/catcam/hads/blob/main/case-studies/polymarket-bot.md

Real codebase, real token counts — 705-line CLAUDE.md for an autonomous trading agent. 48% of context was version history loaded every session regardless of task. The measurement section shows exactly how the split was calculated.