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

[github-actions[bot]]

Executive Summary

A Claude Code user can onboard gh-aw without touching Copilot — engine: claude + ANTHROPIC_API_KEY is a first-class path documented in the quick-start. 0 critical blockers (19 daily runs running). The single most persona-relevant gap: Claude's auth story only documents a pay-per-use console ANTHROPIC_API_KEY, with no PAT-free/subscription-OAuth shortcut equivalent to Copilot's org-billing path — so a Claude Pro/Max subscriber has to create a separate console key. Overall score 7.5/10 (stable).

Severity Findings

Critical → Major → Minor (click to expand)

Critical blockers: none. Every built-in tool is engine-agnostic; no feature is Copilot-gated.

Major obstacles

1. No PAT-free / subscription path for Claude. Copilot offers org billing via copilot-requests:write (no PAT) and a COPILOT_GITHUB_TOKEN PAT (cli.md:171). Claude documents only a console ANTHROPIC_API_KEY (quick-start.mdx:86-88) — a Claude Pro/Max subscriber cannot reuse their subscription and must mint a metered API key. Fix: add a note on which Claude auth methods are/aren't supported (subscription OAuth vs console key vs WIF) directly in quick-start.
2. Silent Copilot default. Copilot is the default engine (how-they-work.mdx:26); 35 example workflows omit engine: entirely and resolve to Copilot. --engine claude exists (cli.md:142) but isn't surfaced in the quick-start add flow. Fix: show --engine claude in the primary add example and state the default explicitly.
3. Uneven secret callouts. Quick-start spells out dedicated secret steps for Copilot + Anthropic only; Codex/Gemini are link-only (quick-start.mdx:71,86-88). Fix: give each engine a parallel secret block.

Minor confusion

• Copilot-first nudge "start there — no extra account setup" with no why-Claude-vs-Copilot guidance (quick-start.mdx:29).
• No default Claude model/version documented (architecture.mdx:279,286).
• custom engine has 0 standalone examples; crush appears in secrets bootstrap --engine list but is undocumented (cli.md:258).
• Doc path drift: agent spec references quick-start.md but the real file is quick-start.mdx.

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Adoption score
Copilot (default)	Wizard default; no --engine needed	124 explicit (~159 incl. 35 omitted)	Org billing copilot-requests:write (no PAT) or COPILOT_GITHUB_TOKEN	9/10
Claude	engine: claude / --engine claude (cli.md:142)	60 (leads inline-string form)	ANTHROPIC_API_KEY only in these docs; WIF/OAuth not surfaced	7/10
Codex	engine: codex	14	OPENAI_API_KEY (CODEX_API_KEY accepted)	5/10
Custom	engine.id: custom overlay	0 standalone (shared include only)	Via engine.env base-url	3/10

Tool classification (tools.md): 14 tools — 13 engine-agnostic, 1 engine-dependent (web-search: disabled-by-default on Codex, tools.md:65-67). 0 Copilot-only, 0 Claude-only tools. Ambiguous: github is listed built-in but is effectively a GitHub MCP server (tools.md:29-39).

Parity (engine-example-counter): Copilot >> Claude > Codex >> Custom. Copilot dominates example coverage (~2× Claude, ~9× Codex); Claude nonetheless has broad, varied coverage (smoke + daily + real workflows) and leads the inline engine: claude string form. Custom is effectively undemonstrated. Each engine has a dedicated smoke test — a positive.

Auth Gaps

• Auth detail lives only in quick-start.mdx + cli.md; tools.md, how-they-work.mdx, architecture.mdx carry zero auth guidance, and README.md:40 lists engines with no setup pointer.
• Claude: only the direct ANTHROPIC_API_KEY path is documented in these 6 files — no Bedrock/Vertex, model selection, or subscription-OAuth note (quick-start.mdx:86-88). (Trend note: WIF keyless auth exists in auth.mdx but is out of this run's 6-file scope and remains absent from quick-start.)
• GH_AW_PROJECT_GITHUB_TOKEN for project creation surfaced only in the cli.md project section, not the general auth flow (cli.md:865).
• MCP gateway key "is not a strong security boundary... treat as leaked by design" (architecture.mdx:269-270) — good to state, but jarring without framing.

Recommended Actions

Priority 1 — In quick-start, add an explicit note on supported Claude auth methods (console ANTHROPIC_API_KEY yes; subscription/OAuth token status; WIF alternative) so subscription users aren't surprised.

Priority 2 — Surface --engine claude in the primary add example and state that omitting engine: silently defaults to Copilot; give Codex/Gemini the same dedicated secret block as Copilot/Anthropic.

Priority 3 — Add a why-choose-which-engine paragraph, document the default Claude model, add at least one standalone custom example, and document crush.

References: §28741263826 · §28706632535 · §28662189611

Generated by 📝 Claude Code User Documentation Review · 457.2 AIC · ⌖ 34.9 AIC · ⊞ 5.3K · ◷

• expires on Jul 6, 2026, 5:06 AM UTC-08:00

[pelikhan]

/plan

[github-actions[bot]]

🚀 Agentic Commands has started processing this discussion comment

[github-actions[bot]]

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

A newer discussion is available at Discussion #43790.