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

[github-actions[bot]]

Executive Summary

gh-aw is well-positioned for Claude Code users with no critical blockers preventing adoption. The quick start guide explicitly lists Claude as a supported AI account, the add-wizard command walks users through Claude engine selection and ANTHROPIC_API_KEY configuration, and 34 real-world Claude-engine workflow examples exist in the repository. However, several persistent documentation gaps create friction: the architecture diagram still hardcodes "Copilot CLI" as the agent label, the GitHub Web Interface workflow-creation path is gated by Copilot access with no Claude alternative shown, and the add-wizard command is central to the quick start but absent from the CLI reference documentation.

Key Finding: Claude Code users can successfully adopt gh-aw, but will encounter moderate friction from Copilot-centric framing in diagrams, examples, and some guides. Score remains 7/10 for the 17th consecutive day — all 11 previously reported issues remain unresolved.

---

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 some friction. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) is largely engine-agnostic and explicitly calls out Claude as a valid option in Prerequisites, Step 2, and secret setup. The gh aw add-wizard command interactively asks which engine to use, making the path to Claude configuration smooth.

However, the How They Work page (docs/src/content/docs/introduction/how-they-work.mdx) says on line 26: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." This omits Gemini entirely, which is now a documented fourth engine. This creates a first impression that gh-aw is primarily a Copilot tool with Claude as an add-on rather than an equal partner.

Specific Issues Found:

• docs/src/content/docs/introduction/how-they-work.mdx line 26 — Lists "Copilot (default), Claude by Anthropic, and Codex" — omits Gemini despite it being a fully documented engine
• docs/src/content/docs/setup/creating-workflows.mdx lines 20-23 — GitHub Web Interface section opens with "If you have access to GitHub Copilot, you can create workflows directly from the Web Interface" with no alternative path shown for Claude Code users
• docs/src/content/docs/setup/quick-start.mdx line 62 — Uses gh aw add-wizard command which does not appear in the CLI reference (docs/src/content/docs/setup/cli.md)

Recommended Fixes:

• Update how-they-work.mdx to list all four engines: "Copilot (default), Claude by Anthropic, Codex, and Gemini"
• Add a note in the GitHub Web Interface section of creating-workflows.mdx that Claude Code users can use the terminal/CLI path in the next section as an equivalent
• Add add-wizard to the CLI reference documentation under "Getting Workflows"

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• GitHub Web Interface workflow creation — creating-workflows.mdx lines 20–57 are gated by "If you have access to GitHub Copilot" (Copilot Chat required for /agent prompts)
• /agent agentic-workflows commands — custom-agent-for-aw.mdx describes using /agent agentic-workflows create, /agent agentic-workflows debug, etc. — these require Copilot Chat or VSCode Agent Mode with Copilot. No equivalent documented for Claude Code users.
• assign-to-agent safe output with Copilot — assign-to-copilot.mdx is specifically for assigning the Copilot coding agent; this is a Copilot-only feature and correctly documented as such.

Features That Work Without Copilot (engine-agnostic):

• All CLI commands: gh aw init, compile, run, list, status, logs, audit, health, mcp
• All tools: github, playwright, cache-memory, bash, edit, web-fetch, repo-memory, agentic-workflows
• All safe outputs: create-issue, add-comment, create-pull-request, etc.
• All trigger types and permissions
• MCP server integrations
• gh aw add-wizard (Claude option in wizard)

Missing Documentation:

• No Claude Code equivalent documented for /agent agentic-workflows commands — Claude Code users cannot use this workflow-authoring workflow at all without guidance
• custom-agent-for-aw.mdx page title says "Copilot Agent Files support for Agentic Workflows" and is entirely Copilot-focused with no Claude Code equivalent

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/introduction/architecture.mdx lines 177, 248 — The AWF (Agent Workflow Firewall) mermaid diagram labels the agent container as "Copilot CLI" and "Copilot CLI + MCP client". These are architectural diagrams showing the system design, but the labels are Copilot-specific when they should show generic "AI Agent" or list all engines.
• File: docs/src/content/docs/introduction/architecture.mdx lines 222–233 — The only network configuration example uses engine: copilot, without noting that the network: field is engine-agnostic.
• File: docs/src/content/docs/setup/creating-workflows.mdx lines 20–23 — Opens with a Copilot-gated section without offering a Claude Code alternative for the same web-based workflow creation experience.
• File: docs/src/content/docs/reference/custom-agent-for-aw.mdx — Entirely Copilot-focused; no mention of how Claude Code users can achieve equivalent workflow-authoring assistance.

