@papi-ai/skills 0.1.0

package/skills/deployment-completeness-audit/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: deployment-completeness-audit
+description: >
+  Audit the codebase for "built but not deployed" patterns — code that exists
+  but isn't wired up, deployed, or executed. Catches orphaned SQL functions,
+  unapplied migrations, env vars read but never set, fallback paths that always
+  run because the primary never activates, and dependency drift. Use when the
+  user says "deployment audit", "wired check", "completeness audit", "is anything
+  built but not deployed", or every 10 cycles as a recurring health check.
+  Read-only — reports findings only, does not fix them.
+---
+
+# Deployment Completeness Audit
+
+Find code that has been built but never connected, deployed, or executed. This is the highest-leverage audit class for fast-moving projects: it catches the gap between "code merged" and "feature live", which is where most silent regressions hide.
+
+## When to Run
+
+- Every 10 cycles as a recurring health check (alongside `/security-audit`)
+- After major schema or adapter changes (high drift risk)
+- When you discover one instance of "built but not deployed" — assume more exist
+- Before a strategy review (so findings inform the next plan)
+- When the user explicitly says "deployment audit", "wired check", "is anything built but not deployed"
+
+## Why This Class of Bug Matters
+
+Past PAPI incidents that match this pattern:
+- `get_plan_context()` SQL function — code path written C49, migration written C52, never deployed. 6 weeks of fallback running silently. Discovered C242 during plumbing audit.
+- C236-C238 handoff drift — handoffs written against imagined schema.
+- C239-C241 grouped-branch merges — `review_submit` reported success while code never landed on main.
+
+The common thread: **two layers drift apart silently because nothing forces them to stay in sync at PR time.** Tests pass on the wrong layer. The codebase looks complete. The fallback path covers the gap.
+
+## Scope
+
+This skill is read-only. Use `Grep`, `Glob`, `Read` only. No `Bash`, no `Edit`, no `Write` other than the final report. The skill produces a findings report — humans (or follow-up cycle tasks) implement fixes.
+
+## Steps
+
+### 1. Orphaned SQL Assets
+
+The most common pattern in PAPI: SQL functions called via try-catch with a fallback that always succeeds.
+
+**Patterns to grep for:**
+- `\.unsafe\(['"]\s*SELECT\s+\w+\(`  — direct function calls via postgres.js
+- `\.rpc\(['"][a-z_]+['"]` — Supabase RPC calls
+- Try-catch blocks where the catch logs `not available` or `falling back`
+- `// TODO.*deploy` or `// FIXME.*migration` near SQL strings
+
+**For each match, verify:**
+1. Is the function defined in any file under `supabase/migrations/`?
+2. If yes, does the migration filename appear in `supabase_migrations.schema_migrations` table? (If you don't have DB access, flag as "deployment unverified — check via `supabase migration list --linked`".)
+3. Read the call site's catch block — does it always log "not available" / "falling back"? That's strong evidence the function isn't deployed.
+4. Compare the SQL function definition (in migration) to the JS fallback path — do they return the **same shape**? Same filters? Same columns? Drift here causes silent regressions even after the function is deployed.
+
+**Severity:**
+- P0 if the call site is in a hot path (plan, build, review) AND the function and fallback diverge in output shape — deploying would corrupt downstream consumers.
+- P1 if function is defined but unapplied, and fallback works correctly.
+- P2 if function exists with an applied migration but is never actually called (dead code).
+
+### 2. Environment & Config Gates
+
+Code paths gated by env vars or feature flags that are never set.
+
+**For env vars:**
+1. Grep all `process\.env\.([A-Z_]+)` reads in production code (`packages/`, `app/`, `lib/`, `src/`).
+2. Grep all `.env*` files and any `vercel.json`, `supabase/config.toml`, deployment docs for the same names.
+3. Flag any var read in code that isn't defined anywhere — that code path never runs.
+4. Flag any var defined but never read — dead config.
+
+**For feature flags:**
+1. Grep for patterns like `FEATURE_FLAG_`, `ENABLE_`, `USE_NEW_`, `flags\.`, `featureFlags\.`.
+2. Trace each flag to its config source. If the config always returns false (or is commented out), the gated code is dead.
+
+**Severity:**
+- P1 for env vars/flags gating user-facing functionality that never activates.
+- P2 for vars that gate optional optimizations (the system works without them).
+- P3 for legacy flags left over from completed migrations.
+
+### 3. Unexercised Code Paths
+
+Code that exists but the runtime never reaches.
+
+**Patterns:**
+- Try-catch where the catch is the de-facto primary (see Step 1, but generalize beyond SQL).
+- Conditionals where the true branch requires conditions that never occur in production (e.g. `if (process.env.NODE_ENV === 'staging')` but the project only deploys to prod).
+- Background jobs registered (cron schedules, queue handlers, scheduled functions) but no scheduler/runtime triggers them. Look in `supabase/functions/`, `app/api/cron/`, any `cron.json` / `vercel.json` schedules vs the handlers that exist in code.
+- Event listeners attached but events never emitted — search for `addEventListener`, `.on(`, observer registrations, then trace whether anything calls the corresponding emitter.
+
+**Severity:**
+- P1 if the unexercised path is the documented behaviour (users expect it to work).
+- P2 if it's a fallback that's silently being used in place of the primary.
+- P3 if it's defensive code that would only fire on rare conditions.
+
+### 4. Dependency Drift
+
+Packages installed but unused, or imports that exist but aren't called.
+
+**Steps:**
+1. Read `package.json` `dependencies` (NOT `devDependencies`).
+2. For each, grep production code (excluding `__tests__/`, `*.test.ts`, `tests/`) for any import.
+3. Flag packages with zero production imports.
+4. For each imported package, sample-check whether the imported symbols are actually used (i.e. an `import` statement isn't enough — the value must appear elsewhere in the file).
+
+**Common false positives:**
+- Type-only packages (`@types/*`) — exclude.
+- Packages used via dynamic `require()` or `await import()` — search both forms before flagging.
+- Build-time tooling (some packages legitimately appear only in config files).
+
+**Severity:**
+- P2 for unused production deps (security surface + bundle size + cost at scale).
+- P3 for unused imports (cleanup, not urgent).
+
+### 5. Schema/Code Parity
+
+Database fields referenced in code that don't exist in migrations, or vice versa.
+
+**Steps:**
+1. Glob `supabase/migrations/*.sql`. Extract column names per table from `CREATE TABLE`, `ALTER TABLE ... ADD COLUMN`.
+2. Read `packages/adapter-md/src/types.ts` (or equivalent type definitions).
+3. Compare: does every field in the TypeScript types correspond to a column in migrations? Does every column have a TS field?
+4. Flag fields in code that don't exist in DB (would cause runtime errors on certain code paths).
+5. Flag columns in DB never read by code (dead schema).
+
+**Also check:** Adapter-pg implementation files — do they reference column names not in any migration? Especially common after partial taxonomy migrations (e.g. `sprint_tasks` → `cycle_tasks` rename leaving stragglers).
+
+**Severity:**
+- P0 if code reads a column that doesn't exist (runtime crash on first call).
+- P1 for write paths that target non-existent columns (silent data loss).
+- P2 for dead columns (cleanup, costs storage at scale).
+
+### 6. Multi-Adapter / Multi-Surface Drift (PAPI-specific)
+
+PAPI has three adapters: `md`, `pg`, `proxy` (data-proxy edge function). All three must implement the same interface.
+
+**Steps:**
+1. Read `packages/adapter-md/src/types.ts` for the `PapiAdapter` interface.
+2. For each method, verify implementations exist in:
+   - `packages/adapter-md/src/adapter.ts`
+   - `packages/adapter-pg/src/pg-papi-adapter.ts`
+   - `supabase/functions/data-proxy/index.ts`
+3. Flag missing implementations.
+4. **For methods stubbed with `return undefined` or `throw "not implemented"`** — verify the stub is intentional (look for a comment explaining why) vs accidental. An intentional stub (e.g. data-proxy returning undefined for `getPlanContextSummary` to force fallback) is correct architecture, not a bug. Flag missing or unclear comments.
+
+**Severity:**
+- P0 if adapters diverge in production behaviour (silent data drift between local and external users).
+- P1 if a method is missing in one adapter and external users hit it.
+- P2 if intentional stubs lack explanatory comments (future-proofing).
+
+### 7. Migration File vs Applied Migration
+
+If you can run SQL via the Supabase MCP, compare:
+
+```sql
+SELECT name FROM supabase_migrations.schema_migrations ORDER BY name;
+```
+
+vs `ls supabase/migrations/`. Anything in the file system but not in the table is unapplied.
+
+If you can't access the DB directly, do the inferential check:
+- Find the most recent migration file by date.
+- Search the dogfood log / git log / build reports for evidence it was deployed (e.g. "deployed migration X" notes).
+- If no evidence, flag as "deployment unverified".
+
+**Severity:**
+- P0 if an unapplied migration is required by code that's already shipped (production bug waiting to fire).
+- P1 if unapplied but only required by a fallback path (silent suboptimality).
+- P2 if unapplied and unused (cleanup).
+
+## Output Format
+
+Save findings as a markdown report at `docs/audits/deployment-completeness-c<NNN>.md` (where NNN is current cycle). Include this frontmatter:
+
+```yaml
+---
+title: Deployment Completeness Audit — Cycle <NNN>
+type: audit
+created: <ISO date>
+cycle: <NNN>
+status: active
+---
+```
+
+Body structure:
+
+```markdown
+# Deployment Completeness Audit — Cycle <NNN>
+
+## Summary
+
+- P0 findings: N
+- P1 findings: N
+- P2 findings: N
+- P3 findings: N
+
+## What Was Checked
+
+- [ ] Orphaned SQL assets
+- [ ] Env & config gates
+- [ ] Unexercised code paths
+- [ ] Dependency drift
+- [ ] Schema/code parity
+- [ ] Multi-adapter drift
+- [ ] Migration file vs applied
+
+## Findings
+
+### [P1-1] Short title
+
+- **Pattern:** Which of the 7 categories above
+- **Location:** `path/to/file.ts:line` (use clickable [markdown links](path/to/file.ts#Lline))
+- **Evidence:** Concrete proof — log line, fallback always runs, env var grep returns nothing, etc.
+- **Impact:** What's broken / wasted / risky as a result
+- **Confidence:** HIGH / MEDIUM / LOW
+- **Recommended fix:** One sentence. If the fix requires a parity test (e.g. SQL function vs JS fallback), say so explicitly.
+- **Effort:** XS / S / M / L
+
+### [P1-2] ...
+
+## Intentional Stubs (NOT Findings)
+
+Document any stubs/skips that look like findings but are deliberate architecture. Future audits should not re-flag these. Format:
+
+- `path/to/file.ts:line` — what it appears to be vs why it's intentional. Add a comment to the source if missing.
+
+## Recommended Next Actions
+
+For each P0/P1 finding, write a one-line idea submission ready to paste into `mcp__papi__idea`. Include `doc_ref: docs/audits/deployment-completeness-c<NNN>.md` and a parity test in acceptance criteria where applicable.
+```
+
+## After the Audit
+
+1. Save the report to `docs/audits/deployment-completeness-c<NNN>.md`.
+2. Register via `doc_register` (type=audit, status=active, cycle=current).
+3. For each P0/P1 finding, submit an `idea` with `doc_ref` pointing to the audit and acceptance criteria including parity tests where applicable.
+4. Add intentional stubs to a tracked list so they aren't re-flagged.
+5. Record the audit run via `ad_hoc` (effort: S, type: research) so it appears in cycle metrics.
+
+## Important Notes
+
+- This skill does NOT fix issues — it reports them only.
+- The fixes belong in cycle work, not ad-hoc — they need handoffs and parity tests.
+- Focus on actionable findings with clear evidence. "Possibly unused" is not actionable; "fallback log line `X` fires every cycle" is.
+- Don't re-flag intentional stubs (e.g. data-proxy `getPlanContextSummary` returning undefined to force MCP fallback for external users — this is correct architecture). Maintain the "Intentional Stubs" section in each audit so future runs reference it.
+- If you find a P0 (production crash waiting), surface it immediately to the user — don't wait until the report is finished.
+
+## Known Drift History (learn from these)
+
+| Cycle | Pattern | Root Cause | Fix |
+|-------|---------|------------|-----|
+| C49→C242 | `get_plan_context()` SQL function called via try-catch fallback, never deployed | Migration written but never applied; SQL/JS shape drift (status filter, missing `has_handoff`) | Pending — see [docs/audits/deployment-completeness-c242.md](../../docs/audits/deployment-completeness-c242.md) |
+| C236-C238 | Handoffs written against imagined schema | Planner lost code/schema context between cycles | "PRE-BUILD VERIFICATION" rule added to handoff template |
+| C239-C241 | Grouped-branch tasks reported as merged but commits never on main | `review_submit` emitted fake success logs for branches without PRs | task-1485 (in-flight) |
+
+Add new entries here on each audit so the institutional memory compounds.

package/skills/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-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-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-plan/SKILL.md

@@ -0,0 +1,164 @@
+---
+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 XS/S tasks, batch build them without stopping between each:
+- Build all XS/S tasks first, then M/L tasks
+- Group tasks touching the same module onto a shared branch where possible
+- One commit per task for traceable history, even on shared branches
+- 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.
+   - **Branching strategy** — flag tasks that need their own branch (M/L, cross-module) vs. tasks that should batch together.
+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-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 -->