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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code as my primary AI tool and has no access to GitHub Copilot, I reviewed the gh-aw documentation to assess whether I could successfully understand and adopt this tool. The documentation has improved substantially and is now broadly accessible — I can get started with Claude as my engine with no blockers. That said, 3 persistent issues remain unfixed across 5–6 consecutive review cycles, and a new dangling reference in the auth docs was identified this run.

Key Finding: Claude Code users can successfully adopt gh-aw. The Quick Start wizard (add-wizard) handles engine selection interactively, and the auth/engines docs cover Claude well. The main friction points are cosmetic and editorial, not functional.

---

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. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) is genuinely engine-neutral. The Prerequisites section explicitly lists "GitHub Copilot, Anthropic Claude or OpenAI Codex" as options. The add-wizard command is interactive and walks users through engine selection and secret setup for all supported engines. A first-time Claude Code user following the Quick Start would not be blocked.

Specific Issues Found:

• creating-workflows.mdx line 21 — 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." No alternative path is offered for Claude or Codex users. A non-Copilot user reading this is left wondering if the web interface is entirely unavailable to them.
• creating-workflows.mdx lines 107–128 — The gh aw init section describes initializing for "the authoring experience in the GitHub code agent" and says it "registers the agentic-workflows custom agent in GitHub Copilot." The Claude Code workflow (using /agent agentic-workflows in Copilot Chat) is entirely Copilot-only. This is fine, but the section doesn't clearly mark itself as Copilot-specific, leaving Claude Code users confused about whether gh aw init provides them any value (it does — the .gitattributes and VS Code settings still apply).

Recommended Fixes:

• In creating-workflows.mdx Web Interface section, add a note: "If you are not using Copilot, you can create workflows using your Claude Code or Codex CLI agent (see next section)."
• In the gh aw init section, clarify which benefits apply to all users (.gitattributes, VS Code settings) vs. which are Copilot-specific (the /agent agentic-workflows chat command).

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot (clearly documented):

• engine: copilot — requires COPILOT_GITHUB_TOKEN (a GitHub PAT with Copilot Requests permission)
• engine.agent custom agent file (engine.agent: my-agent) — Copilot-only per the feature comparison table
• max-continuations autopilot mode — Copilot-only per feature comparison table
• GitHub Web Interface workflow authoring via /agent agentic-workflows — Copilot Chat only
• Safe output: assign-to-copilot — Copilot-only by definition

Features That Work Without Copilot (well documented):

• All core workflow triggers, permissions, tools, safe-outputs
• engine: claude with ANTHROPIC_API_KEY
• max-turns is Claude-only but documented
• web-fetch, bash, edit, playwright, cache-memory, repo-memory tools
• Custom MCP servers, MCP scripts
• All safe-output types (create-issue, add-comment, create-pull-request, etc.)
• gh aw compile, gh aw run, gh aw logs, gh aw audit

Missing Documentation:

• auth.mdx line 111 contains: "See also AI Engines for additional configuration needed when using Claude with GitHub MCP." — The linked anchor (#available-coding-agents) leads to the engine/secret table, but there is no visible "additional configuration for Claude with GitHub MCP" content there. This reference either points to content that was removed, or it was written when some extra step was required and is now stale. It creates unnecessary concern for Claude users.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• docs/src/content/docs/introduction/architecture.mdx — AWF network diagram (lines ~181, ~252) labels the agent process as "Copilot CLI" and the agent container as "Copilot CLI + MCP client". For a security architecture document describing an engine-agnostic system, this is misleading.
• docs/src/content/docs/introduction/how-they-work.mdx line 26 — "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." — Omits Gemini, which is fully supported and documented in engines.md.
• docs/src/content/docs/reference/auth.mdx — The CLI secrets example (gh aw secrets set COPILOT_GITHUB_TOKEN ...) is the first and only engine-specific example shown in the "Adding secrets using the CLI" section.

Missing Alternative Instructions:

• No equivalent for the GitHub.com web authoring experience for Claude/Codex users (acknowledged as Copilot-only but no workaround suggested)

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

None found. Claude Code users can complete the full Quick Start workflow without any blockers.

⚠️ Major Obstacles (Score: 3 obstacles)

Obstacle 1: GitHub Web Interface creation section is Copilot-gated with no alternative path shown

Impact: Claude/Codex users reading creating-workflows.mdx hit a "Copilot only" wall with no guidance on what they can do instead.

Current State: Line 21: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." — nothing follows for non-Copilot users.

Why It's Problematic: A developer without Copilot reads this as "this entire section is unavailable to me" and may not realize the very next section (CLI/coding agent approach) is perfectly valid for Claude Code.

Suggested Fix: Add a brief paragraph or callout: "If you are not using Copilot, use your CLI coding agent (Claude Code, Codex CLI) — see the next section."

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

Obstacle 2: gh aw init Copilot-specific value not clearly scoped

Impact: Claude Code users running gh aw init don't know which parts benefit them and which are Copilot-exclusive.

Current State: The section says gh aw init is "required" to enable "authoring experience in the GitHub code agent," then describes creating a Copilot dispatcher agent for /agent agentic-workflows in Copilot Chat. The benefits that apply to all users (.gitattributes, VS Code config) are buried in the same bullet list.

Why It's Problematic: A Claude Code user might skip gh aw init (thinking it's Copilot-only) and miss the useful VS Code and gitattributes setup. Or they might run it and wonder why the /agent agentic-workflows command does nothing for them.

