🔍 Claude Code User Documentation Review - 2026-04-02

[github-actions[bot]]

I reviewed the gh-aw documentation as a developer who uses Claude Code and GitHub but does not have a GitHub Copilot subscription. The core verdict: Claude Code users can successfully adopt gh-aw. The Quick Start, Engines reference, and Auth reference all treat Claude as a genuine first-class option. There are no critical blockers — but 4 issues have now persisted for 4 consecutive daily reviews without being fixed, and 1 new minor issue was identified today.

Previous review: 2026-03-31 (§23799204919)
Fixes applied since last review: None

---

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 (docs/src/content/docs/setup/quick-start.mdx) lists Claude as a valid option in prerequisites and the add-wizard interactive setup explicitly prompts for engine selection. The How It Works page states upfront: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex."

Specific Issues Found:

• Issue 1: quick-start.mdx line 29 lists prerequisites as "GitHub Copilot, Anthropic Claude, or OpenAI Codex" — Gemini is now a supported fourth engine but is omitted from this list and from the wizard description at line 67-68. This is misleading to Gemini users but does not affect Claude users.
• Issue 2: how-they-work.mdx intro says "GitHub Copilot (default)" which subtly signals Copilot-centricity, though the word "(default)" is clarified right there. No fix needed, but a note saying "you can omit engine: if using Copilot" would be more actionable.
• Issue 3: The README.md is sparse and links to external documentation — it doesn't surface engine choice at all, which may leave first-time visitors unsure if Claude is supported before they dig into docs.

Recommended Fixes:

• Add Gemini to the Quick Start prerequisites list (line 29) and add-wizard description (line 67-68)
• Consider adding "Claude Code users: see engine: claude →" cross-reference link in the README overview

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot (documented, expected):

