PAPI: Persistent Adaptive Project Intelligence

Record work done outside the normal cycle. Creates a Done task with a lightweight build report, or associates work with an existing task if task_id is provided (without changing task status — use build_execute for status transitions). Use for quick fixes, bug patches, or ad-hoc changes. Does not call the Anthropic API.

View one or all Active Decisions with full bodies. Use when you need to read the complete reasoning and evidence behind a specific AD before running strategy_change.

List the sub-agents discovered in the project's `.claude/agents/*.md` files (read-only). Returns each agent's name and description so you can see which specialised sub-agents are available before dispatching one via the Task/Agent tool. Discovery only — does not invoke or manage agents.

Import an existing backlog from another tool into PAPI as Backlog tasks, removing the "start from an empty board" wall. PAPI never connects to the source tool — YOU (the host) read the export and pass it here. Flat-file sources (csv, markdown) take a `raw` string; structured sources (linear) take a `rows` array you read via that tool's MCP. Import is one-way and idempotent: re-running the same import does NOT create duplicates. Shipped sources: csv, markdown, linear. trello/todoist/notion are reserved but not implemented yet. Does not call the Anthropic API.

Archive tasks from the Board to the archive file. When both phase and status are provided, only tasks matching BOTH are archived (AND logic). When only one is provided, all matching tasks are archived. Does not call the Anthropic API.

