1.8.5 pstack wave: inventory, principle MERGE, tighter routing

VERSION

@@ -1 +1 @@
-1.8.4
+1.8.5

docs/pstack-inventory.md

@@ -0,0 +1,80 @@
+# OpenCodeBestFriend — pstack inventory
+
+Upstream: [cursor/plugins](https://github.com/cursor/plugins) `pstack/` (MIT © 2026 Lauren Tan).
+Studied tree: plugins `e31650e`. Vendored skill pin remains `60c641e` unless a row says UPDATE.
+Full Cursor plugin, agents, automations/benny, and model-panel setup are **not** installed.
+
+Contract: `NEW | MERGE | REJECT | DEFER | DONE`.
+Zero catalog twins. A procedure the current model already performs unprompted stays `DEFER` or `REJECT`.
+Capability drift updates the existing specialist or rule. It does not add a sibling skill.
+
+## Summary
+
+| Decision | Count |
+| :--- | :---: |
+| `DONE` | 12 |
+| `MERGE` | 27 |
+| `REJECT` | 8 |
+| `DEFER` | 0 |
+| `NEW` | 0 |
+| **TOTAL** | **47** |
+
+Counts are pstack `skills/*` directories only (23 `principle-*` + 24 named skills). Benny automations and Cursor agents stay out of the catalog.
+
+## Named skills
+
+| Upstream | Decision | BestFriend target | Reason |
+| :--- | :---: | :--- | :--- |
+| `architect` | **DONE** | `manual-skills/architect` | Already adapted. Multi-sketch bake-off stays manual. |
+| `arena` | **DONE** | `manual-skills/arena` | Protocol lives in `rules/arena-protocol.md`. |
+| `blast-radius` | **DONE** | `manual-skills/blast-radius` | Impact beyond the diff. Manual only. |
+| `create-verification-skill` | **DONE** | `manual-skills/create-verification-skill` | Project-local control skill authoring. |
+| `maintain-verification-skill` | **DONE** | `manual-skills/maintain-verification-skill` | Periodic honesty pass on that control skill. |
+| `figure-it-out` | **DONE** | `manual-skills/figure-it-out` | Playbook when no narrower specialist fits. |
+| `interrogate` | **DONE** | `manual-skills/interrogate` | Claim interrogation. Manual only. |
+| `reflect` | **DONE** | `manual-skills/reflect` | Learnings with explicit approval. Never auto-edit skills. |
+| `technical-writing` | **DONE** | `manual-skills/technical-writing` | Doc structure. Prose tells stay `humanizer`. |
+| `unslop` | **DONE** | `manual-skills/unslop` | Manual alias of `humanizer`. |
+| `why` | **DONE** | `manual-skills/why` | Repo rationale. Library facts stay Context7 / `research`. |
+| `decision-log` (upstream `show-me-your-work`) | **DONE** | `manual-skills/decision-log` | TSV operational trail. Protocol in `rules/decision-log-protocol.md`. |
+| `tdd` | **MERGE** | `skills/tdd` | Keep Matt Pocock model-invoked TDD. Do not swap in pstack's disable-model-invocation twin. |
+| `how` | **MERGE** | Codebase Memory, then `/code-tour` or `/why` | Mechanism vs motivation. Default path already explains current shape from repo evidence. Durable walkthrough is `code-tour`. Rationale is `/why`. No `/how` twin. |
+| `show-me-your-work` | **MERGE** | `/decision-log` | Same TSV contract. Already ported under the OpenCode name. |
+| `recall` | **MERGE** | Codebase Memory MCP | Project memory is the owned store. Do not add a Cursor transcript crawler. |
+| `teach` | **MERGE** | `/technical-writing`, `writing-for-agents` | Teaching artifacts are docs or skill bodies. |
+| `no-comments` | **MERGE** | `rules/03-prose-discipline.md`, `rules/02-engineering-principles.md` | Comment-sicko agent and Cursor Task types stay out. Encode constraints in tests/lint, do not narrate them. |
+| `typescript-best-practices` | **MERGE** | Context7 + repo evidence | Language patterns are not a BestFriend specialist. |
+| `automate-me` | **MERGE** | `automation-audit-ops` | Inventory keep/merge/cut of live automation. Cursor Automations UI is foreign. |
+| `poteto-mode` | **MERGE** | `templates/AGENTS.md`, `rules/00-routing.md` | Playbooks map onto existing specialists. The Cursor mode skill, model panel, and 23 bundled playbook files are not copied. |
+| `setup-pstack` | **REJECT** | — | Cursor plugin install + Fable/Sol/Grok panel. OpenCode providers stay user-owned. |
+| `bro` | **REJECT** | — | Personality overlay. Not a capability. |
+| `make-bot-ui` | **REJECT** | — | Product-specific bot chrome. Product UI stays `found-this-design` / `impeccable`. |
+| `swarm` | **REJECT** | — | Cursor multi-agent fleet. OpenCode agents are host-owned. Do not vendor a second orchestrator. |
+| `principle-*` (23) | **MERGE** | `rules/02-engineering-principles.md` | Working rules, Read on demand. Not 23 skills. |
+
+## poteto-mode playbooks → existing routes
+
+| Playbook | Route |
+| :--- | :--- |
+| investigation | Codebase Memory, then `/why` or `/code-tour` |
+| bug fix | `diagnosing-bugs` |
+| perf | `full-performance-audit` |
+| hillclimb | `full-performance-audit` + `eval-harness` when a metric loop is named |
+| runtime / trace forensics | `diagnosing-bugs`; observed Chromium cause → `chrome-devtools-axi` |
+| feature | `grill-with-docs` when interview/ADR is needed; else in-session write; `tdd` when test-first |
+| refactoring | `codebase-design` |
+| prototype | `prototype` |
+| visual parity | `playwright-qa` + `impeccable` |
+| authoring a skill | `writing-for-agents`; catalog hygiene → `skill-stocktake` |
+| eval | `eval-harness` |
+| babysit / shipping / opening a pr | `gh-axi` |
+| multi-phase plan | OpenCode plan agent |
+| autonomous run / orchestrate / autopilot-* | **REJECT** as skills. Overnight unattended merge fleets stay host-owned. `figure-it-out` covers an auditable long playbook when the user asks. |
+| session pickup / pause safely / worktree cleanup | default session + git. No specialist. |
+
+## Do not
+
+- Do not add `/poteto-mode`, `/how`, `/swarm`, `/setup-pstack`, or `principle-*` to the 64-skill catalog.
+- Do not copy Cursor `disable-model-invocation` fields into model-invoked skills.
+- Do not `@`-import this inventory into `AGENTS.md`.
+- Do not treat pstack availability as a reason to load a second implementation specialist.

docs/routing.md

@@ -33,3 +33,5 @@ Prose AI-tell removal and natural tone polishing route to `humanizer` (`/unslop`
 Warehouse diagnostics load only when the user names the job: `agent-architecture-audit` (architecture layers), `cost-aware-llm-pipeline` (token budgeting), `eval-harness` (benchmarks), `prompt-optimizer` (prompt refinement), and `skill-stocktake` (catalog hygiene). Wave 3 warehouse procedures route to `api-design` (REST resources), `contract-first` (consumer/provider contracts), `automation-audit-ops` (live inventory), and `code-tour` (guided tours). Foreign harnesses (such as ECC control plane) remain `FOREIGN_ON_DEMAND`; never vendored, auto-merged, or shadowed.
 
 Operational stack adapters route to `supabase-ops` (Supabase Auth/RLS/migrations/Edge Functions), `mongodb-ops` (MongoDB schemas/indexing/aggregation), and `vercel-ops` (Vercel hosting/deploy config). These operational skills never generate visual UI and never replace `found-this-design` or `impeccable`. FOREIGN vendor packs stay off the overlay; user may npx skills add mongodb/agent-skills|supabase/agent-skills locally; never frontend-design for product UI.
+
+pstack / poteto-mode is a routing source, not a catalog twin. How-does-X-work uses Codebase Memory first, then `/code-tour` or `/why`. What-could-this-break suggests `/blast-radius`. Long unattended work logs through `/decision-log`. A large migration with no narrower skill suggests `/figure-it-out`. Do not load `/poteto-mode`, `/how`, `/swarm`, or `principle-*`. Inventory: `docs/pstack-inventory.md`.

docs/skills.md

@@ -10,3 +10,5 @@ Policy: `vendor/skill-policy.json` plus `vendor/skill-allowlist.txt`.
 OpenCode 1.18.x has no `disable-model-invocation` field. Manual skills must not be copied into the discovered skills directory.
 
 `opencode-bf skills verify` checks counts, missing files, and duplicates.
+
+pstack / poteto-mode is not a 65th skill. Playbooks route through `docs/routing.md` and `docs/pstack-inventory.md`.

rules/00-routing.md

@@ -30,7 +30,7 @@ Do not infer a model provider from a logical model name. Treat custom-gateway al
 - Installable React/shadcn registry items: MCP `shadcn` (pinned CLI `shadcn@4.18.0`). Search, inspect, then install. Context7 stays documentation.
 - Broader web research: built-in `WebSearch` and `WebFetch`. MCP `exa` is foreign/pre-existing and ON_DEMAND. Use it only if already connected and research needs it. Never add or remove `exa`.
 - Hard, high-impact, divergent decisions, fuzzy debugging, API or schema alternatives, trap detection: `/adhd` on demand only. Skip ADHD for typos, ordinary CRUD, or bugs with a known cause.
-- Official library, spec, or first-party API facts: `/research` (Context7 when repo evidence is not enough). Why *this repo* chose an approach: suggest `/why` (manual). Do not mix the two.
+- Official library, spec, or first-party API facts: `/research` (Context7 when repo evidence is not enough). How *this repo* currently works, or where a symbol lives: Codebase Memory first; durable `.tour` → `/code-tour`; motivation and rejected alternatives → suggest `/why` (manual). There is no `/how` skill. Do not mix library facts with repo rationale.
 - Scholarly literature surveys, academic manuscripts (IMRaD/thesis/proposal), and structured peer critique: `/academic` (not `research`, not `smartdoc` unless file extract/render).
 - Fuzzy or conflicting domain terms, glossary, CONTEXT.md / ADR writing: `/domain-modeling`. Full product interviews that should leave CONTEXT.md/ADRs: `/grill-with-docs`.
 - Module, interface, seam, testability, abstraction: `/codebase-design` (distinct from `/api-design` for REST and `/contract-first` for machine schemas). Multi-sketch bake-off: suggest `/architect` (manual). Do not auto-start `/architect`.
@@ -89,6 +89,7 @@ Do not infer a model provider from a logical model name. Treat custom-gateway al
 - Ordinary writes stay in this session. `/matt-implement` is only for a ticket that `/to-tickets` produced.
 - Default review is in-session. Two-axis: `/matt-code-review`.
 - Manual / slash-only (do not auto-start): `/blast-radius`, `/create-verification-skill`, `/maintain-verification-skill`, `/unslop`, `/technical-writing`, `/arena`, `/interrogate`, `/architect`, `/why`, `/reflect`, `/figure-it-out`, `/decision-log`, `/wizard`, `/wait-what`, `/improve-codebase-architecture`. Suggest them when the user names the job; do not load them as the default path.
+- pstack / poteto-mode names are not catalog skills. Map the job and stop: investigation → Codebase Memory then `/why` or `/code-tour`; bug → `diagnosing-bugs`; measured slowness → `full-performance-audit`; feature interview → `grill-with-docs`; refactor seams → `codebase-design`; throwaway spike → `prototype`; visual parity → `playwright-qa`; skill authoring → `writing-for-agents`; eval loop → `eval-harness`; PR land / babysit → `gh-axi`; unattended audit trail → `/decision-log`; no narrower playbook → `/figure-it-out`. Reject `/poteto-mode`, `/setup-pstack`, `/swarm`, `/how`, and `principle-*` as loadable specialists. Principles live in `02-engineering-principles.md`.
 
 ## Grok bundled names (do not fake)
 

rules/02-engineering-principles.md

@@ -4,18 +4,28 @@ Read this file only when a skill or the user asks for operational principles. Do
 
 `~/.config/opencode/bestfriend/rules/02-engineering-principles.md`
 
-These are working rules, not an essay. Apply the smallest set that changes the next action.
+These are working rules, not an essay and not a skill catalog. Apply the smallest set that changes the next action.
+Adapted in part from cursor/plugins pstack principles (MIT © 2026 Lauren Tan). Full `principle-*` skills are not installed.
 
-1. **Smallest change.** Prefer the edit that solves the stated problem and nothing else.
+1. **Smallest change.** Prefer the edit that solves the stated problem and nothing else. Minimize the diff. Question a new signal threaded through types, schemas, or pipelines; look for a direct path.
 2. **Foundational thinking.** Scaffold and verification before features when the shape is still wrong.
-3. **Subtract before add.** Delete or collapse a wrong layer before introducing a new one.
+3. **Subtract before add.** Delete or collapse a wrong layer before introducing a new one. Prefer deletion when asked to refactor.
 4. **First principles.** When the current shape fights the work, redesign from the constraint, not from the last patch.
 5. **Domain first.** Name the real nouns and seams before inventing modules.
 6. **Boundary discipline.** Hide complexity behind a small public surface. Do not leak internals to callers.
 7. **Idempotency.** Operations that may retry must be safe to run twice.
-8. **Prove it.** A claim needs an artifact: test, command output, screenshot, commit, or file:line.
+8. **Prove it.** A claim needs an artifact: test, command output, screenshot, commit, or file:line. Test behavior users can observe, not private implementation details, unless the seam itself is the contract.
 9. **Root cause.** Fix the cause. Do not paper over the symptom unless the user asked for a temporary guard.
 10. **Verifiable units.** Land work in independently checkable pieces. Do not batch verification at the end.
 11. **Guard context.** Load one specialist. Do not dump every skill into the window.
-12. **Encode lessons.** Recurring corrections become a gate, lint, test, or script — not a memory of “be careful”.
+12. **Encode lessons.** Recurring corrections become a gate, lint, test, or script — not a memory of “be careful”, and not a comment that restates the code.
 13. **Exhaust the design space only when warranted.** Two structurally different sketches for one-way-door design. Skip for mechanical work whose shape is already concrete.
+14. **Attack the premise.** After two fixes that share one assumption fail the same gate, write the assumption down and measure who holds the imbalance before writing a third patch.
+15. **Build the lever.** When the same check will run again, write the script that does it. Do not hand-walk the census.
+16. **Experience first.** Judge the running product. A green unit suite is not a substitute for the user-visible path.
+17. **Migrate callers, then delete.** Do not leave a legacy API beside the new one. Move callers, delete the old surface in the same effort when safe.
+18. **Minimize reader load.** Flat call chains. One source of truth for a decision. A human who must trace more than three files to answer “what happens” is a design smell.
+19. **Type-system discipline.** Put invariants in types and tests, not in comments that beg the next editor to be careful.
+20. **Separate before sharing mutable state.** Do not serialize access to a blob that should have been two values.
+21. **Outcome over ceremony.** Optimize for the falsifiable done-predicate, not for looking busy.
+22. **Do not block the human on reversible work.** In this session, make the reversible edit and show it. Confirm only irreversible steps (force-push, production delete, external send) or product direction. This is not a license for `--auto`, overnight merge fleets, or skill self-mutation.

rules/03-prose-discipline.md

@@ -20,5 +20,6 @@ This is not a skill. It does not auto-apply. It does not rewrite code.
 - Cut fabricated metrics and uncited statistics: never invent precise percentages, multipliers, or benchmark numbers.
 - Cut beta-pill voice and sparkle-CTA fluff: do not decorate action buttons with sparkles, emoji flair, or artificial status pills.
 - Never “polish” source code, tests, or command output as if they were marketing copy.
+- Do not add comments that narrate what the next line does. Delete dead comments. A constraint that must survive the next editor belongs in a type, a test, a lint rule, or CI — not in `IMPORTANT` / `do not remove` prose. Intentional comments that record a non-obvious external constraint may stay; offer to encode them when the user asks.
 
 For full prose rewrites and systematic AI-tell removal, use the `humanizer` specialist (manual slash alias: `/unslop`).

templates/AGENTS.md

@@ -57,7 +57,9 @@ Read `~/.config/opencode/bestfriend/rules/01-verification.md`. Profiles: FAST, S
 
 If you need operational principles or prose discipline, Read `~/.config/opencode/bestfriend/rules/02-engineering-principles.md` or `03-prose-discipline.md`. Do not `@`-import them.
 
-There is no user `/implement`, `/code-review`, `/design`, or `/imagine` skill.
+There is no user `/implement`, `/code-review`, `/design`, `/imagine`, `/how`, or `/poteto-mode` skill.
+
+How this repo works / where it lives → Codebase Memory first; durable tour → `code-tour`; rationale → `/why`. What this change could break → suggest `/blast-radius`. No narrower playbook → suggest `/figure-it-out`. Decision trail → `/decision-log`. pstack playbooks map onto the specialists above; do not load `principle-*` or Cursor mode skills.
 
 Manual-only specialists are OpenCode commands, not auto-discovered skills: `/architect` `/arena` `/blast-radius` `/create-verification-skill` `/decision-log` `/figure-it-out` `/improve-codebase-architecture` `/interrogate` `/maintain-verification-skill` `/matt-implement` `/reflect` `/technical-writing` `/unslop` `/wait-what` `/why` `/wizard`. Suggest them when the user names the job; do not load them as the default path.
 <!-- OPENCODEBESTFRIEND:END -->

vendor/sources.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "product": "OpenCodeBestFriend",
-  "productVersion": "1.8.4",
+  "productVersion": "1.8.5",
   "adaptedFrom": {
     "product": "ClaudeBestFriend",
     "version": "1.4.2-claude.1",
@@ -114,10 +114,12 @@
     "pstack": {
       "repository": "https://github.com/cursor/plugins",
       "commit": "60c641e4fad674784b30abcf9f8915dea39df38d",
+      "inventoryTree": "e31650eea443aaea1e84cc15d88c13f40080b275",
       "subdir": "pstack",
       "license": "MIT",
       "copyright": "Copyright (c) 2026 Lauren Tan",
-      "licenseFile": "vendor/licenses/PSTACK-MIT.txt"
+      "licenseFile": "vendor/licenses/PSTACK-MIT.txt",
+      "note": "Vendored skill pin 60c641e. 1.8.5 inventory studied e31650e. principle-* and poteto-mode MERGE into rules/routing. Full plugin not installed."
     },
     "playwright-cli": {
       "repository": "https://github.com/microsoft/playwright-cli",