diff --git a/README.md b/README.md index e76940b..439e980 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,61 @@ + +
# 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 —
-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) +
+
-Bonsai workspace visualized in Obsidian graph view +--- -A Bonsai workspace visualized in Obsidian — every node is a generated file, every edge is a live cross-reference. +## Who Bonsai is for - +**Solo devs and small teams who want to give their coding agent real responsibility** — not just faster autocomplete. -
+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 @@ -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
bonsai init — cinematic flow from Vessel through Planted, ~28s end-to-end -`bonsai init` end-to-end — name your project, tend the soil, shape the branches, observe, plant. +bonsai init end-to-end — name your project, tend the soil, shape the branches, observe, plant.
--- -## 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. + +
+ +Bonsai workspace visualized in Obsidian graph view + +A Bonsai workspace in Obsidian — every node is a generated file, every edge is a live cross-reference. + +
+ +### Six agent types | Agent | Role | |:------|:-----| @@ -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/)** @@ -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. ---
-**[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).
-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).
diff --git a/station/Playbook/Plans/Active/25-readme-revamp.md b/station/Playbook/Plans/Active/25-readme-revamp.md new file mode 100644 index 0000000..639db18 --- /dev/null +++ b/station/Playbook/Plans/Active/25-readme-revamp.md @@ -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 (``). No empty `
` 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 `
`, 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 `
`). +- [ ] `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.