Suggested Fix: Mark the Copilot Chat authoring feature clearly as [Copilot only] and separate out the universal benefits.

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

Obstacle 3: Dangling auth reference for Claude + GitHub MCP

Impact: Creates confusion and doubt for Claude users about whether extra configuration is needed.

Current State: auth.mdx line ~111: "See also AI Engines for additional configuration needed when using Claude with GitHub MCP." The linked anchor shows only the engines table — no "additional configuration" is present.

Why It's Problematic: A Claude user working on GitHub MCP integration will follow this link expecting to find required configuration steps and find nothing relevant. They'll be left wondering if they missed something or if the docs are broken.

Suggested Fix: Either remove the sentence if no extra configuration is currently required, or add the relevant content to engines.md under the #available-coding-agents section.

Affected File: docs/src/content/docs/reference/auth.mdx

💡 Minor Confusion Points (Score: 4 issues)

• Issue 1 (6th run unresolved): architecture.mdx AWF diagram labels the agent container as "Copilot CLI" and "Copilot CLI + MCP client" — should be "AI Engine" or engine-agnostic label. First flagged 2026-03-06.
• Issue 2 (5th run unresolved): how-they-work.mdx line 26 omits Gemini from the engine list despite full Gemini support existing in engines.md. First flagged in prior cycles.
• Issue 3 (6th run unresolved): auth.mdx ANTHROPIC_API_KEY setup says "Create an API key at (platform.claude.com/redacted) — this is a docs page, not the API key creation console. The Copilot setup has a direct pre-filled token creation link. Claude's setup should link directly to the Anthropic console. First flagged 2026-03-06.
• Issue 4: cli.md — gh aw secrets bootstrap --engine flag documentation lists copilot, claude, codex as valid options but omits gemini, which is now a supported engine.

---

Engine Comparison Analysis

Available Engines

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Gemini	⭐⭐⭐⭐	⭐ (0 example workflows)	⭐⭐⭐⭐	⭐⭐⭐

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

---

Tool Availability Analysis

Engine-Agnostic Tools (work with all engines):

• edit, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows
• Custom MCP servers (mcp-servers:)
• All safe-outputs types
• All GitHub toolsets

Engine-Specific Tools:

• engine.agent custom agent file — Copilot only
• max-continuations — Copilot only
• max-turns — Claude only
• tools.web-search — native on Codex; via MCP for others

Unclear/Undocumented:

• The "additional configuration for Claude with GitHub MCP" referenced in auth.mdx — cannot determine what this refers to

---

Authentication Requirements

Current Documentation

Engine	Secret	Setup Quality
Copilot	COPILOT_GITHUB_TOKEN	✅ Direct link to PAT creation
Claude	ANTHROPIC_API_KEY	⚠️ Links to docs page, not API console
Codex	OPENAI_API_KEY	✅ Direct link to OpenAI API keys
Gemini	GEMINI_API_KEY	✅ Direct link to AI Studio

Missing for Claude Users

