Repository navigation
docs: v0.10 feature coverage gap — 11 user-facing features have no dedicated documentation #1272
Description
Summary
Survey of v0.10 feature changesets vs documentation coverage shows ~37% of major shipped features have no dedicated docs page anywhere in the repo. Users running squad --help see commands but can't find docs explaining how to use them.
Methodology
- Counted feature changesets in
.changeset/(excludingfix-,perf-,squash-, etc.): 67 features - For each, searched
docs/src/content/docs/**/*.md*using keyword matches (not just filename matches) - Cross-checked against the live sitemap at https://bradygaster.github.io/squad/sitemap-0.xml (159 pages)
Coverage results — sample of 30 major v0.10 features
✅ Documented (19): rai-built-in-agent, fact-checker-agent, cross-squad-orchestration (in distributed-mesh.md), git-state-backends, external-state, builtin-skills, ado-configurable-items, loop-command, self-upgrade, machine-capability-routing, scratch-dir-utility, cleanup-ceremony, cooperative-rate-limiting, quiet-notifications, watch-circuit-breaker, persistent-ralph, squad-commands-skill, session-recovery-skill, squad-scheduler
❌ Missing dedicated documentation (11):
| Feature | Changeset | What it does | Affected users |
|---|---|---|---|
squad export agent (Coordinator-as-Agent export) |
coordinator-as-agent-export.md |
Compile .squad/ into .github/agents/squad.md for repo-native Copilot |
Anyone shipping Squad without full .squad/ install (Brady's PR #1180) |
squad preset + squad init --preset |
squad-home-presets.md |
Curated agent collections; preset list, preset show, preset apply, preset save, preset init [--remote] |
New project bootstrapping |
squad init --mcp-frontmatter |
mcp-frontmatter-init.md |
Write MCP config into agent frontmatter instead of .copilot/mcp-config.json |
Agent harnesses requiring frontmatter MCP |
| Tiered memory (hot/cold/wiki) | tiered-memory.md |
Implementation of #600/#595 | Anyone hitting context bloat |
| Teams comms adapter | teams-comms-adapter.md |
Microsoft Teams comm channel | Enterprise users |
reflect skill |
reflect-skill.md |
In-session learning capture | All agents that should learn from mistakes |
error-recovery skill |
error-recovery-skill.md |
Standard agent failure recovery patterns | All squads |
squad export --repo / --branch |
repo-import-export.md |
Push/pull Squad config via GitHub Contents API | Distributed teams |
skill-security-scanner |
skill-security-scanner.md |
Markdown-aware skill security scanning | Security-conscious teams |
/fleet hybrid dispatch |
fleet-dispatch-hybrid.md |
Parallel issue analysis (2.9× faster than sequential) | Heavy Ralph users |
| Dual-mode capabilities | dual-mode-capabilities.md |
Routing for dual-mode deployment | Multi-deploy teams |
Note: squad discover / squad delegate exist in code (packages/squad-cli/src/cli/commands/cross-squad.ts) — covered partially by docs/features/distributed-mesh.md but neither command has a how-to section users would find by searching for discover or delegate.
Proposed remediation
Three approaches, in order of effort:
-
Quick wins — stub pages for high-traffic features: Create
docs/features/preset.md,docs/features/coordinator-as-agent-export.md,docs/features/discover.md(cross-squad commands). These have user-facing commands and should be the priority. -
Per-changeset doc audit: For each remaining undocumented feature, either (a) write a doc page, (b) add coverage to an existing related page, or (c) explicitly mark internal-only.
-
Doc gate in changeset workflow: Require new changesets that introduce user-facing commands or flags to either include a doc page in the same PR, or carry a
docs-followup-requiredlabel that's tracked in a parent issue.
Related
- I'm sending a follow-up PR for the top 3 high-priority pages (preset, coordinator-as-agent-export, discover)
- Live docs site sitemap: https://bradygaster.github.io/squad/sitemap-0.xml (no
preset,discover,cross-squad, orcoordinator-as-agentURLs anywhere)
Activity
docs: add feature pages for preset, cross-squad discover/delegate, an…
docs: add feature pages for remaining 8 v0.10 features (tiered-memory…