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

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw: Claude is a first-class engine, quick-start includes inline ANTHROPIC_API_KEY setup, and ~all tools are engine-agnostic. 0 critical blockers. Overall score 7.5/10 (stable vs 2026-06-15). The single most persona-relevant gap persists: CLAUDE_CODE_OAUTH_TOKEN is silently unsupported — only ANTHROPIC_API_KEY works, and this caveat lives in the auth reference, not the quick-start path a new user follows.

Severity Findings

🚫 Critical (0) · ⚠️ Major (3) · 💡 Minor (2) — click to expand

🚫 Critical Blockers: None. Claude works end-to-end via engine: claude + ANTHROPIC_API_KEY.

⚠️ Major Obstacles

1. CLAUDE_CODE_OAUTH_TOKEN unsupported / silently ignored (reference/auth.mdx:~199). Only ANTHROPIC_API_KEY works; provider OAuth (Claude Max/Teams billing) is rejected. This hits the exact persona — a Claude Code user likely has an OAuth token, not a raw API key. The caveat is absent from setup/quick-start.mdx. Fix: add a NOTE in quick-start: "Claude Max/Teams OAuth tokens are not supported — create an ANTHROPIC_API_KEY in the Anthropic Console."
2. gh aw init / add-wizard default to Copilot artifacts (setup/cli.md:139,164). --engine claude exists (cli.md:139, "Skip Copilot-specific artifacts") but is never surfaced in quick-start steps, so a Claude user generates Copilot scaffolding by default. Fix: show gh aw init --engine claude in quick-start.
3. Engine omitted = silent Copilot default (how-they-work.mdx:26, quick-start.mdx:71). Inline secret callouts in quick-start cover only Copilot + Anthropic, not Codex/Gemini. A user who skips engine: unknowingly gets Copilot. Fix: state the default explicitly and add per-engine secret callouts.

💡 Minor Confusion
4. Copilot-first ordering everywhere; no "why Claude vs Copilot" guidance to help a non-Copilot user choose confidently.
5. Custom engine has ~1 example (shared genaiscript.md) and no dedicated auth section in quick-start.

Engine & Tool Matrix

Engine	Setup in quick-start	Examples	Auth secret	Score
Copilot (default)	✅ inline	~135 (dominant)	copilot-requests:write or COPILOT_GITHUB_TOKEN PAT	9
Claude	✅ inline ANTHROPIC_API_KEY	~66 (near-parity in docs/review/analysis families)	ANTHROPIC_API_KEY (+ keyless WIF/OIDC)	7
Codex	⚠️ ref only	~15	OPENAI_API_KEY / CODEX_API_KEY	6
Custom	⚠️ ref only	~1	GH_AW_GITHUB_TOKEN (optional)	4

Counts from raw frontmatter scan likely over-count nested/substring forms (verified runs land ~copilot53/claude48); the signal is Claude has strong, near-parity coverage — a positive for adoption. parity_observations: Copilot dominant (~39%), Claude ~19% spanning smoke + production workflows, Codex specialized, custom single template.

Tools (reference/tools.md): 11 documented, 10 engine-agnostic (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy). 1 caveated: web-search is disabled by default for Codex (tools.md:67) — not Copilot-only; available to Claude. Timeout defaults differ (Claude 60s, Codex 120s — tools.md:157). No Claude-only or Copilot-only tools → near-total feature parity for Claude users.

Auth Gaps

auth-doc-extractor findings

• CLAUDE_CODE_OAUTH_TOKEN unsupported (critical, persona) — ignored if set; must use ANTHROPIC_API_KEY (auth.mdx:~199).
• No inline guidance to obtain ANTHROPIC_API_KEY in the wizard flow (medium) — wizard links to reference instead of an inline step (quick-start.mdx:71).
• Keyless WIF/OIDC requires out-of-band Anthropic federation-rule setup not in quick-start (medium) (since v0.79.6, 2026-06-11).
• GitHub MCP config for Claude deferred to reference docs, not quick-start (low).
• Custom endpoints (ANTHROPIC_BASE_URL via engine.env) only in auth reference (low).

Recommended Actions

Priority 1 — Add a quick-start NOTE that CLAUDE_CODE_OAUTH_TOKEN / Claude Max-Teams OAuth is unsupported and ANTHROPIC_API_KEY is required (closes the #1 persona blocker).

Priority 2 — Surface gh aw init --engine claude in quick-start; state the silent Copilot default explicitly; add per-engine inline secret callouts (Codex/Gemini/Custom).

Priority 3 — Add a short "choosing an engine / why Claude" section and a standalone custom-engine example + auth note.

References: §27623629779

Generated by 📝 Claude Code User Documentation Review · 147.3 AIC · ⌖ 12.2 AIC · ⊞ 4.9K · ◷

• expires on Jun 17, 2026, 6:18 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-17T14:18:53.496Z.

Closed by Workflow