The only gap: ANTHROPIC_API_KEY setup links to `(platform.claude.com/redacted) (a documentation page) rather than directly to the API key creation interface (e.g., the Anthropic Console). Every other engine links directly to the key/token creation page.

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot - 85 workflows
Engine: claude  - 34 workflows
Engine: codex   - 18 workflows
Engine: gemini  -  0 workflows
Total .md files - 178

Quality of Examples

Claude Examples (34 workflows): Good quantity. Includes a variety of use cases (audit, doc-healing, CI checks, daily reports). The fact that this very workflow runs on engine: claude is a strong positive signal.

Copilot Examples (85 workflows): Dominant. Most example configuration snippets in the reference docs (architecture, network, threat-detection) default to engine: copilot.

Codex Examples (18 workflows): Adequate for the engine's feature set.

Gemini Examples (0 workflows): No example workflows exist despite Gemini being a documented, supported engine with its own GEMINI_API_KEY auth documentation.

---

Recommended Actions

Priority 1: Fix Broken Reference (Quick Win)

1. Fix dangling Claude + GitHub MCP reference — auth.mdx: Remove or complete the sentence "See also AI Engines for additional configuration needed when using Claude with GitHub MCP." This sentence has been flagged across multiple runs and creates user doubt. File: docs/src/content/docs/reference/auth.mdx

Priority 2: Persistent Issues (6th Run)

2. Fix AWF architecture diagram engine label — architecture.mdx: Change "Copilot CLI" and "Copilot CLI + MCP client" labels in the AWF network diagram to engine-agnostic labels ("AI Engine" / "AI Agent + MCP client"). This has been flagged since 2026-03-06 with no resolution. File: docs/src/content/docs/introduction/architecture.mdx

3. Fix ANTHROPIC_API_KEY setup link — auth.mdx: Update the link from (platform.claude.com/redacted) to the direct API key creation page in the Anthropic Console, matching the pattern used for all other engines. File: docs/src/content/docs/reference/auth.mdx`

4. Add Gemini to How They Work — how-they-work.mdx: Update the engine list from "GitHub Copilot (default), Claude by Anthropic, and Codex" to include Gemini. File: docs/src/content/docs/introduction/how-they-work.mdx

Priority 3: Nice-to-Have Enhancements

5. Scope Copilot-only features in creating-workflows — Add a non-Copilot alternative note in the Web Interface section and clarify which gh aw init benefits apply to all users.

6. Add Gemini to secrets bootstrap --engine docs — cli.md: The --engine flag for secrets bootstrap currently lists copilot, claude, codex but omits gemini.

7. Add at least one example Gemini workflow — Currently 0 Gemini workflow examples exist in .github/workflows/, making it hard for Gemini users to see real patterns.

---

Positive Findings

What Works Well

• ✅ Quick Start is genuinely multi-engine — Prerequisites list all AI providers; add-wizard handles interactive engine selection and secret setup for all engines
• ✅ Engines documentation is comprehensive — Feature comparison table, per-engine auth, version pinning, custom endpoints all covered
• ✅ 34 Claude workflow examples exist — Strong real-world signal that Claude is well-supported
• ✅ Auth docs cover all engines — Each engine has its own auth section with setup steps
• ✅ gh aw new --engine claude — Creates correct frontmatter template for Claude users
• ✅ gh aw secrets bootstrap — Handles all engine secrets interactively
• ✅ Feature comparison table in engines.md — Clearly shows per-engine capability differences
• ✅ This very workflow runs on engine: claude — Dogfooding demonstrates Claude parity

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes

The documentation is broadly accessible to Claude Code users. The Quick Start wizard is the best onboarding path and handles engine selection gracefully. The engines and auth reference pages are thorough. With 34 Claude workflow examples, there's ample precedent for real-world usage.

The remaining friction is editorial: three diagram/text issues that have persisted across 6 consecutive daily runs without resolution, one dangling broken reference, and one missing engine in a list. None of these prevent adoption — they create momentary confusion or minor trust erosion.

Overall Assessment Score: 8/10

Breakdown:

• Clarity for non-Copilot users: 8/10
• Claude engine documentation: 8/10
• Alternative approaches provided: 8/10
• Engine parity (documentation quality): 7/10

Next Steps

The 6-run persistent issues (AWF diagram Copilot label, Gemini omission from how-they-work, broken ANTHROPIC_API_KEY link) should be the highest priority — they are small editorial changes that have been flagged repeatedly with no resolution. Addressing these three items would likely bring the score to 9/10.

---

Appendix: Files Reviewed

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
• docs/src/content/docs/reference/github-tools.md (partial)
• .github/workflows/*.md — engine distribution analysis (178 total files)

---

References: §23685950282

AI generated by Claude Code User Documentation Review · history

• expires on Mar 29, 2026, 1:18 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 #23458.