@papi-ai/server 0.7.19 → 0.7.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.19",
+  "version": "0.7.21",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "type": "module",
@@ -18,7 +18,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "npm run build:skills && tsup",
+    "build:skills": "PAPI_SKILLS_OUT=skills/papi-cycle node scripts/export-skills.mjs",
     "build:prompts": "tsup src/prompts.ts --format esm",
     "start": "node dist/index.js",
     "test": "vitest run",
@@ -47,6 +48,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.82.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@papi-ai/skills": "^0.1.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

package/skills/papi-cycle/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md
+
+Project: {{project_name}}
+
+This file is loaded at the start of every agent session. Mechanics for specific phases (planning, building, strategy review, ideas) live in lazy-loaded skills under `.agents/skills/`. Invoke a skill when its description matches the work at hand.
+
+## Skills available
+
+- `papi-plan` — Invoke when starting a new PAPI cycle. Covers plan generation, board management, and cycle scoping rules.
+- `papi-build` — Invoke when executing a build via build_execute. Covers branching, gestalt pre-build check, and post-build audit.
+- `papi-strategy` — Invoke when running strategy_review or making Active Decision changes. Covers strategy review cadence and AD lifecycle.
+- `papi-idea` — Invoke when submitting backlog ideas, registering docs, or filing research. Covers idea pipeline and doc registry conventions.
+- `papi-advanced` — Invoke for cross-project patterns, dogfood-derived workflows, or advanced cycle management.
+
+## Project Identity — Verify Before Editing
+
+On the first `orient` of any session, surface the connected project name to the user (e.g. "Connected to: <project_name>") and confirm it matches what they expect before making any code changes. PAPI projects are scoped by ID; if the wrong PAPI_PROJECT_ID is configured, edits land in the wrong project's history — a hard-to-undo class of mistake.
+
+If the user doesn't recognise the project, stop. To fix it from this chat — no file editing — use the project tools: `project_list` to see their projects, `project_create` to make an empty one for this folder, or `project_switch` to point at the right one. Or pass `project=<id>` on a single call to override for that call only.
+
+## Session Start
+
+When a conversation starts — fresh window, new session, or after context compression — orient before doing anything else:
+
+1. **Run `orient`** — single call that returns cycle number, task counts, in-progress/in-review tasks, strategy review cadence, trends, and recommended next action.
+2. **Fix orphaned tasks silently** — check for feat/task-XXX branches that don't match board status. Fix and report after.
+3. **Summarise:** "You're on Cycle N. X tasks to build, Y builds pending review." or "Cycle N is complete — ready for the next plan."
+4. **Run `build_list` when picking a task** — `orient` shows counts only. `build_list` shows the full task list with handoffs.
+
+**CRITICAL: Check task statuses before acting.**
+- **In Review** = already built. Suggest `review_list` → `review_submit`. **NEVER re-build an In Review task.**
+- **In Progress** = build started but not completed. Check the branch and existing changes before writing new code.
+- **Backlog** = not started. But first check if a `feat/task-XXX` branch already exists with commits — fix it, don't rebuild.
+- If all cycle tasks are Done, suggest `release` or next `plan`.
+
+## Branching & PR Convention
+
+- **All in-cycle, in-module tasks share `feat/cycle-N-<module>`** regardless of complexity. One branch per module per cycle, merged together. Module-less tasks fall back to a per-task branch.
+- **Dependent tasks (any size):** When a task's BUILD HANDOFF lists a `DEPENDS ON` task from the same cycle, `build_execute` automatically reuses the upstream task's branch so commits stack for a single PR. Do not create a separate branch manually.
+- **Commit per task within grouped branches** — traceable git history.
+- **Never use `build_execute` with `light=true` on shared branches.** Light mode commits directly to the current branch without creating a PR. When a shared branch is squash-merged, those commits are collapsed — any CLAUDE.md or documentation changes are stripped. Use light mode only on isolated single-task branches where no squash-merge will occur.
+
+## Plumbing Is Autonomous
+
+Board status updates, branch cleanup, orphaned task fixes, commit/PR/merge for housekeeping — these are mechanical plumbing. **Do them end-to-end without stopping to ask.** Report after the fact.
+
+## Code Before Claims — No Assumptions
+
+**Before making any claim about how the codebase works, read the relevant file first.**
+
+This includes:
+- How a feature is implemented ("it works like X") → read the source
+- Whether something exists ("there's no baseline migration") → check the directory
+- Whether a flow is broken or working → trace it in code
+- What a user would experience → check the actual page/component
+
+Do NOT rely on memory, prior conversation, or inference. Read first, then answer.
+If the answer requires checking 2-3 files, check them all before responding.
+
+## User-Facing Replies — Default Brief
+
+When drafting any external user-facing copy (Discord post, support reply, email, release note, marketing blurb): default to ≤4 sentences, friendly tone, no hidden questions buried in prose. Offer to expand if the user wants more depth. Verbose drafts that need trimming are a recurring friction.
+
+This applies to *output for users*, not internal commit messages, build reports, or technical explanations — those follow normal conventions.
+
+## Quick Work vs PAPI Work
+
+PAPI is for planned work. Quick fixes — just do them. No need for plan or build_execute.
+
+**After completing quick/ad-hoc work** (bug fixes, config changes, small improvements done outside the cycle), call `ad_hoc` to record it. This creates a Done task + build report so the work appears in cycle history and metrics. Don't skip this — unrecorded work is invisible work.
+
+## Data Integrity
+
+- **Use MCP tools for all project data operations.** DB is the source of truth when using the pg adapter.
+- Do NOT read `.papi/` files for context — use MCP tools.
+- `.papi/` files may be stale when using pg adapter. This is expected.
+- **`board_edit` handles cycle membership automatically.** Pass `cycle: <n>` to assign, `cycle: null` to clear (also flips status to Backlog), or `status: "In Cycle"` to auto-assign the active cycle. No manual SQL needed.
+
+## Sub-Agents
+
+Project sub-agents live as markdown files in `.claude/agents/*.md`, each with `name` + `description` frontmatter. Run `agent_list` to see what's available (or read the **Sub-agents** line in `orient`). PAPI discovers them and surfaces them — dispatch one via your harness's Task/Agent tool. Discovery only; PAPI does not manage or invoke agents.

