superbee 0.1.6 → 0.2.1-pre.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +88 -80
  2. package/SKILL.md +6 -0
  3. package/dist/publication-bridge.mjs +730 -1207
  4. package/dist/publication.mjs +1377 -1846
  5. package/dist/superbee.mjs +5735 -4478
  6. package/package.json +5 -3
package/README.md CHANGED
@@ -1,106 +1,114 @@
1
1
  # superbee
2
2
 
3
+ Shared, versioned, conflict-safe knowledge for AI coding agents, stored as plain markdown in
4
+ your repo.
5
+
6
+ Superbee is pre-1.0. Commands and formats may change between releases.
7
+
3
8
  ## What is Superbee?
4
9
 
5
- Superbee gives AI coding agents shared, versioned, conflict-safe memory — as a folder of
6
- plain markdown in your repo.
7
-
8
- Agents forget everything between sessions, overwrite each other's work, and keep what they
9
- know invisible to the humans they work for. Superbee fixes all three:
10
-
11
- - **Memory that persists.** Agents write context notes, decisions, plans, and research into a
12
- knowledge bundle that survives the session. The next session — or a different agent — picks
13
- up exactly where the last one left off. An optional `SessionStart` hook (Claude Code, Codex,
14
- OpenCode) orients every new session automatically.
15
- - **Safe for many writers.** Every document write is compare-and-swap versioned and attributed
16
- to an actor. Two agents racing on the same document get a clean, typed conflict instead of a
17
- silent lost update — and `doc history` shows who changed what, when.
18
- - **Visible to humans.** Everything is plain markdown you can open in any editor, render on
19
- GitHub, and diff in git. `superbee ui` serves the bundle locally as rendered, cross-linked
20
- pages with derived backlinks, a live activity feed, and launchable bundle Views. `superbee
21
- sync` shares the bundle with teammates on a dedicated `board` branch — pulling their changes
22
- and pushing yours without touching your code.
23
- - **Views on demand.** Ask your agent to create whatever representation you need and Superbee will
24
- create it: a self-contained HTML View, registered in the bundle as a typed document, that
25
- `superbee ui` launches in a sandboxed iframe. A reading surface for one dense document, a board, a
26
- timeline, a filtered queue, a chart, a dashboard — the shape follows the question rather than a
27
- fixed set of built-in screens, and a view worth keeping stays. A data View reads live bundle
28
- content through a narrow read-only bridge and refreshes as documents change. Views are bundle
29
- content, so they travel with `sync` and open the same way for a teammate's agent.
30
- - **Agent-native by design.** The CLI follows the AXI principles for agent-facing tools:
31
- structured, token-lean output; result counts and truncation with explicit escape hatches;
32
- idempotent mutations; structured errors with a small, stable exit-code taxonomy. Agents get
33
- predictable responses they can act on without parsing prose or flooding their context window.
34
- - **Yours, and portable.** Bundles conform to the Open Knowledge Format — new bundles are
35
- written as OKF v0.2, and existing v0.1 bundles stay supported in place — so they survive the
36
- tool: hand the folder to someone else, or read it with anything that speaks markdown.
37
- Everything works offline; the filesystem is the source of truth. Typed document schemas
38
- ("kinds") live in the bundle itself, so the bundle describes its own structure.
39
-
40
- The npm package ships one self-contained executable with zero runtime dependencies, plus an
41
- Agent Skill that teaches agents how to use it.
42
-
43
- ## How do I download Superbee on Windows?
44
-
45
- **Requirements: Node.js 20 or newer on macOS, Linux, or native Windows.** You do not need WSL,
46
- Ubuntu, or Docker. On Windows, Superbee keeps per-user operational state under
47
- `%LOCALAPPDATA%\Superbee`; npm installs the command as `superbee.cmd`.
48
-
49
- Superbee currently has two npm release channels:
50
-
51
- - `latest` is the stable channel selected by bare `superbee`, including native Windows support.
52
- - `next` is the prerelease channel for release candidates.
53
-
54
- Install Superbee on Windows:
55
-
56
- ```powershell
10
+ Agents forget everything between sessions, overwrite each other's work, and keep what they know
11
+ invisible to the humans they work for. Superbee fixes all three with a **knowledge bundle**: a
12
+ folder of markdown documents, by convention `.superbee/` at your project root, that agents read
13
+ and write through a small command-line tool.
14
+
15
+ - **Context that persists.** Agents write context notes, decisions, plans, and research into the
16
+ bundle. The next session, or a different agent, picks up where the last one left off. An
17
+ optional `SessionStart` hook for Claude Code, Codex, and OpenCode orients every new session
18
+ automatically.
19
+ - **Safe for many writers.** Each write can carry the actor that made it. A writer can name the
20
+ version it last read; if anyone changed the document since, the write fails with a typed
21
+ conflict error instead of silently overwriting their work.
22
+ - **Visible to humans.** The bundle is plain markdown. Open it in any editor, render it on
23
+ GitHub, diff it in git. `superbee ui` serves it locally as cross-linked pages with backlinks and
24
+ a live activity feed. No bundle content leaves your machine until you run `superbee sync`, which
25
+ shares the bundle with teammates through the board: a copy of the bundle kept on its own git
26
+ branch, separate from your code.
27
+ - **Views on demand.** Ask your agent for a dashboard, a timeline, a filtered task queue, or a
28
+ reading view of one dense document. It builds a self-contained HTML page, stores it in the bundle
29
+ as a View, and `superbee ui` hosts it in a sandboxed frame. A View reads the bundle live and can
30
+ change it only through a write you confirm. Views are bundle content, so they travel with `sync`.
31
+ - **Built for agents.** Output is structured and token-lean, and errors carry a small, stable set
32
+ of exit codes. Agents act on responses without parsing prose or flooding their context window.
33
+ - **Yours, and portable.** Bundles follow the Open Knowledge Format (OKF), a convention of
34
+ markdown with frontmatter, so they outlive the tool: hand the folder to someone else, or read it
35
+ with anything that speaks markdown. New bundles are written as OKF v0.2, and existing v0.1
36
+ bundles keep working as they are. Reading and writing the bundle works offline; only sharing
37
+ needs a network. The document schemas, called kinds, live inside the bundle, so it describes
38
+ its own structure.
39
+
40
+ The npm package is one self-contained executable with zero runtime dependencies, plus an Agent
41
+ Skill, an instruction file your agent loads, that teaches it how to use the tool.
42
+
43
+ ## Install
44
+
45
+ Requires Node.js 20 or newer on macOS, Linux, or Windows. Native Windows is supported; you do not
46
+ need WSL or Docker.
47
+
48
+ ```sh
57
49
  npm install -g superbee
