diff --git a/VERSION b/VERSION index bfa363e..8decb92 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.8.4 +1.8.5 diff --git a/docs/pstack-inventory.md b/docs/pstack-inventory.md new file mode 100644 index 0000000..f974af7 --- /dev/null +++ b/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. diff --git a/docs/routing.md b/docs/routing.md index 51646d3..73c34cd 100644 --- a/docs/routing.md +++ b/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`. diff --git a/docs/skills.md b/docs/skills.md index 00bd23a..18a3435 100644 --- a/docs/skills.md +++ b/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`. diff --git a/rules/00-routing.md b/rules/00-routing.md index 5bad3c7..cbfc092 100644 --- a/rules/00-routing.md +++ b/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) diff --git a/rules/02-engineering-principles.md b/rules/02-engineering-principles.md index f996bfd..7444a36 100644 --- a/rules/02-engineering-principles.md +++ b/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. diff --git a/rules/03-prose-discipline.md b/rules/03-prose-discipline.md index 6ee758e..2f0420c 100644 --- a/rules/03-prose-discipline.md +++ b/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`). diff --git a/templates/AGENTS.md b/templates/AGENTS.md index ef45fb5..2d948e7 100644 --- a/templates/AGENTS.md +++ b/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. diff --git a/vendor/sources.json b/vendor/sources.json index 4b85872..f92c85a 100644 --- a/vendor/sources.json +++ b/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",