docs: clean up READMEs, mermaid diagram, quick start with kb CLI
This commit is contained in:
Dustin Byrne
5
.changeset/readme-cleanup.md
Normal file
5
.changeset/readme-cleanup.md
Normal 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
104
README.md
@@ -4,19 +4,29 @@ AI-orchestrated task board. Like Trello, but your tasks get specified, executed,
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Triage Todo In Progress In Review Done
|
||||
---------- ---------- --------------- ------------ --------
|
||||
raw idea AI spec'd AI working ready to merged
|
||||
& ready in worktree merge
|
||||
```mermaid
|
||||
graph LR
|
||||
H((You)) -->|rough idea| T["Triage<br/><i>AI writes spec</i>"]
|
||||
T --> TD["Todo<br/><i>waiting for deps</i>"]
|
||||
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>"]
|
||||
|
||||
| | | | |
|
||||
| AI specs | deps met, | all steps + | squash |
|
||||
+----------->+ agent free + reviews pass + merge |
|
||||
+------------>+-------------->+----------->+
|
||||
^ |
|
||||
| needs work |
|
||||
+----------------------------+
|
||||
subgraph IP[" In Progress "]
|
||||
direction TB
|
||||
E[Execute step] --> R{Cross-model\nreview}
|
||||
R -->|approve| E
|
||||
R -->|revise| E
|
||||
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.
|
||||
@@ -24,44 +34,38 @@ Tasks with dependencies are processed sequentially. Independent tasks run in par
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
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
|
||||
npm i -g @dustinbyrne/kb
|
||||
```
|
||||
|
||||
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`
|
||||
2. **API key configured:** Run `pi` and use `/login` or set `ANTHROPIC_API_KEY`
|
||||
### CLI commands
|
||||
|
||||
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
|
||||
|
||||
@@ -80,12 +84,12 @@ Tasks live on disk in `.kb/tasks/` in the project root:
|
||||
|
||||
```
|
||||
.kb/
|
||||
config.json -- board config + ID counter
|
||||
tasks/
|
||||
KB-001/
|
||||
task.json -- metadata (column, deps, timestamps)
|
||||
PROMPT.md -- task specification
|
||||
attachments/ -- file attachments (optional)
|
||||
├── config.json # Board config + ID counter
|
||||
└── tasks/
|
||||
└── KB-001/
|
||||
├── task.json # Metadata (column, deps, timestamps)
|
||||
├── PROMPT.md # Task specification
|
||||
└── attachments/ # File attachments — images & text files (optional)
|
||||
```
|
||||
|
||||
### Board UI
|
||||
|
||||
@@ -14,14 +14,11 @@ Tasks flow through five columns: **Triage → Todo → In Progress → In Review
|
||||
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`
|
||||
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.
|
||||
If you don't have pi set up yet: `npm i -g @mariozechner/pi-coding-agent && pi` then `/login`.
|
||||
|
||||
## 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.
|
||||
- **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.
|
||||
|
||||
## Standalone binary
|
||||
|
||||
Reference in New Issue
Block a user