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

[github-actions[bot]]

Executive Summary

This is the daily review of gh-aw documentation from the perspective of a developer who uses Claude Code as their primary AI assistant and does not have GitHub Copilot. The good news: Claude Code users can successfully adopt gh-aw with no critical blockers. The onboarding path is functional, authentication is well-documented, and 53 of 191 workflows use the Claude engine. One documentation fix was observed since the last run (Gemini now mentioned in how-they-work.mdx). Six persistent documentation issues remain unresolved, the oldest now at 15 consecutive days.

Key Finding: gh-aw is viable for Claude Code users. The core onboarding path (install extension → gh aw add-wizard → select Claude engine → set ANTHROPIC_API_KEY) is well-supported. The primary friction points are cosmetic/editorial: architecture diagrams hard-code "Copilot CLI" labels, the web UI authoring path requires Copilot, and a few pages omit Gemini as a 4th engine option.

---

Persona Context

Reviewing 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 a Copilot subscription

---

Question 1: Onboarding Experience

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

Yes, with minor effort. The quick start guide (docs/src/content/docs/setup/quick-start.mdx) explicitly lists "Anthropic Claude" as a valid AI Account option in its prerequisites (line 29). The gh aw add-wizard command is interactive and prompts the user to select an engine, including Claude, and walks through ANTHROPIC_API_KEY setup. The README does not assume Copilot — it describes gh-aw as "write agentic workflows in natural language markdown, and run them in GitHub Actions."

Specific issues found:

• quick-start.mdx line 29: Prerequisites list only Copilot, Anthropic Claude, and OpenAI Codex — Gemini is omitted even though it is a fully-supported 4th engine.
• quick-start.mdx line 67: Step 2 description "Choose between Copilot, Claude, or Codex" again omits Gemini.
• creating-workflows.mdx line 21: The GitHub Web Interface authoring path is gated: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly" — Claude Code users who want to author from the GitHub web UI hit a dead end here.

Recommended fixes:

• Add Gemini to prerequisites and Step 2 in quick-start.mdx
• Add a note in creating-workflows.mdx for non-Copilot users pointing to the CLI path as the alternative

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features that require Copilot:

