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

[github-actions[bot]]

Executive Summary

gh-aw's compiler and most tools (edit, bash, playwright, cache-memory, mcp-servers, etc.) are engine-agnostic, and Claude auth itself is now fully documented (0 critical blockers for the 10th consecutive tracked run). The friction for a Claude Code user who avoids Copilot is concentrated in three places: gh aw init only auto-scaffolds agent/MCP wiring for Copilot, example/smoke-test coverage favors Copilot ~1.9x, and Anthropic WIF setup reads thinner than Copilot's fully inline auth wizard. Key finding: no blocker prevents adoption, but every "quick path" in the docs defaults to Copilot, leaving Claude users to assemble equivalent steps manually.

Severity Findings

Critical Blockers: None identified this run.

Major Obstacles:

1. gh aw init artifact-parity gap — only --engine copilot auto-creates the custom agent file (.github/agents/agentic-workflows.md) and MCP wiring (.github/mcp.json, copilot-setup-steps.yml); Claude users are told to "author an agent file in your own agent's format" and "register gh aw mcp-server in your own MCP host configuration" with no inline template. (docs/src/content/docs/setup/cli.md:107, :127-132)
2. Example/smoke-test parity gap — Claude: 61 workflow examples vs Copilot: 115 (~1.9x). Copilot has dedicated cloud-auth smoke variants (smoke-copilot-aoai-apikey.md, smoke-copilot-aoai-entra.md, smoke-copilot-arm.md) with no Claude equivalent.
3. Anthropic WIF setup remains link-only/thin — one short paragraph (docs/src/content/docs/setup/quick-start.mdx:145-151) vs Copilot's full add-wizard walkthrough (cli.md:153: two auth paths, PAT creation page, validation behavior).
4. add-wizard documentation imbalance — cli.md:153 describes Copilot's wizard UX in a full paragraph; the equivalent Claude wizard flow is only described in quick-start.mdx:143-153, not in cli.md itself, so a reader going straight to the CLI reference sees asymmetric depth.

Minor Confusion:

1. quick-start.mdx:70 — "If you already have GitHub Copilot, start there — it requires no extra account setup" implicitly positions Claude as the higher-friction path.
2. tools.md:239 states "Claude and Codex default to 60 seconds" for tools.timeout but leaves Copilot/Gemini/Pi defaults unstated.
3. Ambiguous per-engine applicability for drive-memory and qmd tools (tools.md:157-188) — no statement of which engines support them.

Engine & Tool Matrix

Dimension	Copilot	Claude	Codex	Custom
Setup	Auto-scaffolded agent file + MCP wiring (cli.md:107)	Manual, no inline template (cli.md:131)	Manual (cli.md:125)	No standalone examples found
Examples	115 workflows, 10+ auth smoke variants	61 workflows (~53% of Copilot's count), 0 dedicated cloud-auth smoke variants	76 workflows	0 in top-level .github/workflows
Auth	copilot-requests: write or COPILOT_GITHUB_TOKEN PAT, fully inline wizard (cli.md:153)	ANTHROPIC_API_KEY or WIF (link-only); CLAUDE_CODE_OAUTH_TOKEN explicitly rejected (quick-start.mdx:151)	OPENAI_API_KEY/CODEX_API_KEY (quick-start.mdx:157-161)	n/a
Doc-completeness (rough)	9/10	6/10	7/10	n/a

Tool classification (tools.md): 11 of ~16 documented tools are engine-agnostic (edit, github, bash, playwright, cache-memory, repo-memory, mcp-servers, etc.); 2 are Copilot-restricted/special-cased (web-search/web-fetch rejected at compile time in CLI mode, tools.md:130); 2 explicitly name Claude+Codex together (web-search default-off, 60s timeout, tools.md:128,239); Gemini/Pi have no native web-search and need MCP instead; drive-memory and qmd are ambiguous/experimental with no per-engine statement.

Engine-example-counter parity observations: baseline conformance coverage (engine-conformance-*.md) is 1:1 across all engines (Claude and Copilot each have exactly one), so the gap is concentrated entirely in Copilot's extra auth/platform/SDK smoke matrix (sub-agents, small-model, dynamic-workflow variants) that Claude has no equivalents for.

Auth Gaps

• Claude: ANTHROPIC_API_KEY (from console.anthropic.com) or Anthropic WIF (id-token: write) — quick-start.mdx:145-151. CLAUDE_CODE_OAUTH_TOKEN from everyday claude login is explicitly unsupported and the CLI fails with an error (quick-start.mdx:151, cli.md:232) — this has now been documented (not silent) for 10 consecutive tracked runs, but remains a gotcha for Claude Code users who already hold this credential and expect it to work.
• Copilot: copilot-requests: write repo permission OR COPILOT_GITHUB_TOKEN fine-grained PAT — walked through step-by-step in the add-wizard description (cli.md:153).
• Gap: cli.md has no paragraph-level narrative for Claude's add-wizard auth flow; that detail exists only in quick-start.mdx, creating a documentation asymmetry for anyone reading the CLI reference in isolation.

Recommended Actions

Priority 1:

• Add an inline Claude agent-file template/example to gh aw init --engine claude docs (cli.md:131), mirroring what Copilot auto-generates.
• Expand the Anthropic WIF section (quick-start.mdx:145-151) with the same inline step depth as Copilot's add-wizard (cli.md:153).
• Add Claude-equivalent smoke-test coverage for cloud-auth variants to close the ~1.9x example gap.

Priority 2:

• Add a Claude add-wizard paragraph directly in cli.md instead of only cross-referencing quick-start.mdx.
• Document per-engine tools.timeout defaults for Copilot/Gemini/Pi (tools.md:239).

Priority 3:

• Rebalance quick-start.mdx:70's framing so Claude isn't implicitly cast as the higher-friction path.
• State explicit engine applicability for drive-memory and qmd (tools.md:157-188).

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

• expires on Oct 10, 2026, 4:57 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 #67432.