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

[github-actions[bot]]

Executive Summary

Reviewed gh-aw documentation from the perspective of a developer who uses Claude Code as their primary AI assistant and has no GitHub Copilot subscription. The good news: Claude Code users can fully adopt gh-aw — there are zero critical blockers, authentication is well-documented for Claude, and 39 real-world Claude engine workflow examples exist in the repo. However, three persistent documentation issues (now flagged across 3–4 consecutive weekly reviews) continue to create friction and confusion.

Key Finding: Claude users can get started successfully, but must navigate Copilot-centric language and a few misleading diagrams. The same three issues remain unfixed from the previous four review runs.

Trend: Stable at 7.5/10. One positive change this run: Gemini was added as a 4th supported engine in engines.md and auth.mdx — but this addition exposed a new consistency gap (quick-start and how-they-work don't mention Gemini yet).

---

Persona Context

Documentation 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 a Copilot subscription

---

Question 1: Onboarding Experience

Can a Claude Code user understand and get started with gh-aw?

Yes — and the quick start is impressively inclusive. The prerequisites section (quick-start.mdx:29) explicitly lists all AI options: "GitHub Copilot, Anthropic Claude or OpenAI Codex." The add-wizard step 2 provides a menu to choose between engines. Authentication is fully documented per-engine in auth.mdx.

The workflow is:

1. Install gh extension install github/gh-aw ✅
2. Run gh aw add-wizard githubnext/agentics/daily-repo-status ✅
3. Select Claude engine when prompted ✅
4. Set ANTHROPIC_API_KEY secret ✅ (documented in auth.mdx)
5. Get the workflow running ✅

Specific Issues Found:

• quick-start.mdx:68: Step 2 says "Choose between Copilot, Claude, or Codex" — Gemini is now a supported engine but isn't listed here. Minor, but inconsistent with engines.md.
• how-they-work.mdx:26: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." — Gemini is missing from this introductory statement despite being in engines.md.

Recommended Fixes:

• Update quick-start.mdx step 2 text to include Gemini alongside Copilot, Claude, and Codex
• Update how-they-work.mdx:26 to add Gemini to the engines list

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features that genuinely require Copilot:

• engine.agent (custom agent files in .github/agents/) — documented as Copilot-only in engines.md feature comparison table ✅ well-documented
• max-continuations (autopilot mode) — documented as Copilot-only ✅
• COPILOT_GITHUB_TOKEN — requires an active Copilot subscription ✅ clearly noted

Features that work with any engine (including Claude):

• All built-in tools: edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows
• Custom MCP servers — engine-agnostic ✅
• Safe outputs — engine-agnostic ✅
• Network firewall (AWF) — engine-agnostic ✅
• All triggers, permissions, scheduling — engine-agnostic ✅
• max-turns — Claude-only (not available for other engines)

Missing Documentation:

• architecture.mdx AWF section: the "Configuration Example" only shows engine: copilot. There is no note that the same configuration applies identically to Claude, Codex, and Gemini. A non-Copilot user might assume the firewall is Copilot-specific.

---

Question 3: Documentation Gaps and Assumptions

Where does documentation assume Copilot usage?

Copilot-centric language found in:

• architecture.mdx (AWF diagram, line ~177): The AI agent process is labeled COPILOT["Copilot CLI"] — this is inside a generic diagram titled "AI Agent Process" that should represent any engine
• architecture.mdx (AWF config example): Uses engine: copilot as the only configuration example without noting it applies to all engines
• how-they-work.mdx:26: Omits Gemini from the supported engines list
• quick-start.mdx:68: Omits Gemini from engine selection prompt description

Missing Alternative Instructions:

• architecture.mdx AWF diagram should show ENGINE["AI Engine\n(Copilot / Claude / Codex / Gemini)"] or similar generic label
• The "Configuration Example" in the AWF section should either use a generic/multi-engine example or add a note like "Replace copilot with claude, codex, or gemini as needed"

---

Severity-Categorized Findings

🚫 Critical Blockers: 0

No critical blockers were found. Claude users can adopt gh-aw without any hard dependencies on Copilot.

⚠️ Major Obstacles: 3

Obstacle 1: AWF Architecture Diagram Labels Agent as "Copilot CLI" (4th consecutive review)

Impact: A Claude user reading the architecture documentation will see the AI Agent box labeled as "Copilot CLI" — a Copilot-specific product they don't use and don't want. This creates confusion about whether the security architecture applies to them.

Current State (architecture.mdx lines ~174–179):

subgraph Agent["AI Agent Process"]
    COPILOT["Copilot CLI"]
    WEB["WebFetch Tool"]
    SEARCH["WebSearch Tool"]
end
```

**Why It's Problematic:** The agent diagram node is named `COPILOT` and labeled `"Copilot CLI"` inside what is supposed to be a generic security architecture diagram. This is visually presented as the only option.

**Suggested Fix:** Rename the node to show all supported engines:
```
subgraph Agent["AI Agent Process"]
    ENGINE["AI Engine\n(Copilot CLI / Claude Code\n/ Codex CLI / Gemini CLI)"]
    WEB["WebFetch Tool"]
    SEARCH["WebSearch Tool"]
end
```

**Affected File:** `docs/src/content/docs/introduction/architecture.mdx` (~line 177)

**Persistence:** Flagged in 4 consecutive review runs (2026-03-18 through 2026-03-24). No change made.

</details>

<details>
<summary><b>Obstacle 2: how-they-work.mdx Omits Gemini from Engine List (3rd consecutive review)</b></summary>

**Impact:** The "How They Work" page is the primary conceptual introduction to gh-aw. It lists the supported AI engines but omits Gemini, which was added to `engines.md` and `auth.mdx`. This is now an internal inconsistency.

**Current State** (`how-they-work.mdx:26`):
> "Workflows support **GitHub Copilot** (default), **Claude by Anthropic**, and **Codex**."

**Why It's Problematic:** Gemini users and Claude users reading this page get an incomplete picture. The same page links to the engines reference which does list Gemini, but the introductory statement is factually incomplete.

**Suggested Fix:**
> "Workflows support **GitHub Copilot** (default), **Claude by Anthropic**, **Codex**, and **Gemini**."

**Affected File:** `docs/src/content/docs/introduction/how-they-work.mdx` (line 26)

**Persistence:** Flagged in 3 consecutive review runs (2026-03-19 through 2026-03-24). No change made.

</details>

<details>
<summary><b>Obstacle 3: ANTHROPIC_API_KEY Setup Links to Docs Page Instead of API Console (4th consecutive review)</b></summary>

**Impact:** When a Claude user follows the authentication setup instructions, they click a link that takes them to a documentation "get started" page rather than directly to the API key creation interface. This adds an unnecessary step and may confuse users unfamiliar with the Anthropic platform.

**Current State** (`auth.mdx` ANTHROPIC_API_KEY section):
```
1. Create an API key at (platform.claude.com/redacted)
```

**Why It's Problematic:** The URL points to a documentation landing page. To create an API key, users need to navigate to `https://console.anthropic.com/settings/keys`. The Copilot section has a direct pre-filled link that creates the token with the right permissions — Claude users get a docs page.

**Suggested Fix:** Link directly to the API key creation page:
```
1. Create an API key at https://console.anthropic.com/settings/keys
```

**Affected File:** `docs/src/content/docs/reference/auth.mdx` (ANTHROPIC_API_KEY section)

**Persistence:** Flagged in 4 consecutive review runs (2026-03-18 through 2026-03-24). No change made.

</details>

#### 💡 Minor Confusion Points: 3

- **AWF config examples use `engine: copilot`**: `architecture.mdx` shows only Copilot in the "Configuration Example" block — File: `architecture.mdx`
- **Quick start omits Gemini**: `quick-start.mdx:68` step 2 says "Choose between Copilot, Claude, or Codex" — Gemini was recently added but this wasn't updated — File: `quick-start.mdx`
- **`copilot-custom-agents.md` title**: The page title and framing implies Copilot exclusivity; `engine.agent` is Copilot-only but the page name confuses users about whether it contains anything relevant to them — File: `reference/copilot-custom-agents.md`

---

### Engine Comparison Analysis

#### Available Engines (current state in `engines.md`)

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

**Rating Scale:** ⭐⭐⭐⭐⭐ Excellent → ⭐ Poor/Missing

**Notes:**
- Claude docs rating ⭐⭐⭐⭐ (not ⭐⭐⭐⭐⭐) due to the persistent auth URL issue and 39 real-world workflow examples vs 109 for Copilot
- Gemini examples rating ⭐ — virtually no example workflows in `.github/workflows/` using `engine: gemini` despite being added to the reference docs
- `engines.md` feature comparison table is excellent — clearly shows what each engine supports

---

### Tool Availability Analysis

#### Engine-Agnostic Tools (work with Claude, Copilot, Codex, Gemini)
- `edit:` — file editing
- `github:` — GitHub API operations (local and remote modes)
- `bash:` — shell command execution
- `web-fetch:` — web content fetching
- `playwright:` — browser automation
- `cache-memory:` — persistent cross-run memory
- `repo-memory:` — repository-specific memory
- `qmd:` — documentation search
- `agentic-workflows:` — workflow introspection
- Custom MCP servers — fully engine-agnostic

#### Engine-Specific Tools/Features
- `engine.agent` (custom agent file) — **Copilot only**, clearly documented
- `max-continuations` — **Copilot only**, clearly documented
- `max-turns` — **Claude only**, clearly documented
- `web-search:` via MCP — all engines; Codex has native opt-in support

#### Well-Documented Tool Compatibility
The `engines.md` feature comparison table is thorough and accurate — this is a strength for Claude users trying to understand what they can use.

---

### Authentication Requirements

#### Current Documentation Status

| Engine | Secret Name | Setup Instructions | Direct Link to Key Creation |
|--------|-------------|-------------------|----------------------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Detailed with pre-filled PAT creation link | ✅ Yes |
| Claude | `ANTHROPIC_API_KEY` | ✅ Present but links to docs page | ❌ Links to docs, not console |
| Codex | `OPENAI_API_KEY` | ✅ Direct link to API key page | ✅ Yes |
| Gemini | `GEMINI_API_KEY` | ✅ Direct link to AI Studio | ✅ Yes |

**Note:** The Copilot section has an exemplary pre-filled link that sets the token name, description, and permissions automatically. The Claude and Gemini sections would benefit from a similar direct-to-action approach.

---

### Workflow Example Analysis

#### Count by Engine (`.github/workflows/*.md`)

```
Engine: copilot  → 109 workflows (65%)
Engine: claude   →  39 workflows (23%)
Engine: codex    →  19 workflows (11%)
Engine: custom   →   1 workflow  (<1%)
Engine: gemini   →   0 workflows (0%)  ← no examples despite engine being documented

Claude Engine Examples — Quality Assessment

39 real-world Claude engine workflow examples exist. Notable examples:

• safe-output-health.md — monitoring safe output operations
• go-fan.md — Go module dependency analysis
• daily-code-metrics.md — code quality metrics
• static-analysis-report.md — static analysis automation
• audit-workflows.md — workflow auditing
• claude-code-user-docs-review.md — this very workflow 🐕

Assessment: The 39 examples provide excellent real-world reference material for Claude users. They demonstrate diverse use cases: reporting, analysis, documentation maintenance, CI monitoring. Quality is high.

Gap: Zero Gemini workflow examples exist in the codebase, despite Gemini being added to the reference docs. New adopters of the Gemini engine have no examples to learn from.

---

Recommended Actions

Priority 1: Fix Persistent Issues (4 consecutive reviews)

1. Update AWF architecture diagram — Rename COPILOT["Copilot CLI"] to a generic engine label in architecture.mdx (~line 177). This is a one-line change that has been flagged 4 times.

2. Fix ANTHROPIC_API_KEY setup link — Change (platform.claude.com/redacted) to https://console.anthropic.com/settings/keys` in auth.mdx. This is a one-line change that has been flagged 4 times.

3. Add Gemini to how-they-work.mdx engine list — Update the introductory sentence at line 26 to include Gemini. One-line change flagged 3 times.

Priority 2: Consistency Updates (Gemini rollout)

4. Update quick-start.mdx step 2 — Add Gemini to "Choose between Copilot, Claude, or Codex" text at line 68.

5. Add Gemini workflow examples — Create at least one engine: gemini workflow in .github/workflows/ to demonstrate the engine works end-to-end.

6. Update AWF architecture config examples — Add a note to the "Configuration Example" blocks in architecture.mdx clarifying that engine: copilot is just an example and Claude/Codex/Gemini work identically.

Priority 3: Nice-to-Have Enhancements

7. Add "Why Claude instead of Copilot?" guidance — A short comparison or use-case guide for choosing between engines would help non-Copilot users feel welcome rather than like second-class citizens.

8. Standardize direct-to-action auth links — Mirror the Copilot PAT pre-filled link experience for Claude, Codex, and Gemini auth setup pages.

9. Add engine-specific troubleshooting sections — troubleshooting/common-issues.md likely focuses on Copilot errors; adding Claude-specific troubleshooting guidance would help.

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick start is genuinely engine-inclusive — prerequisites list all AI options; add-wizard provides interactive engine selection
• ✅ 39 real-world Claude engine examples — more than enough reference material for Claude users
• ✅ Authentication well-documented — auth.mdx has a dedicated, clearly structured ANTHROPIC_API_KEY section
• ✅ engines.md feature comparison table — excellent, honest comparison of what each engine supports
• ✅ gh aw new --engine claude — creates a Claude-specific workflow template immediately
• ✅ gh aw secrets bootstrap --engine claude — Claude-aware secret validation
• ✅ Tools are almost entirely engine-agnostic — all major tools (github, bash, playwright, MCP servers) work identically with Claude
• ✅ Engine parity for core functionality — Claude workflows can do everything Copilot workflows can do except max-continuations and custom agent files
• ✅ This very workflow (claude-code-user-docs-review.md) — runs on engine: claude, demonstrating real-world dogfooding

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction

The documentation has matured significantly in its multi-engine support. A Claude Code user can follow the quick start guide, select the Claude engine, set an ANTHROPIC_API_KEY, and have a working workflow in under 10 minutes. The 39 existing Claude engine examples provide excellent reference material.

The friction comes from three persistent documentation issues that have been flagged 3–4 consecutive times without being addressed: a mislabeled architecture diagram, a missing Gemini entry in the how-they-work introduction, and an auth link pointing to a docs page rather than the API console. None of these are blockers, but they create an impression of Copilot-centrism that may deter or frustrate non-Copilot users.

The recent addition of Gemini as a 4th supported engine is positive, but it created new consistency gaps (how-they-work still lists only 3 engines; quick-start still shows only 3 choices; zero Gemini workflow examples exist).

Overall Assessment: 7.5/10 (stable — 4th consecutive run at this score)

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

Next Steps

The three Priority 1 items are each single-line fixes that have been deferred for 3–4 review cycles. Addressing them would push the overall score to 8.5/10 and meaningfully reduce the Copilot-centric feel of the documentation.

---

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

---

References:

• §23491266305

AI generated by Claude Code User Documentation Review · history

• expires on Mar 25, 2026, 1:20 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 #22905.