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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and deliberately avoids GitHub Copilot, I reviewed the gh-aw documentation to assess whether a non-Copilot user can successfully understand and adopt this tool. The documentation has matured significantly: the core adoption path (install extension → gh aw add-wizard → pick Claude engine → set ANTHROPIC_API_KEY) is well-documented and works without Copilot access. However, 7 persistent documentation issues remain unaddressed for 5–13 consecutive days, and no fixes were observed in today's run — the third consecutive day with zero changes to these issues.

Key Finding: Claude Code users can successfully adopt gh-aw (0 critical blockers), but face moderate friction from Copilot-centric language in architecture diagrams, Gemini omissions in introductory docs, and a suboptimal ANTHROPIC_API_KEY setup URL. Overall score: 7.5/10 (unchanged for 3 days).

---

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

---

Question 1: Onboarding Experience

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

Answer: Yes, mostly. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) explicitly lists Anthropic Claude as a valid AI option in the prerequisites section:

"AI Account - GitHub Copilot, Anthropic Claude, or OpenAI Codex"

The gh aw add-wizard command (Step 2) is interactive and guides users through engine selection, setting up the correct secret (ANTHROPIC_API_KEY, COPILOT_GITHUB_TOKEN, or OPENAI_API_KEY) automatically. This is the strongest part of the onboarding experience for non-Copilot users.

Specific Issues Found:

• Issue 1: quick-start.mdx prerequisites and the Step 2 description both list only three engines (Copilot, Claude, Codex) but Gemini is missing despite being a fully supported 4th engine with complete documentation elsewhere. File: docs/src/content/docs/setup/quick-start.mdx (lines 29, 68).

• Issue 2: how-they-work.mdx (line 26) lists "GitHub Copilot (default), Claude by Anthropic, and Codex" — again omitting Gemini. This is an introduction page that shapes first impressions. File: docs/src/content/docs/introduction/how-they-work.mdx.

Recommended Fixes:

• Add Gemini to the Quick Start prerequisites and add-wizard step description
• Update how-they-work.mdx engine list to include Gemini

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features that require Copilot:

• engine.agent (custom agent files in .github/agents/) — Copilot-only per the engines feature comparison table
• max-continuations (autopilot mode) — Copilot-only
• assign-to-copilot safe output — Copilot-only by design
• GitHub Web Interface authoring (creating-workflows.mdx) — gated behind a Copilot subscription (see Major Obstacle rejig docs #1 below)
• COPILOT_GITHUB_TOKEN secret — only needed for Copilot users

Features that work without Copilot (engine-agnostic):

• All safe outputs (create-issue, add-comment, create-pull-request, etc.)
• All standard tools (edit, bash, github, web-fetch, playwright, cache-memory)
• Custom MCP servers
• gh aw compile, gh aw run, gh aw logs, gh aw audit
• secrets bootstrap --engine claude
• gh aw new --engine claude
• max-turns (Claude-only feature, well documented)

Missing Documentation:

• No explicit "if you don't use Copilot, you can skip X" section in the Quick Start or an index of Copilot-only vs. engine-agnostic features.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/introduction/architecture.mdx (lines 181, 252) — The AWF firewall diagram labels the agent container as "Copilot CLI" and "Agent container\nCopilot CLI + MCP client\n172.30.0.20". A Claude user reading the security architecture would see their engine misrepresented.
• File: docs/src/content/docs/setup/creating-workflows.mdx (lines 21–22, 104, 118–119) — The GitHub Web Interface authoring section opens with "If you have access to GitHub Copilot..." and gh aw init is described as enabling a "Copilot coding agent" dispatcher. No alternative is shown for Claude users.
• File: docs/src/content/docs/introduction/how-they-work.mdx (line 26) — Omits Gemini from engine list.

Missing Alternative Instructions:

• creating-workflows.mdx should note that gh aw new (terminal) or direct .md file editing are the equivalent paths for non-Copilot users.

---

Severity-Categorized Findings

🚫 Critical Blockers — Score: 0/10 (none found)

No critical blockers exist. Claude Code users can fully adopt gh-aw without Copilot.

---

⚠️ Major Obstacles — Score: 3 found

Obstacle 1: GitHub Web Interface Workflow Creation is Copilot-Gated [PERSISTENT — day 5]

Impact: Claude users following the "Creating Workflows" guide hit a wall at the first recommended method

Current State: creating-workflows.mdx line 21–22 reads:

"If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface."

Lines 104, 118–119 describe gh aw init as setting up a "Copilot coding agent" dispatcher. No alternative workflow-creation path is surfaced for Claude users in the same section.

Why It's Problematic: A Claude Code user reading this section would conclude they cannot use the web interface and might miss the alternative terminal-based path (gh aw new).

Suggested Fix: Add a note immediately after the Copilot-gated section: "Don't have Copilot? Use gh aw new in the terminal or edit workflow .md files directly in your editor." Alternatively, rename the VSCode/Claude/Codex section heading to be more prominent.

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

Obstacle 2: Architecture AWF Diagram Mislabels Agent as "Copilot CLI" [PERSISTENT — day 10]

Impact: Misleads Claude/Codex/Gemini users about the system architecture

Current State: architecture.mdx lines 181 and 252:

COPILOT["Copilot CLI"]
AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]
```

Both the AWF firewall diagram and the MCP gateway+firewall integration diagram hardcode "Copilot CLI" as the agent process label.

**Why It's Problematic:** The security architecture page is a key trust-building document. Claude users reading it see their engine replaced with a competitor's product name. This erodes trust and creates confusion about which engine is actually running.

**Suggested Fix:** Replace `"Copilot CLI"` with `"AI Agent CLI"` or `"AI Engine CLI (Copilot/Claude/Codex/Gemini)"` in both diagram node labels.

**Affected Files:** `docs/src/content/docs/introduction/architecture.mdx` (lines 181, 252)

</details>

<details>
<summary>Obstacle 3: ANTHROPIC_API_KEY Setup URL Points to Docs Page, Not Key Creation [PERSISTENT — day 13]</summary>

**Impact:** Extra friction when setting up Claude authentication

**Current State:** `auth.mdx` line 109:
```
1. Create an API key at (platform.claude.com/redacted)
```

This URL leads to a documentation overview page, not directly to the API key creation page.

**Why It's Problematic:** The Copilot section (lines 82–86) uses a direct deep link that pre-fills the token name and permissions. The Claude section sends users to a generic docs page, requiring them to navigate further to create a key. Inconsistent UX signals that Claude is a second-class engine.

**Suggested Fix:** Replace with the direct API keys URL: `https://console.anthropic.com/settings/keys`

