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

[github-actions[bot]]

Executive Summary

A Claude Code user can get started without Copilot, but only with an ANTHROPIC_API_KEY or Anthropic WIF. Claude setup clarity is partial. The main gaps are that Copilot is the silent default, Claude-specific wiring is left to the user, and the docs are lopsided toward Copilot (about 7:1 in docs, about 2:1 in workflow files).

Key finding: one critical blocker. Claude Pro/Max/Team subscription login (CLAUDE_CODE_OAUTH_TOKEN) is explicitly rejected, so subscription-only users cannot proceed (quick-start.mdx:148,153, cli.md:207,287).

Severity Findings (1 Critical / 7 Major / 7 Minor)

Critical Blockers

• Subscription login unsupported. Only ANTHROPIC_API_KEY (Console) or Anthropic WIF is accepted (quick-start.mdx:148,153; cli.md:207,287). Fix: state this in the first Claude paragraph of the README and quick-start, and link to the API-key signup.

Major Obstacles

• Copilot is the silent default. On the manual path, omitting engine: claude leads to Copilot auth failures, and the quick-start never says to set engine (how-they-work.mdx:26; cli.md:254,1199).
• repo-status sample is external. Its engine pin is not shown, so it may be Copilot-pinned (unverified) (quick-start.mdx:105-110,125).
• gh aw init without --engine claude creates Copilot-only files. The quick-start never mentions init (cli.md:153,159,181).
• Claude Code wiring is manual. Users must register gh aw mcp-server in their own host config, with no Claude Code instructions (cli.md:179-181).
• Threat detection reuses the same engine. It needs the Claude credential in the detection job, which is not called out (architecture.mdx:416,422).
• Switching to Claude may need compile --approve. A new secret triggers safe-update approval (cli.md:442; quick-start.mdx:226-232).
• WIF setup has no federation-rule steps. It defers to auth.mdx (quick-start.mdx:151).

Minor Confusion

• "Requires only the GitHub CLI" contradicts the AI-account prerequisite (quick-start.mdx:51,70).
• README lists Copilot first, and the default engine appears only in how-they-work.mdx:26 (README.md:20).
• Architecture diagrams label the agent CLI "COPILOT" (architecture.mdx:217,245).
• Install has no version pin, while the README notes retired versions (README.md:35; quick-start.mdx:82).
• A ~400-line contributor list buries the Workshop and Contributing content (README.md:85-482).
• No Anthropic data-handling link next to the data-handling advice (quick-start.mdx:100).
• The Pi section is detailed while Claude defers to another page, so Claude looks less complete (quick-start.mdx:147-177).

Engine & Tool Matrix

Example counts are Grep-based tallies. Workflow files are .github/workflows plus shared fragments.

Row	Setup	Examples (workflows / docs)	Auth	Score
Copilot	Default, 1 step (quick-start.mdx:137-143)	138 / 127	copilot-requests or COPILOT_GITHUB_TOKEN	5/5
Claude	Partial: API key, then manual engine: and wiring (quick-start.mdx:147-155)	65 / 18	ANTHROPIC_API_KEY or WIF; OAuth rejected	3/5
Codex	Clear (quick-start.mdx:159-163)	77 / 11	CODEX_API_KEY or OPENAI_API_KEY	4/5
Custom	No setup or examples found	0 / 0	n/a	0/5
Tools: built-in local (5)	edit, bash, playwright, cache/repo-memory (tools.md:20-175)	Executor and allowlist enforcement unstated	none	Ambiguous
Tools: MCP (8)	linear, jira remote (tools.md:41-100); agentic-workflows, qmd, safeoutputs, mcpscripts provided; custom mcp-servers	none	LINEAR_API_KEY, ATLASSIAN_*	Clear
Tools: engine-dependent (2)	web-fetch, web-search (tools.md:116-132)	Claude and Codex off by default; Gemini and Pi no-op; Copilot CLI mode rejects	n/a	Engine-dependent

Parity observations:

• Per-engine tutorials are near parity. The imbalance sits in reference pages (docs ratio ~7x vs workflow files ~2.1x).
• custom has zero declarations.
• Other engines are not counted: pi, agy, gemini.
• Gaps in the count: inline values with trailing comments are missed by the workflow regex, and shared fragments are included in the workflow totals.

Auth Gaps

• Claude auth: ANTHROPIC_API_KEY or WIF (id-token: write); OAuth rejected (how-they-work.mdx:33; quick-start.mdx:147-153).
• Wizard sets ANTHROPIC_API_KEY only on the pull-request path; the direct-push path is unstated (cli.md:207).
• WIF federation steps are absent (quick-start.mdx:151).
• The detection job needs the same credential (architecture.mdx:416,422).
• assign-to-agent requires a PAT; GitHub App and GITHUB_TOKEN cannot do it (cli.md:320), but this is Copilot-specific.
• Tool secrets appear only in tools.md:43,76,89-90, not in setup guidance.

Recommended Actions

Priority 1

1. Add a Claude auth callout that says subscription login is unsupported and an API key or WIF is required (quick-start.mdx:147-155).
2. State the Copilot default in the quick-start and show engine: claude in a Claude sample (how-they-work.mdx:26).

Priority 2
3. Add Claude Code MCP and subagent wiring instructions (cli.md:179-181).
4. Document wizard secret behavior on the direct-push path (cli.md:207).
5. Call out that detection needs the credential, and the --approve step when switching engines.

Priority 3
6. Fix the "only the GitHub CLI" wording, move the contributor list, add Anthropic data-handling and WIF steps, and make architecture diagram labels engine-neutral.
7. Add Claude examples to the reference and pattern pages.

References: §40977340064

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

• expires on Oct 30, 2026, 4:12 PM 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 #73193.