🔍 Claude Code User Documentation Review - 2026-03-26

[github-actions[bot]]

Executive Summary

gh-aw is substantially usable by Claude Code users — the documentation explicitly lists Claude as a first-class AI engine with its own authentication docs, 34 example workflows, a feature comparison table, and FAQ entries specific to Claude. However, several Copilot-centric assumptions in key documentation files (especially the architecture page) create subtle friction for users who don't use Copilot and aren't familiar with it. The primary issues are cosmetic/labeling rather than functional gaps.

Key Finding: Claude Code users can get started with gh-aw today. No critical blockers exist. The main friction points are architectural diagrams that hardcode "Copilot CLI" as the agent label, and the implicit default engine behavior (omitting engine: = Copilot) that may confuse users new to the project.

---

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 Anthropic Claude explicitly in Prerequisites: "AI Account – GitHub Copilot, Anthropic Claude or OpenAI Codex". The add-wizard command walks users through selecting between Copilot, Claude, or Codex at Step 2. The required secret (ANTHROPIC_API_KEY) is directly linked in that same step.

Specific Issues Found:

• Issue 1 (quick-start.mdx, line 26–29): Claude is listed second after Copilot in Prerequisites, which is fine. However, the implicit "or" framing may lead users to think they need one of many niche alternatives. A brief parenthetical clarifying "no Copilot subscription required" near the Claude option would reduce confusion.
• Issue 2 (how-they-work.mdx, line 26): The sentence "Workflows support **GitHub Copilot** (default), **Claude by Anthropic**, and **Codex**" correctly conveys that Copilot is the default engine, but a first-time reader who doesn't want Copilot may read "(default)" as an implicit recommendation and feel uncertain if Claude is equally capable.
• Issue 3 (README.md): The README overview and Quick Start section contain no engine-choice framing. A non-Copilot user reading README.md first would need to follow the Quick Start link before discovering Claude is supported.

Recommended Fixes:

• Add a brief note near the Prerequisites AI Account line: e.g., "Choose whichever you have — no Copilot subscription required to use Claude or Codex"
• In how-they-work.mdx, change "GitHub Copilot (default)" to "GitHub Copilot (default — you can use Claude or Codex instead)"
• Add a single sentence to README.md overview section mentioning Claude and Codex as supported alternatives

---

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. The copilot-custom-agents.md reference page is clearly labeled but is linked from the engines page in the Copilot Custom Configuration section.
• max-continuations — Copilot-only autopilot mode (documented in the feature comparison table)
• assign-to-copilot safe output — assigns an issue/PR to GitHub's Copilot coding agent feature
• COPILOT_GITHUB_TOKEN — only needed for Copilot engine

Features That Work Without Copilot (Engine-Agnostic):

• All safe-outputs (create-issue, add-comment, create-pull-request, etc.)
• All MCP servers (mcp-servers:)
• All tools: except engine.agent
• tools.web-fetch, tools.bash, tools.github, tools.playwright, tools.cache-memory, tools.repo-memory
• All permissions: fields
• threat-detection, secret-masking, integrity filtering
• gh aw compile, gh aw run, gh aw logs, gh aw audit — all CLI commands
• max-turns — Claude-only (not Copilot)

Missing Documentation:

• No explicit page comparing "what you gain/lose when using Claude vs Copilot." The feature comparison table in engines.md is excellent but users need to navigate there to find it — it's not surfaced in the onboarding flow.
• The assign-to-copilot safe output is listed in auth.mdx under "Additional Authentication" with no visual indicator that it's Copilot-engine-specific. A non-Copilot user could spend time investigating this before realizing it doesn't apply to them.

---

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: The Agent Workflow Firewall (AWF) diagram labels the agent process as COPILOT["Copilot CLI"] specifically, rather than a generic AGENT["AI Engine"]. A Claude user reading this architecture overview would see a Mermaid diagram that shows their container running "Copilot CLI" — potentially confusing.