58
- superbee.cmd setup
59
50
  ```
60
51
 
61
- On macOS or Linux, install it with `npm install -g superbee` and then run `superbee setup`.
52
+ Stable releases publish on npm's `latest` tag and prereleases on `next`. To try the prerelease:
53
+
54
+ ```sh
55
+ npm install -g superbee@next
56
+ ```
62
57
 
63
- After installation, ask your AI agent to run `superbee setup` (`superbee.cmd setup` when invoking
64
- the Windows shim explicitly). Setup walks the agent through Agent Skill, SessionStart hook, and MCP
65
- registration. It is read-only: it inspects your configuration and returns one safe next command at
66
- a time, so the agent performs any actual changes with your approval.
58
+ On Windows, Superbee keeps its private per-user state, such as the workspace catalog and remote
59
+ credentials, under `%LOCALAPPDATA%\Superbee`. npm installs `superbee.cmd` alongside the `superbee`
60
+ command; if PowerShell's execution policy blocks the `.ps1` wrapper, call `superbee.cmd` instead.
67
61
 
68
- The managed Agent Skill works in Claude Code, Codex, and OpenCode. OpenCode discovers Superbee from
69
- its documented Claude-compatible Skill path. It shares Claude Code's Skill bytes by default; if
70
- Claude Code is explicitly relocated, the installer manages the two documented host paths separately.
62
+ Run `superbee version --check` to compare your install with the current stable release.
71
63
 
72
- Upgrading from the legacy `@holaxis/aslite` package or the retired marketplace plugin? Install
73
- `superbee` alongside it, have your agent run `superbee setup` to migrate the exact legacy
74
- integrations, then remove the old package with `npm uninstall -g @holaxis/aslite`. Existing
75
- `.agentstate-lite/` bundles and `.agentstate.json` bindings keep working with no migration.
64
+ ## First run: let your agent finish setup
76
65
 
77
- ## How to use Superbee
66
+ `npm install` gives you the CLI. The integrations (the Agent Skill, the `SessionStart` hook, and
67
+ MCP server registration, where MCP is the Model Context Protocol) are installed by your agent,
68
+ not by hand. Ask it:
78
69
 
79
- Superbee is agent-first: you don't type its commands yourself — you ask your agent for what
80
- you need, and the Agent Skill included with this package helps the agent translate your
81
- instructions into CLI commands. For example:
70
+ > Run `superbee setup` and follow its instructions.
82
71
 
83
- - "Set up a Superbee workspace for this project and track our tasks in it."
72
+ Setup itself changes nothing. It inspects your configuration and returns one safe next command at
73
+ a time, and the agent runs each with your approval. Setup knows Claude Code, Codex, and OpenCode,
74
+ plus Claude Desktop for the MCP registration only.
75
+
76
+ ## Everyday use
77
+
78
+ You rarely type Superbee commands yourself. You ask your agent, and the Agent Skill translates the
79
+ request into CLI calls:
80
+
81
+ - "Set up a Superbee bundle for this project and track our tasks in it."
84
82
  - "Write up what we decided about the auth design as a doc, and link it to the task."
85
83
  - "What did the last session leave off on? Check the context notes."
86
84
  - "Sync the board so my teammate's agent sees this."
87
85
  - "Give me a view of the open tasks grouped by owner."
88
86
 
89
- Behind those requests, the agent drives a small, predictable CLI: `init` creates a bundle in a
90
- conventional `.superbee/` folder (discovered automatically, the way git finds `.git`); `new`,
91
- `doc write`, `doc update`, and `link add` create and connect typed documents; `list` and
92
- `doc read` query them; `sync` shares the board with teammates.
87
+ Behind those requests the agent uses a small set of commands: `init --dir .superbee` creates the
88
+ bundle, `new` creates a document of a declared kind, `doc write` writes a free-form one,
89
+ `doc update` changes a document, `link add` connects two, `list` and `doc read` query them, and
90
+ `sync` shares the board. `superbee --help` lists the commands, and `superbee <command> --help`
91
+ gives each one's full reference.
93
92
 
94
- When you want to see the knowledge yourself, ask the agent to open it — or run the two
95
- human-facing commands directly:
93
+ The two commands meant for you are the ones that show you the knowledge:
96
94
 
97
95
  ```sh
