[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-08-23

[github-actions[bot]]

Executive Summary

gh-aw is usable by a Claude Code user, but Copilot is the default at every layer (default engine, init artifacts, wizard flow), and one real landmine survives from yesterday's review unfixed: claude login's CLAUDE_CODE_OAUTH_TOKEN is silently ignored in CI, producing a misleading API-key error instead of a clear message pointing at ANTHROPIC_API_KEY (quick-start.mdx:211). Example workflows also skew heavily toward Copilot (138 files) vs. Claude (60), per this run's engine scan.

Severity Findings

Critical Blockers / Major Obstacles / Minor Confusion

Critical Blockers

• claude login's CLAUDE_CODE_OAUTH_TOKEN is not honored in Actions and is silently ignored, surfacing as an opaque API-key auth error instead of a documented redirect to ANTHROPIC_API_KEY — quick-start.mdx:211. (Repeat finding from 2026-08-22 review, still unresolved.)

Major Obstacles

• Copilot is the default engine everywhere (add-wizard, docs framing); Claude users must remember --engine claude on every command or fall into the Copilot-centric flow — how-they-work.mdx:26, quick-start.mdx:112.
• gh aw init --engine copilot auto-creates a custom agent file (.github/agents/agentic-workflows.md) and wires MCP integration by default; the same command with --engine claude skips these, leaving Claude users to configure manually with no inline guidance — cli.md:158-166, cli.md:176-189.
• WIF (Workload Identity Federation) is mentioned as a Claude auth option but has no inline setup steps in quick-start — only a link out to /gh-aw/reference/auth/ — quick-start.mdx:124.
• Example workflow library is skewed: 138 Copilot examples vs. 60 Claude vs. 15 Codex vs. 47 assorted custom engines. Claude examples cluster around analysis/review/planning; PR-creation and code-modification patterns are demonstrated mostly through Copilot examples, giving Claude users fewer directly-transferable references.

Minor Confusion

• Pi's authentication is model-prefix-dependent (anthropic/..., openai/..., copilot/...) but the exact resolution logic isn't fully spelled out in tools.md, only briefly in quick-start.mdx:232-234.
• Codex disables web-search: by default unlike other engines (tools.md:67-68) — an engine-inconsistency pattern that isn't cross-referenced from the main tools table, so a reader comparing engines could assume uniform tool defaults.

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot (default)	Full wizard is Copilot-first; init auto-creates custom agent + MCP wiring (cli.md:158-166)	138 files — broadest coverage, dominates creation/PR workflows	copilot-requests: write perm or COPILOT_GITHUB_TOKEN PAT (how-they-work.mdx:32)	5/5
Claude	Needs explicit --engine claude; init skips Copilot-only artifacts, no equivalent auto-setup (cli.md:176-189)	60 files — strong on analysis/review/planning, thinner on creation workflows	ANTHROPIC_API_KEY; WIF unlinked inline; claude login token silently ignored (quick-start.mdx:211)	3/5
Codex	Explicit engine selection; web-search: off by default (tools.md:67-68)	15 files, mostly read-only/moderation, restricted bash/network	OPENAI_API_KEY or CODEX_API_KEY	3/5
Custom (Pi, Aider, Kiro, Goose, etc.)	No unified setup path across the ~9 custom engines	47 files, mostly smoke tests, uneven per-tool depth	Provider-dependent, resolved by model-name prefix (Pi) or ad hoc	2/5

Cross-engine tool classification (from reference/tools.md) is mostly engine-agnostic — Edit, GitHub, Bash, Web Fetch, Playwright, Cache/Repo/Drive Memory, QMD search, and MCP mounting are all documented as "All engines" (tools.md:20-172). The two documented exceptions are Web Search (Codex opt-in only) and Drive Memory (marked experimental/private-preview for all engines) — tools.md:62-99.

Auth Gaps

• No inline WIF walkthrough: Anthropic and Google WIF are named as auth alternatives but quick-start only links out to the reference/auth page rather than showing steps (quick-start.mdx:124, 229).
• Silent token rejection: CLAUDE_CODE_OAUTH_TOKEN from local claude login is accepted-looking but ignored in CI, with no docs-level warning until quick-start.mdx:211 — and even there it's framed as a footnote, not a callout.
• Pi auth resolution underspecified: model-prefix-based auth switching (Copilot/Anthropic/OpenAI) is only described briefly at quick-start.mdx:232-234, not in the tools/auth reference docs.
• Copilot PAT flow is semi-automated (wizard opens a pre-filled PAT creation page, cli.md:203-204) while Claude/Codex/Gemini require the user to locate and set the secret manually with no equivalent guided flow.

Recommended Actions

Priority 1

• Add an explicit warning callout (not just prose) in quick-start.mdx near line 211 that claude login tokens don't work in Actions, with the exact required secret name.

Priority 2

• Extend gh aw init --engine claude to scaffold an equivalent onboarding artifact (or explicitly document what's intentionally omitted vs. Copilot), so Claude users don't infer Claude is second-class.
• Add 2-3 inline WIF setup steps (or a copy-pasteable snippet) for Claude/Anthropic instead of only linking to reference/auth.

Priority 3

• Grow the Claude example set for creation/PR-generation workflows to close the 138-vs-60 gap, prioritizing parity with the most-copied Copilot examples.
• Cross-link the Codex web-search default exception from the main tools table so engine-comparison readers don't assume uniform defaults.

Trend note: engine-example counts shifted sharply since 2026-08-22 (claude 39→60, copilot 39→138) — worth confirming whether this reflects real example growth or a counting-methodology change, since yesterday's run showed near parity.

Generated by 📝 Claude Code User Documentation Review · agent · 129.5 AIC · ⌖ 8.07 AIC · ⊞ 6.3K · ◷

• expires on Aug 24, 2026, 4:40 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 #55401.