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

[github-actions[bot]]

Executive Summary

I reviewed gh-aw's six core docs (README, quick-start.mdx, how-they-work.mdx, architecture.mdx, tools.md, cli.md) as a developer who uses Claude Code and does not have a GitHub Copilot subscription. The product is technically usable end-to-end with engine: claude, and the engine, tools, and feature pages cover Claude correctly when you go looking for them. But the on-ramp is still Copilot-shaped: 87% of literal engine: ... examples in docs/ are engine: copilot (77 of 88), gh aw init silently installs a file titled "Copilot Agent Files" with no warning, and the Claude API-key URL in auth.mdx still points at a docs landing page instead of the key console.

Key Finding: A Claude-only user can complete the Quick Start, but every meaningful decision point during onboarding has Copilot pre-selected as the default and Claude treated as the alternative. No documentation gap is itself disqualifying, but together they make adoption feel like swimming against the doc grain.

---

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?

Yes — barely, and only because add-wizard is interactive. quick-start.mdx:29 lists all four engines as acceptable prerequisites, add-wizard step 2 explicitly says "Choose between Copilot, Claude, Codex, or Gemini" (quick-start.mdx:70), and step 3 lists ANTHROPIC_API_KEY setup with the correct console URL (quick-start.mdx:84). A Claude user who reads carefully can complete the flow.

What still trips them up:

• The two NOTE boxes after the wizard only cover Copilot and Claude (quick-start.mdx:75-90). Codex and Gemini users get no parallel setup guidance — a minor parity issue for those engines, but it signals that the doc was written Copilot-first and Claude was bolted on.
• how-they-work.mdx:26 literally says "Workflows support GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini by Google." The "(default)" annotation appears beside Copilot — fine — but no equivalent sentence says what changes if you switch the default.
• The dispatcher agent created by gh aw init (cli.md:134) is documented as a neutral setup step, but the actual file's documentation page is titled "Copilot Agent Files support for Agentic Workflows" (custom-agent-for-aw.mdx:1) and line 10 of that page reads "Custom Agents are added prompts that can be used with Copilot, Copilot CLI and VSCode Agent Mode." A Claude user who runs gh aw init ends up with a Copilot-only artifact in their repo with no documented signal.

Specific Issues:

• cli.md:134 — gh aw init description omits that the dispatcher agent file is Copilot-only.
• quick-start.mdx:75-90 — NOTE boxes biased toward Copilot/Claude only.
• how-they-work.mdx:26 — "(default)" annotation on Copilot, no equivalent guidance for switching.

Recommended Fixes:

• Add one sentence to cli.md:134: "The dispatcher agent file is consumed by Copilot Chat/CLI; if you use a different engine, you can ignore or delete it."
• Add NOTE boxes for Codex and Gemini in quick-start.mdx to match Copilot/Claude parity.
• Add a "Choosing a default engine" paragraph in how-they-work.mdx linking to engines.md.

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

The core surface is engine-agnostic. Per engines.md:30-46 and tools.md, every tool — edit, bash, github, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers — works with all four primary engines. A Claude user is not blocked from any core capability.

Copilot-only features (with documented restrictions):

• engine.agent — custom agent files in .github/agents/ (engines.md:41)
• engine.harness — custom harness wrapper script (engines.md:44, 293-306)
• max-continuations — autopilot run budget (engines.md:38)
• BYOK via COPILOT_PROVIDER_* envs (engines.md:201-268)

Claude-only features:

• max-turns — Claude iteration budget (engines.md:37, 405-416)

Codex-only feature:

• Native opt-in web search (tools.md:67); other engines must use a third-party MCP.

The asymmetry that matters: Copilot gets two extension points (engine.agent, engine.harness) for authoring custom behavior; Claude gets one knob (max-turns). The product is broader for Copilot users in ways the docs do not flag up-front.

Genuine Quick-Start friction:

• gh aw init creates .github/agents/agentic-workflows.agent.md, which creating-workflows.mdx:118 correctly identifies as registering a Copilot Chat command. A Claude-only user gets this file with no documented opt-out — the closest is --no-mcp, which doesn't skip the agent file.

Missing documentation:

• No "Claude-only quickstart" anywhere that walks through repo setup → engine selection → secret → first workflow without Copilot-specific artifacts.
• engine.agent and engine.harness lack Claude-equivalent extension points or a sentence explaining why those features are Copilot-only.

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Volume tells the story. Across docs/:

