[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-05-26

[github-actions[bot]]

Executive Summary

A Claude Code user reading the gh-aw documentation can successfully adopt the tool — there are no hard blockers, and engine: claude is a fully supported, well-documented option — but the path is noticeably steeper than the Copilot path at every step. The Quick Start, CLI reference, and most examples default to Copilot; Claude users have to read the engine table, override the default, and skip Copilot-only setup notes to make progress.

Key Finding: No critical blockers. The same four major obstacles and several minor paper-cuts identified in the previous four audits remain unfixed in this run — most notably a wrong Anthropic-Console URL at auth.mdx:109, an auth table that omits three supported engines, a Copilot-first Quick Start, and gh aw init silently creating a Copilot-only dispatcher agent file.

---

Persona Context

I reviewed this documentation as a developer who:

• ✅ Uses GitHub for version control
• ✅ Uses Claude Code as primary AI assistant
• ❌ Does NOT use GitHub Copilot
• ❌ Does NOT use Copilot CLI
• ❌ Does NOT have Copilot subscription

---

Question 1: Onboarding Experience

Can a Claude Code user understand and get started with gh-aw?

Yes, with caveats. The overview is product-neutral (README.md:40: "Supports GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini (Google) — pick whichever AI account you already have"), and the Quick Start prerequisites list all four engines on equal footing (quick-start.mdx:29). gh aw add-wizard interactively prompts for an engine and the matching secret (quick-start.mdx:70), so the happy path does work for Claude.

However, the narrative of the Quick Start is Copilot-first:

• The first NOTE box (quick-start.mdx:75-79) walks through COPILOT_GITHUB_TOKEN setup in detail.
• The second NOTE box (quick-start.mdx:82-86) covers ANTHROPIC_API_KEY — shorter, no troubleshooting tip.
• Codex and Gemini get no NOTE box at all, despite being listed as prerequisites.
• The customization example at Step 4 (quick-start.mdx:127-131) shows engine: claude as the override — but only after the workflow has been added with whatever the wizard picked.

Specific Issues Found:

• quick-start.mdx:75-90: setup tips cover only 2 of 4 advertised engines
• engines.md:24: "Copilot CLI is the default" is a one-liner; nothing in the Quick Start mentions that omitting engine: lands on Copilot
• README.md:39-40: "How It Works" link is fine, but the Overview never explains the engine-choice tradeoffs

Recommended Fixes:

• Add parallel NOTE boxes for Codex and Gemini in quick-start.mdx
• Add a one-line "Default engine is Copilot — set engine: claude in the frontmatter to change it" callout in Step 2 before the wizard runs
• Surface the "Which engine should I choose?" paragraph from engines.md:26-28 in the Quick Start or How It Works page

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

engines.md:34-45 is the single most honest piece of cross-engine documentation in the repo and clearly enumerates the asymmetries. From a Claude user's perspective:

Features That Require Copilot:

• engine.agent — custom agent files in .github/agents/ (engines.md:41, engines.md:111-121)
• engine.harness — custom harness script (engines.md:44, engines.md:293-315)
• max-continuations — autopilot multi-run mode (engines.md:38)
• COPILOT_PROVIDER_* BYOK mode for routing through other providers (engines.md:201-268)
• The dispatcher agent file generated by gh aw init at .github/agents/agentic-workflows.agent.md (cli.md:134) is in Copilot agent-file format and is not used by other engines

Features That Work Without Copilot (engine-agnostic):

• All built-in tools: edit, bash, github, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers (tools.md:18-209)
• All safe outputs (create_issue, create_pull_request, add_comment, etc.)
• Network firewall (AWF), MCP Gateway, MCP sandboxing — all engine-neutral (architecture.mdx:168-323)
• timeout-minutes, tools.timeout, tools.startup-timeout, max-runs, engine.api-target, engine.bare, engine.env, engine.args, engine.command (engines.md:43,431-437)
• engine.permission-mode — actually Claude-only (engines.md:439-498), a positive Claude-specific extension

Missing Documentation:

• cli.md:134 describes the dispatcher agent file created by gh aw init but never warns it is Copilot-only. A Claude user running gh aw init will end up with a .github/agents/ file the engine doesn't use, with no signal that this is OK.
• No "what's the Claude equivalent of engine.agent?" guidance — the answer is "use engine.bare plus a self-contained prompt" but that's not stated anywhere.
• No "what's the Claude equivalent of max-continuations?" guidance — answer is "Claude has max-turns but does not have autopilot continuations" but that's only inferable from the table at engines.md:34-45.

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• cli.md:134 — "Initialize repository for agentic workflows. Configures .gitattributes, creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md)" — describes a Copilot agent-file format without flagging the engine dependency
• architecture.mdx:228 — sample firewall config example uses engine: copilot with no Claude variant shown
• engines.md:62-69, engines.md:111-121, engines.md:295-301 — extended-config examples all use id: copilot
• auth.mdx:17-23 — the "Which secret do I need?" lookup table only lists 4 of 7 supported engines; Crush, OpenCode, and Pi are absent despite being documented in engines.md:20-22
• auth.mdx:109 — **the API key creation link still points to (platform.claude.com/redacted) (a docs landing page, not a key-creation page). The correct URL is used at quick-start.mdx:84andauth.mdx:199 (https://console.anthropic.com/settings/keys` / https://console.anthropic.com/). This was flagged in 4 prior audits and is still not fixed.
• how-they-work.mdx:26 — engine intro line — Copilot listed first and tagged "(default)"; ordering choice acceptable, but no compensating "you can use any of these" emphasis

Missing Alternative Instructions:

• No worked Claude example next to Copilot examples in architecture.mdx and engines.md extended-config sections
• No "porting a workflow from Copilot to Claude" mini-guide despite ~30 files containing engine: copilot and only 6 containing engine: claude
• The engine-env-secrets-to-engine-config codemod (cli.md:268) is described without explaining which engines benefit from it (it applies regardless of engine)

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

No critical blockers identified. A Claude user can complete the Quick Start, run a workflow, and customize it. The add-wizard interactive engine selector and gh aw secrets bootstrap --engine claude (cli.md:240-245) bridge the worst gaps.

⚠️ Major Obstacles (Score: 4/10)

Obstacle 1: Wrong Anthropic API key URL in auth reference

Impact: A Claude user clicking the link in auth.mdx to create their API key lands on a docs landing page instead of the keys console.

Current State: auth.mdx:109 reads Create an API key at (platform.claude.com/redacted) The correct URL https://console.anthropic.com/settings/keys` is already used at quick-start.mdx:84 and https://console.anthropic.com/ at auth.mdx:199.

Why It's Problematic: Three URLs in three places for the same task in the same docs site — and the most authoritative one (the auth reference) is wrong. Flagged in 5 consecutive audits.

Suggested Fix: Change auth.mdx:109 to Create an API key in [Anthropic Console](https://console.anthropic.com/settings/keys). to match quick-start.mdx:84.

Affected Files: docs/src/content/docs/reference/auth.mdx

Obstacle 2: Auth lookup table omits 3 supported engines

Impact: Users of Crush, OpenCode, and Pi cannot find their required secret in the auth reference.

Current State: auth.mdx:17-23 lists Copilot, Claude, Codex, Gemini. engines.md:20-22 lists Crush (COPILOT_GITHUB_TOKEN), OpenCode (COPILOT_GITHUB_TOKEN), and Pi (COPILOT_GITHUB_TOKEN or provider-specific).

Why It's Problematic: The auth page is the canonical "which secret do I need" reference. Three engines are silently missing from it. Flagged in 5 consecutive audits.

Suggested Fix: Add three rows to the auth.mdx:17-23 table mirroring engines.md:20-22. Note the experimental status inline.

Affected Files: docs/src/content/docs/reference/auth.mdx

Obstacle 3: `gh aw init` Copilot-only behavior undocumented

Impact: A Claude user running the recommended init command gets a .github/agents/agentic-workflows.agent.md file that their engine ignores, with no signal that this is expected.

Current State: cli.md:134 documents gh aw init as "Initialize repository for agentic workflows. Configures .gitattributes, creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md)". No mention that the dispatcher agent file is a Copilot agent-file format.

Why It's Problematic: Silent format choice masks an engine assumption. A Claude user editing the file would expect Claude to read it. Flagged in 5 consecutive audits.

Suggested Fix: Add one sentence to cli.md:134: "The dispatcher agent file uses Copilot's .agent.md format — it is loaded by the Copilot engine only; other engines ignore it. Use --no-mcp to skip if you are not using Copilot." Also document the --no-mcp flag implications more clearly.

Affected Files: docs/src/content/docs/setup/cli.md

Obstacle 4: Quick Start setup tips only cover 2 of 4 advertised engines

Impact: Codex and Gemini users have no Quick-Start-level setup tips; they have to jump to the auth.mdx reference mid-flow.

Current State: quick-start.mdx:75-79 covers COPILOT_GITHUB_TOKEN setup. quick-start.mdx:82-86 covers ANTHROPIC_API_KEY setup. No parallel NOTE boxes for OPENAI_API_KEY or GEMINI_API_KEY despite both being in the prerequisites list (quick-start.mdx:29) and the wizard selector (quick-start.mdx:70).

Why It's Problematic: Breaks the parity the prerequisites list promised. Flagged in 4 consecutive audits.

Suggested Fix: Add two more NOTE boxes after quick-start.mdx:86, one each for Codex and Gemini, with the same shape (key-creation URL + gh aw secrets set snippet).

Affected Files: docs/src/content/docs/setup/quick-start.mdx

💡 Minor Confusion Points (Score: 6/10)

• Issue 1: Engine timeout defaults split across two reference pages — tools.md:155 mentions Claude (60s) and Codex (120s) only; the full table is at engines.md:381-388. No cross-link. File: docs/src/content/docs/reference/tools.md:155
• Issue 2: architecture.mdx:228 firewall example uses engine: copilot — substitute or duplicate with engine: claude for symmetry. File: docs/src/content/docs/introduction/architecture.mdx:228
• Issue 3: No "what's the Claude equivalent of X?" mapping section anywhere — would close most lingering parity questions in one place
• Issue 4: Engine extended-config examples (engines.md:62-91, 111-121, 270-303) all use id: copilot; even a single id: claude worked example would help
• Issue 5: how-they-work.mdx:26 lists Copilot first with "(default)" but doesn't say engine: can be omitted only for Copilot — that fact lives only at engines.md:24
• Issue 6: engine: custom is not actually a valid engine value per engines.md:14-22, yet this audit prompt and prior agent reports occasionally reference it — the docs are consistent here, but the audit prompt template itself should drop the term

---

Engine Comparison Analysis

Available Engines

Per engines.md:14-22, gh-aw supports seven engines:

• engine: copilot — default, broadest feature set, well-documented
• engine: claude — fully supported, well-documented, exemplary Claude-specific section at engines.md:439-498
• engine: codex — supported, lighter docs presence
• engine: gemini — supported, lighter docs presence
• engine: crush — experimental, very thin docs
• engine: opencode — experimental, very thin docs
• engine: pi — experimental, very thin docs

engine: custom is not a real engine value — ignore prior audit references to it.

Documentation Quality by Engine

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (30 files)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐ (6 files)	⭐⭐⭐⭐ (URL bug)	⭐⭐⭐⭐
Codex	⭐⭐⭐	⭐ (1 file)	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐⭐	⭐ (1 file)	⭐⭐⭐⭐	⭐⭐⭐
Crush / OpenCode / Pi	⭐⭐	⭐ (≤1 file)	⭐⭐ (missing from auth table)	⭐⭐

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools (per tools.md and engines.md):

• edit, bash, github, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers, tools.timeout, tools.startup-timeout

Engine-Specific Tools/Knobs:

• tools.web-search for Codex is native and opt-in; for all others it goes through a third-party MCP server (tools.md:67, engines.md:52)
• Tool allowlists work for Copilot, Claude, Codex, Gemini, Pi — not Crush or OpenCode (engines.md:45)

Unclear/Undocumented:

• Default tool timeouts only listed for Claude and Codex in tools.md:155. Full table appears in engines.md:381-388 but tools.md doesn't cross-reference it.

---

Authentication Requirements

Current Documentation

Quick Start guide covers authentication for:

• ✅ Copilot — detailed NOTE box at quick-start.mdx:75-79
• ✅ Claude — present at quick-start.mdx:82-86 (shorter than Copilot's)
• ⚠️ Codex — listed in prerequisites, missing NOTE box
• ⚠️ Gemini — listed in prerequisites, missing NOTE box
• ⚠️ Crush / OpenCode / Pi — omitted entirely from quick-start

Missing for Claude Users

• auth.mdx:109 link is wrong (see Obstacle 1)
• No "is CLAUDE_CODE_OAUTH_TOKEN supported?" cross-link from quick-start.mdx — only auth.mdx:121-123 answers it
• No troubleshooting tip in the quick-start.mdx:82-86 NOTE box (Copilot's NOTE box at line 75-79 is similarly thin, but Copilot also has a troubleshooting section in auth.mdx:97-99)

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN ✅
• Claude: ANTHROPIC_API_KEY ✅ (CLAUDE_CODE_OAUTH_TOKEN explicitly unsupported)
• Codex: OPENAI_API_KEY or CODEX_API_KEY ✅
• Gemini: GEMINI_API_KEY ✅
• Crush / OpenCode: COPILOT_GITHUB_TOKEN (per engines.md:20-21) — surprising and not in auth.mdx table
• Pi: COPILOT_GITHUB_TOKEN default, switches to provider-specific when model: uses provider/model format — not in auth.mdx table

---

Example Workflow Analysis

Workflow Count by Engine in Docs (engine: <name> literal occurrences)

Engine: copilot   - 30 files (59 occurrences) — default; appears across architecture, examples, guides
Engine: claude    - 6 files  (7 occurrences)
Engine: codex     - 1 file   (1 occurrence)
Engine: gemini    - 1 file   (1 occurrence)
Engine: opencode  - 1 file   (1 occurrence)
Engine: crush     - 0 files
Engine: pi        - 0 files
Engine: custom    - 0 files (not a valid engine value)

Quality of Examples

Copilot Examples: Saturate the docs; every architectural and config example defaults to Copilot. This is consistent and expected given the default-engine choice.

Claude Examples: Sufficient to learn the engine — engines.md:322-325, 344-352, 408-415, 447-451 all show idiomatic Claude config — but no end-to-end Claude workflow file is featured the way Copilot examples are in architecture.mdx. A Claude user has to mentally translate.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix auth.mdx:109 Anthropic URL — Change to https://console.anthropic.com/settings/keys to match quick-start.mdx:84. File: docs/src/content/docs/reference/auth.mdx
2. Complete auth.mdx:17-23 table — Add Crush, OpenCode, Pi rows matching engines.md:20-22. File: docs/src/content/docs/reference/auth.mdx
3. Warn that gh aw init dispatcher agent file is Copilot-only — One sentence at cli.md:134. File: docs/src/content/docs/setup/cli.md
4. Add Codex and Gemini NOTE boxes to Quick Start — Mirror the Claude/Copilot tip-boxes for parity. File: docs/src/content/docs/setup/quick-start.mdx

Priority 2: Major Improvements

1. Add "Default engine = Copilot" callout in Quick Start Step 2 — Before the wizard runs, mention that the default applies if engine: is omitted. File: docs/src/content/docs/setup/quick-start.mdx
2. Cross-link timeout defaults — tools.md:155 should link to the full per-engine table in engines.md:381-388. File: docs/src/content/docs/reference/tools.md
3. Add at least one Claude end-to-end example in architecture.mdx — Mirror the Copilot example at architecture.mdx:228. File: docs/src/content/docs/introduction/architecture.mdx
4. Add a "Choosing an engine" page or section in How It Works — Surface the paragraph at engines.md:26-28 earlier in the funnel. File: docs/src/content/docs/introduction/how-they-work.mdx

Priority 3: Nice-to-Have Enhancements

1. "Claude equivalent of X" mapping — Concise table explaining: engine.agent → no Claude equivalent (use prompt-only); max-continuations → use max-turns for in-run iteration only; etc.
2. A "Why Claude vs Copilot" decision aid — Expand engines.md:26-28 with concrete decision criteria (token cost, max-turns control, ecosystem fit).
3. Drop engine: custom references from any audit/prompt templates — it is not a real engine value.

---

Positive Findings

What Works Well

• ✅ README.md:40 puts all four engines on equal footing in the overview paragraph
• ✅ quick-start.mdx:29 lists all four engines as equally valid prerequisites
• ✅ quick-start.mdx:71 inline-cites all four secret docs anchors — strong wayfinding
• ✅ add-wizard interactively prompts for engine — no manual frontmatter editing required for first run
• ✅ engines.md:34-45 engine-feature comparison table is exemplary — honest, visible asymmetry
• ✅ engines.md:439-498 provides a substantial Claude-specific security/permission section
• ✅ auth.mdx:121-123 explicitly documents CLAUDE_CODE_OAUTH_TOKEN is unsupported — saves Claude Code Max/Teams subscribers from confusion
• ✅ gh aw secrets bootstrap --engine claude exists for Claude-specific secret validation (cli.md:240-245)
• ✅ Tool surface is mostly engine-agnostic — Claude users get the full power of playwright, cache-memory, safe-outputs, agentic-workflows, etc.
• ✅ gh aw new --engine claude (cli.md:202) injects engine: claude into generated frontmatter

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate friction.

Reasoning: No critical blocker prevents adoption. A Claude user who reads engines.md and the auth reference, and runs gh aw add-wizard, will get a working Claude workflow on the first try. The pain is cumulative: a wrong URL here, a missing NOTE box there, a Copilot-only file silently created during init, and a sea of Copilot-flavored examples to mentally translate. Each is small; together they signal "Copilot is the first-class citizen and Claude is a supported alternative."

The good news: every issue identified is a docs fix, not an engineering gap. The product itself genuinely supports Claude at parity for most authoring workflows. The same four major obstacles have been flagged in five consecutive audits — they are tractable, low-risk PRs.

Overall Assessment Score: 6/10

Breakdown:

• Clarity for non-Copilot users: 6/10
• Claude engine documentation: 7/10
• Alternative approaches provided: 6/10
• Engine parity: 5/10

Next Steps

1. Ship the four Priority-1 doc fixes — these have been outstanding for five audits and would shift the score to 7-8/10 immediately.
2. Add at least one Claude-engine worked example to architecture.mdx and the Quick Start.
3. Consider an "engine parity matrix" page that surfaces the comparison table from engines.md:34-45 as a first-class navigational entry.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/setup/cli.md
• docs/src/content/docs/introduction/how-they-work.mdx
• docs/src/content/docs/introduction/architecture.mdx
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• Cross-checked: directory listings of docs/src/content/docs/examples/, docs/src/content/docs/guides/, and engine: literal occurrence counts across all docs

---

References:

• §26450723204 — this run
• §26403073236 — prior run (2026-05-25)

Report Generated: 26450723204
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food 🐕)

Generated by 📝 Claude Code User Documentation Review · opus47 11.6M · ◷

• expires on May 27, 2026, 1:31 PM UTC