Missing Alternative Instructions:

• No documentation on using Claude Code (the CLI tool) for the /agent agentic-workflows workflow-creation tasks
• No Claude-specific troubleshooting in common-issues.md
• No Claude example in the web-search guide

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10 — No Critical Blockers)

No critical blockers exist. A Claude Code user can install gh-aw, configure ANTHROPIC_API_KEY, add a workflow, compile it, and run it without ever needing Copilot access.

---

⚠️ Major Obstacles (Score: 5 found)

Obstacle 1: Architecture diagram hardcodes "Copilot CLI" as the agent

Impact: Significant confusion when reading the architecture docs

Current State: docs/src/content/docs/introduction/architecture.mdx lines 177 and 248 show:

COPILOT["Copilot CLI"]
```
and
```
AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]
```

**Why It's Problematic:** A Claude Code user reading the architecture docs will see "Copilot CLI" as the named agent in the isolation and firewall diagrams. This creates an incorrect mental model that Copilot is the system's core, not just one of multiple engine choices.

**Suggested Fix:** Change to `AGENT["AI Agent\n(Copilot / Claude / Codex / Gemini)\n172.30.0.20"]` or a more generic label.

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

</details>

<details>
<summary><b>Obstacle 2: GitHub Web Interface creation path is Copilot-only, no alternative shown</b></summary>

**Impact:** Claude Code users see a Copilot-gated path and may not notice the equivalent terminal-based path

**Current State:** `docs/src/content/docs/setup/creating-workflows.mdx` lines 20–23:
> "**If you have access to GitHub Copilot**, you can create and edit Agentic Workflows directly from the Web Interface."

**Why It's Problematic:** The prominent placement of this section before the VSCode/Claude/Codex section implies it's the primary path. No callout explains that Claude Code users should use the next section.

**Suggested Fix:** Add a note like: "If you use Claude Code or another non-Copilot agent, skip to the [VSCode/Claude/Codex/Copilot](#vscodeclaudecodexcopilot) section below."

**Affected Files:** `docs/src/content/docs/setup/creating-workflows.mdx` line 20

</details>

<details>
<summary><b>Obstacle 3: custom-agent-for-aw.mdx is 100% Copilot-specific with no Claude alternative</b></summary>

**Impact:** Claude Code users have no documented equivalent for AI-assisted workflow authoring from their tool

**Current State:** The entire `custom-agent-for-aw.mdx` document describes the `agentic-workflows` Copilot agent file and `/agent agentic-workflows` commands. The page title is "Copilot Agent Files support for Agentic Workflows."

**Why It's Problematic:** `creating-workflows.mdx` section heading says "VSCode/Claude/Codex/Copilot" and references using a coding agent, but the linked documentation for the agent-assisted authoring path is entirely Copilot-specific. Claude Code users have no equivalent documented flow.

**Suggested Fix:** Add a section to `custom-agent-for-aw.mdx` or `creating-workflows.mdx` showing how Claude Code users can use the `create.md` or `install.md` raw URLs as context with Claude Code to achieve the same result.

**Affected Files:** `docs/src/content/docs/reference/custom-agent-for-aw.mdx`

</details>

<details>
<summary><b>Obstacle 4: add-wizard is the Quick Start entry point but absent from CLI docs</b></summary>

**Impact:** Users following the Quick Start cannot look up the command's options in the CLI reference

**Current State:** `quick-start.mdx` line 62 uses `gh aw add-wizard githubnext/agentics/daily-repo-status` as the primary onboarding command, but `cli.md` documents `gh aw add` (not `add-wizard`).

**Why It's Problematic:** After following the Quick Start, users who want to understand what happened, explore options, or troubleshoot cannot find `add-wizard` in the CLI reference. This is a discoverability gap that affects all users, not just Claude Code users.

**Suggested Fix:** Add an `add-wizard` section to `cli.md` documenting it as an interactive alias for `add` with engine selection and secret configuration steps built in.

**Affected Files:** `docs/src/content/docs/setup/cli.md`, `docs/src/content/docs/setup/quick-start.mdx`

</details>

<details>
<summary><b>Obstacle 5: ANTHROPIC_API_KEY setup URL may be incorrect</b></summary>

**Impact:** Claude users following setup instructions land on a documentation page, not the API key creation page

**Current State:** `docs/src/content/docs/reference/auth.mdx` line 104:
```
1. Create an API key at (platform.claude.com/redacted)
```

**Why It's Problematic:** This URL points to the "Getting started" documentation page, not to the API key management console. Users need to navigate to `console.anthropic.com/settings/keys` to create API keys. The Copilot setup uses a pre-filled link that goes directly to token creation — Claude should have an equivalent direct link.

**Suggested Fix:** Update the URL to `https://console.anthropic.com/settings/keys` (the direct API key management page).

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

