Core Workflow

The PAPI cycle in seven stages. Each stage is a single tool call (or a prepare/apply pair). Follow them in order and your project stays on track.

Setup

Create a PAPI project for your codebase. This is a one-time operation that generates a Product Brief, initial Active Decisions, and writes a CLAUDE.md (or AGENTS.md) with project conventions.

How it works

papi setup uses a two-phase pattern:

# Phase 1 — Prepare (returns prompts for the LLM)
papi_setup(project_name="my-project")

# The LLM fills in brief, ADs, conventions...
# Then phase 2 persists everything:
papi_setup(mode="apply", brief_response="...", ad_seed_response="...")

Tip

For existing codebases, pass existing_project: true. PAPI will scan your repo structure and generate context-aware setup artifacts instead of starting from scratch.

Session Start — Orient

Every session begins with orient. It returns your cycle number, task counts by status, in-progress and in-review tasks, velocity trends, and a recommended next action. Think of it as the “what should I do now?” call.

papi_orient()

The response tells you whether to build, review, release, or plan. If all cycle tasks are Done, it will suggest running release. If there are tasks in review, it points you to review_list.

Tip

Always call orient first — even before reading files or checking git status. It gives you the full picture in one call.

Planning

The planner selects tasks from your backlog, generates detailed BUILD HANDOFF specs, and assigns them to the next cycle. Like setup, it uses the prepare/apply pattern.

Prepare phase

papi_plan(mode="prepare")

# Returns a planning prompt with full board context,
# recent build reports, active decisions, and carry-forward items.

The LLM analyses the backlog and produces a cycle plan. Then you persist it:

Apply phase

papi_plan(
  mode="apply",
  cycle_number=11,
  llm_response="<your plan output>"
)

This writes the selected tasks, BUILD HANDOFFs, and any board corrections to the database. Tasks move from Backlog to In Cycle.

Tip

For large backlogs, use skip_handoffs: true to run planning without generating handoffs. Then run handoff_generate separately to create handoffs for the selected tasks.

Building

Each task gets built from its BUILD HANDOFF. The build process has two calls: start (returns the handoff) and complete (submits the build report).

Start a build

papi_build_execute(task_id="task-42")

# Returns the BUILD HANDOFF with scope, acceptance criteria,
# files likely touched, and effort estimate.
# Creates a feature branch: feat/cycle-N-<module>

Complete a build

papi_build_execute(
  task_id="task-42",
  completed="yes",
  effort="M",
  estimated_effort="M",
  surprises="None",
  discovered_issues="None",
  architecture_notes="Created shared helper for doc sidebar..."
)

The build report captures what happened: actual effort, surprises, discovered issues, and architecture notes. This data feeds into future planning and strategy reviews.

Branching convention

Same-module tasks share a branch (feat/cycle-N-module) with one commit per task. For XS/S tasks on isolated branches, use light=true to skip PR creation.

Reviewing

After a build completes, it moves to In Review. The human reviews the code and submits a verdict.

List pending reviews

papi_review_list()

Submit a verdict

papi_review_submit(
  task_id="task-42",
  stage="build-acceptance",
  verdict="accept",           # or "request-changes" or "reject"
  comments="Looks good — clean implementation."
)

accept moves the task to Done.request-changes sends it back to In Progresswith your feedback. reject discards the build.

Tip

Always call review_listbefore submitting. You need to see what's pending before you can review it.

Releasing

When all cycle tasks are Done (or Cancelled), cut a release. This creates a git tag, generates CHANGELOG.md, and pushes to the remote.

papi_release(
  branch="main",
  version="v0.4.0"
)

The release aggregates all build reports from the cycle into a changelog entry. It also records any observations you want to capture about the cycle (friction, methodology signals, commercial insights).

Tip

After release, the next session's orient will detect that the cycle is complete and suggest running plan for the next one.

Strategy Reviews

Every 5 cycles, PAPI offers a strategy review — a deep analysis of velocity, estimation accuracy, active decisions, and project direction. It uses the same prepare/apply pattern as planning.

# Prepare — returns a review prompt with full project history
papi_strategy_review(mode="prepare")

# Apply — persist your analysis and AD updates
papi_strategy_review(
  mode="apply",
  cycle_number=10,
  llm_response="<your review output>"
)

Strategy reviews produce recommendations and potential Active Decision updates that feed into the next plan. They're the compounding layer: every review makes future cycles smarter.

Tip

Run strategy reviews in their own session — don't mix them with building. They need the full context window for deep analysis.

The Cycle in Summary

orient → plan → build → review → release → repeat
                                    ↑
                            strategy review (every 5 cycles)

That's the full PAPI workflow. Each stage is one tool call (or a prepare/apply pair). The cycle repeats indefinitely, with strategy reviews every 5 cycles providing course corrections and compounding learnings.

Cheat Sheet

Dashboard Guide