Holaxis-ai/superbee · packages/cli/references/sample-bundle
Bundle OKF 0.1 · 3 conceitos · Holaxis-ai/superbee
Open source Repository Open in the app JSON README (API)
About
# Subdirectories
* [concepts](concepts/index.md) - Core design concepts for Superbee.
* [context-notes](context-notes/index.md) - Cross-session agent handoffs stored as OKF concepts.
* [references](references/index.md) - Mirrored external sources cited by the concepts.
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- holaxis-ai
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Added
- 2026-09-12 03:15:14
- Updated
- 2026-09-12 03:15:14
- Origin id
Holaxis-ai/superbee:packages/cli/references/sample-bundle/index.md
README
<img src="assets/superbee-mark-256.png" alt="" width="96" height="96">
# Superbee
> A markdown knowledge bundle in your repo, plus a CLI built for agents.
Coding agents forget everything between sessions, overwrite each other's work, and keep
what they know invisible to the humans they work for. Superbee gives them
shared, versioned, conflict-safe memory in plain text — offline-first, standards-based,
owned by you.
**Status: early and experimental.** A public npm prerelease is available for testing; formats and
commands will change without ceremony, and some of the project's biggest ideas are still bets
under test. The honest breakdown is below — read it before depending on anything.
## Install
**Requirements: macOS, Linux, or native Windows, and Node.js 20 or newer.** Windows does not need
WSL, Ubuntu, or Docker.
The Windows-capable test release is currently on npm's `next` prerelease channel; `latest` still
points to the older stable package that rejects Windows. Install the prerelease with:
```sh
npm install -g superbee@next
superbee setup
```
On Windows, npm exposes the same command through `superbee.cmd`, which can be invoked explicitly
when PowerShell blocks its `.ps1` wrapper. On macOS or Linux, `npm install -g superbee` remains the
stable-channel install. The package's optional Agent Skill teaches Claude Code, Codex, and OpenCode
how to use the installed command without carrying another copy of the executable. OpenCode uses
its documented Claude-compatible Skill discovery, so it shares Claude Code's Skill bytes unless a
custom Claude config root requires separate documented host paths.
Bare and host-scoped `setup` are read-only and agent-friendly: without flags it reports private-state
health and lists the four supported hosts; after the agent selects its exact host, it inspects npm,
Agent Skill, SessionStart hook, MCP registration,
current bundle, and private workspace catalog, then returns one safe `next.command`. Fill any
explicit placeholder it identifies, run the command, restart the named host after integration
changes, and rerun the same setup command until the plan is complete. It never guesses a host as
permission to edit configuration.
After a CLI upgrade, `home` and SessionStart also report managed Agent Skills whose stale bytes can
pass the installer's complete read-only preflight, with the exact refresh command and restart
requirement; conflicts stay with explicit setup/status diagnostics and no host files change automatically.
If setup returns `superbee setup migrate-state`, that explicit command copies validated legacy
operational records into Superbee's private state root while preserving every legacy byte; it does
not move project bundles.
The hook is recommended rather than required: it gives Claude Code, Codex, and OpenCode a compact
Superbee orientation at session start. To try read-only and bootstrap commands without installing
anything, run `npx -y superbee`; persistent integrations still require the global npm install.
The npm package is the sole executable distribution channel. The optional Agent Skill contains
guidance and references only; it invokes the npm-installed CLI rather than carrying another copy.
The new package installs only `superbee`, so it can coexist with a global `@holaxis/aslite` long
enough for `superbee setup` to inspect and migrate exact legacy integrations. Once setup is
complete, remove the old package with `npm uninstall -g @holaxis/aslite`; the successor does not
keep the retired `aslite` or `agentstate-lite` commands on `PATH`.
If upgrading from the retired marketplace plugin, remove or disable that plugin, then rerun
`superbee setup` and follow its exact next command. The hook installer
replaces exact historical AgentState marketplace hooks rather than leaving two SessionStart hooks.
## Quickstart
```sh
superbee # confirm that no bundle is selected yet
superbee recipes # compare the workspace setups shipped offline
superbee init --create-only --recipe work-tracking --dir .superbee
superbee new "Task" first-task --title "Plan the first change" --progress_status todo \
--actor process:quickstart-agent --dir .superbee
superbee --dir .superbee # see the Task in the live bundle summary
```
`--create-only` refuses an occupied, nested, bound, or concurrently claimed target before it
writes; use `recipe add` when you deliberately want to add capability to an existing bundle.
Bring source material or intent to your agent in the tool you already use. The agent organizes,
types, links, and updates the bundle through `superbee`; these commands are the plumbing, not a
manual data-entry workflow.
`process:quickstart-agent` is an advisory example actor identity; replace it with the actual actor
identity (`human:<id>`, `process:<id>`, or `<producer>/<version>`).
New bundles use Superbee's current portable format automatically. Existing older bundles remain
supported in place; Superbee detects their declared format and applies compatibility behavior
without requiring an ordinary-use migration.
The conventional `.superbee/` folder at the project root is discovered with zero
config (the way git finds `.git`) — every command after setup runs bare from anywhere in
the project tree. A bundle stays local until `sync --establish` explicitly shares it on the
repository's dedicated `board` branch. The remote repository must already exist: Superbee creates
and pushes only the `board` branch, never the GitHub repository that contains it.
Existing `.agentstate-lite/` bundles and `.agentstate.json` bindings continue to work with
Superbee; no migration is required. When the first task needs a roadmap, run
`superbee recipe add roadmap`. Before sharing, determine whether the intended remote repository
exists, then whether `origin/board` exists. A confirmed-missing repository is created outside
Superbee by an authorized account/organization actor (or by an authorized teammate who then grants
access). For an existing repository with no `board`, repository-creation authority is irrelevant:
with explicit consent, repository-specific push capability, and branch-create policy clearance,
run `superbee sync --establish`. If `origin/board` already exists, join with ordinary
`superbee sync` instead. A failed remote check leaves both facts unknown; diagnose URL, network,
HTTPS/SSH identity, visibility, and repository Read access before any establishment attempt.
If valid `.superbee/` and `.agentstate-lite/` bundles exist at the same project level, Superbee
reports a conflict and refuses to choose; move the bundle you do not intend to use outside the
project before retrying.
**When the conventional project folder does not fit:**
- **Project binding:** preferred `.superbee.json`, with `.agentstate.json` retained for existing
projects. Either is a committed local pointer (`{ "bundle": "<path>" }`) for an out-of-tree
directory and beats the conventional folder. Both names at the same level are a conflict rather
than an implicit choice. Remote access is never
ambient: pass `--remote <url>` explicitly. Legacy URL bindings and `AGENTSTATE_LITE_REMOTE`
fail with migration guidance instead of activating HTTP.
- **Private workspace:** the bundle lives outside the repo (for example,
`~/superbee-workspaces/<name>/`); a git-excluded binding points at it, and nothing enters the repo.
- **Personal catalog:** register any local bundle under a user- or agent-defined label so it is
visible when an agent starts outside that project. The catalog is explicit and machine-local:
it never crawls, clones, or creates an ambient active workspace. Resolve a label to a path, then
pass that path to an ordinary command:
```sh
superbee catalog add personal --dir ~/superbee-workspaces/personal
superbee catalog list
superbee catalog resolve personal --field path
```
Then, day to day:
```sh
export SUPERBEE_ACTOR=process:claude # optional default; per-command --actor wins
superbee new "Task" ship-parser --title "Ship the parser" --progress_status todo
superbee list --type Task
superbee doc update tasks/ship-parser --progress_status in_progress
superbee doc history tasks/ship-parser # who changed what, when
superbee ui # the bundle, rendered — local server, no cloud
superbee index generate # optional: complete portable Markdown navigation
superbee sync # ordinary shared-board updates — commits yours,
# pulls theirs, pushes; leaves code files untouched
```
`init` always makes a LOCAL bundle; `sync` joins or updates a SHARED one, while
`sync --establish` is the one-time, explicit act that turns this project's local bundle into a
shared board (a `board` branch in an already-existing `origin` repository) — never automatic, so
a bare `sync` never silently publishes a bundle nobody asked to share. Once a board
exists (here or on a teammate's clone), plain `sync` is everyone's setup AND ongoing verb:
a fresh clone's first `sync` provisions the board from origin; a project with a local
bundle but no shared board reports its local-only state honestly (changes stay on this
machine) and routes to `--establish`. If origin cannot be checked, sync reports the
shared-board state as unknown and waits for a retry instead of recommending publication.
When a doc changed on both sides, sync
converges: your teammate's version is kept, yours is saved to an export file, and
`sync --show-incoming <id>` + `doc update` reconcile — no git surgery. Bundles committed
directly to a code branch are also supported as the IN-TREE mode: board docs travel with
your normal commit/push/pull, `sync --pull-only` fetches the branch's upstream and reports
incoming board changes (session start shows the same awareness), and a full `sync` refuses
with guidance — `sync --establish` is the explicit conversion to a dedicated board branch.
`sync --establish` also handles a project that already committed `.superbee/` or legacy
`.agentstate-lite/` to
its code branch: it prints a preview first, and `--yes` executes — publishing the board
branch from the folder's current files and preparing a cleanup commit on a side branch
that you open as a PR (the folder leaves the code branch; the board takes over after the
merge).
Establishment appends both recognized bundle directories (`.superbee/` and `.agentstate-lite/`) to
the root working-tree `.gitignore` and reports that uncommitted edit. Ordinary sync performs the
same reported repair when provisioning discovers that either ignore entry is missing.
**If you see a `board` branch** in a repo that uses Superbee: that is the shared
board — an orphan branch carrying only the knowledge bundle, written by `superbee sync`. It
never merges into `main` (it shares no history with it, by design). Protect it the way
you protect `main`: enable delete and force-push protection on `board` in the repo
settings — sync only ever appends commits to it.
## How it works
Tools that need a small, portable bundle identity can import the versioned JSON Schema and
TypeScript contract from `superbee/bundle-descriptor`. The contract describes a bundle but grants
no access or authority; see
[Bundle Descriptor v1](https://github.com/Holaxis-ai/superbee/blob/main/packages/bundle-descriptor/README.md).
- **Every concept is a typed markdown document.** One required frontmatter field — `type` — plus
whatever fields its schema declares. New concepts are new types, not new subsystems. Byte-exact
artifacts such as View HTML live as blobs referenced by those documents.
- **Portable navigation is explicit.** `index generate` creates a complete relative-link
`index.md` hierarchy for GitHub, ordinary editors, and copied folders. It refreshes only marked
generated files and refuses curated indexes unless `--force` deliberately adopts them.
- **Schemas are documents too.** A "kind" is declared by a convention doc inside the
bundle; validation fires at write time (warn by default, `--strict` to reject). The
bundle describes itself.
- **Schema guidance travels with the data.** Kinds can describe the concept itself, individual
fields, enum values, and relationship labels; the CLI projects that guidance through `kinds`
and kind-specific `new --help` output so agents do not need a separate live explanation.
- **Relationships are ordinary markdown links with convention-declared semantics.** A kind can
name and describe allowed outbound link labels and expected inbound relationships; the CLI can
warn or lint mismatches and query exact link labels. Backlinks are always derived, never stored.
- **Writes are compare-and-swap.** Every document state has a content-addressed
version; a racing writer gets a typed conflict instead of silently losing an update.
Every mutation is attributed.
- **Storage is a seam.** The engine holds all semantics; filesystem, memory, and wire
backends plug in underneath with byte-identical version tokens.
- **Recipes install capability as text.** A recipe is a folder of definitions, applied
idempotently — it seeds schemas and may carry explicitly declared static References and
self-contained Views, then the bundle owns them. A `definitions-only` package rejects instance
data and undeclared files. Three
recipes ship built-in (`context-notes`, `work-tracking`, `roadmap`);
`examples/recipes/claims` is the minimal custom-Kind example, while
`examples/recipes/review-workflow` is a complete content-free cognitive ecosystem: a
self-describing Review Request kind plus a generic live View, with no review instances.
Bundles are valid [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
— plain markdown any conformant tool can read. Superbee writes the current format for new bundles
and preserves existing legacy bundles without rewriting their declared edition.
## What's solid
- The engine and the storage seam: a broad suite across four workspaces, with the
filesystem, memory, and wire backends pinned to byte-identical version tokens.
- The CLI surface, built agent-first: structured output, counts and truncation with
escape hatches, idempotent mutations, a small stable exit-code taxonomy.
- The byte channel (`promote`/`pull`) for artifacts that should never enter a model's
context window.
- Project discovery: a committed `.superbee/` or legacy `.agentstate-lite/` folder (or an explicit `.superbee.json` /
supported `.agentstate.json` binding) resolves the bundle for any agent on any machine with zero
prior context.
## What's early or experimental
- **Everything is pre-1.0.** The npm package is a prerelease and breaking changes are likely.
- **Windows uses native policy rather than POSIX mode emulation.** Per-user operational state lives
under `%LOCALAPPDATA%`, whose ACL boundary is the Windows containment authority. The required
Windows CI lane runs every workspace suite on Node 22 and installs and exercises the packed npm
artifact on Node 20. WSL2 remains a Linux environment and is not a substitute for that native
Windows coverage.
- **Recipes as composition** is a thesis under test, not a result. The repository includes
small first-party definitions-only packages, including a Kind-plus-View reference, but package
dependencies, upgrades, migrations, and marketplace discovery remain future work. "Cookbooks"
(composed recipes with typed-link glue) are design intent only.
- **Bundle Views and the local web UI** are functional but still early. `ui` launches registered
Views in sandboxed iframes; data Views receive a narrow read-only bridge with live change events,
while `bundle-propose` Views may ask trusted shell chrome to confirm one local, CAS-guarded
scalar-field change. Content Views receive no bundle-data capability. Views can navigate to other registered
Views, and View-bearing definitions-only recipes can carry the operating model, registry entry,
HTML, and authoring reference together. (`Page` is the legacy name for the kind and is no
longer read — a legacy `type: Page` doc does not register, and the legacy `bridge:` field
grants nothing; `superbee status` flags leftover legacy names and the repo's
`migrate-legacy-view-names` script renames them in place. Legacy folder locations stay
recognized.) Authoring is still HTML/agent-driven rather than a
polished end-user builder, so treat the surface as a preview.
- **The public package ends at a generic remote boundary.** `serve` exposes a bundle through the
versioned wire protocol, and bundle commands can target a service explicitly with `--remote`.
A gated service may accept `SUPERBEE_API_KEY` (`AGENTSTATE_LITE_API_KEY` remains supported) or an already-provisioned stored per-origin
credential. This repository ships no hosted deployment, identity system, account-administration
commands, or cloud-provider package.
- **Wire protocol v0.1** is evolving. One recorded caveat: a document's raw bytes
re-serialize to canonical form over the wire; blobs are the byte-exact channel.
- **Filesystem CAS is serialized across same-user local processes** with an external per-target runtime lock.
A process crash can leave a diagnosable lock behind; writes fail closed until it is inspected
and removed rather than silently stealing an ambiguous lock.
- **Richer graph semantics** remain open: conventions type outbound links and can require at least
one matching inbound relationship today, but richer cardinality, cross-edge constraints,
workflow rules, and automation are intentionally not a second graph engine yet.
- OKF itself is young and evolving; we track it as it changes.
## Where the deep documentation lives
This project dogfoods itself: the plans, research, design docs, product statement, and
the full change history live in the project's own Superbee bundle, which the
team develops against daily. The repo also carries three narrow contracts at the boundary where a
fresh clone must remain sufficient: the CLI's [AXI contract](packages/cli/AXI-CONTRACT.md), the
implemented [wire protocol](docs/WIRE-PROTOCOL.md), and private vulnerability routing in
[SECURITY.md](SECURITY.md). Other deep documentation remains in the bundle rather than creating a
second manually coordinated product authority.
## License
Apache-2.0 © 2026 Holaxis