</details>

---

### 💡 Minor Confusion Points (Score: 11 found — all pre-existing from prior reviews)

- **Issue 1:** `how-they-work.mdx` line 26 — "Copilot (default), Claude by Anthropic, and Codex" — omits Gemini as a fourth supported engine
- **Issue 2:** `architecture.mdx` lines 222–233 — Only network config example uses `engine: copilot` without noting engine-agnosticism
- **Issue 3:** `engines.md` line 31 — `model: gpt-5 # defaults to claude-sonnet-4` under Copilot extended config — the comment mixing engine names is confusing (it means: for the copilot engine, the default model is claude-sonnet-4)
- **Issue 4:** `cli.md` line 161 — `secrets bootstrap --engine` flag documents `(copilot, claude, codex)` but omits `gemini` despite being a supported engine
- **Issue 5:** No Claude-specific troubleshooting in `common-issues.md` (vs. dedicated "Copilot CLI Not Found" and "Copilot License Issues" sections)
- **Issue 6:** `web-search.md` (not reviewed today) reportedly shows only copilot engine examples, no Claude equivalent
- **Issue 7:** `custom-agent-for-aw.mdx` uses Copilot-centric prompts without explaining the `Other Agents and Chats` section is for tools like Claude Code
- **Issue 8:** The page title "Copilot Agent Files support for Agentic Workflows" (`custom-agent-for-aw.mdx`) suggests this whole feature is Copilot-only
- **Issue 9:** `creating-workflows.mdx` step 3 says "If not using Copilot, also adjust the `engine:` field" — framing Claude as the non-default that requires extra steps
- **Issue 10:** The sidebar navigation has a "Copilot Custom Agents" item that links to `copilot-custom-agents.md` which is entirely Copilot-specific with no multi-engine equivalent
- **Issue 11:** `how-they-work.mdx` uses "Copilot (default)" framing which is technically accurate but doesn't help Claude Code users feel like first-class users

---

## Engine Comparison Analysis

### Available Engines

Based on my review, gh-aw supports four engines:
- `engine: copilot` — Default; most workflow examples use this; dedicated troubleshooting; web interface integration via `/agent agentic-workflows`
- `engine: claude` — Well-documented in auth.mdx and engines.md; 34 real-world examples in repo; `ANTHROPIC_API_KEY` clearly documented
- `engine: codex` — 10 workflow examples; documented in auth.mdx and engines.md; `OPENAI_API_KEY`
- `engine: gemini` — Documented in auth.mdx and engines.md; `GEMINI_API_KEY`; 0 workflow examples in repo

### Documentation Quality by Engine

| Engine | Setup Docs | Examples | Auth Docs | Overall Score |
|--------|-----------|----------|-----------|---------------|
| Copilot | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Claude | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Codex | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| Gemini | ⭐⭐⭐ | ⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |

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

