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

[github-actions[bot]]

Executive Summary

Daily review of gh-aw docs from a Claude Code (non-Copilot) user's perspective. No critical blockers today — the CLAUDE_CODE_OAUTH_TOKEN silent-failure issue, flagged in every run since 2026-08-22, remains resolved (documented at cli.md:240) for an 8th consecutive day. Three structural parity gaps between Copilot and Claude/Codex persist unresolved for 30+ days: gh aw init scaffolding, example-workflow coverage, and WIF setup depth.

Severity Findings

Critical / Major / Minor (click to expand)

Critical Blockers: none

Major Obstacles

1. gh aw init auto-scaffolds a custom agent file + MCP wiring only for Copilot; Claude/Codex users are told to author an agent file in their own agent's format with no template or example (cli.md:139, cli.md:115,131-144).
2. Example/smoke-test coverage lopsided: 58 Claude-engine workflows vs 113 Copilot (~1.95x) in .github/workflows/*.md; smoke-test auth variants are 3 (Claude) vs 9 (Copilot), suggesting Copilot's integration surface is far more battle-tested.
3. Anthropic Workload Identity Federation is described in one link-only sentence (configure Anthropic WIF with a federation rule and grant the workflow id-token: write, quick-start.mdx:149) with no YAML snippet, unlike Copilot's fully inline PAT creation steps (quick-start.mdx:131-141, cli.md:161).

Minor Confusion

1. The line if you already have GitHub Copilot, start there — it requires no extra account setup (quick-start.mdx:70) reads as a soft default that a Claude-only reader could mistake for a requirement.
2. add-wizard's auth-prompt flow is only detailed for Copilot in the CLI reference (cli.md:161); the Claude equivalent exists only narratively in quick-start (quick-start.mdx:143-153), splitting the single source of truth.
3. No model-selection example for engine: claude (e.g., pinning a specific Claude model) — only Pi's anthropic/claude-sonnet-5 prefix form is shown (quick-start.mdx:173).
4. Web-search tool-default paragraph conflates Codex's shared toggle with Claude/Copilot's independent one in a single dense sentence (tools.md:128).

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	Inline, default, no extra account (quick-start.mdx:70); auto-scaffolded agent + MCP at init (cli.md:115,131-144)	113 workflows, 9 smoke-auth variants	copilot-requests: write (org billing) or COPILOT_GITHUB_TOKEN (cli.md:161)	★★★★★
Claude	Inline API-key steps; WIF is one link-only sentence (quick-start.mdx:149); no init scaffolding (cli.md:139)	58 workflows, 3 smoke variants	ANTHROPIC_API_KEY or WIF; CLAUDE_CODE_OAUTH_TOKEN explicitly unsupported (documented, cli.md:240)	★★★☆☆
Codex	Inline steps (quick-start.mdx:157-161); no init scaffolding	77 workflows	CODEX_API_KEY (precedence) or OPENAI_API_KEY	★★★★☆
Custom (Pi, Gemini, etc.)	Narrower, e.g. Pi needs cli-proxy + gh-proxy mode (quick-start.mdx:171-175)	55 combined across 10 engine ids	Reuses Copilot/Anthropic/OpenAI creds depending on model prefix	★★★☆☆

Tool availability (tools.md) is otherwise engine-agnostic for 12 of 16 catalogued tools (edit, github, bash, playwright, cache-memory, etc.); the 4 engine-specific exceptions are web-search defaults, tools.timeout (Claude/Codex named explicitly at 60s, others unstated), and the Pi-only cli-proxy requirement.

Auth Gaps

• Claude: ANTHROPIC_API_KEY repo secret or Anthropic WIF (id-token: write, no secret) — WIF has no worked YAML example in any of the six reviewed files (quick-start.mdx:149).
• Codex: CODEX_API_KEY (precedence) or OPENAI_API_KEY, both inline-documented (quick-start.mdx:157-161).
• Copilot: copilot-requests: write org billing or COPILOT_GITHUB_TOKEN PAT, with a dedicated add-wizard prompt flow (cli.md:161).
• No documented way to verify a configured ANTHROPIC_API_KEY beyond running gh aw secrets bootstrap --engine claude (cli.md:242-254) — no Claude-specific doctor/validation note exists.

Recommended Actions

• P1: Add an inline Anthropic WIF YAML snippet to quick-start.mdx:149, matching the detail level of Copilot's PAT steps — flagged unresolved since 2026-08-22.
• P2: Give Claude/Codex an init-time template (or link to one) for the author-an-agent-file-in-your-own-format step (cli.md:139), instead of a bare pointer phrase.
• P3: Cross-link the workflows-are-engine-portable note (cli.md:144) more prominently near the engine comparison table so Claude users know existing Copilot smoke-test examples are adaptable, partially offsetting the 58-vs-113 example gap.

References:

• §37465134999

Generated by 📝 Claude Code User Documentation Review · claude · agent · 331 AIC · ⌖ 5.15 AIC · ⊞ 5.2K · ◷

• expires on Oct 7, 2026, 4:54 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 #66578.