# @vtemian/pi-config

Extended workflow configuration for [Pi coding agent](https://github.com/badlogic/pi-mono).

Adds multi-agent orchestration, custom tools, and workflow commands to Pi.

## Installation

Requires [Pi coding agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) to be installed first:

```bash
npm install -g @mariozechner/pi-coding-agent
npm install -g @vtemian/pi-config
```

The package automatically symlinks its configuration to `~/.pi/agent/`.

## What's Included

### Subagents

Specialized agents you can delegate tasks to:

| Agent | Purpose |
|-------|---------|
| `commander` | Orchestrator - delegates to specialists |
| `brainstormer` | Design exploration and ideation |
| `codebase-locator` | Fast file/pattern finding |
| `codebase-analyzer` | Deep code analysis |
| `pattern-finder` | Find existing patterns to follow |
| `implementer` | Execute implementation plans |
| `reviewer` | Code review |

### Custom Tools

| Tool | Purpose |
|------|---------|
| `look_at` | Extract file structure without loading full content |
| `ast_grep_search` | AST-aware code pattern search |
| `ast_grep_replace` | AST-aware code replacement |
| `subagent` | Delegate tasks to specialized agents |

### Workflow Commands

| Command | Description |
|---------|-------------|
| `/implement <task>` | Full workflow: scout -> plan -> implement -> review |
| `/review <files>` | Code review |
| `/scout <query>` | Quick codebase reconnaissance |
| `/analyze <module>` | Deep module analysis |
| `/brainstorm <topic>` | Design exploration session |
| `/research <topic>` | Parallel research with multiple agents |

### Hooks

| Hook | Purpose |
|------|---------|
| `comment-checker` | Warns about comments that explain "what" instead of "why" |
| `token-aware-truncation` | Truncates large outputs to prevent context overflow |

## Usage

After installation, just run `pi`:

```bash
pi
```

### Using Subagents

The `subagent` tool delegates tasks to specialized agents. Three modes are available:

**Single agent:**
```json
{ "agent": "codebase-locator", "task": "find all authentication code" }
```

**Parallel execution** (up to 8 tasks, 4 concurrent):
```json
{
  "tasks": [
    { "agent": "codebase-locator", "task": "find all API routes" },
    { "agent": "pattern-finder", "task": "find validation patterns" }
  ]
}
```

**Chained execution** (use `{previous}` to pass results):
```json
{
  "chain": [
    { "agent": "codebase-locator", "task": "find the auth module" },
    { "agent": "codebase-analyzer", "task": "explain how {previous} works" },
    { "agent": "implementer", "task": "based on {previous}, add OAuth support" }
  ]
}
```

### Using Workflow Commands

```
/implement add Redis caching to the session store
/review src/auth/
/scout how does the database connection work?
```

## Managing Installation

```bash
# Check what's installed
pi-config status

# Reinstall (after package updates)
pi-config install

# Remove symlinks
pi-config uninstall
```

## Updating

```bash
npm update -g @vtemian/pi-config
```

## Requirements

- Node.js 18+
- [@mariozechner/pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) installed globally

## How It Works

This package uses Pi's native file discovery. On install, it symlinks:

- `hooks/` -> `~/.pi/agent/hooks/`
- `tools/` -> `~/.pi/agent/tools/`
- `agents/` -> `~/.pi/agent/agents/`
- `commands/` -> `~/.pi/agent/commands/`

Pi automatically discovers and loads these on startup.

## License

MIT