[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-07-29

[github-actions[bot]]

Executive Summary

gh-aw remains fully usable by a Copilot-free, Claude Code-only developer — Claude has clear setup docs, quick-start auth callouts, and near-first-class example/smoke-test coverage. The gap is not that Claude does not work, it is that several default behaviors and advanced features quietly assume Copilot: gh aw init emits Copilot-Chat artifacts by default, workflows with no engine: field silently become Copilot, and Claude still lacks any subscription/OAuth billing path. New this run: the AI-assisted workflow-authoring flow (agentic-workflows create) is documented as a Copilot Chat-only skill, so Claude Code users must hand-author workflow YAML with no equivalent guided flow.

Severity Findings

Critical Blockers: None. Onboarding without a Copilot subscription is possible end-to-end.

Major Obstacles

1. No OAuth/subscription path for Claude — CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported/ignored; only pay-per-token ANTHROPIC_API_KEY (or WIF) works, vs the Copilot zero-secret copilot-requests: write shortcut. (docs/.../reference/auth.mdx:205-207, setup/quick-start.mdx:146-148, reference/faq.md:449-451)
2. gh aw init defaults to Copilot-Chat artifacts (.github/skills/agentic-workflows/SKILL.md, .github/agents/agentic-workflows.md) unless --engine claude is passed; not surfaced in prerequisites. (setup/cli.md:146-162)
3. Omitting engine: silently defaults new/generated workflows to Copilot (36 of 265 files this run). (setup/quick-start.mdx:113-116, confirmed in pkg/workflow/agentic_engine_test.go)
4. New: AI-assisted authoring (agentic-workflows create) is a Copilot Chat-only skill — Claude Code users get no equivalent guided-authoring path, only manual YAML editing. (setup/creating-workflows.mdx:108-135, guides/agentic-authoring.mdx:58,67, reference/glossary.md:1041)
5. Advanced config is Copilot-exclusive: engine.agent (custom agent file), engine.harness, max-continuations (autopilot), engine.copilot-sdk/BYOK — all show ❌ for Claude/Codex/Gemini. (reference/engines.md:40,43,101-111,292-306,342-389,178-267,490-500)

Minor Confusion

• Copilot-first ordering/nudges throughout ("start there — no extra account setup"). (quick-start.mdx:71, index.mdx:186-198, reference/faq.md:27-28,100-102, reference/engines.md:25-27)
• web-search tool behavior is ambiguous: native opt-in for Codex, third-party MCP server for everyone else. (reference/tools.md:65-67, reference/engines.md:39,46)
• max-turns name collision: a universal invocation cap vs. a same-named Claude-only iteration alias in the same table. (reference/engines.md:35-36,46,497-500)
• Custom engine has zero standalone examples (only embedded in shared/genaiscript.md), and the crush engine was fully removed per ADR 45515 — its zero coverage is expected, not a regression.

Engine & Tool Matrix

Engine	Setup	Examples (workflow frontmatter)	Auth	Score
Copilot	Default, zero-config	127 explicit + 36 silent-default = 163	copilot-requests: write (no secret) or PAT	9/10
Claude	engine: claude, clearly documented	63 — 2nd overall, leads inline-string form 43 vs Copilot 31, has dedicated smoke tests	ANTHROPIC_API_KEY only — no OAuth/subscription	7/10
Codex	engine: codex	15, 1 smoke test	OPENAI_API_KEY/CODEX_API_KEY	8/10
Custom	engine.harness/engine.agent overlay (Copilot-only in practice)	0 standalone examples	Varies (GH_AW_GITHUB_TOKEN, GitHub App creds)	4/10

Tool parity: 17 tools classified — 11 engine-agnostic, 4 Copilot-only (engine.agent, engine.harness, max-continuations, engine.copilot-sdk/BYOK), 1 Claude-only (max-turns alias, likely a naming artifact), 0 Codex-only, 1 ambiguous (web-search). Every first-class engine (Copilot/Claude/Codex/Gemini/Pi/OpenCode/Antigravity) has ≥1 dedicated smoke-test workflow; Copilot alone has ~20 variants vs 1-2 for others.

Auth Gaps

• No PAT-free/subscription-billing route for Claude — Copilot users authorize via a permission (copilot-requests: write), Claude users must always provision a static ANTHROPIC_API_KEY secret or complete full WIF federation setup (external Anthropic Console prerequisite, not detailed step-by-step). (reference/auth.mdx:15-39,220-244)
• CLAUDE_CODE_OAUTH_TOKEN caveat is now correctly surfaced in quick-start itself (not just auth.mdx) — a real improvement over prior runs, but the underlying capability gap (no Claude Max/Teams billing) remains unaddressed.
• gh aw secrets bootstrap --engine claude is documented in one line vs. fuller Copilot PAT walkthroughs. (setup/cli.md:256-268)
• Gemini secret setup is thinner than Copilot/Anthropic/Codex in quick-start (prereq-mention only in some historical runs; confirm still true).

Recommended Actions

Priority 1

• Document that agentic-workflows create (AI-assisted authoring) is Copilot Chat-only, and either add a Claude-compatible authoring flow or explicitly point Claude users to manual-editing docs from the quick-start, not buried in creating-workflows.mdx.
• Add a one-line note to quick-start prerequisites (not just deep in CLI docs) that gh aw init without --engine produces Copilot-specific artifacts.

Priority 2

• Add an explicit "no OAuth/subscription billing for Claude" line directly in the engines comparison table (engines.md), not just in auth.mdx/faq.md, so the limitation is visible before a user commits to Claude.
• Rename or footnote the Claude-only max-turns engine alias to avoid collision with the universal max-turns field.

Priority 3

• Add one standalone custom engine example workflow (not only embedded in shared/genaiscript.md).
• Balance quick-start "start with Copilot" framing with a neutral engine-selection decision guide.

---

Daily automated documentation review — trend: stable for 30 consecutive runs (2026-06-11 through 2026-07-21); this run adds the Copilot-only AI-authoring finding and confirms crush engine removal (ADR 45515) resolved a prior minor gap.

Generated by 📝 Claude Code User Documentation Review · age00 · 291.3 AIC · ⌖ 21.4 AIC · ⊞ 5.1K · ◷

• expires on Jul 30, 2026, 5:14 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 #49136.