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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and has no GitHub Copilot subscription, gh-aw is viable to adopt — the core documentation covers Claude engine setup adequately, and 36 of 177 workflows in this repository use Claude. However, 7 persistent documentation issues remain unresolved for 5+ consecutive runs (score unchanged at 7.5/10 for 22 days). The primary friction points are Copilot-first framing in the workflow creation guide, Copilot-branded diagrams in the architecture docs, and Gemini's consistent omission from various places despite being a documented engine.

Key Finding: Claude Code users can successfully use gh-aw, but will encounter repeated Copilot-centric language that requires mental substitution — particularly when creating new workflows and reading architecture diagrams.

---

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 modest friction. The Quick Start prerequisites (quick-start.mdx) correctly lists all three major engines: "AI Account - GitHub Copilot, Anthropic Claude, or OpenAI Codex". The gh aw add-wizard command's interactive flow handles engine selection and secret configuration for Claude transparently.

The engines.md reference page is well-structured, listing all four engines (including Gemini) with their required secrets in a clear table. The auth.mdx page dedicates equal documentation space to each engine.

Specific Issues Found:

• creating-workflows.mdx line 21 — The "GitHub Web Interface" workflow creation method is exclusively gated behind Copilot access: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." No alternative web-based creation path is offered for Claude users.
• creating-workflows.mdx line 96 — Step 3 of the coding agent path reads: "If not using Copilot, also adjust the engine: field in your workflow's frontmatter." This implies Copilot is the baseline and Claude is a deviation, rather than treating engines as equal alternatives.
• how-they-work.mdx line 26 — States: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." Gemini is absent despite being fully documented in engines.md.

Recommended Fixes:

• In creating-workflows.mdx, reframe the web interface section as "Copilot-only feature" with a callout box, and add a note pointing Claude/Codex/Gemini users directly to the "VSCode/Claude/Codex/Copilot" section below
• Change the step 3 framing from "if not using Copilot, adjust engine:" to "Set the engine: field to your chosen engine (copilot, claude, codex, or gemini)"
• Add Gemini to the how-they-work.mdx supported engines sentence

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• assign-to-copilot safe output — assigns issues/PRs to the Copilot coding agent; intentionally Copilot-specific, but the standalone doc page (assign-to-copilot.mdx) doesn't mention this limitation upfront
• copilot-custom-agents — the .github/agents/*.agent.md system is Copilot-specific; no equivalent for Claude (though Claude Code users familiar with CLAUDE.md could approximate this)
• GitHub Web Interface workflow creation (creating-workflows.mdx) — requires Copilot subscription

Features That Work Without Copilot (Engine-Agnostic):

• All core tools: edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, 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 add-wizard, gh aw init, gh aw status, etc.
• MCP servers, MCP scripts, threat detection, network firewall
• gh aw new --engine claude correctly generates a Claude-configured template

Missing Documentation:

• No dedicated "Using Claude Code with gh-aw" guide (though engines.md + auth.mdx cover the essentials)
• No explanation of what Claude-equivalent exists for Copilot's agent: custom agent field (e.g., using steps: to inject a system prompt file)

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

File	Issue
architecture.mdx line 177	Mermaid diagram labels agent process node "Copilot CLI" instead of "AI Agent CLI"
architecture.mdx line 248	AWF network diagram shows "Agent container\nCopilot CLI + MCP client" hardcoded
creating-workflows.mdx line 21	Web interface creation requires Copilot; no alternative shown
creating-workflows.mdx line 96	"If not using Copilot, also adjust the engine: field" — Copilot-first framing
how-they-work.mdx line 26	Gemini absent from supported engines list
auth.mdx line 104	ANTHROPIC_API_KEY setup links to platform.claude.com/docs/en/get-started — a docs page, not the actual API key creation page at console.anthropic.com/settings/keys

Missing Alternative Instructions:

• No guidance on how to replicate Copilot's agent: custom agent system with Claude or other engines

---

Severity-Categorized Findings

🚫 Critical Blockers — Score: 0

No critical blockers found. Claude Code users can complete the full setup and run workflows without Copilot.

⚠️ Major Obstacles — Score: 3

Obstacle 1: Copilot-Only Web Interface Creation Path

Impact: Claude users who prefer a web-based creation flow have no documented alternative

Current State: creating-workflows.mdx line 21 explicitly states "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." The feature is then explained in full detail, with no note that Claude users should skip this section.

Why It's Problematic: A user skimming the page may assume this approach works for all engines, attempt it with Claude, and fail. Or they may incorrectly conclude gh-aw requires Copilot for initial setup.

Suggested Fix: Add a > [!NOTE] This feature requires GitHub Copilot. Claude, Codex, and Gemini users should skip to the next section. callout at the top of the Web Interface section.

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

Obstacle 2: Architecture Diagrams Brand Copilot Into Core Infrastructure

Impact: Cognitive dissonance for Claude users reading security architecture docs

Current State: The AWF firewall diagram in architecture.mdx (line 177, 248) hardcodes "Copilot CLI" as the agent label, making it appear that the security architecture is Copilot-specific. The firewall works with all engines.

Why It's Problematic: A Claude user reading the security docs will see their chosen engine is absent from the central architecture diagram, undermining confidence that Claude is a first-class citizen.

Suggested Fix: Replace "Copilot CLI" with "AI Agent CLI\n(Copilot/Claude/Codex)" or just "AI Agent" in the mermaid diagrams.

Affected Files: docs/src/content/docs/introduction/architecture.mdx lines 177, 248

Obstacle 3: Anthropic API Key Setup Links to Wrong Page

Impact: Claude users following the authentication setup hit a documentation page instead of the key creation page

Current State: auth.mdx line 104 says: *"Create an API key at (platform.claude.com/redacted) — this is an Anthropic documentation overview page, not the actual API key creation interface.

Why It's Problematic: The correct URL for creating an Anthropic API key is https://console.anthropic.com/settings/keys. A new Claude user following the quickstart will land on a documentation page and need to navigate further to find key creation.

Suggested Fix: Update the link to https://console.anthropic.com/settings/keys

Affected Files: docs/src/content/docs/reference/auth.mdx line 104

💡 Minor Confusion Points — Score: 4

• Gemini missing from how-they-work.mdx line 26 — "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex" — Gemini documented in engines.md but absent here. File: docs/src/content/docs/introduction/how-they-work.mdx
• cli.md line 220: secrets bootstrap --engine omits Gemini — Documents options as (copilot, claude, codex) but Gemini is a documented engine. File: docs/src/content/docs/setup/cli.md
• creating-workflows.mdx Copilot-first step framing — "If not using Copilot, also adjust the engine: field" treats Copilot as default without clear explanation that engine: is always required for non-Copilot engines. File: docs/src/content/docs/setup/creating-workflows.mdx line 96
• No "Claude vs Copilot for gh-aw" comparison — Users choosing an engine have no guidance on tradeoffs (cost, capability, features) between engines for gh-aw use cases

---

Engine Comparison Analysis

Available Engines

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

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

Notes:

• Gemini has 0 example workflows in .github/workflows/ despite being a documented engine
• Claude auth docs get ⭐⭐⭐ due to the incorrect API key link (see Obstacle 3)
• Copilot auth gets ⭐⭐⭐⭐ (not 5) because COPILOT_GITHUB_TOKEN setup requires navigating external GitHub token creation pages

---

Tool Availability Analysis

Engine-Agnostic Tools (work with any engine):

• edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, agentic-workflows, custom MCP servers

Engine-Specific Tools:

• web-search — behavior varies; the docs note "Some engines require third-party MCP servers" for web search; Codex disables it by default unless explicitly declared

Engine-Specific Safe Outputs:

• assign-to-copilot — Copilot-only (intentional product feature)

Unclear/Undocumented:

• Equivalency for Copilot's agent: custom agent file for Claude/Codex/Gemini engines

---

Authentication Requirements

Engine	Secret	Documentation	Key Creation Link
Copilot	COPILOT_GITHUB_TOKEN	✅ Detailed	Links to GitHub PAT page
Claude	ANTHROPIC_API_KEY	⚠️ Partial	Links to docs page, not key creation
Codex	OPENAI_API_KEY	✅ Good	Links directly to api-keys page
Gemini	GEMINI_API_KEY	✅ Good	Links to aistudio.google.com

---

Example Workflow Analysis

Workflow Count by Engine (.github/workflows/)

engine: copilot (explicit)  — 87 workflows
engine: claude              — 36 workflows  (+2 vs yesterday)
engine: codex               — 17 workflows  (+2 vs yesterday)
engine: gemini              —  0 workflows
(no engine / default)       — remaining ~37 workflows (default to Copilot)
Total .md files             — 177

Claude Examples: 36 workflows is solid representation (~20% of the collection). Claude workflows cover a wide range of use cases including analysis, reporting, and triage. Good examples exist for Claude users to reference.

Copilot Examples: Dominant at ~50%+ of explicit engine declarations. Copilot examples are used in most of the documentation inline code samples as well.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix ANTHROPIC_API_KEY link — Change platform.claude.com/docs/en/get-started to console.anthropic.com/settings/keys — File: auth.mdx line 104
2. Update AWF architecture diagrams — Replace hardcoded "Copilot CLI" labels with engine-agnostic "AI Agent CLI" — File: architecture.mdx lines 177, 248
3. Add Gemini to how-they-work.mdx engines list — Sentence at line 26 should include Gemini — File: how-they-work.mdx

Priority 2: Major Improvements

1. Add Copilot-only callout to Web Interface section — creating-workflows.mdx line 21 needs a > [!NOTE] that this is Copilot-only with a redirect to the next section
2. Reframe Copilot-first step language — Change "If not using Copilot, also adjust the engine: field" to positive framing that treats all engines equally — creating-workflows.mdx line 96
3. Add Gemini to secrets bootstrap --engine docs — cli.md line 220 documents (copilot, claude, codex) but should include gemini

Priority 3: Nice-to-Have Enhancements

1. Add engine comparison guide — A "Choosing an Engine" guide explaining tradeoffs between Copilot/Claude/Codex/Gemini for gh-aw use cases
2. Document Claude equivalent of Copilot agent files — Explain how Claude Code users can achieve equivalent customization to Copilot's .github/agents/*.agent.md system
3. Add Gemini example workflows — Currently 0 Gemini workflow examples despite being a documented engine

---

Positive Findings

• ✅ Quick Start prerequisites explicitly list Claude and Codex as Copilot alternatives
• ✅ gh aw add-wizard interactively handles Claude engine selection and secret setup
• ✅ engines.md is comprehensive, covering all 4 engines equally in a clear table
• ✅ auth.mdx dedicates equal space to all 4 engine secrets with setup steps
• ✅ gh aw new --engine claude generates Claude-configured workflow templates
• ✅ gh aw secrets bootstrap --engine claude supports Claude-specific secret validation
• ✅ 36 Claude example workflows in this repository provide strong real-world references
• ✅ engines.md documents Claude custom API endpoints (ANTHROPIC_BASE_URL) for enterprise users
• ✅ gh aw init interactive mode supports engine selection for non-Copilot users
• ✅ All security features (safe outputs, threat detection, AWF, MCP sandboxing) are engine-agnostic

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate effort

Reasoning: The foundational documentation — engines.md, auth.mdx, Quick Start prerequisites — treats Claude as a first-class engine. The add-wizard command handles the full Claude setup flow. With 36 real Claude workflows to reference, users have ample examples. The friction comes from consistent Copilot-first framing in the workflow creation guide and Copilot-branded diagrams in the architecture docs, which require Claude users to mentally translate. None of these are blockers, but they add friction and reduce confidence in Claude's parity.

The same 7 issues have persisted for 5+ consecutive review runs without resolution, suggesting these are known gaps that haven't been prioritized. The overall score has been stable at 7.5/10 for 22 days.

Overall Assessment Score: 7.5/10

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

Next Steps

The 7 persistent issues are small, targeted fixes (mostly single-line text changes and diagram label updates). Resolving them would likely push the score to 9/10 and make gh-aw genuinely welcoming to non-Copilot users on first contact. Priority 1 fixes (incorrect API link, hardcoded diagram labels, missing Gemini) could be resolved in a single PR in under an hour.

---

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/faq.md (partial)
• .github/workflows/*.md (engine distribution analysis)

---

References:

• §23414065985

AI generated by Claude Code User Documentation Review · history

• expires on Mar 23, 2026, 10:36 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-23T22:36:39.877Z.

Closed by Workflow