• engine: copilot literal examples: 77 (in 34 distinct files)
• engine: claude literal examples: 8 (in 6 files)
• engine: codex: 1 (1 file)
• engine: gemini: 2 (2 files)
• engine: custom: 0 (despite "custom" being listed as a supported engine per the original review prompt — it has zero working examples in the entire repo)

Brand mentions in docs/: Copilot 520 (in 153 files) vs. Claude 111 (in 41 files). The Copilot share has grown larger since yesterday's audit, not smaller.

Specific Copilot-centric assumptions:

• engines.md:24 — "Copilot CLI is the default — engine: can be omitted when using Copilot." Hardcoded default, no override guidance.
• architecture.mdx:228 — example workflow opens with engine: copilot for no architectural reason; could be engine-agnostic.
• auth.mdx:109 — Claude API key URL is wrong: (platform.claude.com/redacted) is a docs landing page, not the key console. quick-start.mdx:84uses the correcthttps://console.anthropic.com/settings/keys`. This inconsistency has been present in three consecutive daily audits.
• auth.mdx:17-23 — "Which secret do I need?" table only lists Copilot/Claude/Codex/Gemini. Crush, OpenCode, and Pi are in engines.md:20-22 but absent here.
• custom-agent-for-aw.mdx:1 — title "Copilot Agent Files support for Agentic Workflows," and line 10 explicitly says Copilot/Copilot CLI/VSCode Agent Mode. This is fine for that page, but cli.md:134 should warn that gh aw init creates a file documented here.

Missing alternative instructions:

• No "Setting up a repo without Copilot" walkthrough.
• No statement that the dispatcher agent file is optional for non-Copilot engines.
• No comparison table answering "Why would I use Claude instead of Copilot?" — the closest is engines.md:26-28, which is one sentence and somewhat hedged.

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

No critical blockers. The product genuinely works with engine: claude and the docs do cover Claude in the right places.

⚠️ Major Obstacles (Score: 4/10)

Obstacle 1: Wrong Claude API key URL in auth.mdx:109

Impact: Users following auth.mdx get sent to a docs page, not a key console — adds confusion at exactly the moment they need a key.

Current State: auth.mdx:109 reads "Create an API key at (platform.claude.com/redacted) — landing page, not key console.

Why It's Problematic: quick-start.mdx:84 already uses the correct URL. The same product has two different "create your API key" links in two different docs, and the wrong one is in the authoritative reference page.

Suggested Fix: Replace with https://console.anthropic.com/settings/keys to match quick-start.mdx:84.

Affected Files: docs/src/content/docs/reference/auth.mdx:109

Obstacle 2: gh aw init silently installs a Copilot-only agent file

Impact: Claude-only users get a .github/agents/agentic-workflows.agent.md file with no indication that it's Copilot-specific.

Current State: cli.md:134 describes the file neutrally. custom-agent-for-aw.mdx:1 is titled "Copilot Agent Files support..." and line 10 names Copilot/Copilot CLI/VSCode Agent Mode.

Why It's Problematic: No warning, no skip flag for non-Copilot users (--no-mcp doesn't cover it). Creates dead file in the repo for Claude/Codex/Gemini users.

Suggested Fix: Add one line to cli.md:134: "The dispatcher agent file is used by Copilot Chat/Copilot CLI; it has no effect on Claude/Codex/Gemini workflows and may be removed." Optionally add --no-dispatcher flag.

Affected Files: docs/src/content/docs/setup/cli.md:134, docs/src/content/docs/reference/custom-agent-for-aw.mdx

Obstacle 3: Heavy Copilot bias in worked examples (77 vs. 8)

Impact: Even when a feature is engine-agnostic, the example uses engine: copilot. This signals "Copilot is what you should use; everything else is the exception."

Current State: 77 engine: copilot examples vs. 8 engine: claude across docs/. architecture.mdx:228 is one such case where the example is illustrating the firewall config, not Copilot itself.

Why It's Problematic: The bias has grown across three daily audits (62 → 76 → 77 in the docs Copilot share). New writers default to Copilot examples.

Suggested Fix: Rotate engines in feature documentation (e.g., 50% Copilot, 25% Claude, 25% Codex/Gemini) so engine-agnostic features don't read as Copilot-only.

Affected Files: repository-wide; concrete targets include architecture.mdx:228, cli.md:316, examples under docs/src/content/docs/examples/.

Obstacle 4: No cohesive "Claude-only adoption path"

Impact: A Claude user has to assemble the right path from three pages (quick-start, engines, auth) and infer what to skip. There is no single place that says "if you're a Claude user, here's the minimal path."