---

## Tool Availability Analysis

### Tools Review

**Engine-Agnostic Tools (work with any engine):**
- `github:` — GitHub API operations (toolsets, remote/local modes)
- `playwright:` — Browser automation
- `bash:` — Shell command execution
- `edit:` — File editing
- `web-fetch:` — Web content fetching
- `cache-memory:` — Persistent memory across runs
- `repo-memory:` — Repository-specific memory
- `agentic-workflows:` — Workflow introspection
- All `mcp-servers:` configurations

**Engine-Specific Tools:**
- `engine.agent:` — Copilot-only custom agent configuration (`.github/agents/*.agent.md`)

**Unclear/Undocumented:**
- `web-search:` — The note "Some engines require third-party MCP servers for web search" in `tools.md` line 65 implies different behavior per engine, but no per-engine breakdown is provided

---

## Authentication Requirements

### Current Documentation

Quick Start guide covers authentication for:
- ✅ Copilot — Detailed instructions with pre-filled PAT creation link, troubleshooting section
- ✅ Claude — `ANTHROPIC_API_KEY` documented, URL may be incorrect (see Obstacle 5)
- ✅ Codex — `OPENAI_API_KEY` documented with direct link to platform.openai.com/api-keys
- ✅ Gemini — `GEMINI_API_KEY` documented with direct link to aistudio.google.com/api-keys

### Missing for Claude Users

- Direct API key creation link (current URL points to docs page, not key console)
- No note about Claude API pricing model vs. Copilot subscription model (FAQ covers billing but not upfront)
- No Claude-specific troubleshooting for failed authentication

### Secret Names

| Engine | Secret Name | Documentation |
|--------|------------|---------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Documented with troubleshooting |
| Claude | `ANTHROPIC_API_KEY` | ✅ Documented, URL possibly incorrect |
| Codex | `OPENAI_API_KEY` | ✅ Documented |
| Gemini | `GEMINI_API_KEY` | ✅ Documented |

---

## Example Workflow Analysis

### Workflow Count by Engine (as of 2026-03-09)

```
Engine: copilot  - 79 workflows found (47%)
Engine: claude   - 34 workflows found (20%)
Engine: codex    - 10 workflows found (6%)
Engine: gemini   -  0 workflows found (0%)
Engine: default  - ~26 workflows (no engine specified = copilot default)
Total:           ~168 workflow files

Quality of Examples

Copilot Examples: Comprehensive; cover all major use cases including PR review, issue triage, daily reports, security scans, code quality, and advanced patterns.

Claude Examples: Good coverage; 34 examples including complex multi-tool workflows (smoke-claude.md demonstrates GitHub MCP, Serena MCP, Playwright, Tavily, bash tools all used together). Demonstrates Claude is a full-featured engine, not a second-class option.

Codex Examples: Moderate; 10 examples exist including a dedicated codex-github-remote-mcp-test.md smoke test.

Gemini Examples: Missing entirely — 0 workflow files found using engine: gemini.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix ANTHROPIC_API_KEY setup URL — Change (platform.claude.com/redacted) to https://console.anthropic.com/settings/keys` in docs/src/content/docs/reference/auth.mdx line 104. This is a navigation dead-end for users trying to create their API key.

2. Document add-wizard in CLI reference — Add add-wizard as a documented command in docs/src/content/docs/setup/cli.md under "Getting Workflows". It's the primary Quick Start onboarding command but is invisible to users looking for CLI reference documentation.

3. Update how-they-work.mdx to include Gemini — Line 26 should read "GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini" to accurately reflect all supported engines.

Priority 2: Major Improvements

1. De-Copilot the architecture diagrams — In architecture.mdx lines 177 and 248, replace COPILOT["Copilot CLI"] and "Copilot CLI + MCP client" with engine-agnostic labels to avoid implying Copilot is the only engine.

2. Add Claude Code path to creating-workflows.mdx — The GitHub Web Interface section (lines 20–57) is Copilot-gated. Add a callout directing Claude Code users to the terminal section, or document the equivalent Claude Code prompt for creating a workflow using create.md.