package/skills/papi-cycle/papi-advanced/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: papi-advanced
+description: Invoke for cross-project patterns, dogfood-derived workflows, or advanced cycle management.
+---
+
+# papi-advanced
+
+## When to Start a New Conversation
+
+Start a fresh window when:
+- **After a release** — cycle is done, context is heavy. New window orients in seconds via `orient`.
+- **After 3+ tasks built** — accumulated file reads, diffs, and discussions bloat context. Quality degrades.
+- **Switching modes** — going from building to planning, or from strategy review to building. Each mode benefits from clean context.
+- **After context compression fires** — if you notice earlier messages are missing, the window is getting stale. Open fresh.
+
+Stay in the same window when:
+- Building sequential tasks in a batch (especially XS/S tasks)
+- Mid-task and not yet complete
+- Having a strategic discussion that informs the next action
+
+**Rule of thumb:** If you've been in the same window for 30+ minutes or 3+ tasks, it's time for a fresh one.
+
+## Advanced Patterns
+
+- **Cross-project awareness:** If running multiple PAPI projects, learnings transfer across them via shared patterns and the doc registry.
+- **Dogfood friction:** When something feels painful in the workflow, note it — the `idea` tool turns friction into improvements.
+- **Deferred tasks are intentional:** Tasks moved to Deferred aren't forgotten — they're parked for the right time.
+- **Carry-forward items:** Each plan notes carry-forward from the previous cycle. Check them before planning.

