🔍 Claude Code User Documentation Review - 2026-02-19

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code as their primary AI assistant and actively avoids GitHub Copilot, I reviewed the gh-aw documentation to assess whether it is accessible and actionable for non-Copilot users. The core answer is: Claude Code users CAN successfully adopt gh-aw, but they'll encounter friction from Copilot-first framing, a few documentation gaps, and one confusing model-default comment in the engines reference. No hard blockers prevent getting started.

Key Finding: Claude engine setup is adequately documented in the dedicated engines and auth references, and the Quick Start's add-wizard command explicitly supports engine selection. However, several peripheral areas default to Copilot-only examples without equivalent Claude alternatives.

---

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, mostly. The Quick Start guide's prerequisites clearly list all three engine options ("GitHub Copilot, Anthropic Claude, or OpenAI Codex") and the gh aw add-wizard command walks through engine selection interactively. The How It Works page is balanced and engine-agnostic in its framing.

Specific Issues Found:

• docs/src/content/docs/setup/cli.md line 120 — gh aw init is described as: "Configures .gitattributes, Copilot instructions, prompt files, and logs .gitignore." The phrase "Copilot instructions" is unexplained. A Claude user will wonder: does this create Copilot-specific config that conflicts with or is unnecessary for Claude? Is there a --no-copilot flag? Should they delete these files? No guidance is provided.

• docs/src/content/docs/setup/quick-start.mdx + docs/src/content/docs/setup/cli.md — The Quick Start uses gh aw add-wizard prominently (Step 2) but this command does not appear anywhere in the CLI reference. Users who want to understand flags, options, or what the command does before running it will find nothing. Only gh aw add is documented.

• docs/src/content/docs/setup/creating-workflows.mdx — 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." There is no equivalent alternative for Claude users who want to use the web interface. A Claude user reading this hits a dead end with no workaround offered.

Recommended Fixes:

• Rename or clarify "Copilot instructions" in gh aw init docs to explain what these files do and whether they apply to non-Copilot users (e.g., "Copilot agent prompt files — safe to commit even if using Claude").
• Add add-wizard as a documented command in docs/src/content/docs/setup/cli.md.
• Add an alternative web interface path for Claude users (e.g., manually editing workflow markdown files on GitHub.com).

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• engine: copilot workflows — require COPILOT_GITHUB_TOKEN PAT with copilot-requests scope
• Copilot custom agents (.github/agents/*.agent.md) — Copilot-specific feature; other engines inject the markdown body as a plain prompt instead (documented in copilot-custom-agents.md, though somewhat buried)
• assign-to-agent safe output — assigns GitHub Copilot coding agent to issues/PRs; this is a Copilot platform feature. In docs/src/content/docs/reference/auth.mdx, GH_AW_AGENT_TOKEN documentation discusses this but doesn't prominently label it as Copilot-only until the very end.
• GitHub web interface creation method in Creating Workflows guide

Features That Work Without Copilot:

• All core tools: edit, bash, web-fetch, web-search, github, playwright, cache-memory, repo-memory, agentic-workflows
• All safe outputs: create-issue, add-comment, create-pull-request, create-discussion, dispatch-workflow, etc.
• All CLI commands: compile, run, status, logs, audit, trial, health, etc.
• MCP server integration (engine-agnostic)
• Network firewall configuration
• Safe inputs
• All security features

Missing Documentation:

• No guide specifically for "Getting started without Copilot" or "Migrating from Copilot to Claude"
• No feature comparison table across engines (what each engine does/doesn't support)
• GH_AW_AGENT_TOKEN should be more clearly labeled as Copilot-only at the top of its section

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/setup/cli.md — gh aw init description mentions "Copilot instructions" without explanation for non-Copilot users
• File: docs/src/content/docs/introduction/architecture.mdx — The "Agent Workflow Firewall" mermaid diagram labels the agent process box as containing only "Copilot CLI", "WebFetch Tool", "Search Tool". Claude CLI and Codex are absent from this diagram.
• File: docs/src/content/docs/introduction/architecture.mdx line 224 — The network configuration example uses engine: copilot as the sole example, with no Claude alternative shown.
• File: docs/src/content/docs/reference/engines.md lines 87-88 — Extended configuration example shows model: gpt-5 # defaults to claude-sonnet-4 under id: copilot. This comment is confusing: does Copilot default to a Claude model? (Possibly means "default in general is claude-sonnet-4" but placed under a Copilot example, creating ambiguity.)
• File: docs/src/content/docs/reference/auth.mdx line 110 — Broken link format: See also (/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) — uses parentheses syntax instead of proper Markdown link syntax [text](url).
• File: docs/src/content/docs/setup/creating-workflows.mdx — Web interface option gated on Copilot access; no alternative for Claude users.

Missing Alternative Instructions:

• No "create workflow in GitHub web interface using Claude" path
• No explanation of what happens when gh aw init runs for a Claude-only repo (do "Copilot instructions" files harm anything?)

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0 — None found)

No findings prevent a Claude Code user from getting started entirely. The core documentation path (Prerequisites → Quick Start → Engines reference → Auth reference) is adequate for Claude setup.

---

⚠️ Major Obstacles (Score: 5 found)

Obstacle 1: `gh aw init` sets up "Copilot instructions" — no guidance for Claude users

Impact: Uncertainty about whether init is safe/useful to run

Current State: docs/src/content/docs/setup/cli.md line 120 describes gh aw init as: "Configures .gitattributes, Copilot instructions, prompt files, and logs .gitignore." No explanation of what "Copilot instructions" means or whether they're relevant for Claude users.

Why It's Problematic: Claude users don't know if these files will interfere with their Claude-based workflows or are irrelevant. They may skip gh aw init entirely (losing other benefits like .gitattributes and .gitignore setup) or wonder if they're setting up Copilot inadvertently.

Suggested Fix: Rename to "coding agent prompt files" or add a parenthetical explanation like "(applies to Copilot; Claude users can safely ignore these files)". Alternatively add a note that --no-mcp or similar flag can skip Copilot-specific configuration.

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

Obstacle 2: `gh aw add-wizard` used in Quick Start but not documented in CLI reference

Impact: Users following Quick Start can't find documentation for the primary onboarding command

Current State: docs/src/content/docs/setup/quick-start.mdx step 2 uses gh aw add-wizard githubnext/agentics/daily-repo-status. The CLI reference (docs/src/content/docs/setup/cli.md) documents gh aw add but not gh aw add-wizard. There is no entry for add-wizard anywhere in the CLI docs.

Why It's Problematic: Users who want to understand what the wizard does before running it, or who want to look up flags/options, find nothing. The command runs in interactive mode, so users don't know what to expect or what choices they'll face.

Suggested Fix: Add an add-wizard section to the CLI reference with description, options, and what the interactive steps involve.

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

Obstacle 3: Architecture doc network config example only shows `engine: copilot`

Impact: Suggests Copilot is the canonical engine for security configuration

Current State: docs/src/content/docs/introduction/architecture.mdx (network config example, ~line 224):

engine: copilot

network:
  firewall: true
  allowed:
    - defaults
    - python
    - node
    - "api.example.com"

No alternative showing engine: claude or a generic engine: placeholder.

Why It's Problematic: Architecture is a foundational doc. Showing only engine: copilot in the security example implies that the network configuration applies specifically to Copilot, or that Copilot is the expected/canonical engine.

Suggested Fix: Change the example to engine: claude or add a comment like # works with copilot, claude, or codex.

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

Obstacle 4: Web interface workflow creation requires Copilot access

Impact: Claude users lose one entire creation method with no alternative provided

Current State: docs/src/content/docs/setup/creating-workflows.mdx opens the GitHub Web Interface section with: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." No alternative follows for non-Copilot users.

Why It's Problematic: A first-time user reading this section concludes they cannot use the web interface at all. In practice, Claude Code users can edit workflow markdown files directly in the GitHub web editor, but this isn't mentioned.

Suggested Fix: Add a note: "If you don't have Copilot, you can also edit workflow .md files directly in the GitHub web editor — just make sure to run gh aw compile locally to regenerate the .lock.yml before pushing changes to frontmatter."

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

Obstacle 5: Confusing default model comment in engines reference

Impact: Claude users confused about Copilot engine defaults vs Claude defaults

Current State: docs/src/content/docs/reference/engines.md lines 87-88:

engine:
  id: copilot
  version: latest
  model: gpt-5   # defaults to claude-sonnet-4
```
The comment `# defaults to claude-sonnet-4` appears under `id: copilot` extended configuration. This is extremely confusing: does Copilot default to a Claude model? The comment seems misplaced or referring to the overall gh-aw system default.

**Suggested Fix:** Clarify the comment — if this means "the default model for gh-aw as a whole is claude-sonnet-4 when using Claude engine", move this explanation to the Claude engine section. If Copilot genuinely defaults to claude-sonnet-4, explain this clearly.

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

</details>

---

### 💡 Minor Confusion Points (Score: 5 found)

- **Mermaid diagram labels only Copilot CLI** — `docs/src/content/docs/introduction/architecture.mdx` Agent Workflow Firewall diagram shows only "Copilot CLI" in the agent process. Claude CLI and Codex are absent, making it appear the architecture is Copilot-specific.
- **Broken link in auth.mdx** — `docs/src/content/docs/reference/auth.mdx` line 110: `See also (/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code)` uses parentheses instead of proper Markdown link syntax `[text](url)`.
- **`GH_AW_AGENT_TOKEN` not clearly labeled Copilot-only** — `docs/src/content/docs/reference/auth.mdx` documents this token in the general auth section. The Copilot-specific nature is only stated at the bottom. Adding a "(Copilot only)" label at the section heading would help non-Copilot users skip it confidently.
- **Gemini engine in workflows but undocumented** — 1 workflow file uses `engine: gemini` which is not listed as a supported engine in `docs/src/content/docs/reference/engines.md`. Minor confusion for users who discover this.
- **FAQ data processing section** — `docs/src/content/docs/reference/faq.md` details Copilot data handling thoroughly but Claude/Codex gets a one-liner: "Uses respective providers' APIs with their data handling policies." Claude users may want more specifics here.

---

## Engine Comparison Analysis

### Available Engines

Based on my review:
- `engine: copilot` — Default engine, most documentation, most examples, detailed setup in engines reference
- `engine: claude` — Well-documented setup, 31 example workflows, clear auth docs; some areas lag behind Copilot coverage
- `engine: codex` — Documented, 9 example workflows
- `engine: gemini` — Used in 1 workflow but **completely undocumented**

### Documentation Quality by Engine

| Engine | Setup Docs | Examples | Auth Docs | Overall Score |
|--------|-----------|----------|-----------|---------------|
| Copilot | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Claude | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Codex | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| Custom/Other | ⭐⭐ | ⭐ | ⭐⭐ | ⭐⭐ |

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

---

## Tool Availability Analysis

### Tools Review

**Engine-Agnostic Tools (work with any engine):**
- `edit:` — File editing
- `bash:` — Shell commands
- `web-fetch:` — Web content fetching
- `web-search:` — Web search (may need third-party MCP for some engines)
- `github:` — GitHub API operations
- `playwright:` — Browser automation
- `agentic-workflows:` — Workflow introspection
- `cache-memory:` — Persistent storage
- `repo-memory:` — Repository memory
- Custom MCP servers via `mcp-servers:`

**Engine-Specific Tools:**
- `engine.agent:` field in frontmatter — Copilot custom agents only (other engines receive the markdown body as prompt, but no engine-specific tool equivalent for Claude)

**Unclear/Undocumented:**
- `web-search:` — Note in tools doc says "Some engines require third-party MCP servers for web search" but doesn't specify which engines

---

## Authentication Requirements

### Current Documentation

Quick Start and Engines reference cover authentication for:
- ✅ Copilot (detailed instructions with video)
- ✅ Claude (clear instructions, 2 steps)
- ✅ Codex (clear instructions, 2 steps)
- ⚠️ Custom/GitHub App (documented but complex)

### Missing for Claude Users

- No video walkthrough for creating Anthropic API key (Copilot gets a video; Claude does not)
- Link to Anthropic API key creation goes to `(platform.claude.com/redacted) — this is a documentation URL, not the direct key creation page. A direct link to `https://console.anthropic.com` would be more actionable.
- Auth page has a broken link for the "see also" reference to Claude engine docs

### Secret Names

- Copilot: `COPILOT_GITHUB_TOKEN` — documented with detailed PAT setup instructions, video
- Claude: `ANTHROPIC_API_KEY` — documented clearly, no video
- Codex: `OPENAI_API_KEY` — documented clearly, no video
- Note: `GH_AW_AGENT_TOKEN` is Copilot-only but not labeled as such at first glance

---

## Example Workflow Analysis

### Workflow Count by Engine

```
Engine: copilot  — 74 workflows found (48%)
Engine: claude   — 31 workflows found (20%)
Engine: codex    —  9 workflows found  (6%)
Engine: gemini   —  1 workflow found   (1%)
Complex engine:  — 19 workflows found (12%)
Unspecified:     — 20 workflows found (13%)  ← default to copilot
Total:           — 154 workflows

Quality of Examples

Copilot Examples: Comprehensive coverage across many use cases. Used as the default in architecture docs and configuration examples.

Claude Examples: Good coverage of 31 workflows including audit-workflows, blog-auditor, claude-code-user-docs-review (meta!), cli-version-checker, etc. Quality is high — they show realistic production-grade configurations. However, beginner-friendly starter examples tend to feature Copilot.

Codex Examples: 9 workflows, limited coverage.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Add add-wizard to CLI reference — Users running Quick Start hit a command with no documentation. File: docs/src/content/docs/setup/cli.md
2. Fix broken Markdown link in auth.mdx — See also (/gh-aw/reference/engines/...) should be [See also](/gh-aw/reference/engines/...). File: docs/src/content/docs/reference/auth.mdx line 110
3. Clarify "Copilot instructions" in gh aw init — Explain what these files are and that Claude users can run init without issue. File: docs/src/content/docs/setup/cli.md

Priority 2: Major Improvements

1. Fix engine default model comment confusion — Clarify # defaults to claude-sonnet-4 comment under Copilot engine config. File: docs/src/content/docs/reference/engines.md
2. Update AWF mermaid diagram — Replace "Copilot CLI" node with generic "AI Engine (Copilot/Claude/Codex)" to reflect reality. File: docs/src/content/docs/introduction/architecture.mdx
3. Add Claude alternative for web interface creation — Note that Claude users can edit .md files in the GitHub web editor directly. File: docs/src/content/docs/setup/creating-workflows.mdx
4. Add engine: claude example to architecture network config — Replace or supplement engine: copilot example. File: docs/src/content/docs/introduction/architecture.mdx
5. Label GH_AW_AGENT_TOKEN as Copilot-only — Add "(Copilot only)" to the section heading. File: docs/src/content/docs/reference/auth.mdx

Priority 3: Nice-to-Have Enhancements

1. Add video for Claude API key setup — Match the video quality that Copilot PAT setup receives
2. Fix Anthropic API key link — Point to the direct console URL rather than docs URL
3. Document or remove gemini engine reference — Either add engine: gemini to supported engines or remove/update that workflow
4. Add engine feature comparison table — A clear table showing what each engine supports would help users choose
5. Add "Getting started with Claude engine" guide — A dedicated path for non-Copilot users mirroring the overall Quick Start but explicitly Claude-focused

---

Positive Findings

What Works Well

• ✅ Prerequisites clearly list all three engine options — Quick Start does not assume Copilot
• ✅ Engines reference is well-structured and parallel — Clear, parallel documentation for Copilot, Claude, and Codex
• ✅ ANTHROPIC_API_KEY clearly documented — Auth reference is comprehensive for Claude
• ✅ Core tools are fully engine-agnostic — No Copilot lock-in for edit, bash, github, playwright, etc.
• ✅ secrets bootstrap supports --engine claude — CLI tooling is non-Copilot-friendly
• ✅ 31 Claude workflow examples — Substantial library of real-world Claude workflows in the repo
• ✅ add-wizard covers all engines interactively — The actual onboarding command is engine-neutral
• ✅ How It Works doc is balanced — No Copilot bias in core concepts
• ✅ FAQ clearly explains per-engine cost model — Billing for Claude is clearly explained

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate friction

Reasoning: The fundamental setup path for Claude engine is well-documented. The Quick Start wizard handles engine selection interactively, the Engines reference has clear parallel documentation for all three engines, and the auth reference clearly documents ANTHROPIC_API_KEY. A determined Claude user will get gh-aw running without needing Copilot.

The friction comes from Copilot-first defaults in peripheral documentation: configuration examples using engine: copilot, architecture diagrams labeling only "Copilot CLI", a web interface creation method gated on Copilot, and the gh aw init description mentioning "Copilot instructions" without explanation. None of these are hard blockers, but they collectively create a sense that Copilot is the "real" use case and other engines are second-class citizens.

The add-wizard documentation gap is the most practically impactful issue since it's used in the primary Quick Start guide.

Overall Assessment Score: 7/10

Breakdown:

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

Next Steps

The highest-impact improvement would be: (1) documenting add-wizard in the CLI reference, (2) fixing the broken auth link for Claude, and (3) clarifying the "Copilot instructions" language in gh aw init. These three changes would significantly improve the out-of-the-box experience for Claude Code users following the standard documentation path.

---

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/setup/creating-workflows.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/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/reference/faq.md
• docs/src/content/docs/reference/copilot-custom-agents.md
• .github/workflows/*.md (154 files — engine distribution analysis)

---

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

AI generated by Claude Code User Documentation Review

• expires on Feb 26, 2026, 10:38 PM UTC