**Affected Files:** `docs/src/content/docs/reference/auth.mdx` (line 109)

</details>

---

#### 💡 Minor Confusion Points — Score: 4 found

- **Issue 1:** `how-they-work.mdx` (line 26) omits Gemini from engine list — "GitHub Copilot (default), Claude by Anthropic, and Codex" should also include Gemini. File: `docs/src/content/docs/introduction/how-they-work.mdx`
- **Issue 2:** `cli.md` `secrets bootstrap` flag description (`--engine` option) lists only `copilot, claude, codex` but omits `gemini`. File: `docs/src/content/docs/setup/cli.md`
- **Issue 3:** `engines.md` table lists Claude's URL as `https://www.anthropic.com/index/claude` — a stale URL that may redirect. Should be `https://www.anthropic.com/claude`. File: `docs/src/content/docs/reference/engines.md` (line 17)
- **Issue 4:** `quick-start.mdx` Step 2 description and prerequisites both omit Gemini as an AI account option. File: `docs/src/content/docs/setup/quick-start.mdx` (lines 29, 68)

---

### Engine Comparison Analysis

#### Available Engines

Based on my review, gh-aw supports four engines:

| Engine | Setup Docs | Examples | Auth Docs | Overall Score |
|--------|-----------|----------|-----------|---------------|
| Copilot | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Claude | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Codex | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| Gemini | ⭐⭐⭐ | ⭐ | ⭐⭐⭐⭐ | ⭐⭐ |

Copilot scores highest due to being the default engine with the most workflow examples and dedicated features. Claude scores well with 54 workflow examples and solid auth documentation. Gemini has full auth docs but only 1 workflow example and is absent from several introductory pages.

---

### Authentication Requirements

| Engine | Secret Required | Setup Docs | Direct Key URL |
|--------|----------------|------------|----------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Excellent — deep link pre-fills token settings | ✅ Direct |
| Claude | `ANTHROPIC_API_KEY` | ✅ Good — clear steps, troubleshooting included | ⚠️ Indirect (docs page, not key page) |
| Codex | `OPENAI_API_KEY` | ✅ Good — clear steps | ✅ Direct |
| Gemini | `GEMINI_API_KEY` | ✅ Good — clear steps | ✅ Direct |

