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

[github-actions[bot]]

Executive Summary

This is day 3 of daily automated documentation reviews from a Claude Code user perspective (day 2 was 2026-04-11, day 1 was 2026-04-10). After reviewing all core documentation files — README, Quick Start, How They Work, Architecture, Tools, CLI Commands, Engines, and Authentication — Claude Code users can successfully adopt gh-aw with zero critical blockers. The core adoption path (interactive gh aw add-wizard, engine selection prompt, ANTHROPIC_API_KEY setup) is well-documented and works reliably.

Key Finding: The same 7 issues identified in prior reviews remain unaddressed for 4–12 consecutive days. No documentation fixes were observed. Score holds at 7.5/10. The most actionable items for maintainers are small, targeted text changes to 4 files.

---

Persona Context

Reviewed 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 friction. The quick-start.mdx correctly lists Claude as an option in Prerequisites (line 29) and the add-wizard flow (Step 2) interactively prompts for engine selection and the correct secret (ANTHROPIC_API_KEY). A Claude Code user can complete the Quick Start entirely without touching Copilot.

Specific Issues Found:

• quick-start.mdx line 29 — Prerequisites list only three engines: "GitHub Copilot, Anthropic Claude or OpenAI Codex." Gemini is the 4th supported engine (since engines.md and auth.mdx both document it) but is absent here. A Gemini user would be confused.
• how-they-work.mdx line 26 — States: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." Gemini is missing from the introductory conceptual page.
• creating-workflows.mdx lines 21–23 — The GitHub Web Interface section opens with: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." Claude Code users without Copilot have no equivalent web-UI authoring path documented.

Recommended Fixes:

• Add "or [Google Gemini]((aistudio.google.com/redacted) to the engine lists in quick-start.mdx and how-they-work.mdx.
• In creating-workflows.mdx, add a note that web UI authoring currently requires Copilot, and direct non-Copilot users to the CLI section immediately below.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features that require Copilot:

• GitHub Web Interface workflow authoring (creating-workflows.mdx §"GitHub Web Interface") — explicitly gated behind a Copilot subscription.
• /agent agentic-workflows in Copilot Chat on github.com (creating-workflows.mdx line 123) — uses the dispatcher agent registered in GitHub Copilot's custom agent system. This is expected behavior, but there's no equivalent for Claude Code users in the web UI.
• max-continuations — Copilot-only autopilot mode feature. Well-documented as Copilot-only in engines.md.
• engine.agent — custom Copilot agent files. Clearly marked Copilot-only.

Features that work without Copilot (engine-agnostic):

• All CLI commands (gh aw add-wizard, compile, run, logs, audit, status, etc.)
• All Tools: edit, github, bash, web-fetch, web-search, playwright, cache-memory, repo-memory, agentic-workflows, qmd
• All MCP server integrations
• Safe Outputs subsystem
• Threat detection
• Network firewall
• Manual editing and compilation workflow

Missing Documentation:

• The gh aw init description (creating-workflows.mdx lines 104–123) focuses entirely on what it enables for Copilot Chat. There's no note about what gh aw init provides for Claude Code users (MCP server integration, .gitattributes, VS Code settings are engine-agnostic; only the dispatcher agent is Copilot-specific).

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

File	Location	Issue
quick-start.mdx	Line 29 (Prerequisites)	Lists 3 engines, missing Gemini
how-they-work.mdx	Line 26 (AI Engines section)	Lists 3 engines, missing Gemini
creating-workflows.mdx	Lines 21–23 (Web Interface)	Hard gate: "If you have access to GitHub Copilot"
creating-workflows.mdx	Lines 104–123 (gh aw init)	Describes only Copilot-specific benefits of gh aw init
architecture.mdx	Lines 181, 252 (AWF diagram)	Mermaid node labeled "Copilot CLI" instead of "AI Agent CLI"
cli.md	Line 218 (secrets bootstrap)	--engine option listed as (copilot, claude, codex), missing gemini
auth.mdx	Line 109 (ANTHROPIC_API_KEY setup)	URL points to docs page, not direct API key creation
engines.md	Line 18 (Claude entry)	URL anthropic.com/index/claude appears outdated