• File: docs/src/content/docs/introduction/architecture.mdx — Line 252: The MCP Gateway diagram labels the agent container as AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]. This hardcodes "Copilot CLI" in what should be an engine-agnostic architecture diagram.

• File: docs/src/content/docs/introduction/architecture.mdx — Line 227–237 (Configuration Example): The firewall configuration example uses engine: copilot as the only example, even though the architecture is described as engine-agnostic. Showing engine: claude as a second alternative would reassure non-Copilot users.

• File: docs/src/content/docs/reference/auth.mdx — Lines 35–36: The safe outputs requiring additional auth list includes assign-to-copilot without flagging it as Copilot-engine-specific. Non-Copilot users could be confused why this isn't relevant to their setup.

Missing Alternative Instructions:

• No "Claude-first quick start" path — the only quick start uses the add-wizard flow which engine-selects interactively. This is fine, but a direct "If you're using Claude, here's your minimal frontmatter" example in onboarding docs would help.
• No explanation of Claude's max-turns equivalent for flow control (vs. Copilot's max-continuations)

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10 — None Found)

No critical blockers exist. Claude users can get started, configure authentication, add workflows, and run them without any Copilot dependency.

⚠️ Major Obstacles (Score: 3/10)

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

Impact: Moderate confusion for first-time readers reviewing the security architecture

Current State: Two Mermaid diagrams in architecture.mdx explicitly label containers/processes as "Copilot CLI":

• AWF diagram (line 181): COPILOT["Copilot CLI"]
• MCP Gateway diagram (line 252): "Agent container\nCopilot CLI + MCP client"

Why It's Problematic: A Claude Code user reading the Architecture page (often read early to understand security) sees what appears to be a Copilot-specific architecture, even though the system is engine-agnostic. This undermines trust that Claude is a first-class citizen.

Suggested Fix: Replace COPILOT["Copilot CLI"] with ENGINE["AI Engine\n(Copilot, Claude, Codex)"] in the AWF diagram, and replace "Agent container\nCopilot CLI + MCP client" with "Agent container\nAI Engine + MCP client" in the MCP Gateway diagram.

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

Obstacle 2: Default Engine Behavior Not Immediately Obvious

Impact: Users reading workflow examples without explicit engine: may not realize these are Copilot-only workflows

Current State: The documentation states "Copilot CLI is the default — engine: can be omitted when using Copilot" (engines.md line 21). However, the 85 Copilot workflows in .github/workflows/ that omit engine: are implicitly Copilot workflows. A Claude user copying one of these as a template would get a Copilot workflow and need to add engine: claude.

Why It's Problematic: 85/136 (63%) of example workflows are implicit Copilot workflows. Someone starting by cloning an existing workflow would likely pick a Copilot-default one and not understand why it fails without a Copilot token.

Suggested Fix: In the Quick Start and workflow templates, show engine: claude (or an engine selection comment) in the frontmatter template generated by gh aw new. The --engine claude flag on gh aw new already does this; make it more prominent in the onboarding documentation.

Affected Files: docs/src/content/docs/setup/quick-start.mdx, docs/src/content/docs/setup/cli.md (new command section)

💡 Minor Confusion Points (Score: 4/10)

• Architecture config example uses engine: copilot: The only YAML configuration example in the AWF section (architecture.mdx line 227) shows engine: copilot. A Claude example alongside would normalize it. File: docs/src/content/docs/introduction/architecture.mdx
• assign-to-copilot listed without engine qualifier: The auth page lists this safe output without indicating it's Copilot-only. File: docs/src/content/docs/reference/auth.mdx line 35
• how-they-work.mdx introduces Copilot as default without a "but you can use Claude" aside: The engine mention would benefit from a parenthetical noting Claude is equally supported. File: docs/src/content/docs/introduction/how-they-work.mdx line 26
• No "Why would I use Claude instead of Copilot?" guidance: The FAQ covers billing and capabilities but doesn't address the engine-selection decision from a "I use Claude Code daily" perspective. File: docs/src/content/docs/reference/faq.md
• CLAUDE_CODE_OAUTH_TOKEN FAQ (positive): The FAQ explicitly answers that CLAUDE_CODE_OAUTH_TOKEN is not supported and directs users to ANTHROPIC_API_KEY. This is excellent! But it's buried in a FAQ rather than in the auth page's ANTHROPIC_API_KEY section. File: docs/src/content/docs/reference/faq.md line 332

