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

[github-actions[bot]]

Executive Summary

From a Claude Code user's perspective, gh-aw is fully adoptable with zero critical blockers — Claude is a first-class engine with quick-start auth, 61 workflow examples, a dedicated smoke test, and no Claude-only or Copilot-only tool gating (11/13 tools engine-agnostic). Key finding (persistent across 27 daily runs): the docs still assume an API-key mental model for Claude and never surface that CLAUDE_CODE_OAUTH_TOKEN is silently ignored — the exact friction point for a Claude Pro/Max/Teams subscriber who avoids Copilot. Overall score: 7.5/10 (stable).

Severity Findings (Critical to Major to Minor)

🔴 Critical Blockers: None. A Copilot-free Claude user can complete the entire quick-start with ANTHROPIC_API_KEY.

🟠 Major Obstacles

1. No PAT-free / OAuth path for Claude. Copilot gets an org-billing shortcut (permissions.copilot-requests: write, no PAT — README.md:40, cli.md:177), but Claude offers only a console API key (quick-start.mdx:97-108, README.md:41-42). CLAUDE_CODE_OAUTH_TOKEN (what Claude Code / Max subscribers already hold) is unsupported and silently ignored, and the quick-start Claude tab never says so. Fix: add a one-line note in the Claude tab: subscription OAuth tokens are not accepted; use an API key or WIF keyless auth.
2. gh aw init defaults to Copilot artifacts. Init emits Copilot-specific files unless --engine claude is passed (cli.md:148), and that flag is documented in the CLI reference but not surfaced in the quick-start add flow (quick-start.mdx:69,75). Fix: show --engine claude in the primary quick-start steps.
3. Omitted engine: = silent Copilot default. 33 example workflows omit engine: and fall back to Copilot (DefaultEngine=CopilotEngine); disclosed only at quick-start.mdx:75, not in prerequisites (how-they-work.mdx:26). Dedicated secret callouts detail Copilot + Anthropic + Codex, but Gemini is prereq-only with no auth block. Fix: make the default explicit in prerequisites; add a Gemini secret callout.

🟡 Minor Confusion

• Copilot-first nudge "start there — no extra account setup" (quick-start.mdx:30) with no "why Claude vs Copilot" guidance.
• No default Claude model / version documented anywhere in the six core docs (architecture.mdx:279).
• Anthropic API egress not listed in the firewall allowlist docs (architecture.mdx:227-237) — relevant when firewall: true.
• WIF keyless auth exists but is never surfaced in the quick-start.

Engine & Tool Matrix

Engine	Setup docs	Examples (.github/workflows)	Auth	Score
Copilot (default)	Full quick-start + init default	125 explicit (~158 w/ 33 omitted)	PAT or PAT-free org billing	9/10
Claude	Quick-start tab + --engine claude	61 (2nd, leads inline-string form)	API key or WIF; no OAuth/PAT-free	7.5/10
Codex	Quick-start tab	15	OPENAI_API_KEY/CODEX_API_KEY	7/10
Custom	Reference only	0 standalone (only shared/genaiscript.md)	No dedicated section	4/10

(Also present in examples but out of the core comparison: pi 21, gemini/opencode/antigravity 1 each — pi outnumbers Codex yet isn't in the primary engine list at how-they-work.mdx:26.)

Tool classification (13 tools): 11 engine-agnostic (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, custom mcp-servers). 0 Copilot-only, 0 Claude-only — strong parity positive. 2 ambiguous: web-search ("engine-dependent"; only Codex behavior — disabled by default — is documented, tools.md:63-67) and tools.timeout (per-engine defaults Claude 60s / Codex 120s; other engines unstated, tools.md:153-157).

Parity observation (from example counter): effective Copilot ≈ 2.6× Claude, but Claude leads the inline-string engine: claude form and has a dedicated smoke test — Claude is not underrepresented in production families (analysis, reporting, safe-output).

Auth Gaps

Gap	Ref
Detailed token scopes/rotation/org-billing deferred to external /reference/auth/ (not in core docs)	quick-start.mdx:81, README.md:39
CLAUDE_CODE_OAUTH_TOKEN unsupported — caveat never in quick-start	quick-start.mdx:97-108
No Anthropic/OpenAI/Gemini endpoints in firewall allowlist docs	architecture.mdx:227-237
CODEX_API_KEY vs OPENAI_API_KEY precedence stated but no guidance	quick-start.mdx:107
README.md:6 links quick-start.md; actual file is .mdx	README.md:6

Recommended Actions

Priority 1 (persona blocker): In the quick-start Claude tab, add one line stating subscription OAuth tokens are not accepted and pointing to API-key + WIF keyless auth. This closes the single most persona-relevant gap, unchanged across all 27 runs.

Priority 2: Surface --engine claude and the "omitted = Copilot default" behavior in the primary quick-start steps + prerequisites; add a Gemini secret callout.

Priority 3: Document the default Claude model, add Anthropic egress to the firewall allowlist example, disambiguate web-search/tools.timeout per engine, and fix the README.md:6 .md to .mdx link.

References:

• §29581258634

Generated by 📝 Claude Code User Documentation Review · 553.4 AIC · ⌖ 39.3 AIC · ⊞ 5.2K · ◷

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