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

[github-actions[bot]]

Reviewing the gh-aw documentation from the perspective of a developer who uses Claude Code as their primary AI assistant and has no Copilot subscription. Reviewed core docs: README.md, quick-start.mdx, how-they-work.mdx, architecture.mdx, tools.md, cli.md, engines.md, auth.mdx, creating-workflows.mdx, overview.mdx, and faq.md.

Key Finding: Claude Code users can successfully adopt gh-aw. The core onboarding path works, authentication is documented, and there are 43 Claude-engine workflow examples in the repository. However, 7 minor-to-moderate documentation issues persist unchanged from prior reviews, with Gemini being the most underserved engine.

---

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 minor friction. The quick-start guide explicitly lists Claude as a supported engine in the prerequisites section (quick-start.mdx:29), and the gh aw add-wizard step walks users through selecting their engine and configuring the appropriate secret. The auth docs cover ANTHROPIC_API_KEY thoroughly.

The documentation has noticeably improved its multi-engine messaging over previous weeks — "GitHub Copilot (default), Claude by Anthropic, and Codex" appears prominently in how-they-work.mdx:26.

Specific Issues Found:

• creating-workflows.mdx:21 — The GitHub Web Interface authoring section opens with "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." This Copilot gate has no workaround shown for Claude users who want a browser-based authoring experience. The CLI path is available but not presented as an equivalent alternative in that section.
• quick-start.mdx:29 — The prerequisites list "GitHub Copilot, Anthropic Claude, or OpenAI Codex" — Gemini is missing as a fourth option.

Recommended Fixes:

• Add a note after the Copilot-gated Web Interface section pointing Claude/Codex users toward gh aw new --engine claude + manual editing in the GitHub editor as an alternative workflow authoring path.
• Add Gemini to the prerequisites list in Quick Start.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features that require Copilot specifically:

• Creating workflows via the GitHub Web Interface chat UI (requires Copilot Chat)
• The gh aw init dispatcher agent (agentic-workflows.agent.md) enables /agent agentic-workflows in Copilot Chat — this Copilot Chat integration is Copilot-only
• engine.agent custom agent files (creating-workflows.mdx:118) reference Copilot agent registration
• max-continuations (autopilot multi-run mode) is Copilot-only per the engine feature matrix

Features that work without Copilot:

• All CLI commands (gh aw add-wizard, gh aw compile, gh aw run, etc.)
• All safe-outputs types (create-issue, add-comment, create-pull-request, etc.)
• All MCP servers and tools
• GitHub tools, bash, playwright, cache-memory, repo-memory
• web-fetch, web-search (via MCP)
• Threat detection, secret redaction, integrity filtering
• The gh aw new --engine claude workflow creation path

Missing Documentation:

• gh aw init creates a dispatcher agent file described as registering a "custom agent in GitHub Copilot" and enabling /agent agentic-workflows in Copilot Chat. For Claude users, gh aw init still works (configures .gitattributes, creates the agent file) but the Copilot Chat integration feature will silently not function. This isn't explained anywhere visible.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• creating-workflows.mdx:21 — Web Interface section requires Copilot access (documented, but no alternative shown)
• architecture.mdx:181,252 — AWF firewall diagram labels the agent container as "Copilot CLI" and "Copilot CLI + MCP client" rather than a generic "AI Agent" — implies Copilot-only to first-time readers
• how-they-work.mdx:26 — AI Engines list "GitHub Copilot (default), Claude by Anthropic, and Codex" — Gemini omitted despite being a supported 4th engine
• engines.md:17 — Claude engine links to anthropic.com/index/claude (a page that may no longer exist; the Anthropic product page has been reorganized)

Missing Alternative Instructions:

• No explicit guidance that gh aw new --engine claude is the Claude Code user's equivalent of the Copilot Web UI workflow authoring experience
• auth.mdx:109 — ANTHROPIC_API_KEY setup instruction links to (platform.claude.com/redacted) (a docs page about getting started) rather than the direct key management page at console.anthropic.com/settings/keys`

---

Severity-Categorized Findings

🚫 Critical Blockers — 0

No critical blockers found. Claude Code users can complete the full onboarding flow.

⚠️ Major Obstacles — 0

No major obstacles found. All core CLI workflows function engine-agnostically.

💡 Minor Confusion Points — 7

Issue 1 (persistent, day 9): ANTHROPIC_API_KEY setup links to docs page, not key creation page

Impact: Extra navigation step for new Claude users
Current State: auth.mdx:109 links to (platform.claude.com/redacted) **Why It's Confusing:** That page describes Claude's API concepts. The actual key management UI is at console.anthropic.com/settings/keys. Users have to hunt for the create-key button. **Fix Required:** Change link to https://console.anthropic.com/settings/keys`
Affected Files: docs/src/content/docs/reference/auth.mdx:109

Issue 2 (persistent, day 9): Quick Start prerequisites omit Gemini