---

Engine Comparison Analysis

Available Engines

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

• engine: copilot — Default; most extensively documented; most examples; has unique features (max-continuations, custom agent files)
• engine: claude — Well-documented; has unique max-turns feature; explicit auth docs; 34 example workflows in the repo itself; APM/plugin support documented
• engine: codex — Moderately documented; web-search disabled by default (requires explicit declaration); 17 example workflows
• engine: gemini — Basic documentation; recent addition; 4th listed in engines table

Documentation Quality by Engine

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

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

---

Tool Availability Analysis

Engine-Agnostic Tools (work with all engines):

• tools.edit, tools.bash, tools.github, tools.web-fetch
• tools.playwright, tools.cache-memory, tools.repo-memory, tools.qmd
• tools.agentic-workflows (introspection)
• All custom mcp-servers:

Engine-Specific Tools/Features:

• engine.agent (custom agent files) — Copilot only
• tools.web-search — Codex has native support; others use MCP server
• max-turns — Claude only
• max-continuations — Copilot only

Unclear/Undocumented:

• assign-to-copilot safe output: clear it's Copilot-specific once you read it, but not obvious from the auth page overview

---

Authentication Requirements

Current Documentation

The auth page (auth.mdx) covers authentication for:

• ✅ Copilot — detailed with PAT permission walkthrough and troubleshooting
• ✅ Claude — ANTHROPIC_API_KEY with setup link and CLI command
• ✅ Codex — OPENAI_API_KEY with setup link and CLI command
• ✅ Gemini — GEMINI_API_KEY with setup link and CLI command

Missing for Claude Users

• The ANTHROPIC_API_KEY section (auth.mdx lines 97–111) links to (platform.claude.com/redacted) for creating an API key. Notably, this URL should be verified for accuracy — as of March 2026, the standard Anthropic API key creation URL is https://console.anthropic.com/`.
• The FAQ note about CLAUDE_CODE_OAUTH_TOKEN being unsupported is valuable but could be cross-referenced directly from the ANTHROPIC_API_KEY section.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented ✅)
• Claude: ANTHROPIC_API_KEY (documented ✅)
• Codex: OPENAI_API_KEY (documented ✅)
• Gemini: GEMINI_API_KEY (documented ✅)

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot (default/implicit) — 85 workflows
Engine: claude                     — 34 workflows
Engine: codex                      — 17 workflows
Engine: gemini                     — not found in .github/workflows/

Quality of Examples

Copilot Examples: Extensive coverage. Most workflow library examples default to Copilot (by omission). The agentic-workflows.agent.md dispatcher uses Copilot by default.

Claude Examples: Good coverage for a Claude Code user. The audit-workflows.md, blog-auditor.md, claude-code-user-docs-review.md, and cli-version-checker.md in this very repository use engine: claude, demonstrating real-world usage. The repo literally runs this review workflow using Claude — excellent dogfooding.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix "Copilot CLI" labels in architecture diagrams — Replace engine-specific labels with generic "AI Engine" labels in both the AWF and MCP Gateway Mermaid diagrams. File: docs/src/content/docs/introduction/architecture.mdx lines 181, 252
2. Verify ANTHROPIC_API_KEY setup URL — Confirm the link (platform.claude.com/redacted) resolves correctly and leads to API key creation. Consider updating to https://console.anthropic.com/` if the current URL redirects or changes. File: docs/src/content/docs/reference/auth.mdx line 103

Priority 2: Major Improvements

