brian-lai

PARA-Programming Plugin for Claude Code

Structured planning, automated execution, and independent review for AI-assisted development.

PARA turns ad-hoc prompting into a disciplined engineering process: every task gets a plan, every plan gets reviewed, every implementation follows TDD, and every commit maps to a checklist item. The workflow is designed for agent teams — autonomous agents that can research, plan, execute, review, and ship multi-phase projects with minimal human intervention.

---

Quick Start

# Install the plugin
claude plugin add brian-lai/para-programming-plugin

# Initialize in your project
/para:init

# Run your first task end-to-end
/para:research "add user authentication"
/para:plan "add user authentication"
/para:review --plan
/para:workflow

That's it. /para:workflow handles execution, PR creation, independent review, summarization, and archival — phase by phase — until the work is done.

---

The Workflow

Research → Plan → Review Plan → Execute → Review PR → Summarize → Archive

For multi-phase work, /para:workflow orchestrates this loop automatically across all phases. It creates worktrees for isolation, commits per checklist item, opens PRs, runs independent subagent reviews, and merges — pausing at phase boundaries for human approval (or running fully autonomously with --auto).

Manual vs. Automated

You can run each command individually, or let /para:workflow handle the execution-onward portion automatically:

Manual — run each step yourself: /para:research → /para:plan → /para:review --plan → /para:execute → /para:review --pr → /para:summarize → /para:archive

Automated — after planning and plan review, hand off to the orchestrator: /para:workflow runs the full execute → PR → review → summarize → archive → next phase loop. Add --auto for fully autonomous execution, or --skip-review for speed.

---

Commands

Command	Purpose
/para:init	Initialize PARA structure in a project
/para:research <task>	Deep codebase research before planning
/para:plan <task>	Create a structured implementation plan
/para:review --plan|--pr	Independent subagent review loop
/para:execute	Create worktree, extract todos, start TDD execution
/para:workflow	Orchestrate full cycle across phases
/para:summarize	Generate post-work summary
/para:archive	Archive context, clean up worktrees
/para:status	Show current workflow state
/para:check	Decision helper: should this task use PARA?
/para:help	Quick reference guide

---

How It Works

1. Research

/para:research performs deep codebase exploration and produces a structured document covering architecture, components, API contracts, existing patterns, and gaps. This becomes the primary input for planning — no more ad-hoc exploration during plan creation.

2. Plan

/para:plan creates a collaborative implementation plan through dialogue. It asks clarifying questions, drafts specs and stubs, applies engineering criteria (interface boundaries, graceful degradation, architecture decisions), and runs 2-3 self-review rounds before presenting the plan.

Every implementation step is a checkbox item. Each checkbox becomes one git commit.

3. Review

/para:review spawns an independent subagent to review plans or PRs. The reviewer categorizes issues as MUST FIX, SHOULD FIX, or NIT, and the review loops — with a fresh subagent each round — until there are no blocking issues. Max 5 rounds with convergence detection.

4. Execute

/para:execute creates an isolated git worktree and works through each checklist item following a TDD cycle: confirm spec → write tests → run red → implement → run green → commit. The checklist text is the commit message.

5. Workflow

/para:workflow is the orchestrator. For each phase: execute → create PR → review PR → summarize → merge → archive → next phase. It tracks state in context/context.md for resumability — if interrupted, running it again picks up where it left off.

---

Directory Structure

Per-Project (created by /para:init)

your-project/
├── context/
│   ├── context.md              # Active session state
│   ├── data/                   # Research docs, specs, datasets
│   ├── plans/                  # Implementation plans
│   ├── summaries/              # Post-work reports
│   ├── archives/               # Historical context snapshots
│   └── servers/                # MCP tool wrappers
├── .para-worktrees/            # Git worktree isolation (gitignored)
└── CLAUDE.md                   # Project-specific context

Global (created once)

~/.claude/
└── CLAUDE.md                   # PARA workflow methodology (shared across all projects)

---

Complete Example

# Initialize (first time only)
/para:init