Pagent Usage Guide

Pagent orchestrates specialist AI agents to transform Product Requirement Documents (PRDs) into working code.

Quick Start

# Interactive TUI (recommended)
pagent ui

# Run with a PRD file
pagent run ./prd.md

# Check agent status
pagent status

Agents

Pagent runs 5 specialist agents in dependency order:

Execution Order

Level 0: architect
Level 1: qa, security (parallel)
Level 2: implementer
Level 3: verifier

Commands

Run Agents

# Run all agents (parallel by default)
pagent run ./prd.md

# Run specific agents
pagent run ./prd.md --agents architect,qa

# Sequential mode
pagent run ./prd.md --sequential

# Resume (skip up-to-date outputs)
pagent run ./prd.md --resume

# Force regeneration
pagent run ./prd.md --force

# Custom output directory
pagent run ./prd.md -o ./docs/

Interactive TUI

pagent ui              # Start fresh
pagent ui ./prd.md     # Pre-fill with PRD
pagent ui --accessible # Screen reader support

Monitor & Control

pagent status                    # Check running agents
pagent logs <agent>              # View agent output
pagent message <agent> "text"    # Send guidance
pagent stop <agent>              # Stop specific agent
pagent stop --all                # Stop all agents

MCP Server

pagent mcp                                  # Stdio (Claude Desktop)
pagent mcp --transport http --port 8080     # HTTP mode
pagent mcp --transport http --oauth \
  --issuer https://company.okta.com \
  --audience api://pagent                   # With OAuth

Personas

Control implementation style:

pagent run ./prd.md --persona production

Configuration

Initialize config:

pagent init

Creates .pagent/config.yaml:

output_dir: ./outputs
timeout: 300
persona: balanced

preferences:
  api_style: rest      # rest | graphql | grpc
  language: go         # go | python | typescript
  testing_depth: unit  # none | unit | integration | e2e
  containerized: true
  include_ci: true

stack:
  cloud: aws
  compute: kubernetes
  database: postgres
  cache: redis

Writing a PRD

A good PRD includes:

# Product: [Name]

## Problem Statement
What problem are we solving?

## Features
- Feature 1: description
- Feature 2: description

## Requirements
- Functional requirements
- Non-functional requirements (performance, security)

## Constraints
- Technology constraints
- Timeline constraints

Workflows

Quick Architecture Review

pagent run ./prd.md --agents architect
# Review architecture.md, iterate on PRD

Full Pipeline

pagent ui ./prd.md
# Select production persona
# Run all agents
cd outputs/code && go build ./...

Iterative Development

pagent run ./prd.md --agents architect
# Review architecture.md
pagent run ./prd.md --resume  # Run remaining agents

Troubleshooting