Missing Alternative Instructions:

• No mention of how Claude Code users can author workflows from the GitHub web UI (answer: they can't without Copilot, but this should be stated clearly).
• The gh aw init documentation doesn't distinguish which features are Copilot-only (dispatcher agent) vs. engine-agnostic (MCP server, .gitattributes, VS Code settings).

---

Severity-Categorized Findings

🚫 Critical Blockers — Score: 0/10

None. Claude Code users can successfully install, configure, and run their first workflow.

---

⚠️ Major Obstacles — Score: 3/10

Obstacle 1: GitHub Web Interface Workflow Authoring Copilot-Gated

Impact: Claude Code users cannot use the GitHub web UI to author new workflows interactively.

Current State (creating-workflows.mdx, line 21): "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface."

Why It's Problematic: The section provides no information for non-Copilot users — it just... stops. A Claude Code user skims this, finds no path forward, and must infer from context that they should scroll to the CLI section. An explicit pointer would remove ambiguity.

Suggested Fix: Add a callout: "⚠️ The GitHub Web Interface authoring experience requires GitHub Copilot. If you're using Claude or Codex, use the CLI approach instead."

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

Obstacle 2: ANTHROPIC_API_KEY Setup URL Points to Docs, Not Console

Impact: Extra friction getting the API key — users land on a documentation landing page rather than the key creation form.

Current State (auth.mdx, line 109):

1. Create an API key at (platform.claude.com/redacted)
```

**Why It's Problematic:** `platform.claude.com/docs/en/get-started` is a "Getting Started" documentation page that describes features. The actual API key creation page is `https://console.anthropic.com/settings/keys`. This is a 2-click UX difference but causes confusion for new users who don't know Anthropic's console layout.

**Contrast with Copilot:** The Copilot setup provides a pre-filled URL that navigates directly to the PAT creation form with correct permissions pre-selected — a much better UX.

**Suggested Fix:** Change to `https://console.anthropic.com/settings/keys` and model it after the Copilot setup: include a one-step link that gets the user directly to key creation.

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

</details>

<details>
<summary>Obstacle 3: Gemini Missing from Key Introductory Documentation</summary>

**Impact:** New Gemini users who read the Quick Start or How They Work docs are told gh-aw supports 3 engines. `engines.md` and `auth.mdx` both fully document Gemini, creating inconsistency.

**Current State:**
- `quick-start.mdx` line 29: "GitHub Copilot, Anthropic Claude or OpenAI Codex"
- `how-they-work.mdx` line 26: "GitHub Copilot (default), Claude by Anthropic, and Codex"

**Why It's Problematic:** Gemini is a fully supported engine with 1 workflow example, documentation in `engines.md`, and `auth.mdx`. The introductory docs create a false impression of 3-engine support.

**Suggested Fix:** Update both sentences to: "GitHub Copilot (default), Claude by Anthropic, Codex, and Google Gemini."

**Affected Files:** `docs/src/content/docs/setup/quick-start.mdx`, `docs/src/content/docs/introduction/how-they-work.mdx`

</details>

---

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

- **AWF Diagram Copilot Label** — `architecture.mdx` lines 181 and 252: Mermaid diagram labels agent node as "Copilot CLI" and "Copilot CLI + MCP client". Should be "AI Agent CLI" for accuracy. File: `docs/src/content/docs/introduction/architecture.mdx`
- **`secrets bootstrap` Gemini missing** — `cli.md` line 218: `--engine` option description lists `(copilot, claude, codex)` but Gemini is a supported engine. File: `docs/src/content/docs/setup/cli.md`
- **Claude engine URL outdated** — `engines.md` line 18 links to `anthropic.com/index/claude`. Should be `anthropic.com/claude-code` or `anthropic.com`. File: `docs/src/content/docs/reference/engines.md`
- **`gh aw init` Copilot-centric description** — `creating-workflows.mdx` lines 118–119 describe the dispatcher agent and MCP setup in Copilot-centric terms without noting which benefits are engine-agnostic. File: `docs/src/content/docs/setup/creating-workflows.mdx`

---

### Engine Comparison Analysis

#### Available Engines

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

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

**Notes:**
- Copilot: Default engine, explicit pre-filled setup links, most examples, fully referenced in intro docs.
- Claude: Well-documented auth, good example count (52 workflows), `max-turns` is Claude-only and well-explained. `CLAUDE_CODE_OAUTH_TOKEN` unsupported — explicitly stated in `auth.mdx` (excellent!).
- Codex: Auth docs solid. `web-search` opt-in behavior documented. Fewer examples.
- Gemini: Fully documented in `engines.md` and `auth.mdx`, but missing from 2 introductory pages, and only 1 workflow example.

---

### Tool Availability Analysis

**Engine-Agnostic Tools** (all engines):
- `edit`, `bash`, `github`, `web-fetch`, `playwright`, `cache-memory`, `repo-memory`, `qmd`, `agentic-workflows`
- All custom MCP servers

**Engine-Specific Features:**
- `web-search`: Codex has native support (opt-in with `tools: web-search:`); all others use third-party MCP servers
- `max-turns`: Claude-only
- `max-continuations`: Copilot-only
- `engine.agent` (custom agent files): Copilot-only

**Unclear/Undocumented:**
- `tools.timeout` defaults vary by engine (Claude: 60s, Codex: 120s, Copilot/Gemini: engine-managed) — this IS documented in `engines.md` but only in the Timeout section, not on the Tools page. Low risk.

---

### Authentication Requirements

#### Documentation Status

| Engine | Auth Documented | Direct Key URL | Troubleshooting |
|--------|----------------|----------------|-----------------|
| ✅ Copilot | ✅ Full | ✅ Pre-filled PAT link | ✅ License check notes |
| ✅ Claude | ✅ Full | ⚠️ Docs page, not console | ✅ 401/403 guidance |
| ✅ Codex | ✅ Full | ✅ Direct link | ✅ Azure OpenAI example |
| ✅ Gemini | ✅ Full | ✅ Direct link | ✅ 401 guidance |

#### Missing for Claude Users

The `ANTHROPIC_API_KEY` setup URL (`platform.claude.com/docs/en/get-started`) does not lead directly to key creation. Recommended URL: `https://console.anthropic.com/settings/keys`.

The note about `CLAUDE_CODE_OAUTH_TOKEN` being unsupported is present and helpful — buried in auth.mdx but readable for users who look.

#### Secret Names

| Engine | Secret Name | Status |
|--------|------------|--------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Documented |
| Claude | `ANTHROPIC_API_KEY` | ✅ Documented |
| Codex | `OPENAI_API_KEY` or `CODEX_API_KEY` | ✅ Both documented |
| Gemini | `GEMINI_API_KEY` | ✅ Documented |

---

### Example Workflow Analysis

#### Workflow Count by Engine (2026-04-12)

```
Engine: copilot  — 98 workflows
Engine: claude   — 52 workflows
Engine: codex    — 13 workflows
Engine: gemini   —  1 workflow
No engine field  — 25 workflows (default: copilot)
─────────────────────────────
Total            — 187 workflows (with some workflows having extended block-style engine config)

Compared to yesterday (2026-04-11): total unchanged at 187. Claude: -1, Copilot: -1, Codex/Gemini stable. Likely a workflow had its engine declaration modified.

Quality of Examples

Copilot Examples: Dominant engine. Daily status reports, CI doctor, triage, security scanning — wide variety. Well-tested.

Claude Examples: 52 examples covering a broad range of use cases. This is strong coverage. The workflow running this report itself uses engine: claude — eating our own dog food.

Codex Examples: 13 examples — adequate for demonstrating capabilities.

Gemini Examples: Only 1 workflow (smoke-gemini.md). Users wanting to try Gemini have very few reference points beyond the engine docs. The full engine + auth documentation exists but example workflows are sparse.

---

Trend Analysis (Days 1–3)

Date	Score	Blockers	Major	Minor	Total Workflows	Issues Fixed
2026-04-10	7.0	0	3	5	187	—
2026-04-11	7.5	0	3	4	187	0
2026-04-12	7.5	0	3	4	187	0

Observation: The score improvement from day 1 to day 2 reflected better Gemini coverage being noticed (first Gemini workflow). Since then, no documentation fixes have been applied to any of the 7 issues. The 7 issues have now persisted for 4–12 days each without resolution.

---

Recommended Actions

Priority 1: Critical Documentation Fixes (Small changes, high impact)

1. Fix ANTHROPIC_API_KEY setup URL — Change platform.claude.com/docs/en/get-started to console.anthropic.com/settings/keys in auth.mdx. 1-line fix.
2. Add Gemini to Quick Start prerequisites — Update quick-start.mdx line 29 to include Gemini. 1-line fix.
3. Add Gemini to How They Work — Update how-they-work.mdx line 26. 1-line fix.

Priority 2: Major Improvements (Still small changes)

4. Clarify Web Interface authoring requires Copilot — Add a callout in creating-workflows.mdx pointing non-Copilot users to the CLI section.
5. Fix AWF diagram labels — Change "Copilot CLI" to "AI Agent CLI" in architecture.mdx mermaid diagram (lines 181 and 252).
6. Add Gemini to secrets bootstrap docs — Update cli.md line 218 --engine option list to include gemini.

Priority 3: Nice-to-Have Enhancements

7. Update Claude URL in engines.md — Replace anthropic.com/index/claude with current Claude homepage URL.
8. Add 3–5 more Gemini workflow examples — Currently only 1 exists; users wanting to adopt Gemini have minimal reference.
9. Clarify gh aw init engine-agnostic benefits — Note in creating-workflows.mdx which parts of gh aw init benefit all users (MCP server, .gitattributes, VS Code settings) vs. Copilot-only (dispatcher agent).

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick Start prerequisites — all three major engines listed upfront
• ✅ Interactive add-wizard — prompts for engine choice and correct secret type, works perfectly for Claude
• ✅ auth.mdx ANTHROPIC_API_KEY section — clear setup steps with troubleshooting (401/403 errors documented)
• ✅ CLAUDE_CODE_OAUTH_TOKEN explicitly unsupported — Claude Code users who try to authenticate via OAuth are redirected to the correct method
• ✅ engines.md feature comparison table — covers all 4 engines, Claude's unique max-turns feature is explained
• ✅ 52 Claude engine workflow examples — excellent coverage, more than enough for reference
• ✅ gh aw new --engine claude — injecting engine into frontmatter template out of the box
• ✅ secrets bootstrap --engine claude — targeted secret validation
• ✅ Custom endpoint support — ANTHROPIC_BASE_URL for corporate proxies is well-documented
• ✅ Tools are fully engine-agnostic — Claude users have access to all the same tools as Copilot users

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction.

A Claude Code user can follow the Quick Start, configure ANTHROPIC_API_KEY, and run their first workflow successfully in under 10 minutes. The interactive add-wizard is engine-agnostic and guides users correctly. The authentication documentation is clear and includes the important note that CLAUDE_CODE_OAUTH_TOKEN is not supported (preventing a common mistake).

The friction points are real but small: an API key URL that's one hop too far, Gemini missing from two introductory pages, a web UI authoring path that dead-ends for Claude users without explanation, and some Copilot-centric labeling in architecture diagrams. None of these are blockers — they are polish items that would take a developer 30–60 minutes to fix across all affected files.

Overall Assessment Score: 7.5/10

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

Next Steps

The 7 persistent issues identified on days 1–3 have not been addressed. Priority 1 fixes are all 1-line changes with no risk. If maintainers want to move the score to 8.5/10, addressing items 1–3 (Gemini in intro docs + ANTHROPIC_API_KEY URL) would accomplish that immediately.

---

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/reference/tools.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• .github/workflows/*.md (187 workflow files, engine distribution analysis)
• /tmp/gh-aw/cache-memory/claude-code-docs-review.json (prior run data, days 1–2)
• /tmp/gh-aw/cache-memory/claude-user-review.json (prior run data, day 2 alt format)

---

References:

• §24307545423

Report Generated: Run §24307545423 · 2026-04-12
Workflow: claude-code-user-docs-review · Engine: claude (eating our own dog food)

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

• expires on Apr 13, 2026, 1:18 PM UTC