---
slug: "pi-workflow-agent"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/repolife/pi-workflow-agent@main/README.md"
repo: "https://github.com/repolife/pi-workflow-agent"
source_file: "README.md"
branch: "main"
---
# pi-workflow-agent

[![npm version](https://img.shields.io/npm/v/pi-workflow-agent.svg)](https://www.npmjs.com/package/pi-workflow-agent)
[![Pi package](https://img.shields.io/badge/pi-package-6f42c1)](https://pi.dev/packages)

Generic Pi extension for issue-led coding workflows.

It helps Pi classify work, decide whether planning or external memory is needed, guide verification, and land changes without hardcoding any one project or tool.

> Security: Pi extensions run with full system permissions. Review extensions before installing them.

## Install

From a local checkout:

```bash
pi install /absolute/path/to/pi-workflow-agent
```

From npm:

```bash
pi install npm:pi-workflow-agent
```

Pinned npm version:

```bash
pi install npm:pi-workflow-agent@0.1.1
```

From GitHub:

```bash
pi install git:github.com/repolife/pi-workflow-agent@v0.1.1
```

For project-local installation, add `-l`:

```bash
pi install -l npm:pi-workflow-agent@0.1.1
```

## Commands

```text
/workflow start <task>      classify and start a workflow
/workflow classify <task>   classify without editing
/workflow status            show current workflow state
/workflow verify            ask the agent to run relevant verification
/workflow land              ask the agent to update issue state, commit, and push
/workflow reset             clear workflow state
```

## Flow

```text
issue → classify → optional planner → optional memory/context → execute → verify → land
```

The extension does not duplicate repo hook or CI internals. Configure verification commands and let the repo own its checks.

## Project configuration

Optional project config can live at either:

```text
.pi/workflow.json
.workflow-agent.json
```

Example:

```json
{
  "issueTracker": "beads",
  "planner": "gsd",
  "memory": "tolaria",
  "verification": {
    "defaultCommands": ["pnpm test"],
    "preCommitCommand": "pnpm exec lefthook run pre-commit --no-tty"
  }
}
```

## Defaults

Without config, the extension assumes:

- issue tracker: `beads`
- planner: `gsd`
- memory: `optional`
- verification: choose targeted commands from repo scripts/docs

## Design goals

- Generic and reusable across projects.
- Adapter-friendly without requiring adapters up front.
- Transparent classification before edits.
- No project-specific naming or policy.
- No duplicate task tracker.