Current State: Each step is documented, but the Claude-specific path is not assembled anywhere.

Suggested Fix: Add a short "Using Claude as your engine" sub-section to quick-start.mdx (10–15 lines) that links the three pieces and explicitly says what to skip vs. Copilot defaults.

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

💡 Minor Confusion Points (Score: 6/10)

• Issue 1: auth.mdx:17-23 "Which secret do I need?" table omits Crush, OpenCode, Pi — engines.md:20-22
• Issue 2: engines.md:24 says Copilot is the hardcoded default with no inline mention of how to change it
• Issue 3: quick-start.mdx:75-90 NOTE boxes only cover Copilot and Claude; Codex/Gemini get listed in prerequisites but no setup tip box
• Issue 4: how-they-work.mdx:26 "(default)" annotation but no link to a "choosing your engine" page
• Issue 5: tools.md:155 lists default tool timeouts only for Claude (60 s) and Codex (120 s); Copilot/Gemini timeouts are missing from the inline note (table at engines.md:381-387 has them, but tools.md doesn't cross-reference)
• Issue 6: engine: custom is referenced in the original review prompt as a supported engine but has zero working examples in the entire repo — likely a phantom option

---

Engine Comparison Analysis

Available Engines

Engine	engine: value	Setup Docs	Auth Docs	Example Count (docs)	Overall
Copilot	copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	77	⭐⭐⭐⭐⭐
Claude	claude	⭐⭐⭐⭐	⭐⭐⭐ (wrong URL)	8	⭐⭐⭐
Codex	codex	⭐⭐⭐	⭐⭐⭐⭐	1	⭐⭐⭐
Gemini	gemini	⭐⭐⭐	⭐⭐⭐	2	⭐⭐
Crush (exp.)	crush	⭐⭐	⭐ (missing from auth table)	0	⭐⭐
OpenCode (exp.)	opencode	⭐⭐	⭐ (missing from auth table)	0	⭐⭐
Pi (exp.)	pi	⭐⭐	⭐ (missing from auth table)	0	⭐⭐
"custom"	—	⭐	⭐	0	not a real engine

---

Tool Availability Analysis

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

Engine-Specific Tools / Features:

• Copilot only: engine.agent, engine.harness, max-continuations, COPILOT_PROVIDER_* BYOK
• Claude only: max-turns
• Codex only: native web-search (opt-in)
• All others must reach web-search through a third-party MCP (tools.md:65-67, engines.md:40)

Unclear/Undocumented:

• Whether engine.bare: true behaves identically across engines (table at engines.md:329-335 says no — each engine has a different underlying flag).
• Whether agentic-workflows MCP introspection works identically when running under Claude vs. Copilot (not explicitly tested in docs).

---

Authentication Requirements

Current Documentation State

• ✅ Copilot — detailed setup instructions (auth.mdx:76-99), wizard nudge, troubleshooting section
• ⚠️ Claude — instructions present (auth.mdx:103-126), but key acquisition URL is wrong (line 109)
• ✅ Codex — instructions present including CODEX_API_KEY alternative (auth.mdx:129-167)
• ✅ Gemini — instructions present (auth.mdx:171-185)
• ❌ Crush/OpenCode/Pi — listed in engines.md but absent from auth.mdx "Which secret do I need?" table

Missing for Claude Users

• The wrong URL at auth.mdx:109 is the most actionable single fix in this entire report.
• No documented note that CLAUDE_CODE_OAUTH_TOKEN (used by some Claude tooling) is not supported — actually this IS documented at auth.mdx:121-123, so credit where due.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN
• Claude: ANTHROPIC_API_KEY (only supported method)
• Codex: OPENAI_API_KEY or CODEX_API_KEY
• Gemini: GEMINI_API_KEY
• Crush/OpenCode: COPILOT_GITHUB_TOKEN (per engines.md:20-21, not documented in auth.mdx)
• Pi: COPILOT_GITHUB_TOKEN or provider-specific

---

Example Workflow Analysis

Workflow Count by Engine (docs/ literal engine: X examples)

engine: copilot - 77 examples (87.5%)
engine: claude  -  8 examples ( 9.1%)
engine: codex   -  1 example  ( 1.1%)
engine: gemini  -  2 examples ( 2.3%)
engine: custom  -  0 examples
engine: crush   -  0 examples

Quality of Examples

• Copilot examples are exhaustive: every feature ships with at least one Copilot-flavored snippet.
• Claude examples exist but cluster in 6 files (faq, network, frontmatter-hash, research-plan-assign-ops, cli, quick-start). Most feature-reference pages don't include a Claude variant.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix the Claude API key URL — auth.mdx:109 → change (platform.claude.com/redacted) to https://console.anthropic.com/settings/keys`. This is a one-line PR and has been pending in three consecutive audits.
2. Warn about the dispatcher agent file — cli.md:134 → add one sentence stating the file is for Copilot Chat/CLI and can be ignored by non-Copilot users.
3. Add Crush/OpenCode/Pi rows to the auth table — auth.mdx:17-23 → keep the table aligned with engines.md:14-22.

Priority 2: Major Improvements

1. Add a Claude-only walkthrough to quick-start.mdx (10–15 lines after Step 4) showing the minimal Claude path end-to-end.
2. Add Codex/Gemini NOTE boxes in quick-start.mdx:75-90 to match Copilot/Claude parity.
3. Rotate engines in feature examples so engine-agnostic features stop reading as Copilot features.

Priority 3: Nice-to-Have Enhancements

1. Remove or document engine: custom — zero working examples after three audits.
2. Cross-reference the engine-feature-comparison table from tools.md so readers don't have to bounce between pages.
3. Provide a "What changes if I switch engines?" decision matrix beyond the one-sentence comparison at engines.md:26-28.

---

Positive Findings

What Works Well

• ✅ quick-start.mdx:29 correctly lists all four primary engines as acceptable prerequisites
• ✅ add-wizard step 2 (quick-start.mdx:70) explicitly offers the engine choice interactively
• ✅ The engine-feature-comparison table (engines.md:34-46) is genuinely useful and engine-symmetric
• ✅ All core tools are engine-agnostic and that is consistently true across tools.md
• ✅ auth.mdx:121-123 correctly tells users that CLAUDE_CODE_OAUTH_TOKEN is unsupported — that's a thoughtful disambiguation
• ✅ engines.md:329-335 documents engine.bare flags per engine — exactly the kind of parallel-coverage table the rest of the docs could emulate
• ✅ The Claude permission-mode security model (engines.md:439-472) is documented carefully, including the bypassPermissions caveat — good security-focused writing

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with friction.

Reasoning: Every piece of information a Claude user needs exists somewhere in the docs, but it's scattered, the API-key URL is wrong, and onboarding artifacts (gh aw init dispatcher file) are silently Copilot-shaped. The interactive gh aw add-wizard flow papers over much of the friction by asking for the engine at runtime — a Claude user who runs the wizard probably reaches a working state. A Claude user who reads the docs first will perceive a Copilot-first product.

Overall Assessment Score: 6/10

Breakdown:

• Clarity for non-Copilot users: 6/10 (unchanged from prior run)
• Claude engine documentation: 7/10 (URL bug holds this back)
• Alternative approaches provided: 6/10
• Engine parity: 5/10 (Copilot share grew in last two audits)

Next Steps

1. Land the three Priority 1 fixes. They are small, mechanical, and have been on the punch list for three consecutive audits.
2. Track Copilot-vs-Claude example ratio over time. Today's snapshot is 77/8 in docs. If new feature docs default to Copilot examples, this ratio will keep drifting.
3. Consider whether engine: custom belongs in the supported-engine list at all. Zero examples in three audits.

---

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/custom-agent-for-aw.mdx
• docs/src/content/docs/setup/creating-workflows.mdx

References:

• §26361569918
• Prior audit: §26332951547 (2026-05-23)
• Prior audit: §26289895195 (2026-05-22)

Generated by 📝 Claude Code User Documentation Review · ● opu47 17.2M · ◷

• expires on May 25, 2026, 12:52 PM UTC

[github-actions[bot]]

💥 WHOOSH! 🦸♂️

⚡ ZAP! POW! BAM! 💥 The Smoke Test Agent was here! 🚀

Just swooped in on a Claude-powered streak, kicked the tires on every MCP server in town, and — KABLAM! — gave this discussion a friendly hello! 🔥💨

🦾 Mission status: Nominal!
🛡️ Engine: Claude
🎯 Run: §26361673675

Up, up, and away! ✨🌟

Warning

Firewall blocked 6 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• contentautofill.googleapis.com
• safebrowsingohttpgateway.googleapis.com
• www.google.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "contentautofill.googleapis.com"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

💥 [THE END] — Illustrated by Smoke Claude · ● opu47 8.5M · ◷

[github-actions[bot]]

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

A newer discussion is available at Discussion #34648.