• max-continuations — autopilot mode is Copilot-only (clearly documented in engines.md feature comparison table)
• engine.agent — custom agent file (.github/agents/*.agent.md) is Copilot-only (clearly documented)
• Assigning Copilot coding agent to issues/PRs via safe outputs — Copilot-only by nature

Features That Work Without Copilot (engine-agnostic):

• All tool types: edit, bash, github, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows
• All safe outputs: create-issue, add-comment, create-pull-request, add-labels, etc.
• All CLI commands: gh aw compile, gh aw run, gh aw logs, gh aw audit, gh aw status, etc.
• Custom MCP servers
• All security features (firewall, threat detection, integrity filtering)

Missing Documentation:

• web-search requires a third-party MCP server (e.g., Tavily) for Claude — this is documented in the feature comparison table in engines.md, but the dedicated web search guide (guides/web-search.md) only shows a engine: copilot example with no Claude equivalent. A Claude user following that guide would have to infer the pattern works the same way.

---

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 line 181 — AWF firewall diagram labels the AI agent node as COPILOT["Copilot CLI"] inside the "AI Agent Process" box
• File: docs/src/content/docs/introduction/architecture.mdx line 252 — MCP gateway diagram labels the agent container as "Agent container\nCopilot CLI + MCP client\n172.30.0.20" — a Claude user reading this would see "Copilot CLI" and question whether the architecture applies to them (new finding today)
• File: docs/src/content/docs/guides/web-search.md — entire example workflow uses engine: copilot with no Claude alternative

Missing Alternative Instructions:

• No Claude-specific web search example in web-search.md

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0)

No critical blockers. Claude users can complete the full onboarding independently.

⚠️ Major Obstacles (Score: 1)

Obstacle 1: Architecture Diagrams Label Agent as "Copilot CLI"

Impact: Confusion when reading security architecture; a Claude user may question whether the documented security model applies to their setup

Current State:

• architecture.mdx line 181: COPILOT["Copilot CLI"] inside the "AI Agent Process" subgraph of the AWF firewall flowchart
• architecture.mdx line 252: AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"] in the MCP gateway flowchart
• Contrast: line 276 in the MCP sandboxing diagram correctly shows ENGINE["AI Engine<br/>(Copilot, Claude, Codex)"]

Why It's Problematic: A developer reading the security architecture to understand how Claude runs in the sandbox sees "Copilot CLI" embedded in the diagrams. This is factually inaccurate (the same firewall wraps all engines) and creates doubt for non-Copilot users.

Suggested Fix: Rename diagram nodes to engine-agnostic labels:

• COPILOT["Copilot CLI"] → AGENT_CLI["AI Agent CLI"]
• "Agent container\nCopilot CLI + MCP client\n172.30.0.20" → "Agent container\nAI engine CLI + MCP client\n172.30.0.20"

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

💡 Minor Confusion Points (Score: 5)

• Issue 1 [day 4]: auth.mdx line 103 — ANTHROPIC_API_KEY setup links to (platform.claude.com/redacted) (a docs page) instead of the direct API key creation page https://console.anthropic.com/settings/keys`. A developer following this link has to navigate further to actually create a key. File: docs/src/content/docs/reference/auth.mdx
• Issue 2 [day 4]: guides/web-search.md — the single workflow example uses engine: copilot. No Claude MCP web-search example. A Claude user has to infer the pattern is the same (it is, but it should be shown). File: docs/src/content/docs/guides/web-search.md
• Issue 3 [day 4]: quick-start.mdx lines 29, 67-68 — Gemini is a supported engine but absent from the Quick Start prerequisites and add-wizard description. File: docs/src/content/docs/setup/quick-start.mdx
• Issue 4 [day 4]: engines.md line 17 — Claude link uses https://www.anthropic.com/index/claude which is a blog post URL that may redirect unpredictably. A more stable URL would be https://www.anthropic.com/claude or (claude.ai/redacted). File: docs/src/content/docs/reference/engines.md
• Issue 5 [new]: architecture.mdx AWF firewall and MCP gateway diagrams (lines 181, 252) label the agent as "Copilot CLI" — described in detail under Major Obstacles above. File: docs/src/content/docs/introduction/architecture.mdx

---

Engine Comparison Analysis

Available Engines

Engine	Setup Docs	Examples	Auth Docs	Overall
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (89 explicit + 25 default)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐ (37 workflows)	⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐⭐	⭐⭐⭐ (17 workflows)	⭐⭐⭐⭐	⭐⭐⭐½
Gemini	⭐⭐⭐	⭐ (0 workflows)	⭐⭐⭐⭐	⭐⭐

Rating Scale: ⭐⭐⭐⭐⭐ Excellent → ⭐ Poor/Missing

---

Workflow Count by Engine

Engine: copilot  — 89 explicit + 25 default (no engine: field) = 114 total
Engine: claude   — 37 workflows  (+2 from 2026-03-31)
Engine: codex    — 17 workflows  (-1 from 2026-03-31)
Engine: gemini   — 0 workflows   (supported but no examples in repo)

Claude examples cover a good variety of use cases (doc healing, code review, analysis, daily reports). Sufficient for a newcomer to model their own workflows.

---

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 Differences

• web-search: Codex has native support; Copilot, Claude, Gemini require Tavily/Exa MCP server
• max-turns: Claude-only (limits iterations per run)
• max-continuations: Copilot-only (autopilot consecutive runs)
• engine.agent: Copilot-only (custom agent files)

All differences are clearly documented in engines.md feature comparison table — this is a strength.

---

Authentication Requirements

Engine	Secret Name	Setup URL in Docs	URL Quality
Copilot	COPILOT_GITHUB_TOKEN	Pre-filled PAT creation link	⭐⭐⭐⭐⭐
Claude	ANTHROPIC_API_KEY	platform.claude.com/docs/en/get-started	⭐⭐⭐ (docs page, not key creation)
Codex	OPENAI_API_KEY	platform.openai.com/api-keys	⭐⭐⭐⭐⭐
Gemini	GEMINI_API_KEY	aistudio.google.com/api-keys	⭐⭐⭐⭐⭐

Notable contrast: Copilot setup has a pre-filled token creation link that sets the name, description, and permissions automatically — a standout UX. The Claude equivalent should at minimum link directly to console.anthropic.com/settings/keys (the key creation page) rather than the docs landing page.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

None — no critical blockers this review.

Priority 2: Major Improvements

1. Fix architecture diagrams — Rename "Copilot CLI" labels to engine-agnostic "AI Agent CLI" in the AWF firewall diagram (line 181) and MCP gateway diagram (line 252) of architecture.mdx. These diagrams are meant to explain the security architecture for all engines, not just Copilot.

Priority 3: Nice-to-Have Enhancements (all persistent 4+ days)

1. Fix ANTHROPIC_API_KEY link — Change platform.claude.com/docs/en/get-started to https://console.anthropic.com/settings/keys in auth.mdx line 103. Direct link reduces friction.
2. Add Claude web-search example — Add a parallel Claude-engine workflow example to guides/web-search.md alongside the existing Copilot example. MCP configuration is identical, so this is a 10-line addition.
3. Add Gemini to Quick Start — Update quick-start.mdx lines 29 and 67-68 to mention Gemini as a fourth AI Account option.
4. Update Claude URL in engines.md — Change anthropic.com/index/claude to anthropic.com/claude for a more stable canonical URL.

---

Positive Findings

What Works Well

• ✅ gh aw add-wizard interactively handles all three main engines (Copilot, Claude, Codex) — the first-run experience is inclusive
• ✅ engines.md feature comparison table is comprehensive and accurate — shows all per-engine differences at a glance
• ✅ auth.mdx has dedicated sections for all four engines with clear setup steps
• ✅ 37 Claude workflow examples in .github/workflows/ provide abundant patterns to learn from
• ✅ secrets bootstrap command auto-detects the engine in use and validates the right token — works for Claude without special configuration
• ✅ CLI commands (compile, run, logs, audit) are fully engine-agnostic with no Copilot assumptions

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minimal friction

The documentation is well-structured and Claude is treated as a genuine first-class citizen in the key entry points (Quick Start, Engines reference, Auth reference). A Claude Code developer following the Quick Start can be running their first workflow in under 10 minutes.

The main friction points are minor documentation inconsistencies that don't block progress: one auth URL that requires an extra click, one guide that only shows a Copilot example, and architecture diagrams that label a generic agent container as "Copilot CLI." None of these prevent adoption.

The most actionable short-term fix remains the ANTHROPIC_API_KEY link (Priority 3 item 1) — it's a one-line change that directly improves the Claude onboarding path.

Overall Assessment: 8/10

Dimension	Score
Clarity for non-Copilot users	7/10
Claude engine documentation	8/10
Alternative approaches provided	9/10
Engine parity (in docs)	7/10
Overall	8/10

Score unchanged from 2026-03-31 review. 4 persistent issues remain open for day 4.

---

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/guides/web-search.md
• .github/workflows/*.md (179 workflows sampled for engine distribution)

---

References:

• §23902167574 — This workflow run
• §23799204919 — Previous review (2026-03-31)

AI generated by Claude Code User Documentation Review · history

• expires on Apr 3, 2026, 1:20 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 #24307.