Revamp docs to Elastic Agent Factory

[strawgate]

And highlight top recommended workflows for improving quality, simplifying repo operations, etc

[github-actions]

Highly related (separate issues that significantly overlap or share scope):

• Split docs into Human-Coordinated, Event Driven, and Scheduled #325 — This issue also asks for restructuring workflow documentation categories, while this issue is focused on a broader revamp centered on Elastic Agent Factory guidance and recommended workflows.
  More detail

  Both requests target documentation organization for workflow discovery. Split docs into Human-Coordinated, Event Driven, and Scheduled #325 is specifically about splitting docs into Human-Coordinated, Event Driven, and Scheduled sections, whereas this issue emphasizes presenting Elastic Agent Factory and highlighting top recommended workflows.
• Split workflows in readme #127 — This issue overlaps on separating human-coordinated workflows from agent-factory/continuous-improvement workflows, which is closely aligned with the revamp direction in this issue.
  More detail

  Split workflows in readme #127 was completed and implemented an earlier docs split in README/workflow docs; this issue appears to continue that same area with an updated emphasis on Elastic Agent Factory and recommendation highlights.
• Workflows missing from docs nav #234 — This issue addressed missing workflow discoverability in docs navigation, which overlaps with this issue’s goal of improving how workflows are presented.
  More detail

  Workflows missing from docs nav #234 focused on missing entries in nav/table coverage, while this issue is a broader content/positioning refresh around agent-factory workflows and recommended usage.

---

What is this? | From workflow: Duplicate Issue Detector

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[github-actions]

tl;dr: I recommend treating this as a docs IA + branding pass (not a code/workflow change): rename the primary docs path to Elastic Agent Factory, keep Claude under Legacy, and add a "recommended starter set" + "quality improvement packs" section anchored to the existing quick-setup defaults.

Recommendation

Implement issue #333 as a focused documentation revamp across README.md, docs/index.md, and docs/workflows/gh-agent-workflows.md:

1. Rename the primary docs surface from “GitHub Agent Workflows” to Elastic Agent Factory (with “GitHub Agent Workflows” retained in copy for continuity/search).
2. Keep docs/workflows/claude-workflows.md explicitly in a Legacy section.
3. Add opinionated recommendations for two adoption tiers:
   • Starter repo ops set (current quick-setup defaults)
   • Continuous improvement packs (quality/simplification workflows)

Findings

• Current positioning already favors GitHub Agent Workflows and labels Claude as legacy:
  • README.md:9-10, README.md:19-20
  • docs/index.md:16, docs/index.md:22-24
• Site nav still uses “GitHub Agent Workflows” under Workflows (good migration anchor for a rename):
  • mkdocs.yml:13-16, mkdocs.yml:52-53
• The docs/workflow taxonomy work is already active and related to this request:
  • Split docs into Human-Coordinated, Event Driven, and Scheduled #325 (open): split into Human-Coordinated/Event-Driven/Scheduled
  • Link to workflow file in docs #324 (open) + PR Link workflow source file in generated docs pages #331 (open): add workflow source links in generated docs pages
  • Split workflows in readme #127 (closed) + PR Split workflow tables by type #131 (merged): prior workflow-table split by type
  • Focus the docs on gh-aw workflows and put in a legacy section for Claude #276 (closed): focus docs on gh-aw and move Claude to legacy
• Recommended workflow sets already exist in one place and can be reused verbatim:
  • scripts/quick-setup.sh:121-127 default starter set (pr-review, issue-triage, mention-in-issue, mention-in-pr, pr-actions-detective)
  • scripts/quick-setup.sh:128-140 continuous-improvement list (bug-hunter, bug-exterminator, code-simplifier, docs-patrol, ...)

Verification

I verified trigger-type distribution and docs/build constraints locally.

