Skip to content

docs(readme): revamp — audience-first structure #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LastStep merged 1 commit into from
Apr 22, 2026
Merged

docs(readme): revamp — audience-first structure #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 70 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,61 @@
<!-- Logo placeholder — artwork coming. Keep this comment so we remember to slot it in. -->

<div align="center">

# Bonsai

**A structured language for working with AI agents.**
**A workspace for your coding agent.**

[![GitHub Release](https://img.shields.io/github/v/release/LastStep/Bonsai?style=flat&color=blue)](https://github.com/LastStep/Bonsai/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/LastStep/Bonsai/ci.yml?label=CI)](https://github.com/LastStep/Bonsai/actions?query=workflow%3ACI)
[![Docs](https://img.shields.io/badge/docs-laststep.github.io%2FBonsai-blue)](https://laststep.github.io/Bonsai/)

Give your Claude Code agents identity, memory, protocols, and purpose —<br>
so they work like teammates, not tools.
[![Status: early-stage](https://img.shields.io/badge/status-early--stage-orange.svg)](https://github.com/LastStep/Bonsai/issues)

[Documentation](https://laststep.github.io/Bonsai/) · [Install](#install) · [Quick Start](#quick-start) · [Contributing](CONTRIBUTING.md)

</div>

<br>

<img src="docs/assets/graph-view.png" alt="Bonsai workspace visualized in Obsidian graph view" width="700">
---

<sub>A Bonsai workspace visualized in Obsidian — every node is a generated file, every edge is a live cross-reference.</sub>
## Who Bonsai is for

</div>
**Solo devs and small teams who want to give their coding agent real responsibility** — not just faster autocomplete.

<br>
Claude Code out of the box gets you a smart assistant. But the moment you want it to pick up where it left off last week, stay inside scope across sessions, or follow your team's standards without re-briefing every time, a single `CLAUDE.md` hits its ceiling fast.

---
Bonsai generates a structured workspace under `station/` and wires Claude Code hooks that enforce it.

## Why Bonsai
**What that looks like in practice:**

Claude Code is powerful out of the box. But the moment you need agents to **coordinate**, **stay consistent across sessions**, or **follow your team's standards** — you're writing walls of markdown by hand.
- **Every session starts from the same context.** A `SessionStart` hook injects identity, memory, active plans, and health warnings before the agent's first reply. No re-briefing.
- **The project is navigable, not just searchable.** An indexed codebase, cross-linked plans, and Obsidian-compatible markdown mean the agent reads a map of the project — not a grep output.
- **Rules live in files, not prompts.** Protocols (`security.md`, `scope-boundaries.md`, `memory.md`) are version-controlled. Sensors fire on `PreToolUse` / `Stop` to block scope violations at the tool call, not the transcript.
- **Plans before it acts.** The agent writes a plan to `Playbook/Plans/Active/NN-*.md` before any dispatch. Reviews run from `agent/Skills/review-checklist.md` — not whatever the agent last remembered.
- **Everything is auditable.** Decisions go to `Logs/KeyDecisionLog.md`. Out-of-scope findings go to `Playbook/Backlog.md`. Dispatched agent reports go to `Reports/`. `git log` is your audit trail.

Bonsai treats agent instructions as a **structured language** — a layered system where each layer has clear semantics:
**Not just CLAUDE.md with extra steps.** `CLAUDE.md` is one markdown file, reloaded each session. Bonsai is a workspace: dozens of cross-linked files, version-controlled, enforced by hooks. The agent comes back to the same place every time — and so does the next contributor.

Here's the shape of what lands in your repo after `bonsai init`:

```
Layer 6 │ Sensors │ Automated enforcement via Claude Code hooks
Layer 5 │ Routines │ Periodic self-maintenance on a schedule
Layer 4 │ Skills │ Domain knowledge — standards, patterns, conventions
Layer 3 │ Workflows │ Step-by-step procedures — planning, review, audit
Layer 2 │ Protocols │ Hard rules — security, scope, memory, startup
Layer 1 │ Core │ Identity, memory, self-awareness
station/
├── CLAUDE.md ← workspace navigation
├── INDEX.md ← project snapshot
├── Playbook/ ← Status · Roadmap · Backlog · Plans · Standards
├── Logs/ ← decisions · field notes · routine log
├── Reports/ ← pending · archive
└── agent/
├── Core/ ← identity · memory · self-awareness
├── Protocols/ ← security · scope · memory · session-start
├── Skills/ ← review checklist · planning template · domain standards
├── Workflows/ ← planning · code review · PR review · security audit
├── Sensors/ ← Claude Code hooks (auto-run on session / tool use / stop)
└── Routines/ ← scheduled self-maintenance tasks
```

You pick the components. Bonsai generates a complete, wired-up workspace — cross-linked navigation, auto-enforced hooks, and a shared project scaffold that keeps every agent on the same page.

One binary. No runtime. Works with any project.

---

## Install
Expand Down Expand Up @@ -78,27 +89,48 @@ bonsai init # set up station + Tech Lead agent
bonsai add # add a code agent (backend, frontend, etc.)
```

Your project now has a full agent workspace. Open it in Claude Code and say "hi, get started" — the agent self-orients, reads its identity, checks memory, and reports status.
Open the project in Claude Code and say "hi, get started" — the agent self-orients: reads its identity, checks memory, scans active plans, and reports status.

> **[Your First Workspace](https://laststep.github.io/Bonsai/guides/your-first-workspace/)** — full walkthrough with screenshots and explanations.
> **[Your First Workspace](https://laststep.github.io/Bonsai/guides/your-first-workspace/)** — walkthrough with screenshots and explanations.

---

## See It In Action
## See it in action

<div align="center">

<img src="assets/demos/init.gif" alt="bonsai init — cinematic flow from Vessel through Planted, ~28s end-to-end" width="900">

<sub>`bonsai init` end-to-end — name your project, tend the soil, shape the branches, observe, plant.</sub>
<sub><code>bonsai init</code> end-to-end — name your project, tend the soil, shape the branches, observe, plant.</sub>

</div>

---

## What's Inside
## How it works

### Six Agent Types
Bonsai treats agent instructions as a layered system. Each layer has clear semantics:

```
Layer 6 │ Sensors │ Automated enforcement via Claude Code hooks
Layer 5 │ Routines │ Periodic self-maintenance on a schedule
Layer 4 │ Skills │ Domain knowledge — standards, patterns, conventions
Layer 3 │ Workflows │ Step-by-step procedures — planning, review, audit
Layer 2 │ Protocols │ Hard rules — security, scope, memory, startup
Layer 1 │ Core │ Identity, memory, self-awareness
```

You pick the components at `bonsai init` / `bonsai add` time. Bonsai writes a complete, cross-linked workspace — navigation, hook wiring, file tracking — in one pass. Open it in any editor. Open it in Obsidian for a live graph.

<div align="center">

<img src="docs/assets/graph-view.png" alt="Bonsai workspace visualized in Obsidian graph view" width="700">

<sub>A Bonsai workspace in Obsidian — every node is a generated file, every edge is a live cross-reference.</sub>

</div>

### Six agent types

| Agent | Role |
|:------|:-----|
Expand All @@ -109,23 +141,23 @@ Your project now has a full agent workspace. Open it in Claude Code and say "hi,
| **DevOps** | Infrastructure-as-code, CI/CD, containers |
| **Security** | Vulnerability audits, auth review, dependency scanning |

The Tech Lead orchestrates. Code agents implement. You talk to the Tech Lead — it writes plans, dispatches work via worktree-isolated subagents, and reviews the output.
The Tech Lead orchestrates — plans, dispatches work via worktree-isolated subagents, reviews output. Code agents implement. You talk to the Tech Lead.

### The Catalog
### The catalog

Bonsai ships with **58 catalog items** — all mix-and-match, filtered by agent compatibility:
Bonsai ships with **58 catalog items**, mix-and-match, filtered by agent compatibility:

- **17 skills** — coding standards, API design, auth patterns, testing, infrastructure conventions
- **17 skills** — coding standards, API design, auth patterns, testing, infrastructure
- **10 workflows** — planning, code review, security audit, PR review, session logging
- **4 protocols** — memory, security, scope boundaries, session startup (all required)
- **12 sensors** — scope guards, dispatch validation, context injection, code quality checks
- **8 routines** — backlog hygiene, dependency audit, doc freshness, vulnerability scan

> **[Browse the full catalog](https://laststep.github.io/Bonsai/catalog/overview/)** with descriptions, compatibility tables, and default configurations.
> **[Browse the full catalog](https://laststep.github.io/Bonsai/catalog/overview/)** — descriptions, compatibility tables, defaults.

### Extensible by Design
### Extensible

After generation, you own the files. Add custom skills, workflows, or sensors — run `bonsai update` and Bonsai detects them, tracks them in your config, and includes them in navigation. Lock-aware conflict resolution means your edits are never silently overwritten.
After generation, the files are yours. Add custom skills, workflows, or sensors — `bonsai update` detects them, tracks them in your config, and wires them into navigation. Lock-aware conflict resolution means your edits are never silently overwritten.

> **[Customizing Abilities](https://laststep.github.io/Bonsai/guides/customizing-abilities/)** · **[Creating Custom Sensors](https://laststep.github.io/Bonsai/guides/creating-custom-sensors/)** · **[Creating Custom Routines](https://laststep.github.io/Bonsai/guides/creating-custom-routines/)**

Expand All @@ -143,32 +175,14 @@ After generation, you own the files. Add custom skills, workflows, or sensors
| `bonsai update` | Detect custom files, sync workspace |
| `bonsai guide` | View bundled guides: quickstart, concepts, cli, custom-files |

> **[Command Reference](https://laststep.github.io/Bonsai/commands/init/)** — full documentation with flags, interactive flows, and examples.

---

## Documentation

The full documentation is at **[laststep.github.io/Bonsai](https://laststep.github.io/Bonsai/)**:

- **[Concepts](https://laststep.github.io/Bonsai/concepts/how-bonsai-works/)** — how Bonsai works, agents, abilities, sensors, routines, scaffolding
- **[Guides](https://laststep.github.io/Bonsai/guides/your-first-workspace/)** — tutorials and how-tos
- **[Catalog](https://laststep.github.io/Bonsai/catalog/overview/)** — browse all agents, skills, workflows, protocols, sensors, routines
- **[Reference](https://laststep.github.io/Bonsai/reference/configuration/)** — configuration schemas, template variables, glossary

---

## Contributing

Bonsai is early-stage and evolving fast. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and PR guidelines.
> **[Command reference](https://laststep.github.io/Bonsai/commands/init/)** — flags, flows, examples.

---

<div align="center">

**[Documentation](https://laststep.github.io/Bonsai/)** · **[Releases](https://github.com/LastStep/Bonsai/releases)** · **[MIT License](LICENSE)**
**[Documentation](https://laststep.github.io/Bonsai/)** · **[Catalog](https://laststep.github.io/Bonsai/catalog/overview/)** · **[Contributing](CONTRIBUTING.md)** · **[Releases](https://github.com/LastStep/Bonsai/releases)** · **[MIT License](LICENSE)**

Built with [Cobra](https://github.com/spf13/cobra), [Huh](https://github.com/charmbracelet/huh), [LipGloss](https://github.com/charmbracelet/lipgloss), and [BubbleTea](https://github.com/charmbracelet/bubbletea).<br>
Developed with [Claude Code](https://claude.ai/code).
Built with [Cobra](https://github.com/spf13/cobra), [Huh](https://github.com/charmbracelet/huh), [LipGloss](https://github.com/charmbracelet/lipgloss), and [BubbleTea](https://github.com/charmbracelet/bubbletea). Developed with [Claude Code](https://claude.ai/code).

</div>
66 changes: 66 additions & 0 deletions station/Playbook/Plans/Active/25-readme-revamp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Plan 25 — README revamp

**Tier:** 1
**Status:** Active
**Agent:** tech-lead

## Goal

Replace the top-level `README.md` with an audience-first structure: logo placeholder, outcome-focused tagline, a new "Who Bonsai is for" section with mechanism-based feature bullets and a `station/` tree snippet, a merged "How it works" section that absorbs the old layer-stack and catalog content, and a lightweight footer that carries nav and attribution.

## Context

Current README leads with abstract framing ("a structured language for working with AI agents") and buries the audience pitch. Independent research agent flagged three high-impact issues: (a) the "who is this for" question isn't answered up front, (b) feature framing anthropomorphises the agent ("takes ownership") instead of showing mechanism (hooks, protocol files, checklists), and (c) a `tree station/` snippet is the single most persuasive visual and is missing. This plan lands all three plus the reorder, kills two duplicated sections (Documentation, Contributing body), and reserves a logo slot for art still in progress.

## Steps

1. **Reserve logo slot** at the top of `README.md` using an HTML comment (`<!-- Logo placeholder -->`). No empty `<div>` with fixed size — it renders as a broken gap on GitHub.
2. **Replace tagline** from "A structured language for working with AI agents." to **"A workspace for your coding agent."** Keep the center-aligned `<div>`, badges, and nav link row directly below.
3. **Add `status-early-stage` badge** to the badge row: `[![Status: early-stage](https://img.shields.io/badge/status-early--stage-orange.svg)](https://github.com/LastStep/Bonsai/issues)`.
4. **Remove** the old hero `docs/assets/graph-view.png` from the top of the file. It returns later as a supporting visual inside "How it works".
5. **Delete** the existing "Why Bonsai" section (lines ~29–47 of current file). Its layer-stack diagram is preserved — lifted into the new "How it works" section.
6. **Add new section `## Who Bonsai is for`** with:
- One-line audience hook (solo devs + small teams, give coding agent real responsibility).
- Two-sentence problem framing (single CLAUDE.md hits its ceiling fast).
- Five mechanism bullets (bold lead word + concrete file reference):
- **Every session starts from the same context.** `SessionStart` hook injects identity, memory, active plans, health warnings before first reply.
- **The project is navigable, not just searchable.** Indexed code, cross-linked plans, Obsidian-compatible markdown.
- **Rules live in files, not prompts.** Protocols (`security.md`, `scope-boundaries.md`, `memory.md`) version-controlled. Sensors fire on `PreToolUse`/`Stop` to block at the tool call.
- **Plans before it acts.** Writes a plan to `Playbook/Plans/Active/NN-*.md` before any dispatch. Reviews run from `agent/Skills/review-checklist.md`.
- **Everything is auditable.** Decisions → `Logs/KeyDecisionLog.md`. Out-of-scope findings → `Playbook/Backlog.md`. Agent reports → `Reports/`. `git log` is the audit trail.
- **"Not just CLAUDE.md with extra steps" rebuttal** — one paragraph framing Bonsai as workspace vs single file.
- **`station/` tree snippet** (code block, trimmed to essential dirs with inline annotation).
7. **Keep** `## Install`, `## Quick Start`, `## See it in action` (rename "See It In Action" → sentence case) unchanged in content. Tweak "say 'hi, get started'" copy to show what the agent does: reads identity, checks memory, scans active plans, reports status.
8. **Add merged section `## How it works`** containing:
- Layer-stack diagram (preserved verbatim from old "Why Bonsai").
- One paragraph on the "pick components at init/add time → Bonsai generates cross-linked workspace" mechanism.
- Graph-view PNG (moved here from hero — `docs/assets/graph-view.png`, width 700).
- `### Six agent types` table (preserved from old "What's Inside").
- `### The catalog` bullet list with counts (preserved, copy-edited).
- `### Extensible` paragraph (preserved, trimmed of "by design" boilerplate).
9. **Keep** `## Commands` table unchanged.
10. **Delete** `## Documentation` as its own section. Fold its links into the footer nav row.
11. **Delete** `## Contributing` prose. Keep the `CONTRIBUTING.md` link in the footer nav row and at the top nav.
12. **Rewrite footer** to a single nav row: Documentation · Catalog · Contributing · Releases · MIT License. Keep the "Built with Cobra / Huh / LipGloss / BubbleTea. Developed with Claude Code." attribution line.
13. **Cut stylistic AI-readme smells** flagged by the reviewer: "by design", "powerful out of the box", "One binary. No runtime. Works with any project.", "teammates, not tools", "structured language" framing everywhere.
14. **Preserve** asset paths: `assets/demos/init.gif` (hero demo), `docs/assets/graph-view.png` (moved, not removed).

## Security

> [!warning]
> Refer to `Playbook/Standards/SecurityStandards.md` for all security requirements. No code changes in this plan — documentation only. No secrets, no credentials, no example API keys introduced. All links use HTTPS to the existing project hosts (`github.com/LastStep/Bonsai`, `laststep.github.io/Bonsai`). Shield badge URLs go to `img.shields.io` (same host already in use).

## Verification

- [ ] `README.md` renders on GitHub without broken images or empty gaps (visual inspection after push).
- [ ] All markdown links resolve (`[text](target)` targets: `CONTRIBUTING.md`, `LICENSE`, `laststep.github.io/Bonsai/*`, `github.com/LastStep/Bonsai/*`, `img.shields.io/*`, `assets/demos/init.gif`, `docs/assets/graph-view.png`).
- [ ] Logo slot is an HTML comment (not a visible empty `<div>`).
- [ ] `station/` tree snippet matches what `bonsai init` actually generates (dirs: `Playbook/`, `Logs/`, `Reports/`, `agent/Core/`, `agent/Protocols/`, `agent/Skills/`, `agent/Workflows/`, `agent/Sensors/`, `agent/Routines/`).
- [ ] Badge row parses: 5 badges, no broken shields.
- [ ] Top nav row parses: 4 links.
- [ ] Footer nav row parses: 5 links + attribution line.
- [ ] Tagline is **"A workspace for your coding agent."** (not the old "structured language" line).
- [ ] "Why Bonsai" section no longer exists by name.
- [ ] "Documentation" and "Contributing" no longer exist as standalone sections.
- [ ] `make build && go test ./...` still passes (sanity check — no code touched, but run anyway).
- [ ] PR created as draft targeting `main` with `Closes` line and Plan 25 reference.
Loading