3. Add Gemini to secrets bootstrap --engine docs — cli.md line 161 lists (copilot, claude, codex) but omits gemini. Update to (copilot, claude, codex, gemini).

4. Add Claude section to custom-agent-for-aw.mdx — The "Other Agents and Chats" section (line 130) mentions compatibility with other AI tools but doesn't show a concrete example for Claude Code. Add a brief code example showing how Claude Code users can use create.md as context.

Priority 3: Nice-to-Have Enhancements

1. Add Claude-specific troubleshooting to common-issues.md — Document common Claude authentication failure modes (invalid API key, billing limits) analogous to the "Copilot CLI Not Found" and "Copilot License Issues" sections.
2. Add Gemini workflow examples — Create at least one example workflow using engine: gemini to ensure Gemini is a viable, tested option.
3. Add per-engine web-search examples — The web-search.md guide reportedly shows only Copilot examples; add a Claude equivalent showing the MCP-based alternative.
4. Add engine-agnostic callout to network config example — In architecture.mdx lines 222–233, note that the network: configuration works the same for all engines.

---

Positive Findings

What Works Well

• ✅ Quick Start is largely engine-agnostic — Prerequisites, wizard, and steps all include Claude as a first-class option
• ✅ add-wizard onboarding covers Claude — The interactive wizard prompts for engine choice and correctly sets up ANTHROPIC_API_KEY
• ✅ Auth reference is comprehensive for all engines — Equal detail for Copilot, Claude, Codex, and Gemini
• ✅ 34 real-world Claude workflow examples — More than enough to understand what's possible; smoke-claude.md is a showcase of Claude engine capabilities
• ✅ All tools are engine-agnostic — No tool requires Copilot; Claude users get the same capabilities
• ✅ CLI is fully engine-agnostic — init, compile, run, logs, audit, health all work identically for Claude
• ✅ FAQ addresses CLAUDE_CODE_OAUTH_TOKEN — Explicitly documents that OAuth is not supported, only ANTHROPIC_API_KEY
• ✅ creating-workflows.mdx includes Claude in heading — "VSCode/Claude/Codex/Copilot" signals multi-engine support
• ✅ Engines reference is well-structured — Clear table with engine values, secret names, and links

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction

Reasoning: The core workflow — install extension, run add-wizard, choose Claude, set ANTHROPIC_API_KEY, get first workflow running — is fully documented and Claude-friendly. The interactive add-wizard is the key path, and it handles all engine choices equally. The 34 existing Claude workflow examples in the repo demonstrate that gh-aw is actively used with Claude in production.

The friction points are primarily cosmetic and documentation quality issues: architecture diagrams that say "Copilot CLI" when they should say "AI Agent", a GitHub web interface section that's Copilot-only, and missing add-wizard documentation in the CLI reference. None of these prevent a Claude Code user from successfully using gh-aw, but they do create moments of confusion and a subtle impression that Copilot is the "real" engine.

Overall Assessment Score: 7/10

Breakdown:

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

Score stable at 7/10 for 17 consecutive days (since ~2026-02-21). All 11 previously reported issues remain open.

Next Steps

The most impactful single change would be fixing the ANTHROPIC_API_KEY setup URL and documenting add-wizard in the CLI reference — both are small edits with high user-facing impact. The architecture diagram Copilot labels are the highest-visibility cosmetic issue. No critical blockers require urgent attention.

---

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/faq.md
• docs/src/content/docs/setup/creating-workflows.mdx
• docs/src/content/docs/reference/custom-agent-for-aw.mdx
• docs/src/content/docs/reference/editors.mdx
• .github/workflows/smoke-claude.md (example workflow analysis)
• Cache memory from prior runs (2026-02-26 through 2026-03-08)

---

Report Generated: 22877791352
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food! 🐕)
Score Trend: 7/10 for 17 consecutive days

AI generated by Claude Code User Documentation Review · history

• expires on Mar 10, 2026, 10:37 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-10T22:37:09.859Z.

Closed by Workflow