# Bullx Project Manager — Design Document

## Philosophy

Keep the tool surface minimal. Only 2 tools:

| Tool | Purpose |
|------|---------|
| `list_projects` | Scan workspace, show pipeline stages |
| `assign_project_task` | Create task folder + optionally run a command |

Everything else (create/link/delete projects, set up `.pi/settings.json`) is done via basic `bash`/`write` tools, guided by the SKILL.md.

## Architecture

```
pi Extension
├── index.ts           — 2 tools, 6 commands, event handlers
├── project-store.ts   — file-system data layer
├── types.ts           — shared types + config loading
└── DESIGN.md          — this file

SKILL.md — teaches the LLM how to manage projects
```

### Tools vs Skill Instructions

| Action | How |
|--------|-----|
| List projects | `list_projects` tool |
| Create project folder | `bash mkdir -p` |
| Link existing folder | `bash ln -s` |
| Delete project | `bash rm -rf` |
| Set up .pi config | `write .pi/settings.json` |
| Assign task (delegate) | `assign_project_task` without `command` |
| Assign + run task | `assign_project_task` with `command` |

## Configurable Root

Settings cascade (from `types.ts:loadProjectsRootFromConfig`):

1. `.pi/settings.json` → `projects.root` (project-level)
2. `~/.pi/agent/settings.json` → `projects.root` (global)
3. `cwd` (default — the directory where pi was started)

## File-Based Task Protocol

Each task lives in `<project>/.tasks/<taskName>/`:

| File | Written by | Purpose |
|------|-----------|---------|
| `instructions.md` | `assign_project_task` | Task definition |
| `status.json` | Any session via `write` | Current status |
| `result.json` | Completing session via `write` | Final output |
| `output.log` | `assign_project_task` (when command given) | Command stdout/stderr |

## Push Notifications

Recursive `fs.watch` on the projects root detects changes to `result.json`/`status.json` and injects `project-task-notification` custom messages into the orchestrator session.

## Package Separation

| Session | Has PM Tools? | How |
|---------|--------------|-----|
| Orchestrator | ✅ | Package installed in project `.pi/settings.json` |
| Project session | ❌ | Plain pi — only `read`/`bash`/`write`/`edit` |