Key Concepts

The building blocks behind PAPI. Understand these and the rest of the workflow clicks into place.

Active Decisions

Active Decisions (ADs) are architectural and product choices that PAPI tracks over time. They capture what you decided, why, what alternatives you considered, and when to revisit the decision. Think of them as ADRs (Architecture Decision Records) that live inside your project and surface automatically during planning and strategy reviews.

Every AD has a confidence level: LOW, MEDIUM, or HIGH. This isn't about how confident you feel — it's about how much evidence backs the decision. A new decision starts at LOW. As cycles pass and the decision holds up in practice, confidence rises. If a strategy review surfaces contradictory evidence, confidence drops.

You create and update ADs using strategy_change. During strategy reviews (every 5 cycles), the reviewer examines all ADs and proposes confidence updates or new decisions. ADs can also be superseded — when a decision is replaced, the old one stays as history and the new one links to it.

Reversal Triggers

Every AD should include a Reversal Trigger— a specific signal that would invalidate the stance. For example: “Revisit when path count exceeds 100 entries” or “Revisit when multi-user deployment requires different adapter strategies.” Writing the trigger now prevents sunk-cost drift later.

BUILD HANDOFFs

A BUILD HANDOFF is a structured spec that tells an AI agent exactly what to build. It's the key artifact that makes PAPI's “cold-start LLM execution” work — a fresh agent can pick up a task from nothing but its handoff and produce correct code.

Structure

Every handoff includes these sections:

The Scope Boundaryis especially important. It's the explicit “no” list — things that might seem related but are explicitly out of scope. This prevents agents from “while I'm here" expansion that balloons a Small task into a Large one.

The Pre-Mortemsection (for projects with 10+ cycles) lists the most likely technical blockers based on patterns from recent build reports in the same module. It's generated from dogfood data — real friction from real builds.

Cycles

A cycle is one complete lap: plan → build → review → release. PAPI projects run cycle after cycle indefinitely, with each one producing a versioned release and a set of build reports that feed into the next.

Carry-Forward

Not everything fits neatly into one cycle. Carry-forward itemsare notes from the planner that survive across cycle boundaries — things that should be addressed soon but didn't make it into the current cycle. The planner reviews carry-forward when selecting tasks for the next cycle.

Velocity and Estimation

Every build report captures estimated effort vs actual effort. Over time, PAPI tracks your estimation accuracy — whether you tend to over- or under-estimate. This data surfaces in strategy reviews and helps the planner size future cycles more accurately. The trend line (balanced, optimistic, or pessimistic) is more useful than any single data point.

Roles & Access

PAPI uses a 3-role model for team collaboration. Each role has a specific set of capabilities enforced at the database level by Row Level Security (RLS) policies.

Owner

Full control. The owner can manage team members, send invitations, reset cycles, and delete projects. Every project has exactly one owner — the person who created it. Owners can also perform all editor and viewer actions.

Editor

Build and modify. Editors can create tasks, execute builds, submit reviews, and update task details. They can view everything the owner can, but cannot manage team membership or change project-level settings.

Viewer

Read-only. Viewers can see the board, reports, strategy reviews, and cycle history. They cannot create tasks, start builds, or modify anything. Useful for stakeholders who need visibility without write access.

Invitations

Owners invite team members by email. The invitation creates a token-based link with a 7-day expiry. When the invitee accepts, they're added to project_contributorswith the assigned role. The invitation flow works even for users who don't have a PAPI account yet — they'll be prompted to sign up during acceptance.