98
- superbee ui --open # the bundle, rendered: pages, links, backlinks, live Views
99
- superbee doc open <id> # one exact document in the same local browser reader
96
+ superbee ui --open # the whole bundle, rendered in your browser
97
+ superbee doc open <id> # one document, by an id from `superbee list`
100
98
  ```
101
99
 
102
- Run `superbee --help` (or any subcommand with `--help`) for the full command reference.
103
- Design and format docs live in the [repository](https://github.com/Holaxis-ai/superbee).
100
+ ## Upgrading from aslite
101
+
102
+ If you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install
103
+ `superbee` alongside it, have your agent run `superbee setup` to migrate the integrations, then
104
+ run `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and
105
+ `.agentstate.json` bindings keep working with no migration.
106
+
107
+ ## Learn more
108
+
109
+ The [repository](https://github.com/Holaxis-ai/superbee) holds the source, the
110
+ [CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/cli/AXI-CONTRACT.md),
111
+ and the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).
104
112
 
105
113
  ## License
106
114
 
package/SKILL.md CHANGED
@@ -46,6 +46,11 @@ becoming a second source of truth. Add only the layer justified by current evide
46
46
 
47
47
  - Operate only on the bundle resolved from the current project or one the user explicitly selects.
48
48
  A catalog entry is available for selection; it is not ambient project context.
49
+ - Before remote publication, ask whether the intended remote repository exists, then whether
50
+ `origin/board` exists. If either is unknown, stop remote mutation and diagnose access.
51
+ - Superbee does not create the remote repository. If absence is confirmed, create it externally if authorized, or ask an authorized owner/teammate.
52
+ - On an existing repository without `board`, establishment needs consent, repository-specific Write access,
53
+ and branch-create policy clearance; creation authority is irrelevant. If `origin/board` exists, join with `superbee sync`; never establish another board.
49
54
  - If no bundle resolves, determine whether this repository already shares a board and clarify the
50
55
  intended purpose, privacy, participants, and sharing boundary before creating anything.
51
56
  `superbee sync` joins an existing shared board; `superbee init --create-only --dir .superbee` is
@@ -54,6 +59,7 @@ becoming a second source of truth. Add only the layer justified by current evide
54
59
  explicit publication decision.
55
60
  - Never silently rewrite an established Kind, recipe, or its instances. Inspect dependencies and
56
61
  explain migration consequences first.
62
+ - Writes carry an actor (`--actor`/`SUPERBEE_ACTOR`); OKF v0.2 bundles accept only `human:<id>`, `process:<id>`, or `<producer>/<version>` (e.g. `openai/codex`); a bare name is refused with the fix.
57
63
 
58
64
  ## Deliver after acceptance
59
65