@hybridlabor-api/aos 4.13.2 → 4.14.1

package/skills/global_config/visual-recap/references/local-files.md

@@ -0,0 +1,99 @@
+# Local-files privacy mode — single source of truth
+
+This file is the canonical contract for fully local, no-database planning and
+recaps. It is shared word for word by `/visual-plan` and `/visual-recap`. Read it
+in full before using local-files mode; do not call any hosted Plan tool for a
+local plan/recap except the schema-only block-catalog lookup described below.
+
+<!-- SHARED-CORE:local-files START -->
+
+**When to use it.** Use local-files privacy mode when the user explicitly asks
+for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local
+files, offline/private work, or repo-owned/source-controlled artifacts, or when
+`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo
+policy says the work must stay under their own brand, domain, source control, or
+infrastructure. In this mode the plan/recap data must never be sent to the Plan
+MCP server or the Plan app action surface. This is the only exception to the
+always-publish rule in `references/connection.md`.
+
+The local-files contract:
+
+- **Read context locally.** Read source, diff, and stat context from local files
+  and shell commands only. For recaps, the
+  `npx @agent-native/core@latest recap collect-diff`, `scan`, and
+  `build-prompt --local-files` helpers are safe — they operate on local files and
+  do not write to the Plan database.
+- **Fetch the block catalog first** (it sends no plan content). Use the MCP
+  `get-plan-blocks` tool if it is already available, or run
+  `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
+  file before authoring MDX; it calls the public no-auth `get-plan-blocks` route.
+  Use `--format schema` when you need exact nested fields. If network access is
+  unavailable, use the bundled `references/*.md` and rely on `plan local check` to
+  catch invalid tags. Copy the catalog examples verbatim for the fields the
+  registry table cannot encode: `checklist` items need `id` and `label`;
+  `question-form` questions need `id`, `title`, and `mode`, and each option needs
+  `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive
+  — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
+  (a static template literal is accepted only when it has no `${...}`
+  interpolation). `plan local check` is a quick OFFLINE lint (a subset of the
+  renderer schema), so a green `check` does not guarantee the plan renders.
+  `plan local verify` also stays on-device: it uses the offline lint unless it
+  can reach a Plan renderer on an explicit loopback `--app-url`.
+- **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
+  repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
+  or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
+  folder holds `plan.mdx`, optional `canvas.mdx`, optional `prototype.mdx`, and
+  optional `.plan-state.json`. For a recap, set `kind: "recap"` and
+  `localOnly: true` in the frontmatter/state. Use that exact folder as
+  `<plan-dir>` in every command below.
+- **Check, then serve.** Run
+  `npx @agent-native/core@latest plan local check --dir <plan-dir>` before any
+  preview, then
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open`
+  (use `--kind plan` for plans, `--kind recap` for recaps). Report the local
+  bridge URL from stdout or `<plan-dir>/.plan-url`; treat `.plan-url` as a local
+  token file and do not commit it. The URL opens the hosted Plan UI but reads from
+  the localhost bridge on this machine, so it is not shareable across machines.
+  The token is carried in the URL fragment (which is not sent to the hosted
+  origin), and the local-plan route disables DOM autocapture and session replay
+  while retaining sanitized pageviews and error monitoring. On
+  macOS `--open` prefers Chromium browsers; if Safari opens, switch to
+  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
+  HTTP localhost bridge. If the Plan app itself is running locally with the same
+  `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. In a truly
+  offline environment, hand off the `<plan-dir>` path after `plan local check` and
+  note that interactive preview requires network access to the hosted Plan UI or a
+  running local Plan app.
+- **Headless verify.** Run
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
+  It starts the bridge and checks the private-network preflight and JSON payload
+  entirely on loopback. It never sends MDX or assets to a remote validation
+  action. When `--app-url` points to a loopback Plan app, verify also validates
+  against that local app's real renderer schema via `validate-local-plan-source`.
+  A non-`ok` result with
+  `validation.valid: false` lists the renderer's exact schema-path issues (e.g.
+  `blocks[1].data.tabs[0]...`); fix those before handing off. If `validation.ran`
+  is `false`, verify used the offline lint because the app URL was remote or the
+  local Plan app was unavailable. Run a local Plan app and pass
+  `--app-url http://localhost:8096` for the authoritative check. If the browser hangs on
+  "Loading plan", fetch the `bridgeUrl` from the verify/serve JSON to read the
+  concrete validation error.
+- **Never call hosted tools for that plan/recap.** Do not call
+  `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,
+  `create-plan-design`, `create-visual-recap`, `create-visual-questions`,
+  `import-visual-plan-source`, `update-visual-plan`, `patch-visual-plan-source`,
+  `get-plan-feedback`, `export-visual-plan`, `set-resource-visibility`, or any
+  other hosted Plan tool — except the schema-only block-catalog lookup above.
+- **Feedback is file/chat feedback.** Update the MDX files directly, rerun
+  `plan local check`, and rerun `serve` or `verify` when that preview path is
+  available. Summarize the new local URL when one exists; otherwise summarize the
+  checked `<plan-dir>` path. Hosted comments, sharing, screenshots, history, usage
+  attachment, and publish/export receipts are unavailable until the user
+  explicitly opts into publishing.
+
+Local-files mode prevents plan/recap content from being uploaded to the
+Agent-Native Plan server or database. It does not by itself make the coding agent's language model local;
+for that stronger boundary the host agent/model must also be local or otherwise
+approved by the user.
+
+<!-- SHARED-CORE:local-files END -->

package/skills/global_config/visual-recap/references/wireframe.md

@@ -0,0 +1,319 @@
+# HTML wireframe quality — single source of truth
+
+This file is the canonical quality bar for HTML wireframes / `<Screen>` /
+`WireframeBlock` content, shared word for word by `/visual-plan` and
+`/visual-recap`. Read it in full before authoring ANY wireframe; do not
+author wireframes from memory or paraphrase these rules per command.
+
+<!-- SHARED-CORE:wireframe-quality START -->
+
+**A wireframe is an HTML mockup. The renderer owns the look; you write the
+content.** Set `data.html` to a self-contained, semantic HTML fragment of the
+screen and set `data.surface`. The renderer owns the surface footprint/aspect,
+the dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you
+never write `<html>`/`<body>`/`<script>`/`<style>` tags or any
+width/height/coordinates. You write real HTML layout and real product
+content; the renderer styles and roughens it.
+
+**A wireframe block's data is an HTML screen plus a surface:**
+
+```json
+{
+  "surface": "browser",
+  "html": "<div style=\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\"><h1>Sign in</h1><p class=\"wf-muted\">Use your work email to continue.</p><div class=\"wf-card\" style=\"display:flex;flex-direction:column;gap:10px\"><label>Email<input value=\"jane@acme.co\" /></label><label>Password<input value=\"••••••••\" /></label><label style=\"display:flex;align-items:center;gap:8px\"><input type=\"checkbox\" checked /> Remember me</label><button class=\"primary\">Sign in</button></div><a href=\"#\">Forgot password?</a></div>"
+}
+```
+
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type="checkbox">`, `a`, `hr`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+
+- `.wf-card` / `.wf-box` — a bordered, padded container (a panel, a list item).
+- `.wf-pill` / `.wf-chip` — a rounded tag or filter; add `.accent`
+  (`<span class="wf-pill accent">`) for the accent-filled variant.
+- `.wf-muted` — secondary/muted text (or use `<small>`).
+- `button.primary` or any element with `[data-primary]` — the accent-filled
+  primary button.
+
+**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:
+drop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a
+wireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.
+Mockups should read as flat, bordered surfaces; use spacing, borders, labels,
+and annotations for separation. Only show a shadow when the real product UI
+already has that shadow and it is essential to the change being reviewed.
+
+**Use renderer icons, not visible icon words.** For icon-only buttons or leading
+icons inside fields, chips, menu items, and toolbars, write an empty marker such
+as `<span data-icon="mail" aria-label="Email"></span>` or
+`<i data-icon="lock"></i>`. The renderer replaces it with a Tabler-style SVG and
+the `.wf-icon` class sizes it to the surrounding text. Supported names and
+aliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,
+`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,
+`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,
+`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words
+like "email", "lock", "search", "chevron", or "more" where the product UI would
+show an icon; use text only when it is a real label a user would read.
+
+**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+`style="border:1.4px solid var(--wf-line)"`. The tokens are `--wf-ink` (text),
+`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`
+(page background), `--wf-card` (container surface), `--wf-accent` /
+`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,
+and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
+renderer owns the sketch/clean font.
+
+**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as
+`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,
+`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,
+or arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the
+mockup and can make dark-mode canvas frames unreadable. Use bare semantic
+elements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before
+publishing, scan every wireframe `class` and `style` attribute: if a class sets
+background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
+or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
+are still discouraged; inline flex/grid styles are safer and easier to review.
+
+**Keep Rough.js sparse.** The renderer sketches the outer frame, standard
+`.wf-*` primitives, controls, and inline border dividers by default. Do not add
+`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or
+nested containers unless that single container is the visual point. Use
+`data-rough` only for a deliberate one-off shape. If a mockup starts looking
+like stacked/overlapping sketch lines, remove rough targets from parent
+containers and let backgrounds plus spacing separate the surfaces.
+
+**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
+renderer-owned visual styling, not layout spacing. Do not use guessed spacing
+tokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing
+variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
+padding collapses and content hugs the border. Use explicit CSS lengths for
+layout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.
+
+**Lay out with inline `style` flex/grid.** You write the real layout —
+`display:flex; flex-direction:column; gap:10px; padding:16px` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
+
+**Surface presets — match the real footprint, never default to desktop+mobile.**
+Pick the `surface` that matches what the user will actually see:
+
+- `browser`: a web page that needs a browser chrome frame around it.
+- `desktop`: a full desktop app page or app shell.
+- `mobile`: a phone screen, only when the work is genuinely mobile.
+- `popover`: a small floating menu, dropdown, or inline popover.
+- `panel`: a side panel, inspector, or sidebar widget.
+
+A sidebar popover renders as a small surface, not a desktop page and a phone
+frame. Do not emit `desktop` + `mobile` variants unless responsive behavior
+actually changes the layout. For a component or widget, show one broader
+app-context frame only when placement affects understanding, then the focused
+component states.
+
+**Model the actual component shell for small surfaces.** A rendered UI change
+belongs in a wireframe; reserve `diagram` for architecture, dependency, state,
+or data-flow relationships. Popovers, dropdown menus, command palettes, and
+context menus use `surface: "popover"` unless the surrounding page placement is
+the point of the change. Dialogs, sheets, inspectors, sidebars, and long
+property panels use the matching `panel` / `desktop` surface as appropriate.
+Show the real chrome: trigger or anchor when it matters, title/header row,
+top-right actions, separators, fields, options, selected states, body content,
+and footer actions that are visible in the workflow.
+
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell. Inspect the
+actual app components before drawing an existing product: sidebar density,
+toolbar actions, overflow menus, property panels, and framework chrome should
+match the product unless the plan intentionally changes them.
+
+**Keep product screens pure.** A product wireframe shows the app state a user
+would actually see. Do not embed file contracts, architecture arrows, repo pills,
+mode explanations, or implementation callouts inside the screen just to explain
+the plan. Put those in canvas annotations, a separate diagram, or the document
+body. Secondary UI such as properties, history, sync, export, or agent controls
+should appear where the real product would put them: an overflow popover, sheet,
+panel, or separate framework sidebar state, not a generic permanent right
+inspector unless that inspector is the actual design.
+
+**Classify mockup scope before implementation.** Before turning a plan mockup
+into source code, decide whether each artboard represents the whole page/app
+shell, a route body inside an existing shell, or a component/sub-surface. If an
+artboard includes navigation, sidebars, auth banners, or a signup/login form,
+map those pieces to the real shared shell/auth components instead of nesting the
+entire mockup inside the current page. When a mockup references the product's
+standard signup/login page, find and reuse that existing implementation; do not
+approximate it from the wireframe.
+
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose `html` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+`surface` (e.g. `popover`) so the footprint is right; never widen a popover to
+page width.
+
+**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and
+fill the `html` with neutral, textless placeholder geometry — boxes and bars
+built as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a `custom-html` document block
+to fake a loader.
+
+**Editing an existing mockup.** In hosted mode, to change one element, text, or
+color in an existing html mockup, do not regenerate the frame — call
+`update-visual-plan` with
+`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]`. Each `find` is a unique snippet of the current html (read it
+first with `get-visual-plan`); set `all: true` on an edit to replace every
+occurrence. The result is re-sanitized. In local-files privacy mode, do not call
+hosted Plan tools; edit the local MDX source directly and rerun the local
+check/serve or verify command for `<plan-dir>`.
+
+**Choose the outer frame deliberately.** Wireframe and diagram data accept
+`frame: "auto" | "show" | "hide"` in block data (`<Screen frame="hide">` in
+MDX wireframes, `<Diagram frame="hide">` for MDX diagrams). Leave it unset or
+`auto` when the host context should decide: Plan and recap surfaces default to a
+drawn outer frame; docs surfaces default to no outer frame. Use `show` for
+standalone product screens, before/after recap comparisons, screenshot-like
+artifacts, and visuals that need containment from surrounding prose. Use `hide`
+when a docs page, tab, column, card, canvas artboard, or the visual's own
+internal chrome already supplies the boundary. Do not use `hide` to compensate
+for cramped content; fix the layout instead.
+
+**Inner padding and borders still matter.** Always wrap HTML wireframe content
+in a root container with real inner padding before drawing cards, fields, pills,
+labels, or controls. Use at least 14-16px of padding, `box-sizing: border-box`,
+`height: 100%`, and `gap` between child rows on the root node itself so the
+first row never sits flush against the screen edge. Do not rely on padding on a
+nested page section as the first visible inset; the outermost element must
+create the breathing room. Keep text away from borders: every container, field,
+button, menu item, and annotation needs enough padding and line-height to read
+cleanly in the rendered Plan view.
+
+**Center page-like content inside broad surfaces.** For browser or desktop
+screens, let the outer root provide the full-width frame and padding, then keep
+the page body in a centered wrapper such as
+`width:100%;max-width:720px;margin-inline:auto`. Full-width app bars may span
+the root, but onboarding, auth, settings, and other page-like content should
+not hug the left border unless the real product does.
+
+**For feature-cloud or abundance visuals, optimize the composition over line-by-line
+reading.** Some marketing/product sections need to feel like a large surface area
+of capability rather than a precise app workflow. In those cases, use one padded
+root with a short headline and a dense, aesthetic cloud of short feature labels,
+chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
+and let many labels be glanceable rather than individually essential. Do not
+force dozens of features into equal cards with long wrapped sentences; that
+usually creates a messy unreadable mockup.
+
+**Lay out children safely so they never collide.** Use HTML flex/grid with
+`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute
+positioning, or fixed child widths that can collide when the renderer switches
+between light/dark, sketch/clean, or different zoom levels.
+
+**Do not wrap intentionally single-line labels.** For toolbars, tab rails,
+breadcrumbs, chip/filter rows, branch and file names, file chips, and code
+filenames — any deliberately single-line row — do not let long text wrap. Put
+`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`
+on the individual labels that can grow), so the wireframe demonstrates the actual
+layout behavior instead of producing ugly stacked or vertical text. Use
+horizontally scrollable or clipped rails for overflow.
+
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+
+**Persistent chrome bars span the full frame width.** Top bars, app headers,
+toolbars, and bottom tab/nav bars are full-width chrome, not centered content.
+Lay each one out as a single flex row that fills the frame
+(`style="display:flex;align-items:center;width:100%"`) and push trailing actions
+to the right edge with a flex spacer (`<div style="flex:1"></div>`) between the
+leading group and the trailing group — never center a bar inside a narrow,
+centered block, and never let it collapse to the width of its contents. In a
+Before/After pair the bar stays full-width in BOTH states even when one state has
+fewer controls; the spacer absorbs the difference so the remaining controls hold
+their edge alignment instead of sliding to the center.
+
+**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and
+any persistent bottom action row, make the frame itself a flex column at
+`height:100%` (`style="display:flex;flex-direction:column;height:100%"`), give the
+scrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST
+child of the frame (or set `margin-top:auto` on it). The bar then sits flush at
+the bottom of the surface instead of floating directly under the content with an
+empty band beneath it.
+
+**Before / after must be comparable.** When showing a state change, preserve the
+unchanged controls in both states so the reviewer can see exactly what moved or
+appeared; do not show an added control as a generic box floating elsewhere in
+the surface. Place the new/changed affordance where the implementation puts it —
+for example, a new `Edit with AI` action in a popover header belongs in the
+top-right header slot, aligned with the title, not in the body or footer. Use
+the same frame size, scale, outer padding, border radius, and visual density on
+both sides unless the change itself alters those properties, and let the frame
+height fit the content rather than leaving a tall empty lower half.
+
+**Name the states with the column header, never inside the frame.** For
+document-body wireframes (recaps), put the two
+states in a `columns` block and set each column's `label` to `Before` and
+`After` — the renderer draws that label as an `h4` heading above each frame. Do
+NOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a
+label placed inside reads as part of the product UI, lands in a random corner,
+and clutters the comparison. The column header is the one and only place the
+state name belongs. On a canvas, place the two state artboards as neighbors with
+frame labels — never encode Before/After inside the html.
+
+**Let the surface choose side-by-side vs. stacked.** For document-body
+wireframes (recaps), the `columns` renderer lays
+narrow surfaces (`mobile`, `popover`, `panel`) out side by side, and
+automatically stacks wide surfaces (`desktop`, `browser`) vertically at full
+document width so a large frame is never crushed into a half-width column and
+cropped. Author both wireframes with the real `surface` and the matching
+`Before`/`After` column labels; do not hand-stack the pair into separate
+top-level wireframes or duplicate the state name as body content.
+
+**Good example — a contacts list, surface `browser`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+
+```html
+<div
+  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
+>
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div
+    class="wf-card"
+    style="display:flex;flex-direction:column;gap:0;padding:0"
+  >
+    <div
+      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
+    >
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
+      </div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
+      </div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+```
+
+<!-- SHARED-CORE:wireframe-quality END -->

