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

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw with zero critical blockers — Claude is a first-class engine with a dedicated quick-start auth callout, 60 real workflow examples, and no Claude-only/Copilot-only tool split. The single most persona-relevant obstacle persists for a 26th run: Claude subscription/OAuth billing (CLAUDE_CODE_OAUTH_TOKEN) is silently ignored and this caveat lives only in auth.mdx, never in the quick-start. Overall score 7.5/10, stable.

Severity Findings (Critical → Major → Minor)

🔴 Critical Blockers: None. Claude onboarding is Copilot-free and complete.

🟠 Major Obstacles

1. No OAuth/subscription path for Claude. CLAUDE_CODE_OAUTH_TOKEN is "not supported... it will be ignored — configure ANTHROPIC_API_KEY instead" (auth.mdx:206-208). A Claude Pro/Max/Teams user who reuses their Claude Code OAuth token hits a silent failure. The quick-start Claude tab (quick-start.mdx:97-101) only shows the console API key and never warns about this. Copilot users get a PAT-free copilot-requests: write org-billing shortcut (cli.md:171) with no Claude equivalent.
2. Copilot is the invisible default. gh aw init emits Copilot-specific artifacts unless --engine claude is passed (cli.md:142); omitting engine: silently selects Copilot (how-they-work.mdx:26; 33 repo workflows do this). The opt-out is disclosed only at quick-start.mdx:75, not in prerequisites.
3. Uneven secret setup. Quick-start details Copilot + Anthropic + Codex, but Gemini is prerequisite-only with no auth block; keyless WIF (documented in auth.mdx) is never surfaced in the quick-start (quick-start.mdx:81,109-112).

🟡 Minor Confusion

• Copilot-first nudge "If you already have GitHub Copilot, start there — it requires no extra account setup" (quick-start.mdx:30); no why-Claude-vs-Copilot guidance.
• Custom engine has 0 standalone examples (only shared/genaiscript.md); no default Claude model documented (architecture.mdx:280); crush appears in the secrets-bootstrap list (cli.md:260) but is otherwise undocumented.

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	Default; init emits artifacts	125 explicit + 33 implicit ≈158	PAT or PAT-free copilot-requests:write	9/10
Claude	--engine claude (not in prereqs)	60 (leads inline-string form)	ANTHROPIC_API_KEY / WIF; OAuth ignored	7.5/10
Codex	--engine codex	14	OPENAI_API_KEY/CODEX_API_KEY; web-search off by default	6/10
Custom	engine.env overlay	0 standalone	via engine.env	4/10

Tool classification: 12 tools — 10 builtin/engine-agnostic, 1 MCP (custom mcp-servers), 1 engine-specific (web-search, disabled-by-default on Codex, tools.md:67). 0 Copilot-only and 0 Claude-only tools — strong parity positive.

Parity (from example counter): Copilot leads ~2:1 over Claude and ~9:1 over Codex; custom has no worked example anywhere. Claude leads the inline-string engine: claude form while Copilot dominates the object form — a learner grepping only engine: copilot undercounts. 33 of 256 workflows (~13%) silently inherit the Copilot default. Extra engines (pi=21, plus crush/opencode/antigravity/gemini) exist beyond the four documented.

Auth Gaps

• Claude: ANTHROPIC_API_KEY (quick-start.mdx:97-101) or keyless WIF (auth.mdx, not surfaced). Gap: OAuth subscription token silently ignored (auth.mdx:206-208); no key-scoping/rate-limit/spend guidance vs Copilot's step-by-step PAT scoping.
• Codex: OPENAI_API_KEY (or CODEX_API_KEY); web-search disabled by default.
• Gemini: GEMINI_API_KEY — listed as prerequisite but no dedicated quick-start auth block.
• All non-Copilot engines: the reviewed core files never state the failure/fallback behavior when the engine's secret is missing at run time.

Recommended Actions

Priority 1 — close the OAuth gap for the Claude persona. Add a NOTE in the quick-start Claude tab: "CLAUDE_CODE_OAUTH_TOKEN / Claude subscription billing is not supported — use ANTHROPIC_API_KEY or keyless WIF," linking auth.mdx:206-208. This is the single change that most improves Claude-user onboarding.

Priority 2 — make the default explicit. In prerequisites/Step 2, state that omitting engine: (or running gh aw init without --engine) selects Copilot, and show --engine claude inline. Add the WIF keyless option to the quick-start.

Priority 3 — even out coverage. Add a Gemini quick-start auth block; add one standalone engine: custom example; document the default Claude model and the pi/crush engines; add brief why-Claude-vs-Copilot guidance.

References:

• §29192972380
• §29152985138
• §28944070081

Generated by 📝 Claude Code User Documentation Review · 266.8 AIC · ⌖ 39.7 AIC · ⊞ 5.2K · ◷

• expires on Jul 13, 2026, 4:52 AM UTC-08:00