taskplane 0.1.12 → 0.1.13

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 (3) hide show
  1. package/README.md +188 -180
  2. package/bin/taskplane.mjs +1047 -1007
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,180 +1,188 @@
1
- # Taskplane
2
-
3
- Multi-agent AI orchestration for [pi](https://github.com/badlogic/pi-mono) — parallel task execution with checkpoint discipline, fresh-context worker loops, cross-model reviews, and automated merges.
4
-
5
- > **Status:** Experimental / Early — APIs and config formats may change between releases.
6
-
7
- ## What It Does
8
-
9
- Taskplane turns your coding project into an AI-managed task board. You define tasks as structured markdown files. Taskplane's agents execute them autonomously — one at a time with `/task`, or many in parallel with `/orch`.
10
-
11
- ### Key Features
12
-
13
- - **Task Runner** (`/task`) — Autonomous single-task execution. Workers run in fresh-context loops with STATUS.md as persistent memory. Every checkbox gets a git checkpoint. Cross-model reviewers catch what the worker missed.
14
- - **Task Orchestrator** (`/orch`) — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges with conflict resolution.
15
- - **Web Dashboard** — Live browser-based monitoring via `taskplane dashboard`. SSE streaming, lane/task progress, wave visualization, batch history.
16
- - **Structured Tasks** — PROMPT.md defines the mission, steps, and constraints. STATUS.md tracks progress. Agents follow the plan, not vibes.
17
- - **Checkpoint Discipline** — Every completed checkbox item triggers a git commit. Work is never lost, even if a worker crashes mid-task.
18
- - **Cross-Model Review** — Reviewer agent uses a different model than the worker. Independent quality gate before merge.
19
-
20
- ## Install
21
-
22
- Taskplane is a [pi package](https://github.com/badlogic/pi-mono). You need [Node.js](https://nodejs.org/) ≥ 20 and [pi](https://github.com/badlogic/pi-mono) installed first.
23
-
24
- ### Option A: Global Install (all projects)
25
-
26
- ```bash
27
- pi install npm:taskplane
28
- ```
29
-
30
- ### Option B: Project-Local Install (recommended for teams)
31
-
32
- ```bash
33
- cd my-project
34
- pi install -l npm:taskplane
35
- ```
36
-
37
- Then scaffold your project:
38
-
39
- ```bash
40
- taskplane init
41
- ```
42
-
43
- Verify the installation:
44
-
45
- ```bash
46
- taskplane doctor
47
- ```
48
-
49
- ## Quickstart
50
-
51
- ### 1. Initialize a project
52
-
53
- ```bash
54
- cd my-project
55
- taskplane init --preset full
56
- ```
57
-
58
- This creates config files in `.pi/`, agent prompts, and two example tasks.
59
-
60
- ### 2. Launch the dashboard (recommended)
61
-
62
- In a separate terminal:
63
-
64
- ```bash
65
- taskplane dashboard
66
- ```
67
-
68
- Opens a live web dashboard at `http://localhost:8099` with real-time batch monitoring.
69
-
70
- ### 3. Run your first orchestration
71
-
72
- ```bash
73
- pi
74
- ```
75
-
76
- Inside the pi session:
77
-
78
- ```
79
- /orch-plan all # Preview waves, lanes, and dependencies
80
- /orch all # Execute all pending tasks in parallel
81
- /orch-status # Monitor batch progress
82
- ```
83
-
84
- The default scaffold includes two independent example tasks, so `/orch all` gives you an immediate orchestrator + dashboard experience.
85
-
86
- ### 4. Optional: run one task directly
87
-
88
- `/task` is still useful for single-task execution and focused debugging:
89
-
90
- ```
91
- /task taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md
92
- /task-status
93
- ```
94
-
95
- Important distinction:
96
-
97
- - `/task` runs in your **current branch/worktree**.
98
- - `/orch` runs tasks in **isolated worktrees** and merges back.
99
-
100
- Because workers checkpoint with git commits, `/task` can capture unrelated local edits if you're changing files in parallel. For safer isolation (even with one task), prefer:
101
-
102
- ```text
103
- /orch taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md
104
- ```
105
-
106
- Orchestrator lanes execute tasks through task-runner under the hood, so `/task` and `/orch` share the same core task execution model.
107
-
108
- ## Commands
109
-
110
- ### Pi Session Commands
111
-
112
- | Command | Description |
113
- |---------|-------------|
114
- | `/task <path/to/PROMPT.md>` | Execute one task in the current branch/worktree |
115
- | `/task-status` | Show current task progress |
116
- | `/task-pause` | Pause after current worker iteration finishes |
117
- | `/task-resume` | Resume a paused task |
118
- | `/orch <areas\|paths\|all>` | Execute tasks via isolated worktrees (recommended default) |
119
- | `/orch-plan <areas\|paths\|all>` | Preview execution plan without running |
120
- | `/orch-status` | Show batch progress |
121
- | `/orch-pause` | Pause batch after current tasks finish |
122
- | `/orch-resume` | Resume a paused batch |
123
- | `/orch-abort [--hard]` | Abort batch (graceful or immediate) |
124
- | `/orch-deps <areas\|paths\|all>` | Show dependency graph |
125
- | `/orch-sessions` | List active worker sessions |
126
-
127
- ### CLI Commands
128
-
129
- | Command | Description |
130
- |---------|-------------|
131
- | `taskplane init` | Scaffold project config (interactive or `--preset`) |
132
- | `taskplane doctor` | Validate installation and config |
133
- | `taskplane version` | Show version info |
134
- | `taskplane dashboard` | Launch the web dashboard |
135
- | `taskplane uninstall` | Remove Taskplane project files and optionally uninstall package (`--package`) |
136
-
137
- ## How It Works
138
-
139
- ```
140
- ┌─────────────────────────────────────────────────────────────┐
141
- │ ORCHESTRATOR (/orch) │
142
- │ Parse tasks → Build dependency DAG → Compute waves │
143
- │ Assign lanes → Spawn workers → Monitor → Merge │
144
- └──────┬──────────┬──────────┬────────────────────────────────┘
145
- │ │ │
146
- ┌────▼────┐ ┌──▼─────┐ ┌──▼─────┐
147
- │ Lane 1 │ │ Lane 2 │ │ Lane 3 │ ← Git worktrees
148
- │ /task │ │ /task │ │ /task │ (isolated)
149
- │ Worker │ │ Worker │ │ Worker │
150
- │ Review │ │ Review │ │ Review │
151
- └────┬────┘ └──┬─────┘ └──┬─────┘
152
- │ │ │
153
- └─────────┼──────────┘
154
- │
155
- ┌──────▼──────┐
156
- │ Merge Agent │ ← Conflict resolution
157
- │ Integration │ & verification
158
- │ Branch │
159
- └─────────────┘
160
- ```
161
-
162
- **Single task** (`/task`): Worker iterates in fresh-context loops. STATUS.md is persistent memory. Each checkbox → git checkpoint. Reviewer validates on completion.
163
-
164
- **Parallel batch** (`/orch`): Tasks are sorted into dependency waves. Each wave runs in parallel across lanes (git worktrees). Completed lanes merge into the integration branch before the next wave starts.
165
-
166
- ## Documentation
167
-
168
- 📖 **[Full Documentation](docs/README.md)**
169
-
170
- Start at the docs index for tutorials, how-to guides, reference docs, and architecture explanations.
171
-
172
- ## Contributing
173
-
174
- See **[CONTRIBUTING.md](CONTRIBUTING.md)** for development setup, testing, and contribution guidelines.
175
-
176
- Maintainers: GitHub governance and branch protection guidance is in [docs/maintainers/repository-governance.md](docs/maintainers/repository-governance.md).
177
-
178
- ## License
179
-
180
- [MIT](LICENSE) © Henry Lach
1
+ # Taskplane
2
+
3
+ Multi-agent AI orchestration for [pi](https://github.com/badlogic/pi-mono) — parallel task execution with checkpoint discipline, fresh-context worker loops, cross-model reviews, and automated merges.
4
+
5
+ > **Status:** Experimental / Early — APIs and config formats may change between releases.
6
+
7
+ ## What It Does
8
+
9
+ Taskplane turns your coding project into an AI-managed task board. You define tasks as structured markdown files. Taskplane's agents execute them autonomously — one at a time with `/task`, or many in parallel with `/orch`.
10
+
11
+ ### Key Features
12
+
13
+ - **Task Runner** (`/task`) — Autonomous single-task execution. Workers run in fresh-context loops with STATUS.md as persistent memory. Every checkbox gets a git checkpoint. Cross-model reviewers catch what the worker missed.
14
+ - **Task Orchestrator** (`/orch`) — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges with conflict resolution.
15
+ - **Web Dashboard** — Live browser-based monitoring via `taskplane dashboard`. SSE streaming, lane/task progress, wave visualization, batch history.
16
+ - **Structured Tasks** — PROMPT.md defines the mission, steps, and constraints. STATUS.md tracks progress. Agents follow the plan, not vibes.
17
+ - **Checkpoint Discipline** — Every completed checkbox item triggers a git commit. Work is never lost, even if a worker crashes mid-task.
18
+ - **Cross-Model Review** — Reviewer agent uses a different model than the worker. Independent quality gate before merge.
19
+
20
+ ## Install
21
+
22
+ Taskplane is a [pi package](https://github.com/badlogic/pi-mono). You need [Node.js](https://nodejs.org/) ≥ 20 and [pi](https://github.com/badlogic/pi-mono) installed first.
23
+
24
+ ### Option A: Global Install (all projects)
25
+
26
+ ```bash
27
+ pi install npm:taskplane
28
+ ```
29
+
30
+ ### Option B: Project-Local Install (recommended for teams)
31
+
32
+ ```bash
33
+ cd my-project
34
+ pi install -l npm:taskplane
35
+ ```
36
+
37
+ Then scaffold your project:
38
+
39
+ ```bash
40
+ taskplane init
41
+ ```
42
+
43
+ Verify the installation:
44
+
45
+ ```bash
46
+ taskplane doctor
47
+ ```
48
+
49
+ ## Quickstart
50
+
51
+ ### 1. Initialize a project
52
+
53
+ ```bash
54
+ cd my-project
55
+ taskplane init --preset full
56
+ ```
57
+
58
+ This creates config files in `.pi/`, agent prompts, and two example tasks.
59
+
60
+ Already have a task folder (for example `docs/task-management`)? Use:
61
+
62
+ ```bash
63
+ taskplane init --preset full --tasks-root docs/task-management
64
+ ```
65
+
66
+ When `--tasks-root` is provided, example task packets are skipped by default. Add `--include-examples` if you explicitly want examples in that folder.
67
+
68
+ ### 2. Launch the dashboard (recommended)
69
+
70
+ In a separate terminal:
71
+
72
+ ```bash
73
+ taskplane dashboard
74
+ ```
75
+
76
+ Opens a live web dashboard at `http://localhost:8099` with real-time batch monitoring.
77
+
78
+ ### 3. Run your first orchestration
79
+
80
+ ```bash
81
+ pi
82
+ ```
83
+
84
+ Inside the pi session:
85
+
86
+ ```
87
+ /orch-plan all # Preview waves, lanes, and dependencies
88
+ /orch all # Execute all pending tasks in parallel
89
+ /orch-status # Monitor batch progress
90
+ ```
91
+
92
+ The default scaffold includes two independent example tasks, so `/orch all` gives you an immediate orchestrator + dashboard experience.
93
+
94
+ ### 4. Optional: run one task directly
95
+
96
+ `/task` is still useful for single-task execution and focused debugging:
97
+
98
+ ```
99
+ /task taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md
100
+ /task-status
101
+ ```
102
+
103
+ Important distinction:
104
+
105
+ - `/task` runs in your **current branch/worktree**.
106
+ - `/orch` runs tasks in **isolated worktrees** and merges back.
107
+
108
+ Because workers checkpoint with git commits, `/task` can capture unrelated local edits if you're changing files in parallel. For safer isolation (even with one task), prefer:
109
+
110
+ ```text
111
+ /orch taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md
112
+ ```
113
+
114
+ Orchestrator lanes execute tasks through task-runner under the hood, so `/task` and `/orch` share the same core task execution model.
115
+
116
+ ## Commands
117
+
118
+ ### Pi Session Commands
119
+
120
+ | Command | Description |
121
+ |---------|-------------|
122
+ | `/task <path/to/PROMPT.md>` | Execute one task in the current branch/worktree |
123
+ | `/task-status` | Show current task progress |
124
+ | `/task-pause` | Pause after current worker iteration finishes |
125
+ | `/task-resume` | Resume a paused task |
126
+ | `/orch <areas\|paths\|all>` | Execute tasks via isolated worktrees (recommended default) |
127
+ | `/orch-plan <areas\|paths\|all>` | Preview execution plan without running |
128
+ | `/orch-status` | Show batch progress |
129
+ | `/orch-pause` | Pause batch after current tasks finish |
130
+ | `/orch-resume` | Resume a paused batch |
131
+ | `/orch-abort [--hard]` | Abort batch (graceful or immediate) |
132
+ | `/orch-deps <areas\|paths\|all>` | Show dependency graph |
133
+ | `/orch-sessions` | List active worker sessions |
134
+
135
+ ### CLI Commands
136
+
137
+ | Command | Description |
138
+ |---------|-------------|
139
+ | `taskplane init` | Scaffold project config (interactive or `--preset`) |
140
+ | `taskplane doctor` | Validate installation and config |
141
+ | `taskplane version` | Show version info |
142
+ | `taskplane dashboard` | Launch the web dashboard |
143
+ | `taskplane uninstall` | Remove Taskplane project files and optionally uninstall package (`--package`) |
144
+
145
+ ## How It Works
146
+
147
+ ```
148
+ ┌─────────────────────────────────────────────────────────────┐
149
+ │ ORCHESTRATOR (/orch) │
150
+ │ Parse tasks → Build dependency DAG → Compute waves │
151
+ │ Assign lanes → Spawn workers → Monitor → Merge │
152
+ └──────┬──────────┬──────────┬────────────────────────────────┘
153
+ │ │ │
154
+ ┌────▼────┐ ┌──▼─────┐ ┌──▼─────┐
155
+ │ Lane 1 │ │ Lane 2 │ │ Lane 3 │ ← Git worktrees
156
+ │ /task │ │ /task │ │ /task │ (isolated)
157
+ │ Worker │ │ Worker │ │ Worker │
158
+ │ Review │ │ Review │ │ Review │
159
+ └────┬────┘ └──┬─────┘ └──┬─────┘
160
+ │ │ │
161
+ └─────────┼──────────┘
162
+ │
163
+ ┌──────▼──────┐
164
+ │ Merge Agent │ ← Conflict resolution
165
+ │ Integration │ & verification
166
+ │ Branch │
167
+ └─────────────┘
168
+ ```
169
+
170
+ **Single task** (`/task`): Worker iterates in fresh-context loops. STATUS.md is persistent memory. Each checkbox → git checkpoint. Reviewer validates on completion.
171
+
172
+ **Parallel batch** (`/orch`): Tasks are sorted into dependency waves. Each wave runs in parallel across lanes (git worktrees). Completed lanes merge into the integration branch before the next wave starts.
173
+
174
+ ## Documentation
175
+
176
+ 📖 **[Full Documentation](docs/README.md)**
177
+
178
+ Start at the docs index for tutorials, how-to guides, reference docs, and architecture explanations.
179
+
180
+ ## Contributing
181
+
182
+ See **[CONTRIBUTING.md](CONTRIBUTING.md)** for development setup, testing, and contribution guidelines.
183
+
184
+ Maintainers: GitHub governance and branch protection guidance is in [docs/maintainers/repository-governance.md](docs/maintainers/repository-governance.md).
185
+
186
+ ## License
187
+
188
+ [MIT](LICENSE) © Henry Lach