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

[github-actions[bot]]

Executive Summary

gh-aw is genuinely multi-engine and a Claude Code user can onboard: Claude is a first-class prerequisite, the quick-start has a dedicated ANTHROPIC_API_KEY setup block, all tools are engine-agnostic, and Claude is second-most-used across 258 workflows (62 explicit files). Score: 7.5/10, 0 critical blockers — unchanged for 17 consecutive daily runs. The single most persona-relevant obstacle remains that CLAUDE_CODE_OAUTH_TOKEN is silently ignored — Claude Pro/Max/Teams subscribers must obtain a separate ANTHROPIC_API_KEY, and that caveat lives only in auth.mdx, never in the quick-start a new user actually reads.

Severity Findings

🚫 Critical Blockers — none this run

No documentation gap fully prevents a Claude Code user from adopting gh-aw. Claude is a supported engine with quick-start auth instructions.

⚠️ Major Obstacles (3, all persistent)

1. CLAUDE_CODE_OAUTH_TOKEN unsupported / silently ignored — only ANTHROPIC_API_KEY (or WIF keyless) works. Caveat is at auth.mdx:199-201 but absent from quick-start.mdx. A Claude Code user with a Pro/Max/Teams subscription reasonably expects their existing OAuth login to work; it doesn't, and the quick-start never says so. → Add a one-line NOTE to the Anthropic setup step: "Claude subscription OAuth tokens are not supported — create an API key."
2. gh aw init defaults to Copilot artifacts — --engine claude is documented at cli.md:146 (# Skip Copilot-specific artifacts) but the quick-start add flow never surfaces the flag. → Show gh aw init --engine claude in the quick-start Step 2 example.
3. Omitting engine: silently defaults to Copilot — 23 of 258 workflow files rely on this implicit default. Quick-start spells out Copilot + Anthropic + Codex secrets in detail, but Gemini is a listed prerequisite (quick-start.mdx:29) with no dedicated auth block. → State the default explicitly and add a Gemini secret callout.

💡 Minor Confusion (2)

1. Copilot-first framing — quick-start.mdx:29: "If you already have GitHub Copilot, start there — it requires no extra account setup." No "why choose Claude vs Copilot" guidance anywhere. → Add a short engine-selection paragraph.
2. WIF keyless auth not surfaced — Anthropic github-oidc federation (auth.mdx:207-271) is the modern PAT-free path for Claude but never appears in the quick-start. Custom engine has just 1 example (design-decision-gate.md) and no auth section.

Engine & Tool Matrix

Engine	Setup in quick-start	Examples (.github/workflows)	Auth	Score
Copilot (default)	✅ Full + recommended path	153 (130 explicit + 23 implicit)	COPILOT_GITHUB_TOKEN or copilot-requests: write (PAT-free)	9/10
Claude	✅ ANTHROPIC_API_KEY block (qs:86)	62	API key or WIF (OAuth token not supported)	7.5/10
Codex	✅ OPENAI_API_KEY/CODEX_API_KEY (qs:96)	17	API key; Azure via OPENAI_BASE_URL	7/10
Custom / others (pi 21, gemini/crush/opencode/antigravity)	⚠️ prereq-only, no auth block	pi 21, custom 1, others 1 each	undocumented in quick-start	4/10

Tools (reference/tools.md): 12 documented — 11 engine-agnostic (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers), 0 Copilot-only / Claude-only / Codex-only, 1 unclear (web-search: engine-dependent, disabled-by-default for Codex). No tool is inaccessible to a Claude user.

Parity observation: Claude leads the inline-string engine: claude form; Copilot dominates the object form. Effective Claude:Copilot ratio ≈ 1:2.47, but near-parity in analysis/review/safe-output workflow families — good adoption signal.

Auth Gaps (from quick-start.mdx, per auth-doc-extractor)

• CLAUDE_CODE_OAUTH_TOKEN not supported — documented auth.mdx:199-201, missing from quick-start. (highest impact for this persona)
• Anthropic WIF keyless auth (auth.mdx:207-271) not surfaced in quick-start.
• GH_AW_GITHUB_TOKEN fallback (auth.mdx:151-178) for cross-repo writes not mentioned.
• Recommended copilot-requests: write PAT-free path (auth.mdx:92-116) shown only in tips, not the main flow.
• Custom engine has no auth documentation in either quick-start or auth.mdx.

Recommended Actions

Priority 1 (close the persona blocker): Add a NOTE to the quick-start Anthropic step — Claude subscription OAuth tokens are unsupported, use an API key or WIF. This single edit resolves the most-cited gap across 17 runs.

Priority 2: Surface gh aw init --engine claude in the quick-start add flow; state the implicit-Copilot default explicitly; add a Gemini secret callout.

Priority 3: Add an "engine selection / why Claude vs Copilot" paragraph; surface WIF keyless auth and a custom-engine auth example in the quick-start.

---

17-run trend: score flat at 7.5, 0 critical. The same 3 major gaps have persisted unchanged — these are documentation edits, not code work, and Priority 1 is a one-line fix.

Generated by 📝 Claude Code User Documentation Review · 238.1 AIC · ⌖ 36.1 AIC · ⊞ 5.5K · ◷

• expires on Jul 4, 2026, 5:14 AM UTC-08:00