pi-dev-workflow

Automated code development pipeline for the pi coding agent.

Write → Test → Review → Fix → Verify → Done

Quick Start

/workflow my-project strict create a password hasher with bcrypt... fixes #42
/workflow quick utils create helper functions
/workflow strict auth-service build login API with JWT tokens

Modes

Mode	Pipeline	Gate
default	Write → Test → Review → Fix → Verify → Done	Coverage ≥80%
quick	Write → Test → Verify → Done	None
strict	Write → Test → Review → Fix → Verify → Done	Coverage ≥90%

Usage

/workflow [name] [quick|strict] <spec>

• name — optional project name (auto-generated from spec if omitted)
• mode — optional mode prefix (quick or strict)
• spec — feature description, or path to .md/.txt file

Examples

# Full cycle with custom name
/workflow markdown-parser in @tests create a heading parser...

# Strict mode with linked issue
/workflow strict auth-service create login API with JWT tokens fixes #42

# Quick mode, auto-named
/workflow quick create a set of math utility functions

# From file
/workflow ./specs/feature.md

Pipeline Stages

1. Write

Agent creates implementation in projects/<name>/src/ and tests in projects/<name>/tests/. Commits with wip: prefix.

2. Test

Agent runs test suite. Exit code parsed deterministically — 0 = pass. Commits with test: prefix.

3. Review

Agent reviews code with domain-specific checklist injected based on spec keywords:

Spec keywords	Checklist items
auth, password, login, token	Security: injection, hashing, token safety
api, fetch, http, request	API: error handling, timeouts, response validation
file, fs, read, write, save	I/O: error recovery, missing files, encoding
async, promise, await	Async: error propagation, unhandled rejections
ui, component, render, dom	UI: a11y, loading/empty states, error boundaries
db, database, sql, query	Data: injection, transactions, connection handling

4. Fix

Agent addresses review findings. Commits with fix: prefix. Returns to test stage.

5. Verify

Agent runs tests + coverage. Must meet coverage threshold (80% default, 90% strict). Gate status shown in completion.

6. Done

Workflow finalizes — the completion banner (project name, location, tests, coverage, linked issues) is returned as tool result content from workflow_complete. README, changelog entry, and final commit are generated.

Directory Structure

projects/<name>/
├── src/
│   └── <module>.ts
├── tests/
│   └── <module>.test.ts
├── README.md          ← generated on completion
└── POSTMORTEM.md      ← generated on failure

Tools

Tool	Stage	Description
workflow_next	all	Advance to next stage
workflow_test_result	test, verify	Report test exit code
workflow_review_result	review	Report review findings
workflow_verify_result	verify	Report type-check, lint, coverage
workflow_complete	verify, done	Finalize workflow

Commands

Command	Description
/workflow [name] [mode] <spec>	Start workflow
/workflow:status	Show current stage, gates, issues
/workflow:cancel	Cancel workflow

Git Integration

Auto-commits after each stage with structured messages:

wip: project-name — implementation + tests
test: all passing
fix: project-name — address review feedback
chore: workflow complete — project-name

Issue Linking

Extracts issue references from spec and displays them in completion:

closes #42, resolves RM-123, GH-789

Linked issues appear in the completion banner, README, and changelog.

Changelog

Appends to CHANGELOG.md on completion:

## 2026-05-09 — markdown-parser: fixed trailing whitespace in headings (fixes #42)

Output Artifacts

File	When	Contents
projects/<name>/README.md	Completion	Summary, spec, results table, stats
CHANGELOG.md (root)	Completion	Date, project, summary, linked issues
projects/<name>/POSTMORTEM.md	Failure	Timeline, root cause, spec

Completion Banner

Returned as tool result content from workflow_complete:

✅ **markdown-parser** is complete

📁 **Location:** `projects/markdown-parser/`
🧪 **Tests:** All passing
📊 **Coverage:** 94% ✓ (≥80% required)

Linked: fixes #42

State Persistence

Workflow state persists in session branch entries. Survives context compaction. Restored on session restart.

Installation

Copy index.ts to ~/.pi/agent/extensions/dev-workflow.ts. Restart pi.

cp index.ts ~/.pi/agent/extensions/dev-workflow.ts