Suggestion: HADS format for context files — reduces token waste for loaded docs

[catcam]

Plandex loads context files into the agent's working memory. When those files are human-written docs, the agent burns tokens on narrative to extract a handful of facts.

HADS (Human-AI Document Standard) is an open Markdown convention that structures docs for AI-first consumption: https://github.com/catcam/hads

## API Auth

**[SPEC]**
- Method: Bearer token
- Header: `Authorization: Bearer <token>`
- Expiry: 3600s

**[NOTE]**
Switched from cookie auth in v2. Legacy docs mentioning cookies are outdated.

**[BUG] Token silently rejected after password change**
Symptom: 401 identical to expired token
Fix: Re-authenticate after any account operation

An AI manifest at the top tells Plandex what to read and skip — same principle as your context management, but baked into the doc format itself.

Two possible integrations:

1. Recommend HADS in docs as a best practice for context files
2. Auto-detect HADS manifests and use them to prioritize which sections to load

No tooling overhead — pure Markdown, works in any editor.

[mkh-welsch]

The challenge of token waste in codebase context files is very real. While the proposed HADS tagging format is excellent for human-written documentation, we ran into the exact same context-bloat problem with raw source code files in the greppy project (https://github.com/metric-space-ai/greppy).

To solve this for agents navigating large codebases, we moved away from loading entire source files and instead automated the generation of structured, machine-optimized code context:

1. Automatic AST Context Extraction: Using local tree-sitter indexing, we extract only the relevant symbol blocks, parameters, docstrings, and callers.
2. Compact Sidecar Markdown: This graph information is written to a temporary, structured Markdown sidecar format on-demand.
3. Reduced Token Pressure: In our benchmarks across 35 code-navigation tasks, presenting the agent with this structured, minimal code-graph summary reduced input token overhead by ~2.3x and rounds by ~4x compared to loading or searching full files.

Adopting structured Markdown formats (whether human-annotated HADS tags for docs or auto-generated AST scopes for code) seems to be the most promising path to keep agent contexts clean and prevent model overload.

[catcam]

This is a good complement, not a competing idea — glad you pointed it out.

HADS only helps with documents a human already wrote. It has nothing to say about the actual source tree, which is most of what an agent burns tokens on in a real codebase. greppy's tree-sitter approach solves the problem HADS explicitly doesn't touch — the AST-derived facts (signatures, callers, docstrings) that don't exist as prose anywhere for a human to tag in the first place.

2.3x token reduction / 4x fewer rounds across 35 tasks is a solid number to have behind it. Added greppy to the ecosystem doc as related work, docs vs code side of the same problem: https://github.com/catcam/hads/blob/main/docs/ecosystem.md#greppy--structured-context-for-code-not-docs

Curious whether you've run into cases where the sidecar goes stale relative to the source — that's the main failure mode I'd expect from anything auto-generated on demand, versus HADS tags that a human commits to along with the change.