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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and actively avoids GitHub Copilot products, gh-aw is viable to adopt — but the documentation still has persistent gaps that create friction for non-Copilot users. The Quick Start, Auth, and CLI references handle multi-engine scenarios well. The main issues are a Copilot-centric architecture diagram, Gemini being absent from a key overview page, and the Web Interface creation path being exclusively Copilot-gated. These issues have persisted for at least 15 days without resolution.

Key Finding: Claude Code users can successfully adopt gh-aw. There are zero critical blockers. However, 4 recurring documentation issues continue to create minor-to-moderate friction, and the overall score remains stable at 7/10 — unchanged since the previous 14 runs.

Trend: Score has been stable at 7/10 for 15 consecutive days. The same 4 issues persist. One new Copilot engine workflow was added to the repo since yesterday (80 total, up from 79).

---

Persona Context

Reviewed 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 minor friction. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) correctly lists Claude as a valid AI Account option in prerequisites:

"AI Account - GitHub Copilot, Anthropic Claude or OpenAI Codex"

Step 2's gh aw add-wizard command is described as helping users "Select an AI Engine — Choose between Copilot, Claude, or Codex." This is accurate and inclusive.

Specific Issues Found:

• Issue 1 (creating-workflows.mdx:21): The GitHub Web Interface creation path is exclusively gated: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." No alternative is offered for the web UI path. Claude users must skip this section entirely.
• Issue 2 (creating-workflows.mdx:96): The phrasing "If not using Copilot, also adjust the engine: field" frames Copilot as the easy default and everything else as requiring extra steps, even though adding engine: claude is trivial.
• Issue 3 (how-they-work.mdx:26): The overview page states "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex" — Gemini is absent despite being a fully supported engine documented in engines.md and auth.mdx.

Recommended Fixes:

• Update creating-workflows.mdx:21 to include Claude/Codex alternatives for workflow creation: e.g., "If using Claude Code or Codex, you can create workflows directly from your terminal with gh aw new"
• Reframe creating-workflows.mdx:96 as: "Set the engine: field in your workflow frontmatter to match your AI provider: claude, codex, gemini, or copilot (default)"
• Add Gemini to the engine list in how-they-work.mdx:26

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot (by design):