package/skills/papi-cycle/papi-build/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: papi-build
+description: Invoke when executing a build via build_execute. Covers branching, gestalt pre-build check, and post-build audit.
+---
+
+# papi-build
+
+## Post-Build Audit
+
+After every `build_execute` (complete), audit the branch before presenting for human review. This catches bugs and convention violations early.
+
+1. **Identify changed files:** Run `git diff origin/main --name-only` to find modified files. If no changes, report "No changes to audit" and skip.
+2. **Review each changed file** for:
+   - Logic errors, off-by-one mistakes, incorrect conditions
+   - Unhandled edge cases (null, undefined, empty inputs)
+   - Convention violations defined in this CLAUDE.md
+   - Incorrect type narrowing or unsafe casts
+3. **Documentation check:** If any `docs/` files describe behaviour that the change modified, flag as "Doc drift".
+4. **Report:** For each issue: file path, severity (Bug/Convention/Doc drift), what's wrong, how to fix.
+5. **If findings exist:** Run `review_submit` with `request-changes` and the findings. Fix before human review.
+6. **If clean:** Present for human review — "Ready for your review — approve or request changes?"
+
+## Housekeeping — Opt-In Deep Sweep
+
+`orient` runs a fast cheap-checks-only path by default. The deep sweep — orphaned branches, In Review tasks with no PR, stale In Progress branches, unrecorded commits, unregistered docs — is opt-in via `deep_housekeeping: true`.
+
+When to run with `deep_housekeeping: true`:
+1. Before `release` — catch board/branch drift.
+2. After a long break (>1 day since last session) — surface anything that fell off.
+3. When you suspect drift — odd cycle counts, missing PRs.
+
+**Don't run deep on every session start.** It pollutes early context with cross-reference output that's noise 80% of the time. The default fast path tells you what cycle you're on, what's in flight, and what to do next; that's the daily-driver shape.
+
+If the deep sweep surfaces something fixable (orphaned branches, missing PRs), fix it silently and report after — same autonomous-plumbing rule as before.
+
+## Context Compression Recovery
+
+When the system compresses prior messages, immediately:
+1. **Run `orient`** — single call for cycle state
+2. Check your todo list for in-progress work
+3. Run housekeeping checks
+4. **NEVER re-build a task that is already In Review or Done.**
+5. Continue where you left off — don't restart or re-plan
+
+## Tool Use Discipline
+
+Most tool errors are habit issues, not capability issues. Avoid them up front:
+
+- **Ranged reads for large files.** Before `Read`-ing a file you haven't already touched this session, check its size. For files over ~1000 lines, or known-large surfaces (generated SQL, lockfiles, HTML reports, large templates), use `offset` + `limit` from the start instead of hitting the token ceiling.
+- **Search-before-read for unverified paths.** If a path comes from memory or inference rather than a file you've read this session, run `Glob` or list the parent directory first. Don't `Read` paths you haven't confirmed exist.
+- **Prefer Read/Glob/Grep over Bash for file operations.** Bash `cat`/`grep`/`find`/`ls` is the most common source of failed commands and produces unstructured output. Reserve Bash for genuinely shell-only operations (git, gh, package managers, SQL, real pipelines).
+- **Verify-before-recommend.** Before suggesting a new task, hook, or skill, check whether it already exists: `board_view` for tasks, `doc_search` for docs, `ls .claude/hooks/` for hooks. Recommending duplicates of already-shipped work wastes a build slot.

package/skills/papi-cycle/papi-idea/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: papi-idea
+description: Invoke when submitting backlog ideas, registering docs, or filing research. Covers idea pipeline and doc registry conventions.
+---
+
+# papi-idea
+
+## Idea Pipeline (unlocked at cycle 21)
+
+The `idea` tool is your backlog intake — not just for features, but bugs, research, and big ideas.
+
+- When you discover something during a build, submit it via `idea` rather than stopping to fix it.
+- Include a `Reference:` line pointing to relevant docs so the planner has context.
+- Split large ideas into 2-3 focused submissions for better planner scoping.
+- The backlog is the steering wheel — priority + notes shape what gets planned next.
+
+## Doc Registry
+
+Docs are first-class entities. When research or planning produces a stable document:
+- Register it with `doc_register` after it's finalised.
+- Doc summaries travel with tool context — the planner and strategy review can find relevant docs.
+- Keep docs current — update the review header after any change.
+
+## Documentation Maintenance
+
+Before creating a new doc, check `docs/INDEX.md` — it may already exist. When creating or archiving docs, update the index.
+
+After implementing any code change, check if the change affects any documentation in `docs/`. If a doc describes behaviour, architecture, or file interactions that your change modified, update the doc to stay accurate.
+
+When updating a doc, add or update a review header immediately below the title:
+
+```
+# Document Title
+> Last reviewed: task-NNN — DD-MM-YYYY
+```
+
+Replace `task-NNN` with the task ID that triggered the update, and `DD-MM-YYYY` with today's date.

