From 0b3e7f211a2a912a38764fd9e1b00cefb72a626f Mon Sep 17 00:00:00 2001 From: cafitac Date: Mon, 27 Apr 2026 17:37:53 +0900 Subject: [PATCH] docs: tighten landing page and release framing --- CHANGELOG.md | 4 ++- README.md | 8 +++-- docs/open-source-positioning.md | 27 ++++++++++++++- docs/release-notes-template.md | 59 +++++++++++++++++++++++++++++++++ 4 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 docs/release-notes-template.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 33a4a9a..b66c013 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,9 +6,11 @@ - Refreshed the README opening section to position Hermit as a distinct open-source executor layer for Claude Code and Codex rather than a generic terminal UI. - Added a comparison section that explains why teams would pair Hermit with Claude Code or Codex instead of treating it as a replacement orchestrator. - Added explicit "who Hermit is for / not for" guidance so the landing page qualifies the intended audience instead of only describing features. -- Added a reusable `docs/open-source-positioning.md` copy deck for repository descriptions, social preview messaging, release framing, and audience-fit guidance. +- Added a reusable `docs/open-source-positioning.md` copy deck for repository descriptions, social preview messaging, release framing, audience-fit guidance, and topic candidates. - Added a final social-preview asset set: editable SVG, ready-to-upload PNG export, and a local review page under `docs/assets/` for GitHub/social-preview iteration. - Added `docs/social-preview-ops.md` so maintainers have a concrete review/export/upload checklist for the GitHub social preview image. +- Added `docs/release-notes-template.md` so release blurbs and GitHub Releases can reuse the same planner/executor positioning without improvising each time. +- Reordered the README badge row around release health and package availability, and tightened the hero copy so the landing page reads closer to the final social-preview message. - Updated package and repository-facing descriptions to emphasize the MCP executor + cheaper execution lane story instead of the outdated Codex-first fallback wording. - Tightened the public metadata around predictable local / flat-rate defaults so the repository pitch matches the current install and routing policy. diff --git a/README.md b/README.md index 9c5d1b2..8fecc88 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # HermitAgent +[![GitHub Release](https://img.shields.io/github/v/release/cafitac/hermit-agent?cacheSeconds=300)](https://github.com/cafitac/hermit-agent/releases) [![Python tests](https://github.com/cafitac/hermit-agent/actions/workflows/python-tests.yml/badge.svg)](https://github.com/cafitac/hermit-agent/actions/workflows/python-tests.yml) [![npm version](https://img.shields.io/npm/v/@cafitac/hermit-agent?cacheSeconds=300)](https://www.npmjs.com/package/@cafitac/hermit-agent) [![PyPI version](https://img.shields.io/pypi/v/cafitac-hermit-agent?cacheSeconds=300)](https://pypi.org/project/cafitac-hermit-agent/) -[![npm downloads](https://img.shields.io/npm/dm/@cafitac/hermit-agent?cacheSeconds=300)](https://www.npmjs.com/package/@cafitac/hermit-agent) +[![License: MIT](https://img.shields.io/badge/license-MIT-8b5cf6)](LICENSE) -> Hermit is the executor layer for Claude Code or Codex: keep the premium orchestrator for planning and review, and offload the repetitive coding work to cheaper local or flat-rate models. +> Hermit adds a dedicated MCP execution lane under Claude Code or Codex: keep the premium orchestrator for judgment, and route the repetitive repo work to predictable local or flat-rate models. ``` ┌──────────────┐ @@ -19,7 +20,7 @@ └──────────────┘ ``` -Claude Code or Codex stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on cheaper execution models. The switch is one word in a slash command: `/foo` → `/foo-hermit`. +Claude Code or Codex stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on predictable local or flat-rate execution models. The switch is one word in a slash command: `/foo` → `/foo-hermit`. Why Hermit stands out: - Keep your best reasoning model on the work that needs judgment, not boilerplate execution. @@ -161,6 +162,7 @@ MIT — see [LICENSE](LICENSE). - [docs/hermit-variants.md](docs/hermit-variants.md) — the `-hermit` skill family - [docs/measure-savings.md](docs/measure-savings.md) — cost-savings measurement protocol - [docs/open-source-positioning.md](docs/open-source-positioning.md) — short public-facing copy for descriptions, releases, and future social previews +- [docs/release-notes-template.md](docs/release-notes-template.md) — reusable release-note framing that matches Hermit's planner/executor positioning - [docs/social-preview-ops.md](docs/social-preview-ops.md) — how to review, export, and upload the GitHub social-preview image - [docs/assets/hermit-social-preview.svg](docs/assets/hermit-social-preview.svg) — final editable social-preview asset for repo cards and launch posts - [docs/assets/hermit-social-preview.png](docs/assets/hermit-social-preview.png) — ready-to-upload GitHub social-preview export diff --git a/docs/open-source-positioning.md b/docs/open-source-positioning.md index d032009..8d4ba07 100644 --- a/docs/open-source-positioning.md +++ b/docs/open-source-positioning.md @@ -4,7 +4,11 @@ This file keeps the short public-facing copy for repository metadata, launch pos ## One-line description -MCP executor for Claude Code or Codex that offloads repetitive coding work to cheaper local or flat-rate models. +Primary: +MCP executor layer for Claude Code or Codex that routes repetitive repo work to predictable local or flat-rate models. + +Alternate: +Dedicated MCP execution lane for Claude Code or Codex — keep premium judgment up top, and offload repo mechanics underneath. ## Short pitch @@ -71,3 +75,24 @@ Cheaper execution across multiple orchestrators. ## Release-note framing Hermit helps teams separate high-value reasoning from high-volume execution. That means better cost control, cleaner planner/executor boundaries, and an MCP-native path from idea to tested repo change. + +Template: `docs/release-notes-template.md` + +## Topic candidates + +Core: +- `mcp` +- `mcp-server` +- `claude-code` +- `codex` +- `coding-agent` +- `local-llm` +- `llm-routing` +- `cost-optimization` + +Optional: +- `developer-tools` +- `model-context-protocol` +- `agentic-workflows` +- `terminal-ui` +- `sub-agent` diff --git a/docs/release-notes-template.md b/docs/release-notes-template.md new file mode 100644 index 0000000..b552158 --- /dev/null +++ b/docs/release-notes-template.md @@ -0,0 +1,59 @@ +# Release notes template + +Use this template when publishing GitHub Releases, package announcements, or changelog summaries for Hermit. + +## Short version + +```md +## What changed +- [main user-visible change] +- [workflow or operator-facing change] +- [why it matters for cost, reliability, or usability] + +## Why it matters +[one short paragraph connecting the change back to Hermit's planner/executor positioning] +``` + +## Full version + +```md +## Summary +[One sentence: what changed in this release.] + +## What changed +- [Change 1] +- [Change 2] +- [Change 3] + +## Why it matters +[Explain how this improves planner/executor separation, cost predictability, release reliability, or day-to-day usability.] + +## Operator notes +- [migration / config / rollout note] +- [verification or fallback note] + +## Assets +- npm: https://www.npmjs.com/package/@cafitac/hermit-agent +- PyPI: https://pypi.org/project/cafitac-hermit-agent/ +- README: https://github.com/cafitac/hermit-agent#readme +``` + +## Tone guidelines + +- Lead with the user-facing outcome, not internal implementation detail. +- Use the same framing as the README and social preview: premium orchestrator for judgment, Hermit for repetitive repo execution. +- Prefer "predictable local or flat-rate execution" over provider-specific claims. +- Keep bullets concrete: edits, tests, commits, release follow-through, routing defaults, or maintainer workflow. +- If the release is mostly documentation or positioning, say that plainly instead of overselling it as core product capability. + +## Reusable opening lines + +- Hermit keeps Claude Code or Codex focused on judgment while offloading repetitive repo work to a dedicated MCP executor lane. +- This release sharpens the executor-layer experience: better operator guidance, clearer positioning, and more predictable follow-through. +- This update improves the public-facing story around Hermit's planner/executor split without changing its core role. + +## Reusable closing lines + +- Hermit continues to optimize for one job: cheaper, more predictable execution underneath a premium orchestrator. +- The planner stays premium; the repo mechanics stay efficient. +- The goal remains the same: better judgment up top, cheaper follow-through underneath.