[claude-code-user-docs-review] Claude Code User Documentation Review - 2026-05-09

[github-actions[bot]]

Executive Summary

Reviewed the gh-aw documentation as a developer who uses Claude Code (not GitHub Copilot). The good news: Claude is a first-class engine — it has dedicated authentication docs, 49 example workflows in .github/workflows/, and the engines.md reference is excellent. The friction: the Quick Start treats Copilot as the canonical path, the gh aw init command sets up Copilot-specific scaffolding by default, and several flagship features (custom agents, autopilot, harness) are Copilot-only without prominent disclosure.

Key Finding: A Claude Code user can successfully adopt gh-aw, but the onboarding pushes them down a Copilot-shaped path. The docs reward users who know where to look (reference/engines.md, reference/auth.mdx) and penalize users following the linear Quick Start.

---

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, but with friction. The Quick Start (docs/src/content/docs/setup/quick-start.mdx) is engine-agnostic in spirit — Step 2 explicitly says add-wizard will "Select an AI Engine - Choose between Copilot, Claude, Codex, or Gemini" — but the supporting prose only walks through COPILOT_GITHUB_TOKEN setup inline. The Claude path requires clicking out to reference/auth.mdx.

Specific Issues Found:

• quick-start.mdx:71 — Step 3 only shows the inline [!NOTE] block for COPILOT_GITHUB_TOKEN setup (PAT creation, fine-grained permissions). No equivalent inline block for ANTHROPIC_API_KEY setup.
• quick-start.mdx:14 — The example workflow (githubnext/agentics/daily-repo-status) is hosted in a separate repo. A reader cannot tell from the Quick Start whether this workflow runs equally well on Claude.
• README.md:14 — "Write agentic workflows in natural language markdown, and run them in GitHub Actions" — engine-neutral framing, good. But the README never mentions which engines are supported in the at-a-glance section.

Recommended Fixes:

• Add a parallel [!NOTE] block in Step 3 of Quick Start for ANTHROPIC_API_KEY (link to https://console.anthropic.com/, show gh aw secrets set ANTHROPIC_API_KEY).
• Add a one-line "Engines supported: Copilot, Claude, Codex, Gemini" callout in the README and at the top of Quick Start.
• Annotate the sample workflow with which engines it has been tested against.

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

The engines.md feature comparison table (reference/engines.md:33) is the authoritative source — and it's accurate. The problem is that this critical compatibility info isn't surfaced where users will hit it.

Features That Require Copilot:

• engine.agent (custom agent files in .github/agents/) — Copilot only (engines.md:39)
• engine.harness (custom harness script) — Copilot only (engines.md:42, engines.md:300)
• max-continuations (autopilot mode) — Copilot only (engines.md:36)
• gh aw init creates .github/agents/agentic-workflows.agent.md by default — a Copilot-specific dispatcher agent (setup/cli.md:134). Not labeled as Copilot-specific.

Features Claude-Specific:

• max-turns — Claude only (engines.md:35)

Features That Work Without Copilot (engine-agnostic):

• All tools: entries (bash, edit, github, playwright, cache-memory, repo-memory, qmd, agentic-workflows, web-fetch)
• mcp-servers: (custom MCP integration)
• All safe-outputs: (create-issue, add-comment, create-pull-request, etc.)
• tools.cli-proxy (MCP CLI mounting)
• tools.timeout and tools.startup-timeout
• engine.api-target (custom endpoints)
• engine.bare mode
• engine.env and BYOK-style overrides
• All CLI commands (compile, run, audit, logs, health, status)

Missing Documentation:

• The Architecture page (introduction/architecture.mdx:188) hard-codes COPILOT["Copilot CLI"] in the AWF mermaid diagram — gives the impression that AWF is Copilot-specific. The AWF protects all engines, but the diagram doesn't say so.
• tools.md does not flag which tools are engine-specific (none are, but a brief "all tools work with all engines" reassurance would help).
• No documentation on what happens if you run gh aw init with the intent of using Claude — does the agent file matter? Should it be deleted?

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• introduction/architecture.mdx:188 — AWF diagram subgraph Agent contains COPILOT["Copilot CLI"] as the canonical agent process. Should be a generic AGENT["AI Agent CLI"] or include all engines.
• introduction/architecture.mdx:228 — Configuration example uses engine: copilot. Could include a comment showing this works with claude/codex/gemini too.
• introduction/architecture.mdx:280 — MCP sandboxing diagram lists (Copilot, Claude, Codex) for the AI Engine — Gemini is missing.
• setup/quick-start.mdx:36 — Step 1 (extension install) is engine-agnostic, good.
• setup/quick-start.mdx:67-79 — Step 2-3 narrative is structured around Copilot setup; alternative engine flows are pointer-only.
• setup/cli.md:134 — gh aw init description says "creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md)" without noting this only matters for Copilot users.
• reference/engines.md:23 — "Copilot CLI is the default — engine: can be omitted when using Copilot." Followed by engines.md:27 "If you are unsure, start with Copilot and switch later by changing only engine: and the corresponding secret." For a user who actively chose Claude, this nudge is friction.

Missing Alternative Instructions:

• No "Quick Start for Claude" variant or sidebar flag.
• No comparison guide "Why Claude vs Copilot for gh-aw?" — the engines.md Which engine should I choose? section is one paragraph and Copilot-favoring.
• No FAQ entry for "I don't use Copilot — can I still use gh-aw?"
• The Claude Tool Enforcement Security Model section in engines.md:434 is excellent and Claude-specific — good. But there's no equivalent depth for "Claude differences you should know" outside security.

---

Severity-Categorized Findings

Critical Blockers (Score: 1/10)

No true blockers found. A Claude user who reads reference/engines.md and reference/auth.mdx can fully onboard.

Blocker 1: gh aw init defaults assume Copilot scaffolding

Impact: Mild — users can ignore the agent file or use --no-mcp, but it's confusing.

Current State: setup/cli.md:134 says "Configures .gitattributes, creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md)". No flag like --engine claude documented for init.

Why It's a Blocker: A Claude user running gh aw init gets a Copilot-only artifact (*.agent.md file) committed to their repo, with no explanation of whether to delete it.

Fix Required: Document that the agent file is only used by the Copilot engine. Add a note: "If you plan to use Claude/Codex/Gemini exclusively, you can delete .github/agents/agentic-workflows.agent.md — it has no effect."

Affected Files: docs/src/content/docs/setup/cli.md

Major Obstacles (Score: 4/10)

Obstacle 1: Quick Start does not show Claude auth inline

Impact: Significant friction in the linear onboarding path.

Current State: quick-start.mdx:76-79 has an inline [!NOTE] block walking through PAT creation for COPILOT_GITHUB_TOKEN. ANTHROPIC_API_KEY users must click out to reference/auth.mdx.

Why It's Problematic: Half of the four supported engines (Claude, Codex, Gemini) require API keys, not GitHub PATs. The Quick Start treats the API-key flow as a footnote even though add-wizard lets users pick any of the four.

Suggested Fix: Replace the single Copilot [!NOTE] block with a tabbed/expandable section covering all four engine setups. Each tab links to the API key console and shows the matching gh aw secrets set command.

Affected Files: docs/src/content/docs/setup/quick-start.mdx

Obstacle 2: Architecture diagrams hard-code Copilot CLI

Impact: Reading introduction/architecture.mdx as a Claude user gives the wrong impression that the security architecture is Copilot-shaped.

Current State: architecture.mdx:188 AWF mermaid diagram shows COPILOT["Copilot CLI"] as the agent process. The Squid proxy, MCP gateway, and threat-detection job actually protect all engines.

Why It's Problematic: Visual artifacts carry strong signal. A user evaluating gh-aw for Claude will conclude (incorrectly) that the security model is built around Copilot.

Suggested Fix: Replace COPILOT node label with AGENT["AI Agent CLI<br/>(Copilot, Claude, Codex, Gemini)"] in architecture.mdx:188-191. Also add Gemini to the engine list at architecture.mdx:280.

Affected Files: docs/src/content/docs/introduction/architecture.mdx

Obstacle 3: "Which engine should I choose?" nudges toward Copilot

Impact: Reads as if Claude is a fallback rather than a peer.

Current State: engines.md:27 reads "Copilot is the default choice for most users because it supports the broadest gh-aw feature set... If you are unsure, start with Copilot and switch later."

Why It's Problematic: True for engine.agent/engine.harness/max-continuations — but a Claude Code user who chose Claude deliberately is not "unsure". The framing assumes the reader has no engine preference.

Suggested Fix: Reframe as a tradeoffs paragraph — "Choose Copilot if you need custom agents or autopilot continuations. Choose Claude if you want longer reasoning sessions with max-turns or already pay for Anthropic API access. Choose Codex/Gemini for existing OpenAI/Google tooling integrations."

Affected Files: docs/src/content/docs/reference/engines.md

Minor Confusion Points (Score: 6/10)

• Issue 1: README contains 467 community attribution entries (README.md:60-983) — pushes the actual content (Documentation, Contributing, Sharing Feedback) far below the fold. — File: README.md
• Issue 2: introduction/overview.mdx:13 lists "Copilot CLI, Claude by Anthropic, or Codex" — Gemini is omitted. — File: docs/src/content/docs/introduction/overview.mdx
• Issue 3: No FAQ entry on "Do I need a Copilot subscription to use gh-aw?" — File: docs/src/content/docs/reference/faq.md
• Issue 4: reference/engines.md:280 MCP sandboxing diagram missing Gemini and Crush from (Copilot, Claude, Codex) engine list. — File: docs/src/content/docs/reference/engines.md
• Issue 5: gh aw init --engine claude is not documented as an option — only gh aw new --engine claude injects engine into frontmatter (setup/cli.md:181).

---

Engine Comparison Analysis

Documentation Quality by Engine

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐	⭐	⭐⭐⭐⭐	⭐⭐
Crush (exp)	⭐⭐	n/a	⭐⭐	⭐⭐
OpenCode (exp)	⭐⭐	n/a	⭐⭐	⭐⭐

---

Tool Availability Analysis

Engine-Agnostic Tools (work with Claude): bash, edit, github, playwright, cache-memory, repo-memory, qmd, agentic-workflows, web-fetch, cli-proxy, all mcp-servers: configurations, all safe-outputs:.

Engine-Specific Tools/Features:

• web-search behavior differs (Codex has it native; others need MCP) — documented at tools.md:67.
• Custom agents (engine.agent) — Copilot only.
• Custom harness (engine.harness) — Copilot only.
• Autopilot (max-continuations) — Copilot only.
• max-turns — Claude only.

Unclear/Undocumented: None significant.

---

Authentication Requirements

Current Documentation

Engine	Setup Docs Found	Inline in Quick Start
Copilot	Yes (auth.mdx:76)	Yes
Claude	Yes (auth.mdx:103)	No (link only)
Codex	Yes (auth.mdx:129)	No (link only)
Gemini	Yes (auth.mdx:171)	No (link only)

Missing for Claude Users

• Claude API key setup is not shown inline in Quick Start step 3.
• auth.mdx:109 links to (platform.claude.com/redacted) — should also reference https://console.anthropic.com/` which is the more familiar entry point.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented, fine-grained PAT)
• Claude: ANTHROPIC_API_KEY (documented at auth.mdx:103)
• Codex: OPENAI_API_KEY or CODEX_API_KEY (documented)
• Gemini: GEMINI_API_KEY (documented)

All secret names are documented. Good coverage.

---

Example Workflow Analysis

Workflow Count by Engine

engine: copilot   - 96 workflows (explicit)
engine: claude    - 49 workflows
engine: codex     - 12 workflows
engine: gemini    -  0 workflows
no engine field   - 24 workflows (defaults to Copilot)
Total             - 218 .md workflows

Effective Copilot share: ~55%. Effective Claude share: ~22%.

Quality of Examples

Copilot Examples: Plentiful, cover most workflow patterns.

Claude Examples: 49 workflows is a respectable corpus. Examples like audit-workflows.md, aw-failure-investigator.md, approach-validator.md, and blog-auditor.md showcase Claude with cli-proxy, agentic-workflows, and complex imports. Sufficient for a Claude user to learn from.

Gemini Examples: Zero. The docs claim Gemini support but the project itself does not eat its own dog food for Gemini.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Add inline Claude auth setup to Quick Start Step 3 — show ANTHROPIC_API_KEY setup alongside COPILOT_GITHUB_TOKEN — File: docs/src/content/docs/setup/quick-start.mdx
2. Annotate gh aw init agent-file scaffolding as Copilot-specific — note that .github/agents/agentic-workflows.agent.md only matters for Copilot — File: docs/src/content/docs/setup/cli.md
3. Generalize architecture diagrams — replace Copilot CLI node label with AI Agent CLI and list all engines in MCP sandboxing diagram — File: docs/src/content/docs/introduction/architecture.mdx

Priority 2: Major Improvements

1. Rewrite "Which engine should I choose?" as a tradeoffs guide — drop the "start with Copilot" framing — File: docs/src/content/docs/reference/engines.md
2. Add an FAQ entry: "Do I need GitHub Copilot to use gh-aw?" — File: docs/src/content/docs/reference/faq.md
3. List supported engines in README at-a-glance section — File: README.md

Priority 3: Nice-to-Have Enhancements

1. Per-engine Quick Start variants — "Quick Start with Claude", "Quick Start with Codex".
2. Engine migration guide — "Switching from Copilot to Claude in an existing workflow".
3. Add Gemini example workflows so Gemini users have real-world references.

---

Positive Findings

• The engines.md feature comparison table (reference/engines.md:33) is excellent — clearly maps every feature to every engine.
• auth.mdx:103 has dedicated, well-structured ANTHROPIC_API_KEY setup with troubleshooting.
• gh aw secrets bootstrap --engine claude exists for engine-specific secret discovery.
• gh aw new --engine claude correctly injects engine into frontmatter template.
• 49 Claude-engine workflows in .github/workflows/ provide real, working examples.
• The Claude Tool Enforcement Security Model section (engines.md:434) demonstrates careful engine-specific security thinking.
• All tools:, mcp-servers:, and safe-outputs: configuration is engine-agnostic — no Claude/Copilot fork.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate friction.

Reasoning: A Claude user who reads reference/engines.md and reference/auth.mdx will find everything they need: secret name, setup steps, feature compatibility, working examples. The friction is in the linear onboarding path (Quick Start) and visual identity (architecture diagrams), both of which feel Copilot-shaped. The technical surface is engine-equal; the documentation surface tilts Copilot.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 6/10
• Claude engine documentation: 8/10
• Alternative approaches provided: 8/10
• Engine parity in narrative: 5/10

Next Steps

1. Apply Priority 1 fixes to remove the most visible Copilot bias from onboarding.
2. Consider whether "Quick Start with Claude" deserves a dedicated page given that 22% of in-repo workflows already use Claude.
3. Track this review's score over time to measure improvement.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.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/introduction/overview.mdx
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• .github/workflows/audit-workflows.md (sample Claude workflow)

---

Report Generated: §25601365257
Engine Used: claude (eating our own dog food)

Generated by Claude Code User Documentation Review · ● 11.7M · ◷

• expires on May 10, 2026, 12:46 PM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

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

A newer discussion is available at Discussion #31340.