@blockbite/agent-context 0.1.0

package/skills/template-refine/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: template-refine
+description: Refine an existing BlockBite Studio dynamic template package. Use when the user wants to clean up or improve a template created from Figma or AI, simplify Tailwind classes, fix Liquid/runtime issues, preserve fields and seed data, improve Alpine behavior, or align an existing template with BlockBite package conventions.
+---
+
+# Template Refine
+
+Improve an existing BlockBite Studio template without breaking its dynamic content contract.
+
+Before changing DSL tags, read `../references/block-dsl.md` when it exists.
+For BlockBite-specific Tailwind utilities such as `area-[...]`, `grid-area-[...]`, and `children:*`, read `../references/tailwind-utilities.md` when it exists.
+When simplifying token-backed Tailwind classes, run `wp bb design-tokens db-to-local` if needed and read `<workspace>/dev/css/design-tokens.css`.
+
+## Agent Contract
+
+The agent is the interface; WP-CLI is only the executor. Do not rely on interactive CLI prompts. Resolve the template slug from the chat, ask only when it is missing, then run commands with full flags.
+
+## Build Mode Contract
+
+Treat BlockBite's reported build mode as authoritative:
+
+- auto-build: after template, style, script, or block-style edits, run `ddev wp bb autobuild`; if Node.js is unavailable, open the signed browser fallback URL.
+- custom-build: do not use the signed browser runner; use the project-specific frontend build pipeline.
+- Default to auto-build for template and site work unless `wp bb learn`, `wp bb init`, or `dev/template-start/latest.json` explicitly reports custom-build.
+- Do not infer custom-build from development manifests in mounted plugins or neighboring projects.
+- Do not start, repair, shim, or mutate external Vite/Webpack setup unless the user explicitly asks for plugin development or custom-build work.
+- If autobuild stalls or fails, report the runner status and stop before changing build setup.
+
+## First Pass
+
+Read the package under `<workspace>/templates/<slug>/`:
+
+- `template.liquid`
+- `recipe.json`
+- `seeds.json`
+- `fields.yaml`
+- `manifest.json`
+- `style.css`
+- `module.ts`
+
+Also read one nearby successful template when possible.
+
+## Frontend Runtime Errors
+
+For browser errors, especially Alpine expression errors, open the current
+frontend page with `#blockbite-debug-panel`, inspect the Client JS chapter, and
+read this in the browser console:
+
+```js
+window.BlockBiteDebug?.errors;
+```
+
+Use those entries to identify the template slug, `template.liquid`, `module.ts`,
+failing expression, selector, and rendered element before editing.
+
+## Preserve Contract
+
+Keep existing field handles stable unless the user explicitly asks to rename them. Dynamic-content field ids live in the database, not in YAML.
+
+Use:
+
+- `props.fields.<handle>` for top-level fields
+- `props.subcollections.<handle>` for repeaters
+- `bb_str | raw` for editable text
+- existing component includes when the package already relies on them
+
+Supported `fields.yaml` field types are: `string`, `text`, `textarea`, `richtext`, `media`, `image`, `file`, `link`, `svg`, `number`, `integer`, `float`, `boolean`, `bool`, `toggle`, `select`, `radio`, `date`, `datetime`, `color`, `email`, `telephone`, `url`, `password`, and `post_relation`.
+
+For editable images, prefer `type: media`; `type: image` and `type: file` normalize to `media`. Do not convert media fields into `image_url: type: string` unless preserving an existing external URL-only contract. If changing a string URL field into media, treat it as a data-shape change and sync dynamic-content intentionally.
+
+For icon or shape picker fields, use `type: svg` with `kind: icon` or `kind: shape`; `kind` defaults to `icon`. Do not change these to string IDs or invent `type: icon` unless preserving a legacy contract.
+
+## Fill Layers
+
+When refining hero backgrounds, overlays, or other visual layers, prefer the
+child DSL API:
+
+```liquid
+<bb-fills>
+  <bb-fill type="image" field="{{ props.fields.hero_artwork }}" class="opacity-70" />
+  <bb-fill type="gradient" class="bg-gradient-to-b from-black/20 to-black/70" />
+</bb-fills>
+```
+
+Keep the owning section or group responsible for sizing and clipping, for
+example `relative isolate min-h-* overflow-hidden`. Do not move fills into
+`bb-group` props. If a template uses an absolutely positioned `core-image` or
+`bb-image` only as a background layer, migrate it to `bb-fill type="image"` and
+preserve the media field handle. Keep normal image blocks for images that are
+part of the layout.
+
+## Refinement Goals
+
+Prioritize:
+
+- valid Liquid and HTML
+- lean Tailwind classes that match the existing design language
+- responsive layout that does not overlap text or controls
+- reusable fields and repeaters instead of hardcoded repeated content
+- shared block styles for repeated visual variants instead of long duplicated Tailwind classes
+- Alpine behavior that uses already-loaded CDN plugins
+- `recipe.json`, `seeds.json`, and `fields.yaml` consistency
+
+Do not rewrite unrelated components or database rows.
+
+## Shared Styles Boundary
+
+Do not move template-specific styling or global `html`, `body`, `button`,
+`input`, typography, background, or reset rules into
+`<workspace>/app/styles-shared/*.css`.
+
+`app/styles-shared/shared.css` is bundled into `app.bundle.css` and loaded in
+block editor previews as well as the frontend. Use it only for intentionally
+shared, scoped component or template-family classes. Keep island CSS in
+`templates/<slug>/style.css`; keep frontend-only globals in
+`app/styles-app/app.css` or the theme stylesheet.
+
+## CLI Flow
+
+After file changes, run:
+
+```bash
+ddev wp bb dynamic-template update --slug=<slug>
+ddev wp bb dynamic-content sync --slug=<slug> --fields=<slug>/fields.yaml
+```
+
+Only import seeds when the user wants seed data replaced:
+
+```bash
+ddev wp bb source import-seeds --slug=<slug> --file=wp-content/blockbite/templates/<slug>/seeds.json
+```
+
+## Finish
+
+Validate JSON, inspect the template manually, run focused CLI checks, and report exactly what changed and what was preserved.