package/skills/playbooks/pb-ci-fix/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pb-ci-fix
+description: >-
+  Fix red CI or set up GitHub Actions end to end: read the failing run, find
+  the root cause, patch and validate the workflow, push only after GO, and
+  watch the run go green on the pushed commit. Use for "CI is red", "the
+  build fails on GitHub", "set up CI for this repo", "fix the workflow".
+category: engineering-method
+kind: playbook
+trigger: ["CI is red", "set up CI", "fix the GitHub Actions run"]
+inputs: [repo, failing_run_id?]
+requires:
+  skills: [github, deja-memory, systematic-debugging, ci-pipeline, github-actions-generator, github-actions-validator, bdbresilience, verification-before-completion, "gh (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [git push]
+outputs: [".github/workflows/*.yml", "production_artifacts/pb-ci-fix-<date>.md"]
+verify: "gh run list --commit <sha> --json conclusion -q '.[0].conclusion' == success"
+difficulty: intermediate
+est_time: 15-45 min
+disable-model-invocation: true
+---
+
+# Fix red CI or set up GitHub Actions
+What you get: a green GitHub Actions run on a pushed commit, with the cause and the fix written down.
+
+## Inputs
+- repo — the current directory, or the one the user names
+- failing_run_id (optional) — from the GitHub Actions page; otherwise the latest failed run
+
+## Steps
+1. github — repo → `gh run list --limit 5` (gh missing, not authenticated, or no GitHub remote → log it, give the `gh auth login` / remote hint, stop) and `gh run view <id> --log-failed` excerpt in the run log — failing job and step named; no workflows exist → go to step 4 (setup path; skips steps 2, 3 and 6, and step 7 runs the new workflow's commands locally)
+2. deja-memory — error text → `deja fix` result in the run log — prior fix found, or "none"
+3. systematic-debugging — failing step → root cause and a local repro command — repro fails locally, or the reason it cannot run locally (a config-only fault: the validator or step commands are the repro for step 7)
+4. ci-pipeline (no workflows) or github-actions-generator (patch) — root cause → `.github/workflows/*.yml` diff — diff touches only the cause
+5. github-actions-validator — workflows → validator report — zero errors after the mandatory rerun
+6. bdbresilience — only if step 3 classified the failure as transient → retry or timeout on that step only — no blanket retries
+7. verification-before-completion — repro command → fresh passing output pasted in the run log — output pasted, not claimed
+8. git commit `ci: <cause>` — stage only the changed `.github/workflows/*` files (never the run log) → SHA in the run log — commit hook passes
+9. [GO] git push — SHA → remote branch (name the branch in the WAITING FOR GO line) — The run stops here until the human types GO. Each retry cycle that pushes again needs its own fresh GO here.
+10. github — SHA → `<id>` from `gh run list --commit <sha> --limit 1 --json databaseId` (wait until it exists), then `gh run watch <id> --exit-status` — `gh run list --commit <sha> --json conclusion -q '.[0].conclusion'` equals `success`; otherwise back to step 3, at most 2 cycles (each push behind a fresh GO at step 9), then stop and escalate
+
+Run log: `production_artifacts/pb-ci-fix-<date>.md`
+
+Rules
+- Anything other than the literal GO (case-insensitive) is not a GO; a GO covers only that one step, one time.
+- A failed check stops the run: write the failure into the run log and report. No silent retries beyond what a step names.
+- Write one run-log line per step as it completes (`N. done|skipped|failed — artifact — check result`) and `WAITING FOR GO: <step>` at each gate.

package/skills/playbooks/pb-event-tracker/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pb-event-tracker
+description: >-
+  Build one spreadsheet for an event covering guests, vendors, timeline and
+  budget, from your event brief and vendor list, and draft the vendor
+  messages for your GO. Use for "event tracker", "plan this event", "track
+  vendors and budget", "event spreadsheet".
+category: media-eventtech
+kind: playbook
+trigger: ["event tracker", "track my event", "vendor and budget sheet"]
+inputs: [event_brief, vendor_list]
+requires:
+  skills: [bdb-eventagency-skill]
+  agents: []
+  mcps: []
+  store: []
+go_points: [send vendor or guest messages]
+outputs: ["brief.md", "tracker.csv", "summary.md", "vendor-requests-draft.md", "run-log.md"]
+verify: "summary.md total recomputed from tracker.csv matches"
+difficulty: intermediate
+est_time: 20-40 min
+disable-model-invocation: true
+---
+
+# Event tracker
+What you get: guests, vendors, timeline and budget for one event in a single spreadsheet.
+
+## Inputs
+- An event brief — a text or document file describing the event
+- A vendor list — a file with the vendors and what each provides
+- A save folder — asked once; default `./pb-event-tracker-<date>/`
+
+## Steps
+1. Ask once — save folder, event brief, vendor list → `run-log.md` — the files are readable
+2. bdb-eventagency-skill (section "2. Client & Project Intake") — brief → `brief.md` with date, venue, attendance estimate, budget range — missing fields listed as `?`
+3. bdb-eventagency-skill (section "4. Vendor Management", status list) — vendor list → `tracker.csv`, columns section, item, owner, status, due, cost, notes; sections guest, vendor, timeline, budget (the budget section holds one budget line whose amount goes in `notes`, never in `cost`; costs sit on their rows; guest rows from a guest list if given, else one `?` row) — every vendor from your list is present
+4. bdb-eventagency-skill (section "5.1 Pre-production", run-of-show and day-minus milestones) — event date → timeline rows in `tracker.csv` (date `?` → ask, else skip the timeline and log it) — no row dated after the event
+5. Total = sum of `cost` over all rows except the budget row; budget = the amount in the budget row's `notes` → `summary.md` with total versus budget, over or under — the sum recomputed from `tracker.csv` matches; budget `?` is reported as "budget unknown"
+6. Show `tracker.csv` and `summary.md` in full and apply your edits until you approve — approval logged
+7. Write `vendor-requests-draft.md` (requests and confirmations), each recipient as name + address (`?` blocks sending until you fill it) — draft only, nothing is sent
+8. [GO] Send the vendor or guest messages through a connector you name, or send them yourself — show every recipient and the full text of every message first. The run stops here until the human types GO. The GO covers exactly the recipients and messages shown and nothing else; a different or added recipient needs a fresh GO. Never send to anyone not listed in `vendor-requests-draft.md`.
+
+The tracker is a CSV file that opens in any spreadsheet app.
+
+Run log: `run-log.md` in the save folder. One line per step as it completes (`N. done|skipped|failed — file — check result`), and `WAITING FOR GO: <step>` at the gate. Anything other than the literal GO (case-insensitive) is not a GO. If a check fails, stop, write the failure into the log and tell the user.

package/skills/playbooks/pb-meeting-actions/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pb-meeting-actions
+description: >-
+  Turn a meeting transcript into clean notes, the decisions, and who does
+  what by when, then draft the follow-up mail and send it only after your GO.
+  Use for "meeting notes", "action items from this meeting", "who did what
+  in this transcript", "who does what after the call".
+category: bdb-core
+kind: playbook
+trigger: ["meeting notes", "action items from this meeting", "follow-up mail"]
+inputs: [transcript_file]
+requires:
+  skills: [memb-skill]
+  agents: []
+  mcps: []
+  store: []
+go_points: [send follow-up]
+outputs: ["notes.md", "decisions.md", "actions.md", "followup-draft.md", "run-log.md"]
+verify: "every decision and action in the files cites a transcript line"
+difficulty: beginner
+est_time: 10-20 min
+disable-model-invocation: true
+---
+
+# Meeting notes and action list
+What you get: clean notes, the decisions, and who does what by when, from a meeting transcript.
+
+## Inputs
+- A transcript file (.txt, .md, .vtt or .srt) — exported from your meeting tool; an audio file alone is not enough
+- A save folder — asked once; default `./pb-meeting-actions-<date>/`
+
+## Steps
+1. Ask once — save folder and transcript file → `run-log.md` (create the folder only after the file check passes) — the file is readable; if you only have audio, ask for the transcript export instead (no transcription is available here)
+2. Read the transcript → `notes.md` with attendees and at most 10 summary bullets — each bullet cites a timestamp or line
+3. Read the transcript → `decisions.md` — each decision traced to a transcript line
+4. Read the transcript → `actions.md` as a table: owner, task, due, source — an unknown owner or due date is written as `?`, never guessed
+5. Show notes, decisions and actions in full and apply your edits until you approve — approval logged
+6. Write `followup-draft.md`, one mail per recipient group, each recipient as name + address (`?` blocks sending until you fill it) — draft only, nothing is sent
+7. [GO] Send the follow-up through a connector you name; without one, you copy the draft yourself — show every recipient and the full text of every message first. The run stops here until the human types GO. The GO covers exactly the recipients and messages shown and nothing else; a different or added recipient needs a fresh GO. Never send to anyone not listed in `followup-draft.md`.
+8. memb-skill — optional, ask first: store the decisions — memory ids logged
+
+Run log: `run-log.md` in the save folder. One line per step as it completes (`N. done|skipped|failed — file — check result`), and `WAITING FOR GO: <step>` at the gate. Anything other than the literal GO (case-insensitive) is not a GO. If a check fails, stop, write the failure into the log and tell the user.

package/skills/playbooks/pb-project-new/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pb-project-new
+description: >-
+  Start a new private GitHub project the AOS way: create the private repo,
+  bootstrap AOS (project card, AGENTS.md, wiki, memory, CI choice), push
+  after GO, and confirm the first CI run is green and the repo is still
+  private. Use for "new project", "start a repo", "bootstrap a project".
+category: bdb-core
+kind: playbook
+trigger: ["new project", "start a new repo", "bootstrap a project"]
+inputs: [name, owner, local_folder, upstream_url?]
+requires:
+  skills: [github, aos-project-init, pb-ci-fix, "gh (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [gh repo create, git push -u origin main]
+outputs: [".aos/project.json", "AGENTS.md", ".openwiki/", "production_artifacts/pb-project-new-<date>.md"]
+verify: "gh repo view <owner>/<name> --json visibility -q .visibility == PRIVATE"
+difficulty: intermediate
+est_time: 20-40 min
+disable-model-invocation: true
+---
+
+# New private AOS project
+What you get: a private GitHub repo with AOS bootstrapped, pushed, and a first CI run checked.
+
+## Inputs
+- name, owner — asked in step 1
+- local_folder — where the clone goes, asked in step 1
+- upstream_url (optional) — a repo to track as `upstream`, asked in step 1
+
+## Steps
+1. Ask — name, owner, local folder, optional upstream URL → run log header in the start directory (`production_artifacts/pb-project-new-<date>.md`, never committed) — all answered
+2. [GO] github — from the parent of `<local_folder>` (`cd` there first; the clone lands in `<name>/`), `gh repo create <owner>/<name> --private --clone` → repo and local clone — The run stops here until the human types GO.
+3. github — `gh repo view <owner>/<name> --json visibility -q .visibility` → value in the run log — must equal `PRIVATE`; otherwise fail-stop: write the value to the run log, tell the user, push nothing, and do not delete or change the repo (destructive actions need the user's confirmation)
+4. Upstream given → `git remote add upstream <url>` — `git remote -v` shows it; never push to `upstream` (no `gh repo fork`: a fork of a public repo cannot be private)
+5. aos-project-init — folder → `.aos/project.json`, `AGENTS.md` and symlinks, OpenWiki, memB project card, Synapse, CI choice (it may create triage labels and write `../WORKTREE.md`; aos-project-init asks for its own write-list approval) — doctor rows green or exceptions named, `.openwiki/` present; accept aos-project-init's own commit if it makes one, step 6 commits only what is left, never the run log
+6. git commit `chore: bootstrap AOS project` — remaining bootstrap files → SHA — commit hook passes (skip if nothing is left)
+7. [GO] `git branch -M main`, then git push -u origin main — SHA → remote — The run stops here until the human types GO.
+8. pb-ci-fix — only if CI was chosen in step 5: run its step 10 (watch the run on the pushed SHA) → conclusion `success`; if red, hand over to `/pb-ci-fix` from its step 1 (it has its own GO); then re-run the step 3 check — still `PRIVATE`
+
+Run log: `production_artifacts/pb-project-new-<date>.md` in the start directory, outside the new repo
+
+Rules
+- Anything other than the literal GO (case-insensitive) is not a GO; a GO covers only that one step, one time.
+- A failed check stops the run: write the failure into the run log and report. No silent retries.
+- Write one run-log line per step as it completes (`N. done|skipped|failed — artifact — check result`) and `WAITING FOR GO: <step>` at each gate.