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

[github-actions[bot]]

Executive Summary

A Claude Code user can onboard to gh-aw without Copilot — Claude is a first-class engine with a dedicated ANTHROPIC_API_KEY callout in quick-start and 60 workflow examples. But three documentation gaps persist unchanged across all 16 daily reviews (score 7.5/10, 0 critical blockers). Key finding: the single most persona-relevant obstacle is that CLAUDE_CODE_OAUTH_TOKEN — the token Claude Code / Claude Max & Teams users already have — is silently ignored, and this caveat lives only in auth.mdx:199-201, never surfaced in quick-start.

Answers to the Three Key Questions

1. Onboarding without Copilot? Yes. Prereqs list Claude/Codex/Gemini as valid AI accounts (quick-start.mdx:29) and the add-wizard offers engine selection (quick-start.mdx:70).
2. Copilot-only features? None. tools.md documents 14 engine-agnostic tools; only web-search is engine-dependent (Codex disabled-by-default). No copilot-only/claude-only tools exist.
3. Claude clarity? Setup, auth, and examples exist, but Copilot-first ordering + the OAuth-token gap add friction.

Severity Findings (Critical → Major → Minor)

🚫 Critical Blockers

None. Claude is fully documented; a Claude Code user can complete every step.

⚠️ Major Obstacles

1. CLAUDE_CODE_OAUTH_TOKEN silently ignored — only ANTHROPIC_API_KEY (or WIF) works. Caveat is buried in auth.mdx:199-201; the quick-start Claude callout (quick-start.mdx:84-88) never warns that OAuth/subscription auth won't work. A Claude Code user who reuses their existing OAuth token gets a silent failure. This directly hits the persona.
2. gh aw init defaults to Copilot artifacts — --engine claude skips them (cli.md:135,139), but quick-start Step 2 uses add-wizard and never surfaces the init --engine flag.
3. Engine omitted = silent Copilot default — 35 workflow files omit engine: and get Copilot. Quick-start has dedicated NOTE callouts only for Copilot (quick-start.mdx:77-81) and Anthropic (84-88); Codex/Gemini appear only as a wizard bullet at quick-start.mdx:71 with no inline setup.

💡 Minor Confusion

• Copilot-first nudge in prereqs: "If you already have GitHub Copilot, start there" (quick-start.mdx:29); no "why Claude vs Copilot" guidance.
• WIF keyless OIDC auth (auth.mdx:207-269) and the PAT-free copilot-requests: write path are absent from quick-start.
• custom engine: 0 standalone examples, no dedicated auth section.

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	✅ Default (init builds artifacts)	124 (+35 omitted ≈159)	✅ Dedicated PAT callout qs:77-81	🟢 High
Claude	⚠️ Needs --engine claude	60 (leads inline form 49 vs 32)	⚠️ ANTHROPIC_API_KEY callout qs:84-88, OAuth caveat missing	🟡 Good
Codex	⚠️ Wizard only	14	⚠️ No inline callout, OPENAI_API_KEY wizard bullet qs:71	🟡 Medium
Custom	❌ Not in quick-start	0	❌ None	🔴 Low

Tools: 14/15 engine-agnostic (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers, timeouts). Only web-search is engine-dependent (tools.md:62,67 — Codex disabled-by-default). No copilot-only or claude-only tools.

Parity: Copilot ~2.6× Claude by workflow count, but Claude leads the inline engine: string form (49 vs 32); Copilot's lead comes from object-form blocks carrying sub-keys. Claude reaches near-parity in analysis/review/safe-output families.

Auth Gaps

Gap	Ref	Severity
CLAUDE_CODE_OAUTH_TOKEN not mentioned; user setting it gets no warning it's ignored	quick-start.mdx:84-88 / auth.mdx:199-201	High
ANTHROPIC_API_KEY-only caveat (OAuth/Max/Teams unsupported) not surfaced in quick-start	quick-start.mdx:84-88	High
Unequal callouts: Copilot+Anthropic get step-by-step; Codex/Gemini get only wizard bullet	quick-start.mdx:71	Medium
WIF keyless OIDC auth absent from quick-start	auth.mdx:207-269	Medium
PAT-free copilot-requests: write path not surfaced	auth.mdx:92-115	Medium
custom engine has no quick-start auth coverage	quick-start.mdx:70	Low

Recommended Actions

Priority 1 — Add a NOTE to the Claude callout (quick-start.mdx:84-88): "CLAUDE_CODE_OAUTH_TOKEN is not supported — Claude Code / Max / Teams OAuth tokens are ignored. Use ANTHROPIC_API_KEY." This closes the top persona blocker, unchanged for 16 runs.

Priority 2 — In quick-start Step 2, show the non-Copilot path explicitly (gh aw init --engine claude / engine: claude frontmatter) and note that omitting engine: defaults to Copilot. Give Codex/Gemini equal inline secret callouts.

Priority 3 — Add a short "Choosing an engine (Copilot vs Claude vs Codex)" section; surface WIF keyless auth and the copilot-requests: write PAT-free path in quick-start; add a custom engine example.

References:

• §28591962795
• §28520373607

Generated by 📝 Claude Code User Documentation Review · 587.7 AIC · ⌖ 36.5 AIC · ⊞ 5.5K · ◷

• expires on Jul 3, 2026, 5:18 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Claude Code User Documentation Review.

A newer discussion is available at Discussion #43193.