package/skills/papi-cycle/papi-plan/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: papi-plan
+description: Invoke when starting a new PAPI cycle. Covers plan generation, board management, and cycle scoping rules.
+---
+
+# papi-plan
+
+## Workflow Sequences
+
+PAPI tools follow structured flows. The agent manages the cycle workflow automatically — the user should never need to type tool names or remember the flow. Handle the plumbing, surface the summaries.
+
+### Cycle Workflow (auto-managed)
+
+- **Run tools automatically** — don't ask the user to invoke MCP tools manually
+- Before implementing: silently run `build_execute <task_id>` (start phase)
+- After implementing: run `build_execute <task_id>` (complete phase) with report fields
+- After build_execute completes: audit the branch changes for bugs, convention violations, and doc drift (see Post-Build Audit below)
+- After audit with findings: *MUST* automatically run `review_submit` with verdict `request-changes` and a concise summary of the audit findings as the changes requested — the builder fixes these before the task goes to human review
+- After audit clean: present for human review — "Ready for your review — approve or request changes?"
+- User approves/requests changes → run `review_submit` behind the scenes
+
+### The Cycle (main flow)
+
+```
+plan → build_list → build_execute → audit → review_list → review_submit → build_list
+```
+
+1. **plan** — Run at the start of each cycle to generate the cycle plan and populate the board.
+   Next: `build_list` to see prioritised tasks.
+2. **build_list** — View tasks ready for execution, ordered by priority.
+   Next: `build_execute <task_id>` to start a task.
+3. **build_execute** (start) — Creates a feature branch and marks the task In Progress. Returns the build handoff.
+   Next: Implement the task, then `build_execute <task_id>` again with report fields to complete.
+4. **build_execute** (complete) — Submits the build report, commits, and marks the task In Review.
+   Next: Run the post-build audit automatically.
+5. **Post-build audit** — Review branch changes for bugs, convention violations, and doc drift (see Post-Build Audit section below).
+   Next: If findings exist, run `review_submit` with `request-changes` and the audit findings. If clean, proceed to `review_list`.
+6. **review_list** — Shows tasks pending human review (handoff-review or build-acceptance).
+   Next: `review_submit` to approve, accept, or request changes.
+7. **review_submit** — Records the review verdict and updates task status.
+   Next: `build_list` to view next build
+
+   **DO NOT** use `review_submit` as a substitute for `review_list`. If you need to see what is pending review, always call `review_list` first. If `review_list` is unavailable in your tool set (e.g. your MCP client filters parameterless tools), STOP and tell the human their MCP integration is incomplete — never guess at the next pending task. To submit an accept verdict on a build-acceptance review, either pass `reviewer_confirmed: true` or ensure `review_list` has run in the same session within the last 15 minutes. (SUP-2026-010.)
+
+### Strategy Review
+
+```
+strategy_review → strategy_change
+```
+
+- **strategy_review** — Analyses project health, velocity, and estimation accuracy.
+  Next: `strategy_change` if the review recommends adjustments.
+- **strategy_change** — Updates active decisions, north star, or project direction based on review findings.
+
+### Detect Strategic Decisions in Conversation
+
+Watch for: direction changes, architecture shifts, deprioritisation with reasoning, new principles, competitive positioning decisions.
+
+When detected:
+1. Flag it: "That sounds like a strategic direction change — should I run `strategy_change`?"
+2. If confirmed, run `strategy_change` immediately.
+3. If mid-build, finish the current task first.
+
+### Idea Capture
+
+```
+idea → (picked up by next plan)
+```
+
+- **idea** — Captures a new task idea and writes it to the backlog.
+  Next: The next `plan` run will prioritise and schedule it.
+
+### Project Bootstrap
+
+```
+setup → plan
+```
+
+- **setup** — {{setup_description}}
+  Next: `plan` to run the first cycle planning session.
+
+### Board Management
+
+- **board_view** — Read-only view of all tasks on the board.
+- **board_archive** — Removes completed/cancelled tasks from the board to an archive.
+- **board_deprioritise** — Moves a task to a later phase.
+
+### Quick Reference: Tool → Next Step
+
+| Tool | Next Step |
+|------|-----------|
+| `setup` | `plan` |
+| `plan` | `build_list` |
+| `build_list` | `build_execute <task_id>` |
+| `build_execute` (start) | Implement, then `build_execute` (complete) |
+| `build_execute` (complete) | Post-build audit (automatic) |
+| Audit (findings) | `review_submit` with `request-changes` |
+| Audit (clean) | `review_list` |
+| `review_list` | `review_submit` |
+| `review_submit` (approve/accept) | `build_list` |
+| `review_submit` (request-changes) | `build_execute` (redo) or `build_list` |
+| `strategy_review` | `strategy_change` (if needed) |
+| `idea` | Next `plan` picks it up |
+
+## Process Rules
+
+These rules come from 80+ cycles of dogfooding. They prevent the most common sources of wasted time and rework.
+
+### Building
+- **Verify before claiming done.** Hit the endpoint, check the rendered output, confirm the data round-trips. Never say "should work" — prove it works.
+- **Preview frontend changes.** After any UI/styling build, provide the localhost URL so the user can visually review. Don't make them ask for it.
+- **Debug one change at a time.** When fixing issues, make one change, verify it, then move on. Don't stack multiple untested fixes.
+- **Test the write-read roundtrip.** Every data write path must have a verified read path. If you write to DB, confirm the read query returns what was written. This is the #1 source of silent failures.
+- **Test after every build.** Run the project's test suite after implementing. Suggest follow-up tasks from learnings when meaningful.
+- **Build patiently.** Validate each phase against the last. Don't rush through implementation — test through the UI, not just the API.
+
+### Security
+- **Audit before widening access.** Before any build that adds endpoints, modifies auth/RLS, introduces new user types, or changes access controls — review the security implications first. Fix findings before shipping.
+- **Flag access-widening changes.** If a build touches auth, RLS policies, API keys, or user-facing access, note "Security surface reviewed" in the build report's `discovered_issues` or `architecture_notes`.
+- **Never ship secrets.** Do not commit .env files, API keys, or credentials. Check `.gitignore` covers sensitive files before pushing.
+- **Telemetry opt-out.** PAPI collects anonymous usage data (tool name, duration, project ID). To disable, add `"PAPI_TELEMETRY": "off"` to the `env` block in your `.mcp.json`.
+
+### Planning & Scope
+- **NEVER run `plan` more than once per cycle.** Adjust the cycle with `board_deprioritise` or `idea` instead.
+- **NEVER skip cycles.** Complete and release the current cycle before running the next `plan`.
+- **Large plan/handoff outputs:** If the prepare-phase output is too large to pass inline (>50 KB), write it to a file and pass the absolute path via `llm_response_file` instead of `llm_response`. The `plan`, `strategy_review`, and `handoff_generate` apply modes all accept `llm_response_file`. The two parameters are mutually exclusive.
+- **Only build tasks assigned to the current cycle.** Use `build_list` — it filters to current-cycle tasks with handoffs.
+- **Don't ask premature questions.** If the project is in early cycles, don't ask about deployment accounts, hosting providers, OAuth setup, or commercial features. Focus on building core functionality first.
+- **Split large ideas.** If an idea has 3+ concerns, submit it as 2-3 separate ideas so the planner creates properly scoped tasks — not kitchen-sink handoffs.
+- **Auto-release completed cycles.** When all cycle tasks are Done and reviews accepted, run `release` immediately. Forgetting causes cycle number drift and merge conflicts in the next session.
+- **Verify cycle readiness before releasing.** Before calling `release`, run `board_view` to confirm every task in the current cycle has status Done or Cancelled. The review queue is NOT sufficient evidence — `review_list` only shows built-and-pending-review tasks; it does not show Backlog or In Progress tasks. If any task is Backlog or In Progress: (a) build it, (b) move it to the next cycle via `board_edit({ task_id, cycle: N+1 })`, or (c) cancel it via `board_edit`. Do not call `release` until the cycle has no pending work. The `release` tool enforces this server-side and will block with a task list if the check fails.
+
+### Communication
+- **Show task names, not just IDs.** When summarising board state or reconciliation, include task names — e.g. "task-42: Add supplier form" not just "task-42".
+- **Surface the next command.** After each step, tell the user what comes next. Commands should be surfaced, not memorised.
+
+### Stage Readiness
+- **Access-widening stages require auth/security phases.** Before declaring a stage complete, check if it widens who can access the product (e.g. Alpha Distribution, Alpha Cohort). If so, auth hardening and security review must be completed first — not discovered after the fact.
+- **Pattern:** Audit access surface → fix vulnerabilities → then widen access. Never ship access-widening without a security phase.
+
+
+<!-- PAPI_ENRICHMENT_TIER_1 -->
+
+## Batch Building (unlocked at cycle 6)
+
+For cycles with multiple tasks, batch build them without stopping between each:
+- Build XS/S tasks first, then M/L — same-module tasks land on the cycle branch automatically regardless of size
+- One commit per task for traceable history on the shared cycle branch
+- After all tasks built, batch review them together
+
+### Gestalt Pre-Build Check (multi-task cycles)
+
+**Before `build_execute` on the first task of any multi-task cycle, read the cycle as a whole:**
+
+1. Run `build_list` to see every task assigned to the current cycle.
+2. Read the BUILD HANDOFFs together — not one at a time. Look for:
+   - **Shared files** across handoffs — the same path in two FILES LIKELY TOUCHED lists usually means a refactor opportunity, a shared helper to extract first, or a sequencing constraint.
+   - **Shared modules** — multiple tasks in the same module should land on a shared cycle branch (`feat/cycle-N-<module>`) so they merge together.
+   - **Design decisions implicit across tasks** — e.g. one task introduces a new field, a later task consumes it. Build the producer first.
+   - **Module split** — tasks in different modules will land on different cycle branches (`feat/cycle-N-<module>`) and merge separately. Flag any cross-module coordination required before kicking off.
+3. Only then run `build_execute` on the first task.
+
+This is a one-time check at the start of the cycle, not per-task. It catches scope conflicts, redundant work, and ordering hazards that an isolated handoff read can't see. Skip it for single-task cycles.

