Skip to content

docs: bullet-ize README hero; align platform README with new framing#8

Merged
mandarnilange merged 2 commits intomainfrom
docs/messaging-bullets-platform-align
May 1, 2026
Merged

docs: bullet-ize README hero; align platform README with new framing#8
mandarnilange merged 2 commits intomainfrom
docs/messaging-bullets-platform-align

Conversation

@mandarnilange
Copy link
Copy Markdown
Owner

Summary

Two follow-up improvements after the BYO-framework messaging revamp (#7):

  1. Main README hero — the dense paragraph after the headline was a wall of text. Replaced it with five scannable bullets organized around the verbs that carry the pitch.
  2. Platform README — was still positioned generically; now ties to the new "open framework for agentic workflows" story and makes the BYO framing explicit.

Main README — before / after

Before (one paragraph, 5 ideas mashed together):

Compose agent harnesses in YAML from LLM calls, scripts, validators, and transforms — wired with loops and conditionals. Mix deterministic and non-deterministic steps so your linter, tests, and schemas gate the LLM. Built-in support for Anthropic / OpenAI / Gemini / Ollama, coding-agent runtimes, SQLite / Postgres, OTel, and local / Docker / remote workers. Every layer has an extension point where the built-in doesn't fit. Scale agentic workflows like production infrastructure.

After (parallel-structure bullets, each ~12–15 words):

  • Compose agent harnesses in YAML — LLM calls, scripts, validators, transforms, loops, and conditionals.
  • Gate the LLM with your tools — deterministic steps (linters, tests, schemas) wrap non-deterministic LLM calls, so output is checked on every run.
  • Plug in your stack — Anthropic, OpenAI, Gemini, Ollama, coding-agent runtimes. Every layer has an extension point where the built-in doesn't fit.
  • Run anywhere — local, Docker, or remote workers; SQLite or Postgres; OTel-native.
  • Scale like infra — multi-worker scheduling, approval gates, cost ceilings, live dashboard.

The bold one-liner hero and the "For platform teams" K8s callout are unchanged.

Platform README — before / after

Before:

Production infrastructure for AgentForge. Distributed execution, PostgreSQL, full observability, crash recovery.

Extends @mandarnilange/agentforge-core with everything needed to run AI agent workflows at scale — Docker/remote executors, PostgreSQL persistence, OpenTelemetry tracing, rate limiting, and multi-node worker scheduling.

After:

Production infrastructure for AgentForge. Run agentic workflows at scale — distributed execution, PostgreSQL, full observability, crash recovery.

Extends @mandarnilange/agentforge-core — the open framework for agentic workflows — with everything needed to run it at scale: Docker / remote executors, PostgreSQL persistence, OpenTelemetry tracing, rate limiting, and multi-node worker scheduling. Bring your own LLMs, scripts, agents, and infra; this package handles the orchestration plane.

Aligns with the core README so a reader landing on either npm page gets a consistent story.

What was not changed

Test plan

  • README hero renders cleanly on GitHub (bullet alignment, no orphaned bold)
  • Platform README renders cleanly on GitHub
  • Both READMEs ship with the next npm publish (descriptions don't update retroactively)

Main README:
- Replace the dense paragraph after the hero with five scannable bullets
  organized around the verbs that carry the pitch: Compose, Gate, Plug in,
  Run anywhere, Scale.
- Tighten the trailing "domain-agnostic" line.
- Hero one-liner and "For platform teams" K8s callout unchanged.

Platform README:
- Tie the lead to the new framework story ("Run agentic workflows at
  scale") and reference core as "the open framework for agentic workflows".
- Make the BYO framing explicit: bring your own LLMs, scripts, agents,
  and infra; this package handles the orchestration plane.
Add a Kubernetes analogy in two places where platform engineers will
expect it and the analogy is genuinely load-bearing:

1. Lead paragraph (visible on npmjs.com) — closing phrase identifies
   the package as the "Kubernetes-style orchestration plane underneath"
   with control plane + capability-scheduled workers.

2. Architecture section — one-paragraph preamble explaining the
   control-plane / execution-plane separation, capability-based
   nodeAffinity scheduling, and the deployment topology.

Audience is platform teams; the analogy teaches the design rather
than serving as a marketing line. Hero one-liner stays clean.
@mandarnilange mandarnilange merged commit 5e4f341 into main May 1, 2026
4 checks passed
@mandarnilange mandarnilange deleted the docs/messaging-bullets-platform-align branch May 1, 2026 17:10
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