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

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw — Claude is a first-class engine with quick-start auth, near-parity examples (claude leads inline engine: declarations in .github/workflows), and 14/15 tools are engine-agnostic. No critical blockers (score 7.5/10, stable for 11 consecutive daily runs). The single most persona-relevant obstacle persists: CLAUDE_CODE_OAUTH_TOKEN (the token Claude Code / Claude Max/Teams users naturally have) is silently ignored — only ANTHROPIC_API_KEY or WIF works — and this caveat lives only in auth.mdx, never in the quick-start a new user follows.

Severity Findings

Critical / Major / Minor (click to expand)

🚫 Critical Blockers

None. Claude is documented end-to-end (quick-start.mdx:71,84-88), tools are engine-agnostic, and Claude has its own auth callout.

⚠️ Major Obstacles

1. CLAUDE_CODE_OAUTH_TOKEN silently ignored. auth.mdx:201 — "CLAUDE_CODE_OAUTH_TOKEN is not supported ... if you have set [it] as a repository secret, it will be ignored — configure ANTHROPIC_API_KEY instead." Re-stated at auth.mdx:349 (401 troubleshooting). A Claude Code user reaching for their existing OAuth token sets a secret that does nothing, with no mention in quick-start.mdx. This is the exact persona's first stumble.
2. gh aw init defaults to Copilot artifacts. cli.md:133,139 — default init generates Copilot dispatcher/designer/agent; --engine claude is needed to "skip Copilot-specific artifacts" but is not surfaced in the quick-start steps.
3. Engine omitted = silent Copilot default. how-they-work.mdx:26 ("GitHub Copilot (default)"). Quick-start step-by-step NOTE callouts give full secret setup only for Copilot (quick-start.mdx:77-82) and Anthropic (84-88); Codex/Gemini get only a secret name.

💡 Minor Confusion

• Copilot-first nudge: quick-start.mdx:29 — "If you already have GitHub Copilot, start there — it requires no extra account setup." No "why Claude vs Copilot?" guidance anywhere.
• Thinner Claude hand-holding: Copilot PAT NOTE is 5 lines (quick-start.mdx:77-82); Anthropic is 2 (84-88).
• No supported Claude model list / default model documented in any core doc.
• custom engine: 0 standalone examples; not in quick-start engine picker.

Engine & Tool Matrix

Engine	Setup in quick-start	Examples (.github/workflows)	Auth (secret)	Score
Copilot (default)	✅ Full NOTE w/ PAT steps qs:77-82	Dominant (256 raw / leads object form)	COPILOT_GITHUB_TOKEN or org-billing	9
Claude	✅ NOTE, 2-line qs:84-88	Near-parity (103 raw; leads inline engine: form)	ANTHROPIC_API_KEY / WIF; ⚠️ OAuth token ignored	7
Codex	⚠️ Secret named only, no steps qs:71	Thinnest of 3 real engines (39 raw, ~5 prod)	OPENAI_API_KEY	6
Custom	❌ Not in picker qs:70	0 standalone	—	3

Tools: 14/15 engine-agnostic (declared uniformly in frontmatter, adapted per-engine by the compiler). Sole ambiguous tool: web-search — built-in only on Claude + Codex, and disabled-by-default for Codex (tools.md:65-67). No copilot-only / claude-only tools exist — strong positive for engine portability.

Parity observations: Copilot dominates raw counts (inflated by docs/test snippets), but .github/workflows frontmatter — the real signal — shows Claude at near-parity and leading the inline short engine: claude form. Test fixtures under pkg/cli/workflows are deliberate per-engine triplets (test-claude-* / test-copilot-* / test-codex-*), confirming intentional feature parity.

Auth Gaps

Per-engine auth gaps (from auth-doc-extractor)

• custom engine documented nowhere in quick-start; add-wizard picker (qs:70) omits it.
• Codex / OPENAI_API_KEY has no inline step-by-step NOTE (unlike Copilot qs:77-82 and Anthropic qs:84-88).
• Gemini / GEMINI_API_KEY also lacks an inline setup NOTE despite being selectable.
• Claude: no mention of Bedrock/Vertex/alternative providers or model selection — only the direct ANTHROPIC_API_KEY path is shown in quick-start (WIF keyless exists at auth.mdx:207-271 but isn't surfaced).
• No guidance on org-vs-repo secrets, rotation, or token expiry.
• CLAUDE_CODE_OAUTH_TOKEN unsupported — documented only in auth.mdx:199-201,349, absent from quick-start.

Recommended Actions

Priority 1 (persona-blocking): Add a one-line warning to quick-start.mdx next to the Anthropic secret NOTE (qs:84-88): "Claude Code's CLAUDE_CODE_OAUTH_TOKEN is not supported — use ANTHROPIC_API_KEY." Mirrors auth.mdx:201. Cheapest fix, highest persona impact; recurred 11 runs.

Priority 2: In the quick-start engine-selection step, surface that omitting engine: defaults to Copilot and that gh aw init --engine claude skips Copilot artifacts (cli.md:139). Expand the Anthropic NOTE to step-parity with the Copilot PAT NOTE; add inline secret steps for Codex/Gemini.

Priority 3: Add a short "Choosing an engine" section (why Claude vs Copilot, supported Claude models/default) and at least one custom-engine example.

References: §28239790379 · auth.mdx:199-201,349 · quick-start.mdx:29,71,77-88 · cli.md:133,139

Generated by 📝 Claude Code User Documentation Review · 310.2 AIC · ⌖ 37 AIC · ⊞ 5.5K · ◷

• expires on Jun 27, 2026, 5:12 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-27T13:12:48.416Z.

Closed by Workflow