root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure README

Browse Source
This commit is contained in:
Dustin Byrne
2026-03-28 22:48:55 -04:00
parent 0208c2fee5
commit 98ed082e85
3 changed files with 131 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
packages/cli/README.md
View File

@@ -1,99 +1,77 @@
# @dustinbyrne/kb
AI-orchestrated task board CLI. Create tasks, and let AI agents specify, execute, and deliver them — powered by [pi](https://github.com/badlogic/pi-mono).
## What it does
kb is a kanban-style task board where AI does the heavy lifting. Toss in a rough idea and the AI engine writes a full specification, resolves dependencies, executes the work in isolated git worktrees, and hands you the result to review and merge.
Tasks flow through five columns: **Triage → Todo → In Progress → In Review → Done**.
An automated Kanban board for [pi](https://github.com/badlogic/pi-mono). You (or an agent) add high level ideas to your task list, and a team of agents execute them using worktrees.
## Installation
```bash
npm install -g @dustinbyrne/kb
pi install npm:@dustinbyrne/kb
```
## Authentication
This gives pi the ability to manage and create tasks in your kanban dashboard.
kb uses [pi](https://github.com/badlogic/pi-mono) for AI agent sessions and reuses your existing pi authentication. You can also authenticate directly through the dashboard UI.
## The dashboard
If you don't have pi set up yet: `npm i -g @mariozechner/pi-coding-agent && pi` then `/login`.
Run `/kb` in pi to launch the dashboard and AI engine.
## Usage
### Start the dashboard
Launch the web UI and AI engine:
```bash
kb dashboard
kb dashboard --port 8080
```
/kb # start on default port 4040
/kb stop # stop it
/kb 8080 # run on a custom port
```
### Create a task
The dashboard gives you:
```bash
kb task create "Fix the login redirect bug"
kb task create "Update hero section" --attach screenshot.png --attach design.pdf
```
### Manage tasks
```bash
kb task list # List all tasks
kb task show KB-001 # Show task details, steps, and log
kb task move KB-001 todo # Move a task to a column
kb task merge KB-001 # Merge an in-review task and close it
kb task log KB-001 "Added context" # Add a log entry
kb task pause KB-001 # Pause a task (stops automation)
kb task unpause KB-001 # Resume a paused task
kb task attach KB-001 ./error.log # Attach a file to a task
```
### Typical workflow
```bash
# 1. Create a task — it lands in triage
kb task create "Add dark mode support"
# 2. Start the dashboard — AI specs the task and begins working
kb dashboard
# 3. Check progress
kb task list
kb task show KB-042
# 4. When it reaches "in-review", review the changes and merge
kb task merge KB-042
```
## Columns
| Column | What happens |
|---------------|-------------------------------------------------|
| **Triage** | Raw idea. AI writes a full task specification. |
| **Todo** | Specified and ready. Scheduler waits for deps. |
| **In Progress** | AI is executing the task in a git worktree. |
| **In Review** | Work is done. Review the changes and merge. |
| **Done** | Merged and shipped. |
- **A live kanban board** — tasks move through columns automatically as AI works on them
- **Task detail view** — see the generated spec, step-by-step progress, reviewer verdicts, and full execution log
- **Dependency-aware scheduling** — declare dependencies between tasks or let the engine infer them; work starts in the right order automatically
- **Auto-merge** — on by default; reviewed work squash-merges into your branch without you lifting a finger
- **Parallel execution** — independent tasks run simultaneously in isolated git worktrees
- **Self-sustaining board** — agents may spawn follow-up tasks as they work, which get triaged, scheduled, and executed like any other task; the board feeds itself
## How it works
- **Triage processor** — An AI agent reads your project, understands the codebase, and turns your rough idea into a detailed specification with steps, file scope, and acceptance criteria.
- **Scheduler** — Resolves dependency graphs and moves tasks to in-progress when ready. Independent tasks run in parallel.
- **Executor** — Creates an isolated git worktree and spawns an AI agent to implement the spec step by step. At each step boundary, a separate reviewer agent (different model, read-only) independently checks the plan or code. Verdicts: approve (proceed), revise (fix issues), or rethink (change approach). Review depth scales with task complexity (levels 0–3, assigned during triage).
- **You review** — Inspect the changes and merge with `kb task merge`, or toggle auto-merge in the dashboard.
You create a task with a rough description. From there, a pipeline of specialized agents takes over.
## Standalone binary
### Specification
Prebuilt standalone binaries are available that require no Node.js runtime. You can also build one yourself with [Bun](https://bun.sh/):
A triage agent reads your codebase — file structure, existing patterns, related code — and turns your rough idea into a detailed specification. It breaks the work into discrete steps, identifies which files are in scope, writes acceptance criteria, and assigns a complexity rating that determines how aggressively the work gets reviewed later.
```bash
bun run build.ts
```
### Scheduling
See the [GitHub repository](https://github.com/dustinbyrne/kb) for platform-specific binaries and build instructions.
Tasks declare dependencies on each other. The scheduler builds a dependency graph and starts work only when upstream tasks are done. Independent tasks run in parallel — each in its own isolated git worktree, so there are no conflicts during execution.
### Execution & review
An executor agent works through the spec step by step in the worktree. At each step boundary, a separate reviewer agent, with read-only access, independently evaluates the work. The reviewer can approve (continue), request revisions (fix specific issues), or force a rethink (change the approach entirely). Review depth scales with the task's complexity rating: trivial tasks get light checks, complex tasks get thorough multi-pass review. This execution model is heavily based on [Taskplane](https://www.npmjs.com/package/taskplane).
### Merge
When execution finishes and the reviewer signs off, the task moves to "in review." By default, the completed work is automatically squash-merged into your current branch with a clean commit. Worktrees can be cleaned up after merge or reused by the next task to keep build caches warm. You can disable auto-merge if you prefer to review and merge manually.
Tasks flow through: **Triage → Todo → In Progress → In Review → Done**.
## Working from chat
You can manage tasks without leaving the conversation:
> "Every ten minutes, analyze the server code for logic the client hasn't implemented yet and create tasks. Tasks may spawn additional tasks, so just add enough to keep the board saturated."
> "Create a kb task to fix the login redirect bug"
> "Add a task for dark mode support, it depends on KB-003"
> "What's the status of KB-042"
> "Attach screenshot.png to KB-007"
> "Pause KB-012 — I want to add more context first"
The extension gives pi tools to create tasks, check progress, attach files, and pause or resume automation.
## Standalone CLI
kb also works as a standalone CLI outside of pi. See [STANDALONE.md](./STANDALONE.md) for installation and usage without the pi extension.
## Full documentation

73
packages/cli/STANDALONE.md Normal file
View File

@@ -0,0 +1,73 @@
# Standalone CLI
kb works as a standalone CLI without pi. This is useful for CI environments, scripting, or if you prefer working from the terminal.
## Installation
```bash
npm install -g @dustinbyrne/kb
```
## Authentication
kb uses [pi](https://github.com/badlogic/pi-mono) for AI agent sessions and reuses your existing pi authentication. You can also authenticate directly through the dashboard UI.
If you don't have pi set up yet: `npm i -g @mariozechner/pi-coding-agent && pi` then `/login`.
## Usage
### Start the dashboard
Launch the web UI and AI engine:
```bash
kb dashboard
kb dashboard --port 8080
```
### Create a task
```bash
kb task create "Fix the login redirect bug"
kb task create "Update hero section" --attach screenshot.png --attach design.pdf
```
### Manage tasks
```bash
kb task list # List all tasks
kb task show KB-001 # Show task details, steps, and log
kb task move KB-001 todo # Move a task to a column
kb task merge KB-001 # Merge an in-review task and close it
kb task log KB-001 "Added context" # Add a log entry
kb task pause KB-001 # Pause a task (stops automation)
kb task unpause KB-001 # Resume a paused task
kb task attach KB-001 ./error.log # Attach a file to a task
```
### Typical workflow
```bash
# 1. Create a task — it lands in triage
kb task create "Add dark mode support"
# 2. Start the dashboard — AI specs the task and begins working
kb dashboard
# 3. Check progress
kb task list
kb task show KB-042
# 4. When it reaches "in-review", review the changes and merge
kb task merge KB-042
```
## Standalone binary
Prebuilt standalone binaries are available that require no Node.js runtime. You can also build one yourself with [Bun](https://bun.sh/):
```bash
bun run build.ts
```
See the [GitHub repository](https://github.com/dustinbyrne/kb) for platform-specific binaries and build instructions.