• GitHub Web UI / Mobile App workflow authoring — gh aw init configures a dispatcher agent that hooks into Copilot Chat. The web-based /agent agentic-workflows authoring command is Copilot-only. No alternative for Claude users is documented in creating-workflows.mdx.
• max-continuations — Autopilot multi-run mode is Copilot-only (engines.md feature comparison table).
• engine.agent — Custom agent file references (.github/agents/*.agent.md) are Copilot-only.
• Assign to Copilot safe outputs — safe-outputs: assign-to-copilot requires Copilot access by definition.

Features that work without Copilot:

• gh aw add-wizard / gh aw new / gh aw compile / gh aw run — all CLI commands work with any engine
• All tools: (edit, bash, github, web-fetch, playwright, cache-memory, repo-memory) are engine-agnostic
• Safe outputs (create-issue, add-comment, create-pull-request, add-labels) are engine-agnostic
• MCP servers are engine-agnostic
• max-turns is Claude-specific and well-documented
• Custom API endpoints (ANTHROPIC_BASE_URL) documented for Claude

Missing documentation:

• creating-workflows.mdx should explain what non-Copilot users should do instead of the web UI authoring path (the CLI approach is the answer — a single paragraph would suffice)

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-centric language found in:

• docs/src/content/docs/introduction/architecture.mdx line 181: AWF firewall mermaid diagram has COPILOT["Copilot CLI"] as the agent node label — implies architecture requires Copilot
• architecture.mdx line 252: MCP Gateway diagram shows AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"] — same issue
• docs/src/content/docs/setup/creating-workflows.mdx line 104: gh aw init documentation says it configures the repository "so that you can create and modify agentic workflows directly from github.com or the GitHub mobile app, using the Copilot coding agent" — no mention of alternatives
• docs/src/content/docs/setup/cli.md line 219: secrets bootstrap examples only show --engine copilot — no example for --engine claude or --engine gemini

Missing alternative instructions:

• No "Getting started without Copilot" guide or callout box, though the information is scattered across auth.mdx, engines.md, and the interactive add-wizard
• No "Why use Claude instead of Copilot for gh-aw?" comparison to help Claude Code users understand the trade-offs

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

No critical blockers found. Claude Code users can adopt gh-aw without Copilot access.

⚠️ Major Obstacles (Score: 3/10)

Obstacle 1: Web UI Workflow Authoring is Copilot-Only (Persistent: day 7)

Impact: Claude Code users cannot use the GitHub web interface or mobile app to author or edit workflows

Current State: creating-workflows.mdx line 21 says "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly..." and line 104 says gh aw init is "required to enable the authoring experience...using the Copilot coding agent." No alternative for Claude users is offered in this section.

Why it's problematic: Users who find the web UI authoring path and lack Copilot see a dead end with no guidance to the CLI alternative.

Suggested fix: Add a callout box or note after line 21: "If you're using Claude, Codex, or Gemini, use gh aw new or the VSCode/editor path below."

Affected files: docs/src/content/docs/setup/creating-workflows.mdx

Obstacle 2: Architecture Diagrams Hardcode "Copilot CLI" (Persistent: day 12)

Impact: Misrepresents the system architecture as Copilot-specific; creates doubt for Claude users about whether the architecture supports their engine

Current State: Two mermaid diagrams in architecture.mdx hard-code "Copilot CLI" as the agent label:

• Line 181: COPILOT["Copilot CLI"] inside "AI Agent Process" subgraph
• Line 252: AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"] inside AWF network diagram

Why it's problematic: A Claude user reading the architecture docs will see "Copilot CLI" in the agent container and wonder if the architecture requires Copilot.

Suggested fix: Replace both with generic labels: AGENT["AI Agent CLI\n(Copilot / Claude / Codex / Gemini)"]

Affected files: docs/src/content/docs/introduction/architecture.mdx lines 181, 252

Obstacle 3: ANTHROPIC_API_KEY Setup URL Sends Users to Docs, Not Key Creation (Persistent: day 15)

Impact: Extra friction in the setup flow — users arrive at a documentation page and must navigate to find the actual API key creation form

Current State: auth.mdx line 109 says "Create an API key at (platform.claude.com/redacted) — this is a documentation landing page. The troubleshooting section (line 199) correctly references console.anthropic.com as where to verify key status, which suggests the setup link should point directly there.

Suggested fix: Update auth.mdx line 109 to link directly to https://console.anthropic.com/settings/keys for immediate key creation, consistent with how Copilot and OpenAI setup links are structured.

Affected files: docs/src/content/docs/reference/auth.mdx line 109

💡 Minor Confusion Points (Score: 5/10)

• Gemini omitted from Quick Start: quick-start.mdx lines 29 and 67 list only 3 engines (Copilot, Claude, Codex), omitting Gemini. File: docs/src/content/docs/setup/quick-start.mdx
• Outdated Claude URL in engines.md: Line 17 links to https://www.anthropic.com/index/claude — should point to https://www.anthropic.com/claude-code or https://docs.anthropic.com/. File: docs/src/content/docs/reference/engines.md
• secrets bootstrap examples only show Copilot: cli.md line 219 example shows --engine copilot only; no Claude/Gemini examples. File: docs/src/content/docs/setup/cli.md
• No "why Claude instead of Copilot" guidance: Developers choosing between engines get no comparison of strengths or use-case guidance
• CLAUDE_CODE_OAUTH_TOKEN not supported (well-documented but surprising): Claude Code users accustomed to OAuth auth for their IDE won't be able to use it — must obtain an API key separately. This is correctly documented in auth.mdx but may still surprise users.

---

Engine Comparison Analysis

Available Engines

Based on documentation review:

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Gemini	⭐⭐⭐	⭐ (1 workflow)	⭐⭐⭐	⭐⭐

Notes:

• Claude documentation quality is good — feature comparison table, max-turns configuration, ANTHROPIC_BASE_URL, token weights, all documented
• Gemini has only 1 example workflow and is omitted from multiple intro-level pages

---

Workflow Count by Engine

Engine: copilot - 101 workflows (53%)
Engine: claude  -  53 workflows (28%)
Engine: codex   -  13 workflows ( 7%)
Engine: gemini  -   1 workflow  ( 1%)
No explicit engine (defaults to copilot) - 23 workflows (~12%)
Total: 191

Quality of Claude examples: Claude workflows are well-represented across functional categories including CI doctors, daily reports, code analysis, and security audits. Real-world examples like audit-workflows.md, deep-report.md, scout.md, and go-fan.md use engine: claude with realistic configurations. Quality is high.

---

Authentication Requirements

Quick Start and auth docs cover:

• ✅ Copilot: Detailed instructions with direct link to PAT creation, troubleshooting for license issues
• ✅ Claude: Clear instructions, direct ANTHROPIC_API_KEY setup, explicit note that CLAUDE_CODE_OAUTH_TOKEN is NOT supported
• ✅ Codex: Clear instructions, OPENAI_API_KEY and CODEX_API_KEY alternative both documented
• ✅ Gemini: Clear instructions for GEMINI_API_KEY

Secret names documented:

• Copilot: COPILOT_GITHUB_TOKEN (fine-grained PAT, well-documented)
• Claude: ANTHROPIC_API_KEY (API key from Anthropic Console, well-documented)
• Codex: OPENAI_API_KEY or CODEX_API_KEY (documented)
• Gemini: GEMINI_API_KEY (documented)

One gotcha for Claude Code users: CLAUDE_CODE_OAUTH_TOKEN is explicitly not supported — auth.mdx states this clearly. This is the right behavior but will catch Claude users who expect to use their existing Claude subscription auth.

---

Trend Analysis

Metric	2026-04-13	2026-04-15	Change
Overall Score	7.5/10	7.5/10	→
Critical Blockers	0	0	→
Major Obstacles	3	3	→
Minor Confusion	4	5	↑ +1
Persistent Issues	7	6	↓ -1 ✅
Total Workflows	187	191	+4
Claude Workflows	54	53	-1 (grep method)

Fix observed: how-they-work.mdx AI Engines section now includes "Gemini by Google" as the 4th engine (was missing in prior runs). ✅

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix ANTHROPIC_API_KEY setup URL — Change platform.claude.com/docs/en/get-started to console.anthropic.com/settings/keys for direct key creation. File: docs/src/content/docs/reference/auth.mdx line 109
2. Fix architecture AWF diagrams — Replace COPILOT["Copilot CLI"] and "Agent container\nCopilot CLI + MCP client" with engine-agnostic labels. File: docs/src/content/docs/introduction/architecture.mdx lines 181, 252
3. Add non-Copilot path to creating-workflows.mdx — After the Copilot web UI description, add a note directing Claude/Codex/Gemini users to gh aw new as the equivalent CLI path

Priority 2: Major Improvements

1. Add Gemini to quick-start.mdx — Update prerequisites (line 29) and Step 2 (line 67) to include Gemini as the 4th engine option
2. Update engines.md Claude URL — Replace https://www.anthropic.com/index/claude with https://docs.anthropic.com/en/docs/claude-code or similar current URL
3. Add Claude/Gemini examples to secrets bootstrap documentation — Include --engine claude and --engine gemini examples alongside existing --engine copilot example

Priority 3: Nice-to-Have

1. Add "Choosing your engine" comparison — A short table or prose comparing Copilot vs Claude vs Codex vs Gemini strengths for common workflow types would help Claude Code users self-select
2. Add explicit "Getting started without Copilot" callout — A boxed note early in quick-start.mdx saying "Using Claude or Codex? This guide covers all engines — just select your engine in Step 2" would reduce anxiety
3. Expand Gemini workflow examples — Currently only 1 Gemini workflow exists vs 53 Claude, 101 Copilot

---

Positive Findings

What works well for Claude Code users:

• ✅ gh aw add-wizard interactive setup — asks for engine selection, handles ANTHROPIC_API_KEY setup natively
• ✅ auth.mdx has excellent Claude documentation including the important CLAUDE_CODE_OAUTH_TOKEN not-supported callout
• ✅ engines.md feature comparison table is comprehensive and accurate (all 4 engines)
• ✅ max-turns (Claude-only) is well-documented with concrete examples
• ✅ ANTHROPIC_BASE_URL custom endpoint support is documented with a working example
• ✅ 53 real-world Claude workflows in the repo provide excellent examples
• ✅ gh aw new --engine claude injects engine into frontmatter automatically
• ✅ Token weights customization for Claude models is documented
• ✅ how-they-work.mdx now correctly lists all 4 engines including Gemini (fixed!)

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor effort (7.5/10)

Reasoning: The core adoption path is solid. A developer installing gh aw for the first time, running gh aw add-wizard, selecting "Claude" when prompted, and providing their ANTHROPIC_API_KEY will get a working workflow without needing Copilot. The engines documentation and authentication reference are comprehensive. 53 Claude-engine example workflows provide practical templates. The main friction points are editorial: architecture diagrams that visually imply Copilot-only architecture, a web UI authoring path that is Copilot-gated, and a handful of pages that omit Gemini as a fourth option.

Overall Assessment Score: 7.5/10

Breakdown:

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

Next Steps

The score has been stable at 7.5/10 for multiple consecutive days. The oldest unresolved issue (ANTHROPIC_API_KEY URL) has been flagged for 15 days. Priority 1 fixes are small editorial changes (2–3 line edits) that could be completed in under an hour. The architecture diagram relabeling is the most impactful single fix for reducing Claude user confusion.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• 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/setup/cli.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/reference/faq.md
• docs/src/content/docs/setup/creating-workflows.mdx
• Sample workflows: audit-workflows.md, deep-report.md, daily-news.md (engine verification)

---

References:

• §24456574654

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

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