**Important Claude-specific note (well-documented):** `CLAUDE_CODE_OAUTH_TOKEN` is explicitly stated as **not supported** in `auth.mdx`. Claude Code users who try to reuse their OAuth token will find a clear error explanation and the correct fix. This is excellent documentation.

---

### Example Workflow Analysis

```
Engine: copilot  — 103 workflows in .github/workflows/
Engine: claude   — 54 workflows in .github/workflows/
Engine: codex    — 13 workflows in .github/workflows/
Engine: gemini   — 1 workflow in .github/workflows/
Total:             187 workflows

Claude has strong example representation (54 workflows, ~29% of total). The repo itself uses Claude as its primary engine for many production workflows (this very review workflow runs on engine: claude), demonstrating real-world parity.

---

Recommended Actions

Priority 1: Critical Documentation Fixes (Low effort, high impact)

1. Fix ANTHROPIC_API_KEY setup URL — Change (platform.claude.com/redacted) to https://console.anthropic.com/settings/keys` — File: auth.mdx line 109 (PERSISTENT 13 days)
2. Fix architecture AWF diagram labels — Replace "Copilot CLI" with "AI Agent CLI" in both mermaid diagrams — File: architecture.mdx lines 181, 252 (PERSISTENT 10 days)
3. Fix stale Claude URL in engines table — Change anthropic.com/index/claude to anthropic.com/claude — File: engines.md line 17 (PERSISTENT 13 days)

Priority 2: Major Improvements

1. Add Claude alternative path in creating-workflows.mdx — Surface gh aw new as the equivalent for non-Copilot users immediately after the Copilot-gated web UI section (PERSISTENT 5 days)
2. Add Gemini to Quick Start prerequisites and Step 2 — File: quick-start.mdx lines 29, 68 (PERSISTENT 13 days)
3. Add Gemini to how-they-work.mdx engine list — File: how-they-work.mdx line 26 (PERSISTENT 7 days)

Priority 3: Nice-to-Have Enhancements

1. Add Gemini to cli.md secrets bootstrap --engine option list — File: cli.md
2. Add a "Copilot-only features" callout box — Clearly list features that require Copilot (agent files, max-continuations, assign-to-copilot) in one place to set expectations
3. Add a "Which engine should I use?" decision guide — Help new users choose between Claude, Codex, Gemini, and Copilot based on their situation

---

Positive Findings

• ✅ Quick Start prerequisites explicitly mention Anthropic Claude as a valid alternative to Copilot
• ✅ gh aw add-wizard interactively handles engine selection and secret setup for all engines
• ✅ auth.mdx explicitly warns that CLAUDE_CODE_OAUTH_TOKEN is NOT supported — critical for Claude Code users
• ✅ Comprehensive ANTHROPIC_API_KEY setup instructions with troubleshooting
• ✅ Engine feature comparison table covers all 4 engines equally
• ✅ 54 Claude engine workflows in the repo demonstrate real-world parity
• ✅ gh aw new --engine claude injects engine into frontmatter automatically
• ✅ max-turns (Claude-only) and ANTHROPIC_BASE_URL (custom endpoint) are well-documented
• ✅ This workflow itself runs on engine: claude — the project eats its own dog food

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor effort.

The core adoption path is well-designed and engine-agnostic. The add-wizard command handles engine selection interactively, authentication docs are comprehensive, and there are 54 real Claude engine workflows demonstrating production viability. A motivated Claude Code user can be up and running in under 10 minutes without touching any Copilot documentation.

The friction points are documentation polish issues, not architectural ones: a Copilot-centric architecture diagram, Gemini omissions in introductory pages, a suboptimal setup URL, and a Copilot-gated web authoring path with no alternative surfaced. None of these block adoption — but they create a "second-class citizen" impression that reduces confidence.

Overall Assessment Score: 7.5/10 (unchanged for 3 consecutive days)

Dimension	Score
Clarity for non-Copilot users	7/10
Claude engine documentation	8/10
Alternative approaches provided	7/10
Engine parity (features/examples)	8/10

Trend

All 7 previously identified issues remain unresolved. No documentation changes were observed today — the third consecutive day with zero fixes. The issues are collectively small in scope (most are 1–2 line changes) but their persistence suggests they may not be on the team's radar.

---

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

---

References:

• §24345348137

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

• expires on Apr 14, 2026, 1:22 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Claude Code User Documentation Review.

A newer discussion is available at Discussion #26220.