1. Add engine-selection callout to Quick Start — After the add-wizard step, add a note like: "If you chose Claude, your workflow will include engine: claude — no Copilot subscription needed". File: docs/src/content/docs/setup/quick-start.mdx
2. Update architecture.mdx AWF config example — Add a Claude alternative to the engine: copilot YAML example, or use engine: <your-engine> as a placeholder. File: docs/src/content/docs/introduction/architecture.mdx line 227
3. Mark assign-to-copilot as Copilot-specific in auth.mdx — Add "(Copilot only)" next to the assign-to-copilot line in the Additional Authentication section. File: docs/src/content/docs/reference/auth.mdx line 35

Priority 3: Nice-to-Have Enhancements

1. Add "Choosing your engine" guidance — A brief section in either the FAQ or a dedicated guide addressing "I use Claude Code daily — should I use engine: claude?" would help users coming from the Claude ecosystem.
2. Surface CLAUDE_CODE_OAUTH_TOKEN FAQ note in auth.mdx — Cross-reference the FAQ entry in the ANTHROPIC_API_KEY section so users don't get stuck trying OAuth-based auth.
3. Add Claude-specific frontmatter example to Quick Start — Show a minimal engine: claude frontmatter template early in the onboarding documentation so Claude users can see exactly what their workflow should look like.

---

Positive Findings

What Works Well

• ✅ Quick Start explicitly lists Claude as a supported AI Account — immediately visible to non-Copilot users
• ✅ add-wizard engine selection is interactive — prompts user to choose Claude/Copilot/Codex and automatically handles secret setup
• ✅ engines.md feature comparison table — clear, accurate, and covers all engines side-by-side
• ✅ Authentication page covers all engines — ANTHROPIC_API_KEY section is complete with setup steps
• ✅ FAQ has a dedicated Claude auth FAQ entry — correctly explains that CLAUDE_CODE_OAUTH_TOKEN is not supported
• ✅ 34 Claude engine example workflows in the repository — more than sufficient for modeling real usage patterns
• ✅ This review workflow itself uses engine: claude — the project demonstrates Claude as a first-class engine by using it for its own automation
• ✅ gh aw new --engine claude works — the CLI supports creating Claude-prefilled templates directly
• ✅ Claude-specific features documented — max-turns, APM/plugin support for Claude are documented

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor orientation effort.

Reasoning: The documentation fundamentally supports Claude Code users. The onboarding flow (Quick Start → add-wizard → engine selection → secret setup) is engine-agnostic and guides users through Claude setup interactively. Authentication is documented, examples exist, and Claude-specific features like max-turns are covered. The main friction is cosmetic: architecture diagrams label components as "Copilot CLI" when they're actually engine-agnostic, and 63% of example workflows omit the engine: field (implicitly defaulting to Copilot), which could trip up users who copy-paste an example without realizing they need to add engine: claude.

A skilled developer using Claude Code would likely spend 5–10 extra minutes resolving confusion from the Copilot-centric architecture diagram labels before successfully setting up their first Claude workflow. This is friction, not a blocker.

Overall Assessment Score: 7.5/10

Breakdown:

• Clarity for non-Copilot users: 7/10 (onboarding is fine; architecture docs are Copilot-centric)
• Claude engine documentation: 8/10 (auth, feature comparison, and FAQ all solid; architecture diagrams drag it down)
• Alternative approaches provided: 8/10 (all four engines documented; features table clear)
• Engine parity (in docs): 7/10 (85 Copilot examples vs 34 Claude examples; Copilot has more unique features)

Next Steps

1. Fix the two Mermaid diagram labels in architecture.mdx (quick win, high impact on first impressions)
2. Verify the Anthropic API key setup URL is current
3. Add a "no Copilot required" callout in the Quick Start guide
4. Consider a short "Choosing your AI engine" section for users deciding between Claude, Copilot, and Codex

---

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 (excerpts)
• docs/src/content/docs/reference/github-tools.md (excerpts)
• docs/src/content/docs/reference/copilot-custom-agents.md (excerpts)
• .github/workflows/audit-workflows.md (sample Claude workflow)

---

Report Generated: §23596216828
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food 🐕)

AI generated by Claude Code User Documentation Review · history

• expires on Mar 27, 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 #23238.