[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-04-03

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and avoids GitHub Copilot entirely, I reviewed the gh-aw documentation for the fifth consecutive day. The docs have matured into a multi-engine-friendly resource: Quick Start, Auth, and Engines pages all treat Claude as a first-class option. No critical blockers exist for Claude Code users. However, five persistent minor issues remain unresolved for a second or fifth consecutive day — the same set identified in previous runs, with no new issues and no fixes.

Key Finding: Claude Code users can successfully adopt gh-aw today. The onboarding path is clear, authentication is documented, and 35 example workflows use engine: claude. The five open issues are low-severity but are accumulating days without resolution.

---

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 minor friction. The Quick Start (docs/src/content/docs/setup/quick-start.mdx) now clearly lists "Anthropic Claude" as a supported AI Account in prerequisites. The gh aw add-wizard step explicitly mentions choosing between Copilot, Claude, or Codex, and references ANTHROPIC_API_KEY alongside the Copilot token. The How They Work page (docs/src/content/docs/introduction/how-they-work.mdx) states: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." — clear and engine-neutral.

Specific Issues Found:

• Issue 1 (docs/src/content/docs/setup/quick-start.mdx, line 29): Prerequisites list "GitHub Copilot, Anthropic Claude or OpenAI Codex" — Gemini is missing as the 4th supported engine (persists since day 1).
• Issue 2 (docs/src/content/docs/setup/quick-start.mdx, line 68): add-wizard description says "Choose between Copilot, Claude, or Codex" — Gemini omitted again (persists since day 1).

Recommended Fixes:

• Add "or Google Gemini" to both Quick Start mentions of supported engines.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Only one feature is genuinely Copilot-exclusive: the assign-to-agent safe output (docs/src/content/docs/reference/assign-to-copilot.mdx) — which programmatically assigns the Copilot coding agent to issues/PRs. This is clearly documented as Copilot-specific and makes logical sense given it's a Copilot product feature.

Features That Require Copilot:

• assign-to-agent safe output (assigning GitHub Copilot coding agent to issues/PRs)
• engine.agent custom agent files (Copilot-only per engines.md feature table)
• max-continuations autopilot mode (Copilot-only)
• COPILOT_GITHUB_TOKEN (only needed for Copilot engine)

Features That Work Without Copilot:

• All other safe outputs (create-issue, add-comment, create-pull-request, add-labels)
• All tools (edit, bash, web-fetch, playwright, cache-memory, repo-memory, github, qmd)
• MCP server integrations
• Compilation, validation, gh aw CLI commands
• Security architecture (firewalls, sandboxing, threat detection)
• max-turns (Claude-only feature, a Claude advantage)

Missing Documentation:

• No explicit "what changes for Claude vs Copilot users" comparison page — though the engines.md feature table fills this role adequately.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

The docs have largely moved past Copilot-only assumptions. A few residual areas:

Copilot-Centric Language Found In:

• File: docs/src/content/docs/introduction/architecture.mdx, lines 181 and 252 — AWF Firewall diagram labels the agent process as "Copilot CLI". Claude users reading the security architecture see their engine misrepresented in the diagram.
• File: docs/src/content/docs/reference/custom-agent-for-aw.mdx — Entire page titled "Copilot Agent Files support for Agentic Workflows" with no equivalent Claude Code integration guide.
• File: docs/src/content/docs/guides/web-search.md, line 17 — Only example uses engine: copilot; no Claude MCP web search example shown.

Missing Alternative Instructions:

• No guide showing Claude users how to set up web search via MCP (the web-search.md guide only shows a Copilot workflow).
• No "Claude Code as your authoring tool for gh-aw" equivalent to the Copilot Agent Files guide.

---

Severity-Categorized Findings

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

No critical blockers found. Claude Code users can complete a full onboarding flow without Copilot.

⚠️ Major Obstacles (Score: 1)

Obstacle 1: ANTHROPIC_API_KEY Setup URL Is Incorrect (Day 5)

Impact: User follows auth setup link and lands on a docs overview page instead of the API key creation page.

Current State: docs/src/content/docs/reference/auth.mdx, line 103:

1. Create an API key at (platform.claude.com/redacted)
```

**Why It's Problematic:** `platform.claude.com/docs/en/get-started` is a documentation landing page, not the API key management console. Users expecting a direct link to key creation must navigate further. The equivalent Copilot link uses a pre-filled token creation URL. Claude users get a less direct experience.

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

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

</details>

#### 💡 Minor Confusion Points (Score: 4 active issues)

- **Issue 1 (Day 5):** Quick Start prerequisites missing Gemini engine — File: `docs/src/content/docs/setup/quick-start.mdx` line 29
- **Issue 2 (Day 5):** `add-wizard` description missing Gemini engine — File: `docs/src/content/docs/setup/quick-start.mdx` line 68
- **Issue 3 (Day 5):** Web search guide `engine: copilot` only, no Claude example — File: `docs/src/content/docs/guides/web-search.md` line 17
- **Issue 4 (Day 5):** `engines.md` Claude link points to `anthropic.com/index/claude` (potentially stale URL) — File: `docs/src/content/docs/reference/engines.md` line 17
- **Issue 5 (Day 2):** AWF firewall architecture diagram labels agent as "Copilot CLI" — File: `docs/src/content/docs/introduction/architecture.mdx` lines 181, 252

---

### Engine Comparison Analysis

#### Available Engines

- `engine: copilot` — Default engine; most documentation examples use this; well-documented
- `engine: claude` — Clearly documented; 35 example workflows; first-class treatment in Quick Start and Auth
- `engine: codex` — Documented; 17 example workflows; web-search opt-in behavior explicitly noted
- `engine: gemini` — Documented in engines.md and auth.mdx but absent from Quick Start prerequisites; 0 example workflows in this repo

#### Documentation Quality by Engine

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

---

### Tool Availability Analysis

#### Tools Review

**Engine-Agnostic Tools (work with any engine):**
- `edit:`, `bash:`, `web-fetch:`, `playwright:`, `cache-memory:`, `repo-memory:`, `qmd:`, `github:`, `agentic-workflows:`, all custom MCP servers

**Engine-Specific Tools:**
- `tools.web-search`: Codex supports natively; all others require third-party MCP server
- `engine.agent`: Copilot only (custom agent files)
- `max-turns`: Claude only
- `max-continuations`: Copilot only

**Unclear/Undocumented:**
- No tool compatibility gaps identified beyond those in the feature table.

---

### Authentication Requirements

#### Current Documentation

Quick Start guide covers authentication for:
- ✅ Copilot (detailed instructions with pre-filled token creation link)
- ✅ Claude (found; link goes to docs page not direct key console — see major obstacle above)
- ✅ Codex (found; links to `platform.openai.com/api-keys`)
- ✅ Gemini (found in auth.mdx; missing from Quick Start prerequisites)

#### Secret Names

- Copilot: `COPILOT_GITHUB_TOKEN` (documented)
- Claude: `ANTHROPIC_API_KEY` (documented)
- Codex: `OPENAI_API_KEY` (documented)
- Gemini: `GEMINI_API_KEY` (documented in auth.mdx)

---

### Example Workflow Analysis

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

```
engine: claude   — 35 workflows
engine: copilot  — 90 workflows (explicit)
engine: (none)   — 25 workflows (defaults to copilot)
engine: codex    — 17 workflows
engine: gemini   — 0 workflows

Note: Claude workflow count decreased by 2 from yesterday (35 vs 37). Likely due to normal workflow maintenance/refactoring rather than a concern.

Quality of Examples

Copilot Examples: Extensive coverage across a wide variety of use cases. Most community workflows default to Copilot.

Claude Examples: Good variety — includes audit-workflows.md, blog-auditor.md, claude-code-user-docs-review.md, claude-token-optimizer.md, daily-doc-healer.md, daily-doc-updater.md, and more. Sufficient for a Claude user to find relevant templates.

---

Recommended Actions

Priority 1: Quick Fix (< 30 min)

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 103. Day 5 unresolved.
2. Add Gemini to Quick Start — Add "or Google Gemini" to prerequisites line 29 and add-wizard description line 68 in docs/src/content/docs/setup/quick-start.mdx. Day 5 unresolved.
3. Fix architecture diagram labels — Rename "Copilot CLI" to "AI Agent" in docs/src/content/docs/introduction/architecture.mdx lines 181 and 252. Day 2 unresolved.

Priority 2: Low-Effort Improvements

1. Update Claude engine URL — Verify/update anthropic.com/index/claude in docs/src/content/docs/reference/engines.md line 17. Day 5 unresolved.
2. Add Claude example to web search guide — Add a engine: claude variant to docs/src/content/docs/guides/web-search.md. Day 5 unresolved.

Priority 3: Nice-to-Have

1. Add a "Using Claude Code to author gh-aw workflows" guide — Equivalent to the Copilot Agent Files guide but for Claude Code users using Claude Code CLI.
2. Add Gemini example workflows — Currently 0 Gemini workflows exist as examples.

---

Positive Findings

What Works Well

• ✅ Quick Start explicitly names Claude as a supported engine in prerequisites
• ✅ gh aw add-wizard handles Claude engine selection interactively end-to-end
• ✅ Authentication docs (auth.mdx) give Claude equal treatment alongside Copilot
• ✅ Engines.md has a clear feature parity table showing what Claude supports
• ✅ 35 real engine: claude workflows exist as reference material
• ✅ "Self-Contained Debugging (Without Copilot)" section is explicitly non-Copilot-friendly
• ✅ Architecture is genuinely engine-agnostic (all engines run through the same AWF/MCP/SafeOutputs pipeline)
• ✅ gh aw init, gh aw new --engine claude, and gh aw secrets bootstrap all support Claude natively
• ✅ max-turns is a Claude-exclusive feature that gives Claude users a unique capability

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes

The documentation gives Claude Code users a complete path from zero to running their first workflow. The Quick Start is engine-inclusive, authentication is documented, and there are enough Claude engine workflow examples to learn from. The five open issues are real but none rises to a critical blocker — they represent polish opportunities rather than adoption barriers.

The most actionable item remains the ANTHROPIC_API_KEY URL fix (Priority 1, < 5 min change) which has now been open for 5 days.

Overall Assessment Score: 8/10 (unchanged)

Breakdown:

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

Trend

Date	Score	Blockers	Major	Minor	Fixed
2026-03-30	8/10	0	1	4	—
2026-03-31	8/10	0	1	4	0
2026-04-01	8/10	0	1	4	0
2026-04-02	8/10	0	1	5	0
2026-04-03	8/10	0	1	5	0

Score is stable. No regressions detected. No issues have been fixed across 5 days of tracking.

---

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/custom-agent-for-aw.mdx
• docs/src/content/docs/reference/assign-to-copilot.mdx
• docs/src/content/docs/guides/web-search.md
• .github/workflows/*.md (183 workflows surveyed, engine distribution analyzed)

---

References:

• §23947386706

AI generated by Claude Code User Documentation Review · history

• expires on Apr 4, 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 #24491.