package/skills/papi-cycle/papi-strategy/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: papi-strategy
+description: Invoke when running strategy_review or making Active Decision changes. Covers strategy review cadence and AD lifecycle.
+---
+
+# papi-strategy
+
+## Strategy Reviews
+
+Every 5 cycles, PAPI offers a strategy review — a deep analysis of velocity, estimation accuracy, active decisions, and project direction.
+
+- **Don't skip them.** They're where compounding value comes from.
+- Strategy reviews run in their own session — don't mix with building.
+- Reviews produce recommendations that feed into the next plan.
+- If the review recommends AD changes, use `strategy_change` to apply them.
+
+## Active Decision Lifecycle
+
+Active Decisions (ADs) track architectural and product choices with confidence levels (LOW → MEDIUM → HIGH).
+
+- Check ADs before making architectural choices — run `health` for the AD summary.
+- ADs are for product/architecture choices only, not process preferences.
+- When new evidence appears, update AD confidence via `strategy_change`.
+- Supersede rather than overwrite — old decisions stay as history.
+- New ADs should include a `### Reversal Trigger` section: specify the signal that would invalidate the stance, the action to take (modify/supersede/abandon), and why writing it now prevents sunk-cost drift later.
+
+
+<!-- PAPI_ENRICHMENT_TIER_2 -->