$ grep -R -nE "^on:|^  (issues|issue_comment|pull_request|workflow_run|schedule|workflow_dispatch):" gh-agent-workflows/*/example.yml | head -20
gh-agent-workflows/agent-suggestions/example.yml:2:on:
gh-agent-workflows/agent-suggestions/example.yml:3:  schedule:
gh-agent-workflows/agent-suggestions/example.yml:5:  workflow_dispatch:
...
gh-agent-workflows/docs-pr-review/example.yml:2:on:
gh-agent-workflows/docs-pr-review/example.yml:3:  issue_comment:
...
gh-agent-workflows/issue-triage/example.yml:2:on:
gh-agent-workflows/issue-triage/example.yml:3:  issues:

$ mkdocs build -q
bash: mkdocs: command not found

$ make docs-build
make: uv: No such file or directory
make: *** [Makefile:192: docs-install] Error 127

So I could validate source structure and triggers, but not run MkDocs build in this runtime due missing tooling.

Detailed Action Plan

1. Reframe top-level docs language to “Elastic Agent Factory”

   • Update README.md and docs/index.md headings/lead paragraphs.
   • Keep “GitHub Agent Workflows” in body text as an alias during transition (avoid breaking search/discovery).

2. Add explicit recommendation tiers using existing workflow sets

   • In docs/index.md and docs/workflows/gh-agent-workflows.md, add:
     • Recommended starter set (from scripts/quick-setup.sh:121-127)
     • Quality/simplification add-ons (from scripts/quick-setup.sh:128-140)
   • Include one-line “why/when to use” per workflow cluster (quality, docs freshness, simplification, bug loop).

3. Align taxonomy with Split docs into Human-Coordinated, Event Driven, and Scheduled #325 while doing the revamp

   • In docs/workflows/gh-agent-workflows.md, split tables by:
     • Human-coordinated
     • Event-driven
     • Scheduled
   • Mirror category labels in mkdocs.yml nav so docs structure and page content match.

4. Preserve and clarify Legacy section

   • Keep docs/workflows/claude-workflows.md in nav under Legacy.
   • Add short migration note from legacy Claude actions to Elastic Agent Factory style setup.

5. Cross-link to workflow prompt source after Link workflow source file in generated docs pages #331 lands

   • Once PR Link workflow source file in generated docs pages #331 merges, ensure the revamped pages mention that each generated workflow page links directly to .github/workflows/gh-aw-*.md source prompts.

6. Validation

   • Run make docs-build in a dev environment with uv installed.
   • Spot-check nav and generated workflow pages for broken links and category consistency.

Related Items

Type	Item	Relevance
Issue	#333	Current request
Issue	#325	Active taxonomy split request (Human/Event/Scheduled)
Issue	#324	Source-link discoverability for workflow docs
PR	#331 (open)	Implements generated docs links to workflow source files
Issue	#127 (closed)	Earlier “split workflows in readme” direction
PR	#131 (merged)	Prior table split implementation
Issue	#276 (closed)	Earlier shift to gh-aw-first + Claude legacy
File	docs/index.md:16-24	Current recommended + legacy framing
File	docs/workflows/gh-agent-workflows.md:37-85	Current workflow taxonomy tables
File	mkdocs.yml:13-53	Current docs nav structure
File	scripts/quick-setup.sh:121-140	Canonical recommended workflow sets

---

What is this? | From workflow: Issue Triage

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

/ai let's make a pr

[github-actions]

Opened a draft PR with the docs revamp for this issue.

What changed

• Reframed docs to Elastic Agent Factory (GitHub Agent Workflows) in:
  • README.md
  • docs/index.md
  • docs/workflows/gh-agent-workflows.md
  • mkdocs.yml nav label
• Added explicit Top recommended workflows sections covering:
  • Starter repo operations set (pr-review, issue-triage, mention-in-issue, mention-in-pr, pr-actions-detective)
  • Continuous improvement add-ons (including bug-hunter, bug-exterminator, code-simplifier, docs-patrol, test-improver, etc.)
• Kept Claude path positioned as Legacy.

Validation

• Ran make docs-build.
• Result: failed in this runtime due missing dependency (uv not installed), so MkDocs build could not be executed here.

---

What is this? | From workflow: Mention in Issue

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.