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

[github-actions[bot]]

Executive Summary

A Claude Code user who avoids Copilot can onboard fully on standard GitHub with zero Copilot dependency: pass --engine claude and set ANTHROPIC_API_KEY (or configure WIF keyless). No tool is Copilot-, Claude-, or Codex-exclusive. Overall score 7.5/10, 0 critical blockers — stable across 25 consecutive runs. The single most persona-relevant friction remains: CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported/silently-ignored and this caveat never appears in the quick-start — a Claude Code user's most likely wrong assumption surfaces only after failure.

Severity Findings

Critical / Major / Minor (click to expand)

Critical Blockers: none. Every Copilot step has a working Claude-equivalent path; capability parity is intact.

Major Obstacles

1. No OAuth / PAT-free path for Claude. CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token, Claude Max/Teams billing) is not supported and silently ignored — docs/reference/auth.mdx:206-208, restated at troubleshooting auth.mdx:356. Only ANTHROPIC_API_KEY (or Anthropic WIF) works. The quick-start Claude tab (quick-start.mdx:97-101) shows only the static console key, so the exact persona hits this only after a run fails. Copilot, by contrast, has a genuine PAT-free path via copilot-requests: write + ${{ github.token }} (auth.mdx:15).
2. gh aw init defaults to Copilot artifacts; engine omission silently defaults to Copilot. gh aw init emits Copilot-specific artifacts unless --engine claude (cli.md:142); an omitted engine: field makes the runtime default to Copilot (37 of 256 workflow files). This consequence is disclosed only at quick-start.mdx:75, not in Prerequisites — a Claude-only user who removes/omits engine: gets a Copilot run that fails on their Anthropic key.
3. Quick-start auth coverage is uneven. Dedicated secret callouts spell out Copilot + Anthropic + Codex in detail; Gemini is prereq-only with no auth block (quick-start.mdx:30 vs :97-112). WIF keyless auth (auth.mdx:214-278) — the closest thing to a keyless Claude path — is never surfaced in the quick-start or the add-wizard.

Minor Confusion

• Copilot-first nudge in Prerequisites: "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/version documented (architecture.mdx:280); crush appears in the CLI secrets-bootstrap list (cli.md:260) but is otherwise undocumented.

Engine & Tool Matrix

Engine	Setup in quick-start	Examples (.github/workflows)	Auth	Score
Copilot (default)	Full callout + PAT-free path	121 explicit (~158 w/ 37 omitted)	copilot-requests:write or COPILOT_GITHUB_TOKEN	9
Claude	Full callout, API-key only	60 (leads inline-string form 45; dedicated smoke-claude.md)	ANTHROPIC_API_KEY or WIF; OAuth token ignored	7
Codex	Callout present	14	OPENAI_API_KEY/CODEX_API_KEY	7
Custom	None	0 standalone (shared/genaiscript.md only)	engine.env base-url, no quick-start section	4

Parity observations: Copilot outnumbers Claude ~2.6:1 including silent defaults, but Claude leads the inline-string engine: claude form (45 vs 29) and has a dedicated smoke test — Claude is first-class, not an afterthought. Tools: 11/12 engine-agnostic, 0 engine-exclusive. Only web-search is engine-dependent (Codex disabled-by-default, others via MCP) — tools.md:56-68. No Copilot-only, Claude-only, or Codex-only tool exists — a strong parity positive.

Auth Gaps

Gap	Where documented	Surfaced in quick-start?
CLAUDE_CODE_OAUTH_TOKEN unsupported/ignored	auth.mdx:206-208, :356	❌ No
Anthropic WIF keyless (OIDC)	auth.mdx:214-278	❌ No
PAT-free path for Claude	does not exist (Copilot-only)	❌ N/A
Gemini secret setup	prereq mention quick-start.mdx:30	❌ No dedicated block

Recommended Actions

Priority 1 — Add a one-line note to the quick-start Claude auth tab (quick-start.mdx:97-101): "CLAUDE_CODE_OAUTH_TOKEN and Claude Max/Teams OAuth billing are not supported — use ANTHROPIC_API_KEY." This closes the persona's #1 friction point at the exact moment of setup.

Priority 2 — In Prerequisites/Step 2, state that omitting engine: (or running gh aw init without --engine) defaults to Copilot and will fail with only an Anthropic key. Surface WIF keyless as the Claude "no-static-secret" option with a link to auth.mdx:214-278.

Priority 3 — Add a Gemini quick-start auth block for parity; add at least one custom-engine standalone example; document the default Claude model and the crush engine.

References: §29152985138 · §29094634866 · §29021096731

Trend: stable vs 2026-07-10 — score 7.5, 0 critical (25 runs running). Identical 3 major gaps persist; auth.mdx re-read this run confirmed the OAuth-token caveat verbatim.

Generated by 📝 Claude Code User Documentation Review · 424.8 AIC · ⌖ 41.6 AIC · ⊞ 5.2K · ◷

• expires on Jul 12, 2026, 4:55 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-12T12:55:12.125Z.

Closed by Workflow