Impact: Gemini users not informed upfront what they need
Current State: quick-start.mdx:29 — "GitHub Copilot, Anthropic Claude, or OpenAI Codex"
Fix Required: Add "or Google Gemini" to the AI Account prerequisite line
Affected Files: docs/src/content/docs/setup/quick-start.mdx:29

Issue 3 (persistent, day 9): engines.md Claude link may be stale

Impact: Broken or misdirected link for users clicking through to learn about the Claude engine
Current State: engines.md:17 links to https://www.anthropic.com/index/claude
Why It's Problematic: Anthropic's site structure has changed; this was a blog post URL that now 404s or redirects unpredictably
Fix Required: Update to https://www.anthropic.com/claude or (claude.ai/redacted)
Affected Files: docs/src/content/docs/reference/engines.md:17

Issue 4 (persistent, day 6): Architecture diagram labels agent as "Copilot CLI"

Impact: Creates impression that AWF only works with Copilot CLI
Current State: architecture.mdx:181 — COPILOT["Copilot CLI"] and architecture.mdx:252 — AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]
Why It's Confusing: The Agent Workflow Firewall (AWF) is described as supporting all engines, but diagrams show only Copilot CLI as the agent. Non-Copilot users may wonder if AWF applies to them.
Fix Required: Rename "Copilot CLI" to "AI Agent (Copilot / Claude / Codex / Gemini)" or similar in both diagram nodes
Affected Files: docs/src/content/docs/introduction/architecture.mdx:181, 252

Issue 5 (persistent, day 3): how-they-work.mdx omits Gemini from AI Engines list

Impact: Gemini users don't see their engine mentioned in the first conceptual doc they're likely to read
Current State: how-they-work.mdx:26 — "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex."
Fix Required: Add "and Gemini by Google" to the list
Affected Files: docs/src/content/docs/introduction/how-they-work.mdx:26

Issue 6 (persistent, day 2): secrets bootstrap --engine omits Gemini

Impact: Gemini users can't use bootstrap for their engine
Current State: cli.md:220 — --engine option documented as "(copilot, claude, codex)" — no gemini
Fix Required: Add gemini to the options list
Affected Files: docs/src/content/docs/setup/cli.md:220

Issue 7 (persistent, day 1): GitHub Web Interface authoring is Copilot-gated with no alternative shown

Impact: Claude/Codex/Gemini users see the Web Interface section as inaccessible with no alternative
Current State: creating-workflows.mdx:21 — "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface."
Why It's Problematic: There is no follow-up sentence saying "If you use Claude or Codex, use gh aw new --engine claude instead" or pointing to the VSCode/Terminal section.
Fix Required: Add a single-sentence note pointing non-Copilot users to the terminal/VS Code workflow creation path in the section immediately below, or add a tip callout.
Affected Files: docs/src/content/docs/setup/creating-workflows.mdx:21

---

Engine Comparison Analysis

Available Engines

Engine	Setup Docs	Auth Docs	Examples in repo	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	88 workflows	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	43 workflows	⭐⭐⭐⭐
Codex	⭐⭐⭐⭐	⭐⭐⭐⭐	10 workflows	⭐⭐⭐⭐
Gemini	⭐⭐⭐	⭐⭐⭐⭐	0 workflows	⭐⭐⭐

Rating Scale: ⭐⭐⭐⭐⭐ (Excellent) to ⭐ (Poor/Missing)

Notable Claude-specific docs quality: The auth page has excellent Claude-specific guidance including the critical CLAUDE_CODE_OAUTH_TOKEN warning (not supported — only ANTHROPIC_API_KEY works). This is a known pain point for Claude Code CLI users who use OAuth by default, and it's proactively documented.

---

Tool Availability Analysis

Engine-Agnostic Tools (work with all engines):

• edit:, bash:, web-fetch:, playwright:, cache-memory:, repo-memory:, qmd:
• github: toolsets, MCP servers, custom MCP scripts
• All safe-outputs types

Engine-Specific Tools:

• web-search: — Codex has native support; others need a third-party MCP server
• max-turns — Claude only
• max-continuations — Copilot only
• engine.agent (custom agent files) — Copilot only

Unclear/Undocumented:

• The AWF firewall docs (architecture.mdx) diagram labels suggest Copilot-only, but the text and Reference docs confirm all engines use AWF.

---

Authentication Requirements

Current Documentation

Engine	Auth Doc Status
Copilot	✅ Complete (PAT setup, troubleshooting, GHES)
Claude	✅ Complete (API key, CLAUDE_CODE_OAUTH_TOKEN warning, custom endpoint)
Codex	✅ Complete (API key, CODEX_API_KEY alternative, Azure endpoint)
Gemini	✅ Complete (API key setup, troubleshooting)

Missing for Claude Users:

• ANTHROPIC_API_KEY setup link points to docs page not direct key creation URL (Issue 1 above)
• No mention that CLAUDE_CODE_OAUTH_TOKEN is unsupported in Quick Start prerequisites or add-wizard description — only in auth.mdx deep-dive section. A Claude Code user who just installed gh-aw might not read auth.mdx before running their first workflow.

---

Example Workflow Analysis

Engine: copilot  — 88 workflows (48%)
Engine: claude   — 43 workflows (24%)
Engine: codex    — 10 workflows (5%)
Engine: gemini   —  0 workflows (0%)
No engine (default Copilot) — 26 workflows (14%)
Other/mixed      — 15 workflows (8%)

Claude Examples: 43 Claude-engine workflows exist, covering audit reports, code review, docs maintenance, security compliance, repository analysis, and CI investigation. Coverage is solid and demonstrates Claude's capabilities across a wide range of use cases.

Copilot Examples: Still the majority with 88 explicit + 26 default workflows, reflecting the project's Copilot-first origins.

Gemini Examples: Zero workflows use engine: gemini, making it the least validated engine from a documentation perspective.

---

Recommended Actions

Priority 1: Quick Wins (1-line fixes)

1. Fix ANTHROPIC_API_KEY setup link — auth.mdx:109 — Change platform.claude.com/docs/en/get-started to console.anthropic.com/settings/keys
2. Add Gemini to Quick Start prerequisites — quick-start.mdx:29 — Add "or Google Gemini" to AI Account line
3. Add Gemini to how-they-work.mdx engines list — how-they-work.mdx:26 — Append "and Gemini by Google"
4. Add Gemini to secrets bootstrap --engine options — cli.md:220 — Add gemini to the option list
5. Update Claude engine link in engines.md — engines.md:17 — Change anthropic.com/index/claude to anthropic.com/claude

Priority 2: Moderate Effort

6. Add non-Copilot alternative note to Web Interface creation section — creating-workflows.mdx after line 21 — Add a tip callout: "Using Claude or Codex? Use gh aw new --engine claude in your terminal or follow the CLI/VS Code section below."
7. Genericize architecture diagram agent labels — architecture.mdx:181,252 — Replace "Copilot CLI" with engine-agnostic label like "AI Agent"

Priority 3: Nice-to-Have

8. Add a "Claude Code specific gotcha" callout in Quick Start — Mention that CLAUDE_CODE_OAUTH_TOKEN is not supported and only ANTHROPIC_API_KEY works, before a user hits this in production.
9. Add at least one Gemini example workflow to the repo to validate the engine's documentation.
10. Add "Why choose Claude over Copilot?" guidance to the engines reference page to help users make an informed engine selection.

---

Positive Findings

What Works Well for Claude Code Users:

• ✅ The gh aw add-wizard interactive path fully supports Claude engine selection and ANTHROPIC_API_KEY configuration
• ✅ Auth docs comprehensively cover Claude setup, including the critical CLAUDE_CODE_OAUTH_TOKEN unsupported warning
• ✅ Engine feature comparison table (engines.md) is accurate and complete for all 4 engines
• ✅ gh aw new --engine claude injects engine: claude automatically into frontmatter template
• ✅ gh aw secrets bootstrap --engine claude is supported
• ✅ gh aw trial auto-detects and prompts for Claude API keys
• ✅ 43 Claude-engine workflow examples demonstrate wide feature coverage
• ✅ Claude-specific config (max-turns, custom ANTHROPIC_BASE_URL, token weights) is well documented
• ✅ All tools (edit, bash, github, playwright, MCP servers, safe-outputs) work identically regardless of engine

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction.

The fundamentals are solid: Clear Claude engine documentation, working CLI onboarding path, sufficient example workflows, and well-documented auth requirements (including the proactive CLAUDE_CODE_OAUTH_TOKEN warning). A Claude Code user can complete the Quick Start in ~10 minutes without needing Copilot.

The friction comes from Copilot-first presentation in certain sections (Web Interface creation, architecture diagrams) and the consistent omission of Gemini from lists where it belongs. None of these are blockers, but they add cognitive overhead for non-Copilot users.

Overall Assessment Score: 8.5/10 (stable, unchanged from yesterday)

Category	Score
Clarity for non-Copilot users	8/10
Claude engine documentation	8/10
Alternative approaches provided	8/10
Engine parity (across all 4 engines)	7/10

Trend

Score has been stable at 8.5/10 since 2026-03-31 when it improved from 8.0 after a major obstacle was resolved. The 7 persistent minor issues have remained unaddressed across 9 daily review cycles. Gemini engine documentation quality is the single most consistent gap.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/setup/creating-workflows.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/introduction/overview.mdx
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/reference/faq.md
• .github/workflows/*.md (182 workflow files analyzed for engine distribution)

---

References:

• §24137282054

Generated by Claude Code User Documentation Review · ● 343.9K · ◷

• expires on Apr 9, 2026, 1:21 PM UTC