Skip to content

README as landing page, practitioner docs, changelog, and repo health signals - #87

Merged
stempeck merged 1 commit into
mainfrom
visibility/readme-docs-health
Jul 12, 2026
Merged

README as landing page, practitioner docs, changelog, and repo health signals#87
stempeck merged 1 commit into
mainfrom
visibility/readme-docs-health

Conversation

@stempeck

Copy link
Copy Markdown
Owner

Executes the Tier A repo-content phases of the visibility plan.

What changed

  • README.md — restructured as an indexable landing page: prose "Why agentfactory" opening, CI/Go/license/release badges, native Mermaid architecture diagram (skills → formulas → agents → sessions), an honest comparison table vs LangGraph/CrewAI/raw subagents, roadmap section linking real issues, author line. Formula table now reflects the 19 shipped formulas (was 5). Removed the manual .gitignore instruction — af install --init already writes .git/info/exclude.
  • docs/formulas.md, docs/agent-lifecycle.md, docs/recovery-model.md — short practitioner pages, every command verified against internal/cmd/; cross-linked with each other and docs/architecture/.
  • CHANGELOG.md — seeded from the full PR history, grouped by theme, for the upcoming v0.1.0 release.
  • Issue templates — standard bug/feature templates alongside the existing agent-dispatch default.
  • .github/workflows/visibility-health.yml — monthly watchdog: verifies topics, description, release presence, and README badges; opens one issue on regression, never commits.

Verification

  • Docs commands cross-checked against CLI source by a dedicated verification pass (one invented gate type caught and removed before commit).
  • Markdown/workflow changes only — no Go code touched; make test not applicable.

🤖 Generated with Claude Code

… signals

- README: indexable prose opening, badges, Mermaid architecture diagram,
  honest comparison table (LangGraph/CrewAI/subagents), roadmap, author
  line; formula table updated to the 19 shipped formulas; stale manual
  .gitignore instruction replaced (install --init writes .git/info/exclude)
- docs/: formulas reference, agent lifecycle, recovery model — practitioner
  pages grounded in internal/formula, internal/session, internal/checkpoint
- CHANGELOG.md seeded from git history for the v0.1.0 release
- Issue templates: bug report + feature request alongside the agent-dispatch
  default
- visibility-health.yml: monthly check that topics/description/release/
  badges haven't regressed; opens a single issue on regression

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@stempeck
stempeck merged commit 70c015a into main Jul 12, 2026
7 checks passed
@stempeck
stempeck deleted the visibility/readme-docs-health branch July 12, 2026 01:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant