Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 5 additions & 15 deletions .bb/skills/plugin-guide-maintenance/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
name: plugin-guide-maintenance
description: Keep the Plugin Guide accurate when a public Plugin SDK change affects its documented contract or an existing Guide annotation changes order, placement, target, or overlay ownership. Use for additions, changes, renames, stabilizations, or removals in @get-bb/plugin-sdk, app.slots.*, or BbPluginApi that affect a Guide card, fixture, symbol list, or SDK inventory, and for annotation-only maintenance. Do not use for internal implementation or API work that leaves the Guide accurate.
description: Keep the Plugin Guide accurate when a public Plugin SDK change affects its documented contract or an existing Guide annotation changes order, placement, target, or overlay ownership. Use for additions, changes, renames, stabilizations, or removals in @get-bb/plugin-sdk, app.slots.*, or BbPluginApi that affect a Guide card, fixture, or symbol list, and for annotation-only maintenance. Do not use for internal implementation or API work that leaves the Guide accurate.
---

# Maintain the Plugin Guide

The Plugin Guide is bb's public Plugin SDK reference. For a public API change,
follow the full workflow. For annotation-only maintenance, start at Maintain
annotation layout, skip the public-API and SDK-inventory sections, and then
follow the annotation-only verification path.
annotation layout, skip the public-API section, and then follow the
annotation-only verification path.

## Confirm a public API change

Expand All @@ -19,8 +19,8 @@ pnpm exec turbo run build:types --filter=@get-bb/plugin-sdk
git diff -- packages/plugin-sdk/package.json packages/plugin-sdk/src
```

Continue only when the API change affects a Guide card, API symbol list,
fixture, or SDK inventory. If the Guide remains accurate, do not change it.
Continue only when the API change affects a Guide card, API symbol list, or
fixture. If the Guide remains accurate, do not change it.

New public members also require:

Expand Down Expand Up @@ -96,16 +96,6 @@ renumbered, or its target or surrounding layout changes:
If responsive layouts cannot share one spatial order, fix the layout or define
one stable readable sequence before shipping.

## Refresh the SDK inventory

Refresh the inventory after the Guide represents a public API change:

```sh
pnpm exec turbo run update:sdk-inventory --filter=@bb/plugin-api-map
```

Review `packages/plugin-api-map/sdk-public-api.json`. Do not edit its hashes.

## Verify the result

For a public API change, run:
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
## Plugin API

- Any new public plugin API member (a `@get-bb/plugin-sdk/app` export, an `app.slots.*` method, or a `BbPluginApi` property) ships with an `experimental_` name prefix and an entry in [docs/api_to_audit.md](docs/api_to_audit.md) describing what it does and what to audit before stabilizing. Dropping the prefix is the deliberate stabilization step: audit the entry, rename project-wide, and remove it from the doc in the same change.
- The Plugin Guide (the `plugin-api-docs` plugin, rendering `packages/plugin-api-map`) is bb's only plugin API documentation. A new surface needs a card in `packages/plugin-api-map/src/surfaces.ts` naming its SDK symbols in the same change; `packages/plugin-api-map/test/api-sync.test.ts` fails the build when the map and the SDK drift apart.
- The Plugin Guide (the `plugin-api-docs` plugin, rendering `packages/plugin-api-map`) is bb's only plugin API documentation. A new surface needs a card in `packages/plugin-api-map/src/surfaces.ts` naming its SDK symbols in the same change.

## Data Access

Expand Down
1 change: 0 additions & 1 deletion packages/plugin-api-map/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@
"scripts": {
"clean": "rimraf tsconfig.tsbuildinfo",
"scaffold:surface-entry": "node scripts/scaffold-surface-entry.mjs",
"update:sdk-inventory": "node scripts/sdk-api-inventory.mjs --write",
"typecheck": "tsc --noEmit",
"test": "vitest run --config vitest.config.ts"
},
Expand Down
9 changes: 0 additions & 9 deletions packages/plugin-api-map/scripts/sdk-api-inventory.d.mts

This file was deleted.

87 changes: 0 additions & 87 deletions packages/plugin-api-map/scripts/sdk-api-inventory.mjs

This file was deleted.

45 changes: 0 additions & 45 deletions packages/plugin-api-map/sdk-public-api.json

This file was deleted.

111 changes: 0 additions & 111 deletions packages/plugin-api-map/test/api-sync.test.ts

This file was deleted.

7 changes: 0 additions & 7 deletions turbo.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,10 @@
"@bb/plugin-api-map#test": {
"dependsOn": [
"//#ensure-native-modules",
"@get-bb/plugin-sdk#build:types",
"topo"
],
"inputs": [
"$TURBO_DEFAULT$",
"$TURBO_ROOT$/packages/plugin-sdk/bundled-types/**",
"$TURBO_ROOT$/packages/plugin-sdk/package.json",
// wireframes.test.ts asserts fixture fidelity against the real app
// source, and maintenance-skill.test.ts reads the repository skill plus
// Plugin Guide source; all are inputs to prevent stale cache hits.
Expand All @@ -52,10 +49,6 @@
"$TURBO_ROOT$/vitest.shared.ts"
]
},
"@bb/plugin-api-map#update:sdk-inventory": {
"dependsOn": ["@get-bb/plugin-sdk#build:types"],
"cache": false
},
"@bb/plugin-api-map#scaffold:surface-entry": {
"cache": false
},
Expand Down
Loading