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

[github-actions[bot]]

Executive Summary

gh-aw fully supports Claude Code as a first-class engine (engine: claude) with dedicated setup steps, secrets, and a --engine claude flag on add-wizard/init/new/upgrade — a Claude-only user can onboard without ever touching Copilot. The core problem is documentation imbalance, not missing capability: most engine-agnostic reference pages and the majority of example workflows only show Copilot syntax, and a silent default-to-Copilot fallback (quick-start.mdx:116) means copy-pasting those examples verbatim can produce a workflow that quietly uses the wrong engine.

Severity Findings (click to expand)

Critical Blockers

• Silent engine fallback: if engine: is omitted/removed, the runtime defaults to Copilot (quick-start.mdx:116). Reference pages that are meant to be engine-agnostic — reference/imports.md (12 copilot-only fences: lines 16,36,66,98,175,204,220,238,276,363,478,539), reference/serena.md (lines 20,39,54,112), reference/threat-detection.md (lines 37,52,90) — never show a engine: claude fence to copy instead. A Claude-only user who copies these as-is gets a Copilot workflow with no explicit signal, then hits confusing Copilot-auth failures.

Major Obstacles

• CLAUDE_CODE_OAUTH_TOKEN (from claude login) is explicitly rejected; a separate ANTHROPIC_API_KEY (Anthropic Console) is required (quick-start.mdx:148-150, cli.md:274). No explanation is given for why, nor whether this is billed separately from an existing Claude Code subscription — a likely point of confusion for the target persona.
• gh aw init --engine claude explicitly skips the custom-agent-file + MCP wiring that Copilot users get automatically (cli.md:151-176). The suggested replacement — "author an agent file in your own agent's format (Claude Code subagents...)" (cli.md:175) — has no concrete template or example anywhere in the reviewed docs.
• Engine-agnostic feature pages default every example to Copilot: reference/feature-flags.md (lines 185,263,308) has no engine: claude fence at all.
• reference/tools.md:65-67 documents web-search MCP behavior only for Codex; Claude's web-search setup requirements are unstated.

Minor Confusion

• Inconsistent engine lists: architecture.mdx:15 and :300 omit Pi (and :300 also omits Gemini) vs. the 5-engine list in how-they-work.mdx:26.
• .github/workflows/copilot-agent-analysis.md is misleadingly named but actually runs engine: claude (line 18).
• Tool/MCP timeout defaults are documented only for Claude (60s) and Codex (120s) (tools.md:169); Copilot/Gemini/Pi are unstated (an inverse gap, but still confusing).

Engine & Tool Matrix

Engine	Setup Path	Workflow Examples	Doc Code-Fences	Auth	Score
Copilot	Guided add-wizard, default, auto PAT-page flow (cli.md:195)	136	68 (34 files)	copilot-requests: write or COPILOT_GITHUB_TOKEN PAT	9/10
Claude	add-wizard/init --engine claude; manual Anthropic Console key	60	13 (7 files)	ANTHROPIC_API_KEY or Anthropic WIF (no OAuth reuse)	6/10
Codex	--engine codex flag	16	4 (3 files)	CODEX_API_KEY (preferred) or OPENAI_API_KEY	5/10
Custom	Manual authoring only	1	1	Per your own MCP config	3/10

Copilot outnumbers Claude ~2.3x in workflow examples and ~5x in doc code-fences. Tool inventory (tools.md) classifies 12 tools/integrations across read (2), write (1), exec (2), read/write (2), mcp (4), config/exec (1) — none are documented as engine-restricted except web-search (Codex-specific opt-out) and cli-proxy, whose per-engine parity is unstated. The engine landing pages themselves (engines/claude.md, engines/copilot.md) are balanced; the imbalance is concentrated in shared reference docs.

Auth Gaps

Engine	Required Secret(s)	Notes
Copilot	copilot-requests: write perm (preferred) or COPILOT_GITHUB_TOKEN	Guided PAT creation UX in add-wizard (cli.md:195)
Claude	ANTHROPIC_API_KEY or Anthropic WIF	CLAUDE_CODE_OAUTH_TOKEN explicitly not supported (quick-start.mdx:148-150, cli.md:274) — no migration note for subscription-only users
Codex	CODEX_API_KEY (takes precedence) or OPENAI_API_KEY	—
Gemini	GEMINI_API_KEY or Google WIF	—
Pi	Provider-prefixed (anthropic/..., openai/..., codex/...)	Inherits the underlying engine's key requirement

Gaps: no template for the Claude equivalent of Copilot's auto-generated agent file (cli.md:167-180); web-search setup unstated for Claude (tools.md:65-67).

Recommended Actions

Priority 1 — Add an engine: claude fence alongside every Copilot-only fence in engine-agnostic reference docs (imports.md, serena.md, threat-detection.md, feature-flags.md) to prevent the silent-fallback failure mode.

Priority 2 — Publish a concrete Claude Code subagent/agent-file template as the documented replacement for gh aw init --engine claude's skipped artifacts, and add a short note clarifying ANTHROPIC_API_KEY billing vs. an existing Claude Code subscription.

Priority 3 — Reconcile the Pi/Gemini omissions in architecture.mdx, document web-search and timeout defaults per engine consistently, and rename or fix copilot-agent-analysis.md to match its actual engine: claude usage.

References:

• §32252975018

Generated by 📝 Claude Code User Documentation Review · agent · 178.8 AIC · ⌖ 8.3 AIC · ⊞ 5.8K · ◷

• expires on Aug 20, 2026, 4:43 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-20T12:43:00.530Z.

Closed by Workflow