Remove a task from the current cycle. Four actions: "backlog" (not now, maybe later — preserves handoff), "defer" (valid but premature — hidden from planner), "block" (waiting on external dependency — visible on board but skipped by planner), "cancel" (don't want this — permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.

Edit fields on an existing task. Supports title, priority, complexity, module, epic, phase, notes (with notes_mode for append/replace/clear), status, maturity, and cycle (number or null). Pass task_id plus any fields to update. Does not call the Anthropic API.

Holistic board review — backlog + deferred tasks in one pass. Surfaces strategic context (ADs, phases, docs), grouping signals, merge candidates, priority drift, and stale tasks. "prepare" assembles context for you to analyse; "apply" commits your decisions after user confirmation. Does not call the Anthropic API.

View the Board. To find a SPECIFIC task or subset, FILTER FIRST — do not dump the whole board: pass task_id for one task (full detail), query="<text>" for a title/notes substring match, or cycle=<n> for one cycle. Combine with status/phase. By default shows active tasks only (excludes Done/Cancelled), sorted by priority, limited to 50; titles are truncated in the table (single-task lookup shows the full title). Use status="all" to see everything, mode="summary" for counts only. Does not call the Anthropic API.

Report a bug OR submit an idea. Routing: a bug about PAPI itself (a PAPI tool/MCP error, the connector, a handoff/cycle problem) auto-submits UPSTREAM to PAPI maintainers with diagnostics — you do NOT need to set report=true for these. A bug in the user's OWN project auto-files as a Backlog task on their board. IMPORTANT: report=true is ONLY for a genuine PAPI-product defect — it is NOT the catch-all for "not about my app". A bug in the user's harness/editor/OS/git/other tooling (e.g. Claude Code, Codex, VS Code, a shell command) is NOT a PAPI bug: file it on the user's own board (report=false / default) or that tool's own tracker, never upstream. Override the routing explicitly: report=true forces upstream (PAPI-product only), report=false forces the user's own board. Set `type` ("bug"/"idea") and optional notify-when-fixed / contact-ok consent for upstream submissions. Does not call the Anthropic API.

List the upstream bug/idea reports YOU filed to the PAPI maintainers (via the `bug` tool with report=true or an auto-routed PAPI bug), newest first. Read-only. Shows each report's id, kind (bug/idea), triage status, description, and when it was filed. Scoped to your own submissions only — never another user's. Requires a database adapter (pg or hosted proxy); the local md adapter has no upstream store. Does not call the Anthropic API.

Cancel a build task with a reason. Sets the task status to Cancelled and records the closure reason. Does not call the Anthropic API.

Show the full BUILD HANDOFF for a specific task, including scope, acceptance criteria, and implementation guidance. Does not call the Anthropic API.

Build one task with its spec, its branch and its record kept for you. Starting a build hands back that task's BUILD HANDOFF (scope, what is out of scope, acceptance criteria, the decisions that constrain it, and what recent builds in the same area already learned or ruled out), puts the work on the right branch, and marks the task In Progress so a second session can see it is taken. Completing it records what actually happened: effort against estimate, surprises, dead ends, and bugs found outside the scope. That record is what later cycles are sized and planned from, so nothing has to be remembered. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish — do not wait for user confirmation between start and complete. Never call on tasks that are already In Review or Done. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.

List cycle tasks that have BUILD HANDOFFs ready for execution. Shows task ID, title, status, priority, and complexity. In Progress tasks appear first, then Backlog. Does not call the Anthropic API.

Add a contributor to a project by email, or change an existing member's role (owner-only). The person must already have a PAPI account. Grants membership on project_contributors. Pass role="editor" for a working teammate who needs to run the full cycle — the default, "viewer", cannot release. Calling it again with a different role promotes or demotes that member.

List the current project's contributors (any project member). Shows each member's email, display name, role, and join date. Does not call the Anthropic API.

Remove a contributor from the current project by email (owner-only). Deletes their project_contributors row — they lose contributors-tier visibility.

Record a settled build rule once so every future task on this project is told about it, instead of re-explaining it each session. Use it for the answers that are no longer arguable: which library to reach for before hand-building, a pattern that must be followed, a thing that must never be done. Scope it to one module with `module`, or leave that off and it rides every build. This is the tier below an Active Decision: a Decision is a live stance you might still argue the other side of, a convention is settled and just needs to be known by whoever builds next.

List the build rules this project has declared, with the id needed to remove one. Shows which rules ride every build and which are scoped to a single module.

Remove a declared build rule so it stops appearing in future builds. Takes the id from `convention_list`. Existing handoffs already generated are unaffected; the next build no longer carries it.

Mark a discovered_issue (cycle_learnings row, category="issue") as resolved. Pass the learning_id you saw in orient / learning_action list output. The row stays in the database for history, but default reads exclude it. Use this when the underlying fix has actually landed — NOT when you just created a follow-up task (that is `learning_action mark` with action_taken="task_created"). Optional `note` is recorded as resolved_by.

Promote a single pending action from a registered doc into a Backlog task. The new task gets a `Reference:` line pointing to the source doc, and the doc action is marked resolved with `linkedTaskId` set. Use to close the research-to-action loop — turn unactioned findings into trackable cycle work. Identify the doc by `doc_path` (preferred) or `doc_id`, and the action by 0-based `action_index` (as listed in `doc_search` output).

Permanently delete a registered doc. Guarded: ALLOWED only for the doc's creator or the project owner, and only when nothing depends on it — a delete is BLOCKED if another doc supersedes it, or a task references it (doc_ref) or a linked action. The guard never cascade-deletes dependents; resolve the dependency first. Identify the doc by `doc_path` (preferred) or `doc_id`.

Read a registered document's stored BODY back out of the database, and optionally restore it to disk. This is the recovery path: when a doc is gone from the working tree — a branch switch, a stash, a gitignored docs/private/ folder that never made it into git — doc_read is how the content comes back. Identify the doc by path or UUID via `id_or_path`. Pass `write_to_disk: true` to write the body back to its registered path; an existing file with DIFFERENT content is never overwritten (the conflict is reported and nothing is written). Bodies are stored by doc_register from C356 onward, so a doc registered before that, or one whose body was skipped at a storage ceiling, has metadata but no body — doc_read says so plainly rather than returning an empty document.

Register or update a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata, a structured summary, AND the document body (task-3017) so a doc survives a branch switch, an autostash, or a gitignored docs/private/ folder — pass `body`, or omit it and the file is read from disk when a local workspace is available. Bodies are stored per-user against a plan ceiling; at the ceiling the registration still succeeds and only the body is skipped. Only .md paths are accepted. An untracked doc is still committed at registration to make it durable (or you get a loud warning if it cannot be). Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.

Persist the display order of docs within this project. Pass `doc_ids` as the full desired sequence of doc UUIDs — each doc's position is saved so the dashboard renders them in that order. Ids not in this project are ignored.

Scan docs/ and plans directories for unregistered .md files. Returns a list of files not yet in the doc registry. Use this to find docs that need registration.

Search the doc registry for documents by type, tags, keyword, or pending actions. Returns summaries, not full content. Use for context gathering in plan, strategy review, and idea dedup.

Read Active Decisions from sibling PAPI projects that share the same Supabase instance. Requires PAPI_SIBLING_PROJECT_IDS env var (comma-separated project UUIDs). Returns ADs labelled by source project — useful for cross-project architectural alignment. pg adapter only — returns an error if using md or proxy adapter.

Generate BUILD HANDOFFs for cycle tasks that don't have one yet. Run after `plan` (with skip_handoffs=true) or to regenerate stale handoffs. Uses the prepare/apply pattern — first call returns a prompt, second call persists results.

Create or update a horizon, stage, or phase in the project hierarchy (AD-14). For stages and horizons this UPSERTS: if the named entity exists it is updated, otherwise it is CREATED (pass a label). Phases are update-only (they evolve via plan/strategy). For stages you can set exit_criteria (a checklist), or flip a single criterion with set_criterion_met. NEVER auto-advances — progression is human-in-loop via strategy_review. Does not call the Anthropic API.

Capture an idea as a Backlog task. The next plan run will triage and scope it. Use anytime to log bugs, feature requests, or improvements without interrupting the current cycle. IMPORTANT: If this idea originates from a research or planning session, you MUST include a Reference: line in notes pointing to the source doc. Without it, the planner has no context and will misinterpret the intent. Does not call the Anthropic API.

Write the MCP config file that connects this project to PAPI. Generates .mcp.json, or the equivalent for whichever MCP client you use — Claude Code, Cursor, VS Code, Windsurf, OpenCode, Amazon Q, Kilo Code, Gemini CLI, Codex CLI, or Hermes Agent. Config-only — does not create any project data. Run this first, then run `setup` to create your PAPI project.

Sync this project's harness inventory — skills, sub-agents, hooks, and MCP tools — to the database so the dashboard can surface it. Gated by a cheap change-fingerprint: a no-op when the harness hasn't changed since the last sync. Set force=true to re-scan and write regardless. Runs automatically at setup and release; use this for an explicit refresh after editing your harness.

Join a project that already exists, as a new team member. Run this instead of `setup` when someone else already set the project up — setup is for creating a project, and running it as a joiner writes scaffolding into a repo that already has it. `join` confirms which project you are bound to, shows the Active Decisions and canon docs you are expected to read, and shows the task pool you can claim from. It writes NOTHING to your repo. Does not call the Anthropic API.

Mark a cycle learning as actioned (linking it to a task or idea) or list unactioned learnings. Use "mark" to close out a learning after you've submitted an idea or created a task for it. Use "list" to see which learnings from recent cycles still need follow-up.

Session orientation — run this FIRST at session start before any other tool. Single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, recommended next action, and a release reminder when all cycle tasks are Done but release has not run. Read-only, does not modify any files. PAPI detects build capability from the connecting harness (clientInfo); pass `environment` only to override that detection for git-dependent recommendations (build_execute, release, review_submit).

Say "papi" to check in with Papi — an alias for `orient`. Run this FIRST at session start: it returns your cycle number, task counts, in-progress/in-review work, strategy-review cadence, a velocity snapshot, and the recommended next action. Identical to `orient` (same inputs, same output); use whichever name you prefer. Read-only.

Turn a backlog into one scoped cycle of work, with a written spec for every task in it. plan reads the whole board, the decisions this project has already taken, and how much it actually delivered in recent cycles, then prioritises what to do next and writes a per-task BUILD HANDOFF: scope, what is deliberately out of scope, acceptance criteria, files likely touched, security notes, and the shared branch each task belongs on. It also reports board health, so stale, blocked and drifting work is visible instead of accumulating. This is not the same as planning inside one session: the cycle, the specs and the reasoning are stored, so the next session, the next tool, or the next person picks up where this one stopped. Run once per cycle, after setup the first time, or after completing all builds AND running release for the previous cycle. NEVER call when unbuilt cycle tasks exist: build and release first. First call returns a planning prompt for you to execute (prepare phase). Then call again with mode "apply" and your output to write results. Use skip_handoffs=true for large backlogs, and generate handoffs separately via `handoff_generate`.

Create an EMPTY PAPI project for the current workspace (no plan, no seeded backlog) and return its id. Idempotent: re-running in the same folder (or with the same name) returns the EXISTING project instead of creating a duplicate. Use when "set up papi here" / "create a project" and none matches this folder. No Anthropic API.

List the PAPI projects on your account (id, name, slug, mapped folder). Use to see which project you are about to write to, or to find the id/slug to pass to project_switch or the per-call `project` arg. No Anthropic API.

Select a project you own by id or slug and map the current folder to it (sets papi_dir on local stdio). Use when "switch to golf" / "point papi at <project>". Fails closed if the project is not on your account. No Anthropic API.

Cut a versioned release — creates a git tag, generates CHANGELOG.md, and pushes to remote. Pass skipVersion=true to update CHANGELOG and close the cycle without creating a tag or bumping version numbers.

Claim a Pending Review from the shared cross-user review queue so you are the one reviewing it. Atomic first-claim-wins — two reviewers cannot grab the same build. After claiming, run review_submit to record your verdict. Owner-or-active-member only. Does not call the Anthropic API.

List tasks ready for your sign-off — shows completed builds waiting for approval or feedback. Does not call the Anthropic API.

Record a review verdict on a completed build (build-acceptance) or task plan (handoff-review). ALWAYS ask the human for their verdict before calling — never auto-submit without human input. Accept moves the task to Done, request-changes sends it back for rework, reject discards the build. Updates task status based on the verdict. On handoff-review with suggested changes, returns a prompt to revise the BUILD HANDOFF. DO NOT use this tool as a substitute for review_list. If you need to see what is pending review, call review_list first. If review_list is unavailable in your tool set, STOP and tell the human their MCP integration is incomplete rather than guessing at the next pending task. (SUP-2026-010.)

Decompose a brief-class task (Large/XL, too large to build directly) into a structured scope document. Two phases, like plan/strategy — PAPI never calls a model itself (AD-58): first call (mode "prepare") returns a scoping prompt for YOU to run in your own AI workspace; then call again (mode "apply") with your markdown output in llm_response to write docs/scopes/<task-id>.md, register it, and mark the source task decomposed. Use before planning a cycle that includes brief-class tasks.