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

docs: clean up READMEs, mermaid diagram, quick start with kb CLI

Browse Source
This commit is contained in:
Dustin Byrne
2026-03-26 23:49:50 -04:00
parent 26bb077bc5
commit efdb7de21c
3 changed files with 63 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.changeset/readme-cleanup.md Normal file
View File

@@ -0,0 +1,5 @@
---
"@dustinbyrne/kb": patch
---
Clean up README: plain ASCII file tree, mermaid workflow diagram with column descriptions, update quick start to use `kb` CLI, add authentication section to CLI README, document cross-model review in executor description.

104
README.md
View File

@@ -4,19 +4,29 @@ AI-orchestrated task board. Like Trello, but your tasks get specified, executed,
## Workflow ## Workflow
``` ```mermaid
Triage Todo In Progress In Review Done graph LR
---------- ---------- --------------- ------------ -------- H((You)) -->|rough idea| T["Triage<br/><i>AI writes spec</i>"]
raw idea AI spec'd AI working ready to merged T --> TD["Todo<br/><i>waiting for deps</i>"]
& ready in worktree merge TD -->|agent free| IP
IP -->|steps + reviews pass| IR["In Review<br/><i>ready to merge</i>"]
IR -->|squash merge| D["Done<br/><i>shipped</i>"]
| | | | | subgraph IP[" In Progress "]
| AI specs | deps met, | all steps + | squash | direction TB
+----------->+ agent free + reviews pass + merge | E[Execute step] --> R{Cross-model\nreview}
+------------>+-------------->+----------->+ R -->|approve| E
^ | R -->|revise| E
| needs work | end
+----------------------------+
style H fill:#161b22,stroke:#8b949e,color:#e6edf3
style T fill:#2d2006,stroke:#d29922,color:#d29922
style TD fill:#0d2044,stroke:#58a6ff,color:#58a6ff
style IP fill:#1a0d2e,stroke:#bc8cff,color:#bc8cff
style E fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
style R fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
style IR fill:#0d2d16,stroke:#3fb950,color:#3fb950
style D fill:#1a1a1a,stroke:#8b949e,color:#8b949e
``` ```
Tasks with dependencies are processed sequentially. Independent tasks run in parallel. Tasks with dependencies are processed sequentially. Independent tasks run in parallel.
@@ -24,44 +34,38 @@ Tasks with dependencies are processed sequentially. Independent tasks run in par
## Quick Start ## Quick Start
```bash ```bash
# Install dependencies npm i -g @dustinbyrne/kb
pnpm install
# Start the board (with AI engine)
pnpm dev dashboard
# Create a task via CLI
pnpm dev task create "Fix the login redirect bug"
# List tasks
pnpm dev task list
# Move a task
pnpm dev task move KB-001 todo
# Pause a task (stops all automation)
pnpm dev task pause KB-001
# Unpause a task (resumes automation)
pnpm dev task unpause KB-001
# Attach a file to a task (images, logs, configs)
pnpm dev task attach KB-001 ./screenshot.png
# Create a task with attachments
pnpm dev task create "Fix the login bug" -- --attach screenshot.png --attach error.log
``` ```
Then open [http://localhost:4040](http://localhost:4040). Then from the root of your repository:
## Prerequisites ```bash
kb dashboard
```
The AI engine uses [pi](https://github.com/badlogic/pi-mono) agent sessions under the hood. You need: Open [http://localhost:4040](http://localhost:4040) — create tasks from the board or the CLI.
1. **pi installed:** `npm install -g @mariozechner/pi-coding-agent` ### CLI commands
2. **API key configured:** Run `pi` and use `/login` or set `ANTHROPIC_API_KEY`
kb reuses your existing pi authentication — no separate setup needed. ```bash
kb task create "Fix the login redirect bug"
kb task create "Button misaligned" --attach screenshot.png
kb task list
kb task show KB-001
kb task move KB-001 todo
kb task merge KB-001
```
Agents can use these same commands, or see [`.agents/skills/`](.agents/skills/) for structured skill docs.
### Prerequisites
The AI engine uses [pi](https://github.com/badlogic/pi-mono) under the hood:
1. `npm i -g @mariozechner/pi-coding-agent`
2. Run `pi` and use `/login`, or set `ANTHROPIC_API_KEY`
kb reuses your existing pi authentication.
## Packages ## Packages
@@ -80,12 +84,12 @@ Tasks live on disk in `.kb/tasks/` in the project root:
``` ```
.kb/ .kb/
config.json -- board config + ID counter ├── config.json # Board config + ID counter
tasks/ └── tasks/
KB-001/ └── KB-001/
task.json -- metadata (column, deps, timestamps) ├── task.json # Metadata (column, deps, timestamps)
PROMPT.md -- task specification ├── PROMPT.md # Task specification
attachments/ -- file attachments (optional) └── attachments/ # File attachments — images & text files (optional)
``` ```
### Board UI ### Board UI

11
packages/cli/README.md
View File

@@ -14,14 +14,11 @@ Tasks flow through five columns: **Triage → Todo → In Progress → In Review
npm install -g @dustinbyrne/kb npm install -g @dustinbyrne/kb
``` ```
## Prerequisites ## Authentication
kb uses [pi](https://github.com/badlogic/pi-mono) agent sessions under the hood. You need: 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.
1. **Install pi:** `npm install -g @mariozechner/pi-coding-agent` If you don't have pi set up yet: `npm i -g @mariozechner/pi-coding-agent && pi` then `/login`.
2. **Authenticate:** Run `pi` and use `/login`, or set the `ANTHROPIC_API_KEY` environment variable
kb reuses your existing pi authentication — no separate setup needed.
## Usage ## Usage
@@ -85,7 +82,7 @@ kb task merge KB-042
- **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. - **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. - **Scheduler** — Resolves dependency graphs and moves tasks to in-progress when ready. Independent tasks run in parallel.
- **Executor** — Creates an isolated git worktree, spawns an AI agent to implement the spec, and moves the task to in-review on completion. - **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 review** — Inspect the changes and merge with `kb task merge`, or toggle auto-merge in the dashboard.
## Standalone binary ## Standalone binary