---
name: project-manager
description: Orchestrate work across pipeline stages. Assign tasks with isolated folders. Guide the LLM to create/link/delete projects and configure .pi/settings.json with packages, skills, and tools for each project's purpose.
---

# Project Manager — Pipeline Orchestrator

## Overview

**Projects = subdirectories of the current working directory that contain `.pi/pipeline.md`.** Live-discovered every time — no registry. The workspace root defaults to `cwd` and can be changed via `projects.root` in settings. Pipeline.md frontmatter provides the project's `name` and `description`.

Only **2 tools** exist. Everything else is done with basic `bash`/`write`:

| Tool | When to use |
|------|-------------|
| `list_projects` | See all pipeline stages |
| `assign_project_task` | Create a task folder, optionally spawn a pi session |

## Project Context Enforcement

**always ensures you're working inside a project**:

- ✅ If cwd is inside a subdirectory of the workspace root → that directory is the active project
- 🆕 If cwd has no subdirectories yet → a **temp project** is auto-created at `<root>/.tmp/<name>-<ts>/`
  - Includes a minimal `.pi/settings.json` for isolation
  - The system prompt marks it as `(temp)` and shows its path
  - All work should go under that temp project path
- 📌 Use `/project:adopt [name]` to make a temp project permanent (moves it from `.tmp/` to the workspace root)

## Key Steps for Project Management

### Create a new project
```bash
mkdir -p ./<project-name>
```

### Link an existing folder as a project
```bash
ln -s /path/to/existing-folder ./<project-name>
```

### Delete a project (removes folder + all task data)
```bash
rm -rf ./<project-name>
```

### Adopt a temp project into a permanent one
```bash
/project:adopt <name>
```
Moves the auto-created temp project from `.tmp/<temp-name>` to `<root>/<name>`.

### Set up .pi for a project's purpose
A project **must** have `.pi/pipeline.md` to be discovered. Create it first:

```bash
mkdir -p ./<project>/.pi
```

Write `.pi/pipeline.md` with frontmatter:

```markdown
---
name: My Project
description: What this pipeline stage does
---

# My Project

## Purpose
...
```

Then optionally write `.pi/settings.json` with project-specific config:

```json
{
  "packages": ["npm:some-skill-package"],
  "skills": ["./custom-skills"],
  "extensions": ["./extensions/my-tool.ts"]
}
```

This lets each project session have its own **model, tools, skills, memory, and extensions** when started with:
```bash
cd ./<project>
```

### Pipeline definition (pipeline.md)

Each project must have a `.pi/pipeline.md` that defines the project's purpose,
conventions, and workflow. This file is **auto-injected into the system prompt**
whenever work happens in this project, so the LLM always has the full context.

```markdown
# my-pipeline

## Purpose
What this pipeline stage does. Why it exists.

## Conventions
- Code style, commit format, testing requirements
- Tools and frameworks used
- Expected input/output format

## Workflow
1. First step
2. Second step
3. Done when...

## Learnings
- Lesson learned from previous tasks (updated after each task)
```

**Create it when setting up a new project:**
```bash
mkdir -p ./<project>/.pi
write ./<project>/.pi/pipeline.md
# Define purpose, conventions, workflow
```

**Update it after each task:** read the current `pipeline.md`, then append
or modify the `## Learnings` section with what was learned. This makes
the pipeline self-improve over time.



## Task Workflow

### assign_project_task(projectName, taskName, instructions[, mode])

**Omit `mode` (interactive)** — creates a task folder. Work directly in this session:
```
assign_project_task(
  projectName: "api-redesign",
  taskName: "design-db",
  instructions: "Design the database schema..."
)
```
→ Creates `./api-redesign/.tasks/design-db/` with `instructions.md` + `status.json (assigned)`

Then cd into the task folder and work directly:
- `read instructions.md` — understand the task
- `bash`, `write`, `edit` — do the work
- `write result.json` — final response
- `write status.json` — `{ "status": "completed" }`

**With `mode: "sync"` or `"async"`** — spawns a pi child session to do the work:
```
assign_project_task(
  projectName: "api-redesign",
  taskName: "audit-deps",
  instructions: "Run npm audit, check for vulnerable dependencies, and write a report",
  mode: "async"
)
```
→ Creates task folder + spawns a pi session in `<taskFolder>` → pi reads `instructions.md`,
does the work, writes `result.json` + `status.json` when done.

- `sync` — wait for pi to finish, returns exit code + output
- `async` (default when mode is set) — pi runs in background, returns PID immediately.\
  Watcher notifies orchestrator when pi writes result.json.
- Omit mode entirely — no pi spawn, work interactively in current session

## Cross-Session Communication

**File protocol** (all files live in the task's `.tasks/<taskName>/` folder):

| File | Purpose |
|------|---------|
| `instructions.md` | What to do (written by orchestrator via `assign_project_task`) |
| `status.json` | Current status (read/write by any session with `write`/`read`) |
| `result.json` | Final output (written by completing session with `write`) |
| `output.log` | Pi session stdout/stderr (written during async/sync pi execution) |

**Push notifications:** The file watcher detects `result.json`/`status.json` changes and injects a `project-task-notification` custom message into the orchestrator session automatically.

## Examples

### Create a pipeline stage with custom .pi config
```
User: "Set up a typescript library project"

  mkdir -p ./ts-lib/.pi

  write ./ts-lib/.pi/settings.json:
  {
    "packages": ["npm:pi-hermes-memory"],
    "defaultModel": "anthropic/claude-sonnet-4-20250514"
  }

  write ./ts-lib/.pi/pipeline.md:
  ---
  name: ts-lib
  description: TypeScript library pipeline stage
  ---
  # ts-lib

  assign_project_task(
    projectName: "ts-lib",
    taskName: "init-project",
    instructions: "Initialize a TypeScript project with pnpm and vitest",
    mode: "sync"
  )
```

### Working directly in a task folder
```
User: "Review the API routes"

  assign_project_task(
    projectName: "api-redesign",
    taskName: "review-routes",
    instructions: "Review all API route handlers for security issues"
  )
  # → Creates .tasks/review-routes/ with instructions.md

  # Work directly in this same session:
  bash: cd ./api-redesign/.tasks/review-routes
  read instructions.md
  read ../../src/routes/*.ts
  write review-report.md
  write result.json
  write status.json → completed

  # File watcher pushes notification automatically
```

### Link an existing repo as a project
```
User: "Add the docs repo"

  ln -s ~/work/docs-repo ./docs

  write ./docs/.pi/pipeline.md:
  ---
  name: docs
  description: Documentation repo
  ---
  # docs

  → Immediately visible in list_projects

  write ./docs/.pi/settings.json:
  { "packages": ["npm:pi-hermes-memory"] }
```