package/skills/update-template-draft/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: update-template-draft
+description: Plan and apply sandbox edits to an existing BlockBite template. Use when the user wants to change layout, styles, fields, or sample content of a template. All writes stay in the sandbox.
+---
+
+# Update a BlockBite template (sandbox)
+
+## Steps
+
+1. Ensure a project is selected.
+2. Call `blockbite-template-update-draft` with
+   `{ "slug": "<slug>", "change": "<plain-language change>", "scope": "layout|styles|fields|sample-content" }`.
+   This returns suggested tools, a preview URL, and guidance. It does not write.
+3. Apply the suggested edits with `blockbite-workspace-patch` (search/replace) or
+   `blockbite-workspace-write` (full file). These write to the sandbox overlay.
+4. Preview with the render-preview skill and confirm with the user.
+5. After the user approves the sandbox package, use `blockbite-build-status`
+   and `blockbite-build-run` if bundles are dirty. Do not run Node.js, import
+   BlockBite build chunks, or call build request endpoints directly.
+
+## Guardrails
+
+- Read the file with `blockbite-workspace-read` before patching.
+- Never assume file contents; verify with analyze-template first.
+- Keep section/island work as `templates/<slug>/` dynamic-template packages
+  (`template.liquid` + `style.css` + `fields.yaml` + `seeds.json`). Never convert
+  a section into a raw `<!-- wp:html --><style>…</style>` block or hand-write
+  `islands/<slug>/island-pattern.html` (compiler output, not agent-authored).
+- Use `example-use/blockbite/templates/dynamic-template-reference/` as the
+  canonical package reference when changing fields, seeds, scoped CSS, or local
+  `module.ts` behavior.
+- After editing, return the `blockbite_preview_mcp` preview URL. Do **not** open
+  a browser or use browser automation to verify — the preview URL is the
+  deliverable.
+- MCP build orchestration stays in MCP tools: use `blockbite-build-status` /
+  `blockbite-build-run`, never local probes.