• engine: copilot workflows and COPILOT_GITHUB_TOKEN secret
• safe-outputs: assign-to-copilot / assign-to-agent — explicitly Copilot-specific
• Copilot custom agent files (.github/agents/*.agent.md) with engine.agent config
• GitHub Web Interface workflow creation (documented as Copilot-only)

Features That Work Without Copilot:

• All built-in tools: edit:, github:, bash:, web-fetch:, web-search:, playwright:, cache-memory:, repo-memory:, agentic-workflows:
• All CLI commands: gh aw init, add-wizard, compile, run, status, logs, audit, health, etc.
• All safe outputs: create-issue, add-comment, create-pull-request, add-labels
• MCP server integrations (engine-agnostic)
• Threat detection pipeline
• Network firewall / AWF
• Secret bootstrap: gh aw secrets bootstrap --engine claude

Missing Documentation:

• No "which features are Copilot-only vs engine-agnostic" summary page or table
• The assign-to-copilot feature is documented but there's no corresponding "assign to Claude Code" equivalent (may be a product gap, not a docs gap)

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

File	Line	Issue
architecture.mdx	177	Mermaid diagram labels agent process COPILOT["Copilot CLI"]
architecture.mdx	248	MCP Gateway diagram labels agent "Agent container\nCopilot CLI + MCP client"
architecture.mdx	222	AWF configuration example uses engine: copilot without showing Claude alternative
how-they-work.mdx	26	Engine list omits Gemini despite it being fully supported
creating-workflows.mdx	21	Web Interface section gated to Copilot users
creating-workflows.mdx	96	"If not using Copilot" framing
auth.mdx	49	CLI example for secrets uses COPILOT_GITHUB_TOKEN only

Missing Alternative Instructions:

• No guidance on creating workflows via GitHub web UI for Claude/Codex users (the web interface path is Copilot-only)

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

None. Claude Code users can install, configure, and run gh-aw workflows without any Copilot products.

⚠️ Major Obstacles (Score: 3/10)

Obstacle 1: Architecture Diagrams Show "Copilot CLI" as the Agent (Persistent - Day 15)

Impact: Confusion about what runs inside the security sandbox — makes Claude users wonder if they're excluded from the described architecture.

Current State: architecture.mdx line 177 shows:

COPILOT["Copilot CLI"]
```
And line 248:
```
AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]
```

**Why It's Problematic:** The security architecture diagrams are among the most important for understanding how gh-aw works. Showing "Copilot CLI" as the canonical agent process implies the architecture is built around Copilot, when in fact Claude Code and other engines run in exactly the same environment.

**Suggested Fix:** Rename the diagram nodes to engine-agnostic labels:
- `COPILOT["Copilot CLI"]` → `AGENT_CLI["AI Engine CLI\n(Claude Code / Copilot / Codex / Gemini)"]`
- `"Agent container\nCopilot CLI + MCP client\n172.30.0.20"` → `"Agent container\nAI Engine CLI + MCP client\n172.30.0.20"`

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

</details>

<details>
<summary><b>Obstacle 2: Web Interface Workflow Creation Requires Copilot (Persistent - Day 15)</b></summary>

**Impact:** Claude Code users land on the "Creating Workflows" page and find the first creation method (Web Interface) is gated to Copilot users. There's no equivalent web-based path offered.

**Current State:** `creating-workflows.mdx:21`:
> "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface."

**Why It's Problematic:** This is the first creation method listed. A Claude Code user reading this for the first time encounters an immediate "not for you" message before reaching the terminal/VS Code path.

**Suggested Fix:** Add a brief note that terminal-based creation (`gh aw new`) and Claude Code / Codex-based creation are available regardless of Copilot access, or restructure to lead with the engine-agnostic paths.

**Affected Files:** `docs/src/content/docs/setup/creating-workflows.mdx` (lines 21–61)

</details>

#### 💡 Minor Confusion Points (Score: 4/10)

- **Gemini omitted from How They Work** — `how-they-work.mdx:26` lists "Copilot, Claude, and Codex" but not Gemini, despite full Gemini support in engines.md and auth.mdx. File: `docs/src/content/docs/introduction/how-they-work.mdx`
- **AWF config example uses Copilot** — The network firewall configuration example in architecture.mdx uses `engine: copilot` with no multi-engine alternative shown. File: `docs/src/content/docs/introduction/architecture.mdx:222`
- **CLI example uses COPILOT_GITHUB_TOKEN** — The auth page's CLI example uses `gh aw secrets set COPILOT_GITHUB_TOKEN` as the sample, with no Claude equivalent alongside it. File: `docs/src/content/docs/reference/auth.mdx:49`
- **ANTHROPIC_API_KEY setup URL** — Points to `(platform.claude.com/redacted) which may redirect or be incorrect vs the current Anthropic console at `console.anthropic.com`. File: `docs/src/content/docs/reference/auth.mdx:104`
- **"If not using Copilot" framing** — Language implies Copilot is the primary path. File: `docs/src/content/docs/setup/creating-workflows.mdx:96`
- **No engine comparison summary** — No page or table compares feature parity between Claude, Copilot, Codex, and Gemini at a glance
- **`gh aw init` default engine** — The interactive mode documentation says it "selects engine" but doesn't tell you what the default will be if you press Enter without selecting

---

### Engine Comparison Analysis

#### Available Engines (as documented in engines.md)

| Engine | `engine:` value | Required Secret | Documentation Quality |
|--------|-----------------|-----------------|----------------------|
| GitHub Copilot (default) | `copilot` | `COPILOT_GITHUB_TOKEN` | ⭐⭐⭐⭐⭐ |
| Claude by Anthropic | `claude` | `ANTHROPIC_API_KEY` | ⭐⭐⭐⭐ |
| OpenAI Codex | `codex` | `OPENAI_API_KEY` | ⭐⭐⭐⭐ |
| Google Gemini CLI | `gemini` | `GEMINI_API_KEY` | ⭐⭐⭐ |

#### Documentation Quality by Engine

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

---

### Tool Availability Analysis

**Engine-Agnostic Tools (all engines):**
- `edit:` — File editing
- `github:` — GitHub API toolsets
- `bash:` — Shell command execution
- `web-fetch:` — Web content fetching
- `web-search:` — Web search (note: Codex requires explicit declaration)
- `playwright:` — Browser automation
- `cache-memory:` — Persistent memory across runs
- `repo-memory:` — Repository-specific memory
- `agentic-workflows:` — Workflow introspection
- All custom `mcp-servers:` configurations

**Engine-Specific Features (Copilot only):**
- `safe-outputs: assign-to-copilot` / `assign-to-agent` — Copilot-specific
- `engine.agent` field (custom agent files) — Copilot-specific per docs
- Web Interface workflow creation — Copilot-only per creating-workflows.mdx

**Unclear/Undocumented:**
- Whether `engine.agent` custom agents have equivalents for Claude (e.g., CLAUDE.md system prompts)

---

### Authentication Requirements

#### Current Documentation Coverage

| Engine | Secret Name | Documentation | Setup Instructions |
|--------|------------|---------------|-------------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Detailed | ✅ Step-by-step with PAT creation link |
| Claude | `ANTHROPIC_API_KEY` | ✅ Good | ✅ Present (URL may need verification) |
| Codex | `OPENAI_API_KEY` | ✅ Good | ✅ Present with platform.openai.com link |
| Gemini | `GEMINI_API_KEY` | ✅ Good | ✅ Present with aistudio.google.com link |

#### Missing for Claude Users

- The `ANTHROPIC_API_KEY` setup URL (`platform.claude.com/docs/en/get-started`) should be verified — the current Anthropic API key management page is at `console.anthropic.com/settings/keys`
- No guidance on Claude model selection via `engine.model` (though `engines.md` shows `model: gpt-5` for Copilot as an example — a Claude equivalent example would help)

---

### Example Workflow Analysis

#### Workflow Count by Engine (in `.github/workflows/`)

```
Engine: copilot - 80 workflows (47.9%)  [+1 since yesterday]
Engine: claude  - 34 workflows (20.4%)  [unchanged]
Engine: codex   - 10 workflows ( 6.0%)  [unchanged]
Engine: gemini  -  0 workflows ( 0.0%)
Total MD files  - 167

Quality Assessment

Copilot Examples (80 workflows): Very well represented — the default engine is used pervasively throughout the repo's own automation.

Claude Examples (34 workflows): Good coverage — 20.4% of all workflows use Claude, which is significant. The repo "eats its own dog food" with Claude in real workflows like typist.md, pr-triage-agent.md, daily-issues-report.md. This is reassuring for Claude users.

Codex Examples (10 workflows): Moderate — enough to understand basic Codex usage patterns.

Gemini Examples (0 workflows): No Gemini workflows in the repo at all, which makes it harder for Gemini users to find working examples.

---

Recommended Actions

Priority 1: Quick Fixes (Low Effort, High Impact)

1. Add Gemini to how-they-work.mdx — One-line change: "Workflows support GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini". File: how-they-work.mdx:26

2. Verify ANTHROPIC_API_KEY URL — Check if (platform.claude.com/redacted) correctly routes to API key creation, or update to https://console.anthropic.com/settings/keys`. File: auth.mdx:104

3. Update AWF config example — Show a Claude example alongside the Copilot one in the AWF Configuration Example section. File: architecture.mdx:222

Priority 2: Moderate Effort, Significant Impact

4. Rename architecture diagram nodes — Change COPILOT["Copilot CLI"] and "Copilot CLI + MCP client" to engine-agnostic labels. These are Mermaid diagrams that are easy to update. File: architecture.mdx:177, 248

5. Update creating-workflows.mdx Web Interface section — Add a note for non-Copilot users about terminal-based alternatives, or restructure to lead with engine-agnostic paths. File: creating-workflows.mdx:21

Priority 3: Nice-to-Have

6. Add engine feature comparison table — A dedicated table showing which features work with each engine, especially around assign-to-agent and agent custom files
7. Add Claude model selection example — Show engine.model: claude-sonnet-4-6 (or similar) as an example in engines.md alongside the model: gpt-5 Copilot example
8. Add Gemini workflow example — Even one real workflow using Gemini would validate the documentation

---

Positive Findings

What Works Well for Claude Code Users:

• ✅ Quick Start is engine-inclusive — Prerequisites explicitly list "Anthropic Claude" as a valid AI account option
• ✅ gh aw add-wizard handles Claude — The wizard prompts for engine selection and sets up ANTHROPIC_API_KEY correctly
• ✅ Auth docs are comprehensive — ANTHROPIC_API_KEY is fully documented with setup steps
• ✅ All tools are engine-agnostic — No tool requires Copilot
• ✅ CLI is fully engine-agnostic — gh aw new --engine claude, gh aw secrets bootstrap --engine claude, etc.
• ✅ Engines reference is excellent — Clear table, version pinning for all 4 engines, custom API endpoints for Claude
• ✅ Repo uses Claude extensively — 34 of 167 workflows (20.4%) in the gh-aw repo itself use Claude engine, demonstrating real-world viability
• ✅ Custom base URL for Claude — ANTHROPIC_BASE_URL is documented for routing through internal proxies
• ✅ gh aw new --engine claude generates correct frontmatter — Template injection documented in CLI reference

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction

Reasoning: The core adoption path — install the extension, run gh aw add-wizard, select Claude as the engine, set ANTHROPIC_API_KEY, get a workflow running — works without any Copilot dependency. The authentication, CLI, and engine documentation are all solid for Claude users. The 34 Claude engine workflows in the repo itself validate that this path is production-tested.

The friction comes from cosmetic issues: architecture diagrams that show "Copilot CLI" as the canonical agent, a Web Interface creation path that's Copilot-only, and Gemini being absent from an overview sentence. These create a first-impression problem ("is this a Copilot-first tool?") but don't actually block adoption.

Overall Assessment Score: 7/10

Dimension	Score
Clarity for non-Copilot users	7/10
Claude engine documentation	8/10
Alternative approaches provided	8/10
Engine parity (examples/features)	6/10

Next Steps

The same 4 issues have persisted for 15 consecutive days:

1. Architecture diagram Copilot-centric labels
2. how-they-work.mdx missing Gemini
3. ANTHROPIC_API_KEY URL verification
4. creating-workflows.mdx Web Interface Copilot gate

These are all small fixes. Resolving them would likely push the score to 8/10. Consider assigning these as tracked issues to ensure they don't remain open indefinitely.

---

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/auth.mdx
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/setup/creating-workflows.mdx
• .github/workflows/*.md (167 files, engine distribution analysis)

---

References:

• §23026994242

AI generated by Claude Code User Documentation Review · history

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