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

[github-actions[bot]]

Executive Summary

A Claude Code user can fully onboard to gh-aw without touching GitHub Copilot — the Quick Start documents the Claude engine, ANTHROPIC_API_KEY, and engine: claude frontmatter. No critical blockers. The friction is that Copilot is the silent default everywhere (init artifacts, omitted-engine behavior, doc ordering), and the one genuine trap — Claude OAuth tokens are unsupported — is buried in auth.mdx, not the Quick Start. Overall score: 7.5/10, stable vs. the last two daily reviews (0 critical, 3 persistent major gaps).

Severity Findings (Critical / Major / Minor)

🚫 Critical Blockers

None. The Claude path is documented end-to-end.

⚠️ Major Obstacles

1. Claude OAuth tokens (Max/Teams) are silently unsupported. Only ANTHROPIC_API_KEY works; CLAUDE_CODE_OAUTH_TOKEN is explicitly ignored. This directly hits the Claude Code persona — many such users have a Max/Teams subscription, not a console API key. The caveat lives in reference/auth.mdx:200-202 but is absent from setup/quick-start.mdx, where a Claude user looks first.
   Fix: add a callout in quick-start.mdx near the ANTHROPIC_API_KEY block (lines 84-88): 'Claude subscription OAuth tokens are not supported — use a Console API key.'

2. gh aw init / add-wizard default to Copilot artifacts. --engine claude skips Copilot-specific artifacts (cli.md:135, wizard cli.md:164) but this flag is not surfaced in the Quick Start. A Claude user following the happy path generates Copilot scaffolding.
   Fix: show gh aw init --engine claude in quick-start.mdx as a first-class alternative.

3. Omitting engine: silently defaults to Copilot (how-they-work.mdx:26); 34 of 246 example workflows rely on this implicit default. The Quick Start's inline secret callouts cover only Copilot + Anthropic (quick-start.mdx:71,77-88) — Codex/Gemini users get no inline guidance.
   Fix: state the default explicitly and add Codex/Gemini secret callouts (or link them).

💡 Minor Confusion

• Copilot-first ordering in every list (README.md:40, how-they-work.mdx:26, architecture.mdx:279) with no 'why choose Claude vs Copilot?' guidance.
• Custom engine has 0 standalone examples and no dedicated section; custom endpoints (ANTHROPIC_BASE_URL / engine.env) appear only in auth.mdx:226-244, not the Quick Start.
• crush engine is a valid --engine value (cli.md:251) but is missing from the engine prose lists — minor inconsistency.

Engine & Tool Matrix

Engine	Setup docs	Examples (.github/workflows)	Auth	Score
Copilot	✅ default, wizard-first	129	copilot-requests: write or COPILOT_GITHUB_TOKEN PAT	9/10
Claude	✅ documented, not default	64 (~1⁄2 of Copilot)	ANTHROPIC_API_KEY only — no OAuth	7/10
Codex	✅ in auth ref, thin quick-start	14	OPENAI_API_KEY (or CODEX_API_KEY)	6/10
Custom	⚠️ engine.env only, no section	0	per-engine *_BASE_URL + secret	3/10

Tool parity (reference/tools.md): 14 documented tools — 13 engine-agnostic, 0 Copilot-only, 0 Claude-only, 1 unclear (web-search: is 'engine-dependent': needs MCP on some engines, off-by-default on Codex, tools.md:62,65,67). Tool access is essentially engine-neutral — a strong positive for Claude adoption.

Parity observation: Copilot has ~2× Claude's example count and dominates the daily-* / smoke-test families; Claude examples cluster in analysis, auditing, docs, and safe-output review and favor inline engine: claude. Functionally near-parity, but the example imbalance reinforces a Copilot-default perception.

Auth Gaps

Per-engine auth detail

• Claude: ANTHROPIC_API_KEY from console.anthropic.com (quick-start.mdx:84-88). Gap: CLAUDE_CODE_OAUTH_TOKEN / subscription OAuth explicitly unsupported and ignored (auth.mdx:200-202,282) — not repeated in Quick Start.
• Copilot: copilot-requests: write (no PAT) or fine-grained COPILOT_GITHUB_TOKEN PAT; GitHub App/OAuth tokens not accepted for this secret (auth.mdx:144,306).
• Codex: OPENAI_API_KEY (or CODEX_API_KEY tried first) (auth.mdx:208-224); no inline Quick Start callout.
• Custom: no standalone recipe — *_BASE_URL via engine.env + referenced secret; deferred to reference/engines/ (auth.mdx:226-244).

Recommended Actions

Priority 1 (blocks Claude Code users): Add a Quick Start callout stating Claude OAuth/subscription tokens are unsupported and a Console ANTHROPIC_API_KEY is required (quick-start.mdx:84-88).

Priority 2 (reduces Copilot-default friction): Surface gh aw init --engine claude in the Quick Start; explicitly document that omitting engine: defaults to Copilot; add Codex/Gemini secret callouts.

Priority 3 (polish): Add a short 'choosing an engine' comparison, give the custom engine a dedicated section + one example, and reconcile the crush engine in the prose lists.

References: §27467397420

Generated by 📝 Claude Code User Documentation Review · 434.4 AIC · ⌖ 11.2 AIC · ⊞ 5.5K · ◷

• expires on Jun 14, 2026, 5:10 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-14T13:10:51.006Z.

Closed by Workflow