[claude-code-user-docs-review] Claude Code User Documentation Review - 2026-07-15

[github-actions[bot]]

Executive Summary

A developer who uses Claude Code and deliberately avoids GitHub Copilot can adopt gh-aw — the Quick Start supports --engine claude and every tool is engine-agnostic. But the docs treat Copilot as the privileged default: it's the fallback engine, gh aw init scaffolds Copilot artifacts, and the README's hidden agent-onboarding block hardcodes Copilot with no Claude equivalent. Key finding: a Claude user who follows the README (rather than the Quick Start) provisions Copilot and never sets ANTHROPIC_API_KEY.

Severity Findings (Critical → Major → Minor)

🔴 Critical Blockers

1. README onboarding is Copilot-only. The hidden agent-onboarding block (README.md:13-41) hardcodes engine: copilot and copilot-requests: write with no Claude path or secret guidance. A Claude user (or an agent) following the README verbatim sets up Copilot and never configures ANTHROPIC_API_KEY. Fix: add a Claude branch (engine: claude + ANTHROPIC_API_KEY) or link to the Quick Start engine selector.

🟠 Major Obstacles

2. gh aw init defaults to Copilot artifacts (cli.md:147); --engine claude is needed to skip them (cli.md:153) but isn't surfaced in Quick Start. Fix: show gh aw init --engine claude in the first-run path.
3. Silent revert to Copilot. Removing/omitting engine: reverts the runtime to Copilot (quick-start.mdx:75); 33 of 256 example workflows declare no engine and therefore run on Copilot. A Claude user copying an example silently gets Copilot. Fix: warn prominently and/or set an explicit engine in all examples.
4. Claude auth stops at the API key. Core docs name only ANTHROPIC_API_KEY (quick-start.mdx:81); Bedrock/Vertex, model selection, and enterprise auth are deferred to /reference/auth/ and /reference/engines/ (not in the core pages). Fix: cross-link these from Quick Start's Claude tab.
5. Example parity gap. 124 copilot vs 61 claude worked examples (≈157 vs 61 counting the 33 defaults). Custom engine has 0 examples. Fix: add Claude equivalents for flagship examples.

🟡 Minor Confusion

6. Copilot documents two auth paths — org billing (no PAT) or COPILOT_GITHUB_TOKEN PAT (cli.md:176) — while Claude/Codex/Gemini show only the single API-key path; no "org billing" note for non-Copilot engines.
7. web-search is engine-dependent/ambiguous (tools.md:62-67): Codex disables it by default; some engines need third-party MCP servers. A Claude user can't tell at a glance whether it "just works."
8. Secrets bootstrap (cli.md:265) accepts --engine {copilot,claude,codex,gemini} but doesn't restate the engine→secret-name mapping.

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot (default)	gh aw init scaffolds it by default (cli.md:147)	124 (+33 defaults)	2 paths: org billing (no PAT) / COPILOT_GITHUB_TOKEN PAT (cli.md:176)	★★★★★
Claude	--engine claude / engine: claude (quick-start.mdx:69,163); init --engine claude skips Copilot (cli.md:153)	61	ANTHROPIC_API_KEY only; enterprise deferred (quick-start.mdx:81)	★★★☆☆
Codex	engine: codex; must declare web-search: to enable web (tools.md:67)	14	OPENAI_API_KEY / CODEX_API_KEY	★★☆☆☆
Custom	via mcp-servers (tools.md:184)	0 worked examples	n/a	★☆☆☆☆

Tools (all engine-agnostic — good news for Claude users): edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, custom mcp-servers — 11 engine-agnostic, 0 Copilot-only, 1 unclear (web-search, tools.md:62). No tool is gated to Copilot; Copilot's only privilege is being the default engine.

Parity: Copilot has ~2× Claude's example coverage; the default-engine bias widens the effective gap to ~157 vs 61. An experimental pi engine appears in 21 workflows (more than Codex's 14). Custom-engine users have no worked examples.

Auth Gaps

• Core how-they-work/architecture pages contain zero secret/API-key setup; auth is entirely offloaded to Quick Start + linked /reference/auth/ (architecture.mdx, how-they-work.mdx).
• Only Copilot gets a no-key/org-billing option documented; Claude/Codex/Gemini show a single API-key path only (cli.md:176).
• gh auth login --scopes repo,workflow appears only in quick-start.mdx:34; cli.md:403 separately notes workflows:write — no consolidated auth-scope reference.
• README onboarding block gives no secret-setup steps for any engine (README.md:13-41).

Recommended Actions

• Priority 1 (Critical): Add a Claude branch to the README onboarding block (engine: claude + ANTHROPIC_API_KEY) so README-only readers aren't funneled into Copilot.
• Priority 2 (Major): Surface gh aw init --engine claude in Quick Start; add an explicit engine to all 33 engine-unspecified example workflows and warn about the silent Copilot fallback; cross-link Claude enterprise auth (Bedrock/Vertex, model selection) from the Claude tab.
• Priority 3 (Minor): Note whether non-Copilot engines have org-billing options; clarify web-search behavior per engine in tools.md; restate engine→secret mapping in cli.md secrets bootstrap; add Claude equivalents for flagship examples to close the parity gap.

---

Data source: automated doc-reader + engine-example-counter scans of README + 5 core docs and 256 workflow files (2026-07-15). Note: this run could not persist to cache-memory (sandbox blocked /tmp/gh-aw/cache-memory), so trend history was not updated.

Generated by 📝 Claude Code User Documentation Review · 392.1 AIC · ⌖ 39.2 AIC · ⊞ 5.2K · ◷

• expires on Jul 16, 2026, 5:02 AM UTC-08:00