[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-06-24

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw: Claude is a first-class engine, the quick-start includes an ANTHROPIC_API_KEY setup callout, and every documented tool is engine-agnostic (13/14; web-search is the only engine-dependent one). No critical blockers. The dominant gap — persistent across 10 daily runs — is that the exact Claude Code persona (Claude Pro/Max/Teams OAuth users) is silently rejected: CLAUDE_CODE_OAUTH_TOKEN is unsupported and ignored, documented only in auth.mdx:201/faq.md:368, never surfaced in the quick-start. Overall score: 7.5/10 (stable).

Severity Findings

Critical / Major / Minor (with file refs)

🚫 Critical Blockers: None. Claude works end-to-end via engine: claude + ANTHROPIC_API_KEY.

⚠️ Major Obstacles

1. OAuth token silently ignored — CLAUDE_CODE_OAUTH_TOKEN (Claude Max/Teams/Pro subscription auth, the natural credential for this persona) is not supported and ignored if set. Buried in auth.mdx:201 + faq.md:368; absent from setup/quick-start.mdx. A subscription-only Claude user hits a confusing failure. Fix: add a NOTE in quick-start step ~71 stating only ANTHROPIC_API_KEY or WIF works, not the OAuth token.
2. gh aw init defaults to Copilot artifacts — generates Copilot dispatcher/agent unless --engine claude is passed (cli.md:133,138), but that flag is never shown in the quick-start steps. Fix: show gh aw init --engine claude in the quick-start.
3. Omitting engine: silently defaults to Copilot (how-they-work.mdx:26) across 35 example workflows; quick-start inline secret callouts cover only Copilot + Anthropic, not Codex/Gemini (quick-start.mdx:70-71,84-87). Fix: make the default explicit and add per-engine secret callouts.

💡 Minor Confusion

• Copilot-first ordering everywhere (README.md:40, how-they-work.mdx:26); no "why Claude vs Copilot" guidance.
• custom engine: 0 standalone example workflows (only a shared/genaiscript.md import fragment) and no quick-start auth section.
• Codex setup is thin — quick-start.mdx:71 names OPENAI_API_KEY with a link but no step-by-step, unlike Copilot (78-81) and Claude (84-87).

Engine & Tool Matrix

Engine	Setup (quick-start)	Examples (.github/workflows)	Auth	Score
Copilot (default)	✅ default path, org-billing or PAT choice	121	COPILOT_GITHUB_TOKEN or copilot-requests:write, fully documented	9
Claude	⚠️ works but --engine claude not surfaced	57	✅ ANTHROPIC_API_KEY in quick-start + WIF keyless; ❌ OAuth token unsupported	7
Codex	⚠️ thin steps, link only	16	OPENAI_API_KEY, named not detailed	6
Custom	❌ no quick-start coverage	0 (import fragment only)	❌ undocumented in setup docs	3

Tool classification (reference/tools.md): 13/14 engine-agnostic, 1 unclear (web-search, engine-dependent — Codex disables it by default unless declared, tools.md:62-67). No copilot-only, claude-only, or codex-only tools exist — a strong positive for Claude adoption. Only cross-engine variance is timeout defaults (Claude 60s / Codex 120s, tools.md:157).

Parity: Copilot dominates (~71% of engine-declaring files); Claude has solid coverage (57, near-half of Copilot, concentrated in analysis/security/reporting workflows) plus smoke-test parity (smoke-claude.md). Codex modest (16). Custom has zero standalone runnable parity.

Auth Gaps

Per-engine auth extraction

Engine	Secret	Gap
copilot	COPILOT_GITHUB_TOKEN	distinct from GITHUB_TOKEN; org-billing alternative documented
claude	ANTHROPIC_API_KEY	✅ in quick-start; OAuth token unsupported & not warned in quick-start; no Bedrock/Vertex/model-selection mention
codex	OPENAI_API_KEY	no step-by-step key creation in quick-start
custom	none	no auth/secret/setup documented in quick-start or cli.md

Both setup docs defer full credential specifics to reference/auth.mdx (not in setup/), so a quick-start-only reader misses the OAuth caveat and WIF option entirely.

Recommended Actions

Priority 1 — Add a quick-start NOTE: Claude requires ANTHROPIC_API_KEY (or WIF); CLAUDE_CODE_OAUTH_TOKEN / subscription OAuth is not supported. Closes the single most persona-relevant gap (open 10 runs).

Priority 2 — Surface gh aw init --engine claude in quick-start steps; make the implicit Copilot default explicit; add per-engine (Codex/Gemini) secret callouts.

Priority 3 — Add a "choosing an engine" / why-Claude-vs-Copilot section; add at least one standalone engine: custom example with auth notes; flesh out Codex key-creation steps.

---

Note: cache-memory (review-history.jsonl) write was blocked by sandbox this run (working-dir-only writes); trend data — score 7.5, 0 critical, identical 3 major gaps — is reported inline above.

Generated by 📝 Claude Code User Documentation Review · 331.2 AIC · ⌖ 35.5 AIC · ⊞ 5.5K · ◷

• expires on Jun 25, 2026, 5:18 AM UTC-08:00