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

[github-actions[bot]]

Executive Summary

A Claude Code user can complete onboarding without Copilot: add-wizard offers Claude, and ANTHROPIC_API_KEY setup is documented (quick-start.mdx:145-155). The main gaps are a Copilot-first framing and Claude setup detail that sits outside the reviewed docs. Key finding: the Claude path is prose-only. None of the six core docs shows a runnable engine: claude snippet or a Claude WIF example.

Setup clarity for Claude: partial. Onboarding is Copilot-free: yes.

Severity Findings

Critical Blockers

None found. A Claude user can finish setup with ANTHROPIC_API_KEY.

Major Obstacles

• No engine: claude example in the core docs. Claude is mentioned only in prose (cli.md:183, cli.md:159). Users are sent to /gh-aw/engines/claude/ (quick-start.mdx:155).
• Claude WIF is undocumented in the core docs. It needs id-token: write and an engine.auth block, but no YAML is shown (quick-start.mdx:151, cli.md:207).
• Subscription tokens are rejected. CLAUDE_CODE_OAUTH_TOKEN from claude login is unsupported (quick-start.mdx:153, cli.md:287). Claude Code users commonly have only this token, and no migration guidance is given.
• Copilot-first steering. Copilot is the default (how-they-work.mdx:26). The prerequisites say "If you already have GitHub Copilot, start there" (quick-start.mdx:70). The init description lists Copilot-only artifacts (cli.md:153), and the engine used by default init is not named (cli.md:158).
• No Claude equivalent of the Copilot custom agent. Users are told to author their own subagents (cli.md:180).

Minor Confusion

• quick-start.mdx:51 says the guide "requires only the GitHub CLI", but quick-start.mdx:70 also requires an AI account and a secret.
• The report name differs: "Daily Repo Status Report" (quick-start.mdx:55) vs "Daily Repo Report" (quick-start.mdx:188).
• Claude web search needs an explicit web-search: entry with no example (tools.md:128). The Claude and Codex default tool timeout is 60s (tools.md:253).
• agy appears only in the secrets bootstrap (cli.md:299) and is missing from the engine lists (README.md:20, how-they-work.mdx:26).
• The wizard stores ANTHROPIC_API_KEY only on the pull-request path, and direct-push behavior is unstated (cli.md:207).

Engine & Tool Matrix

Example counts are top-level engine: declarations in .github/workflows/*.md (338 total). 63 declarations (18 Pi, 45 unresolved nested ids such as agy) are not attributed to the four engines below.

Engine	Setup docs	Examples	Auth	Score
Copilot	Detailed (quick-start.mdx:137-143)	135	PAT or copilot-requests: write (org billing)	🟢 5/5
Claude	Short (quick-start.mdx:145-155)	63	ANTHROPIC_API_KEY or WIF; OAuth token rejected	🟡 3/5
Codex	Short (quick-start.mdx:157-163)	77	CODEX_API_KEY or OPENAI_API_KEY	🟡 3/5
Custom	Not in the reviewed docs	0	n/a	🔴 1/5

Parity observations: Claude has about 47% of Copilot's examples. Claude favors the scalar form (34 of 63) while Copilot favors the nested form. Neither form is explained in the docs. Threat-detection overrides are nested under safe-outputs (3 files) and excluded from the counts.

Tool classification (19 entries in tools.md: 3 built-in, 2 web, 2 remote MCP, 3 gh-aw MCP, 2 memory, 2 experimental, 1 custom MCP, 1 browser, 3 config knobs):

• Engine-dependent web tools are ambiguous. web-fetch and web-search are disabled for Claude and Codex by default, Copilot rejects them at compile time, and Gemini and Pi silently no-op (tools.md:128-132). This is the most relevant tool gap for Claude users.
• Copilot runs in offline BYOK mode with web tools disabled (tools.md:130).
• playwright has no stated class (tools.md:134-144). github mode and auth are unspecified (tools.md:29-39).
• safeoutputs and mcpscripts are referenced but not declared (tools.md:224-231, tools.md:352).
• Linear and Jira secrets are documented only in tools.md (:41-100), not in the engine secret tables.

Auth Gaps

• Claude WIF setup has no YAML example (quick-start.mdx:151). The auth reference page is unverified because it is outside the six docs.
• The wizard's Copilot token reuse trusts the user's claim about PAT scope (cli.md:205). The PAT permission level also differs: "Read" (quick-start.mdx:142) vs unspecified (cli.md:205).
• Secret presence does not verify validity, expiry or permissions, and no check for engine keys is given (cli.md:320-326).
• The Pi secret depends on the model: prefix and is described in a single sentence (quick-start.mdx:175).
• Copilot assignment cannot use GitHub App tokens or the default GITHUB_TOKEN (cli.md:320). This matters for Claude users only if they follow Copilot-assignment flows.

Recommended Actions

Priority 1

1. Add a complete engine: claude frontmatter example with ANTHROPIC_API_KEY to quick-start.mdx near line 145.
2. Add a Claude WIF YAML example (permissions.id-token: write plus engine.auth) at quick-start.mdx:151.
3. Explain why CLAUDE_CODE_OAUTH_TOKEN is unsupported and what to use instead (quick-start.mdx:153).

Priority 2
4. Make the quick start engine-neutral. Replace the Copilot-first line at quick-start.mdx:70 with an engine chooser, and fix the "only the GitHub CLI" claim at :51.
5. Name the default engine for gh aw init and show init --engine claude as a peer example (cli.md:153-159).
6. Provide a starter Claude subagent template to replace the Copilot custom agent (cli.md:180).

Priority 3
7. Add a web-search support matrix by engine with a Claude snippet (tools.md:128-132).
8. Document the scalar vs nested engine: forms, and add agy to the engine lists (README.md:20, how-they-work.mdx:26).
9. Fix the report-name mismatch (quick-start.mdx:55, :188).

Coverage notes

• quick-start.md does not exist; the file is quick-start.mdx.
• cli.md:694-1583 was only grep-sampled. The engine pages and the auth reference are linked but were not reviewed.
• No prior review-history.jsonl existed (cold start), so no trend data is available.

Generated by 📝 Claude Code User Documentation Review · claude · routed: sonnet55 high · ~36 AIC · ⌖ ~1 AIC · ⊞ 2.7K · ◷

• expires on Oct 31, 2026, 4:38 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 #73504.