@hybridlabor-api/aos 4.15.0 → 4.17.0

package/skills/playbooks/pb-landing-page/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pb-landing-page
+description: >-
+  Build and launch a landing page: confirmed copy without invented claims, a
+  generated page in your brand tokens, UI and SEO review, deploy only after
+  GO, then a check on the live URL. Use for "landing page", "launch page for
+  this product", "ship a one-pager".
+category: design-ui-ux
+kind: playbook
+trigger: ["landing page", "launch page for this product", "ship a one-pager"]
+inputs: [brief, brand_tokens, deploy_target, launch_video?]
+requires:
+  skills: [copywriting, landing-page-generator, godmode-ui-ux, ui-review, seo-audit, bdb-deploy, vercel-deployment, pb-launch-video]
+  agents: []
+  mcps: [chrome-devtools]
+  store: []
+go_points: [deploy]
+outputs: ["<page source>", "production_artifacts/pb-landing-page-<date>.md"]
+verify: "curl -sI <url> returns 200; seo-audit on the live URL has zero blocking items"
+difficulty: intermediate
+est_time: 1-3 h
+---
+
+# Landing page launch
+What you get: a live landing page with checked copy, SEO basics and, if you have one, a launch video.
+
+## Inputs
+- brief — product brief: audience, offer, proof you can show
+- brand_tokens — path to the design tokens or brand notes
+- deploy_target — `bdb-deploy` (rsync over SSH) or `vercel`, with the target host or project
+- launch_video (optional) — an mp4 from pb-launch-video, used as the hero video
+
+## Steps
+1. Ask — brief, brand_tokens, deploy_target, launch_video → run log — all answered; token path exists; `chrome-devtools` is optional, if its tools are not loaded the screenshot in step 3 is skipped and logged
+2. copywriting — brief → confirmed brief, then page copy in the run folder — brief confirmed by the human, no claim without a source in the brief (no fabricated numbers, logos or quotes) — stops for approval
+3. landing-page-generator + godmode-ui-ux — approved copy, brand_tokens, launch_video → page source in the project — page opens locally; `puppeteer_navigate` and `puppeteer_screenshot` of the local page attached to the run log when chrome-devtools is available
+4. ui-review + seo-audit — page → findings table in the run log — no open blocking finding; fixes applied and rechecked before step 5
+5. [GO] deploy — via bdb-deploy (rsync) or vercel-deployment (`vercel deploy`), target host or project and the file list named in the WAITING FOR GO line. The run stops here until the human types GO. Neither command is hook-guarded, so this GO is the only guard. One GO = one deploy.
+6. Live check — `curl -sI <url>` and seo-audit on the live URL → run log — status 200 and zero blocking items; otherwise stop and report, no redeploy without a fresh GO at step 5
+
+Run log: `production_artifacts/pb-landing-page-<date>.md` in the start directory, never committed
+
+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.

package/skills/playbooks/pb-launch-video/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pb-launch-video
+description: >-
+  Turn a live app or landing page into a short launch video: composition
+  brief, render in Hyperframes or Remotion, an ffprobe check per format,
+  publish hand-off only after GO. Use for "launch video", "make a video of
+  the shipped app", "promo clip for the landing page".
+category: media-eventtech
+kind: playbook
+trigger: ["launch video", "video of the shipped app", "promo clip for the landing page"]
+inputs: [url, project, length, formats, render_tool]
+requires:
+  skills: [brag, remotion, "hyperframes (external)", "ffprobe (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [publish]
+outputs: ["renders/<project>/launch_<fmt>.mp4", "renders/<project>/publish.md", "production_artifacts/pb-launch-video-<date>.md"]
+verify: "ffprobe shows the asked WxH and duration per file"
+difficulty: intermediate
+est_time: 30-90 min
+---
+
+# Launch video of a shipped app
+What you get: a short launch video per format, checked with ffprobe, handed off for publishing after your GO.
+
+## Inputs
+- url — the live URL of the shipped app or landing page (for example from pb-landing-page)
+- project — a slug for `renders/<project>/`
+- length — target duration in seconds
+- formats — for example 16:9 (1920x1080) and 9:16 (1080x1920)
+- render_tool — `hyperframes` or `remotion` (remotion needs an existing Remotion project)
+
+## Steps
+1. Preflight — ask render_tool first; then `command -v ffprobe` and, for hyperframes, `test -f ~/.claude/skills/hyperframes/SKILL.md`. ffprobe missing → stop with "Missing tool: ffprobe. Install ffmpeg and rerun." Hyperframes missing → stop with "Missing skill: hyperframes (installed locally only, not shipped by AOS). Install it, or rerun with render_tool = remotion and the path of an existing Remotion project." Remotion chosen without an existing project → stop and ask for its path. Write nothing except the run log on a stop — all probes answered
+2. Ask — url, project slug, length, formats, render_tool → run log and `renders/<project>/` — all answered; `curl -sI <url>` returns 200
+3. brag — url → composition brief in `renders/<project>/brief.md` (scenes, copy lines, length, formats; brag's brief stage only, the render choice stays with render_tool) — stops for approval
+4. Render — either way one file per format:
+   - hyperframes: brag with hyperframes → `renders/<project>/launch_<fmt>.mp4`
+   - remotion: from the Remotion project dir, `npx remotion render <Composition> <out>` per format (network/npm on first run needs approval)
+5. ffprobe — per file: `ffprobe -v error -select_streams v:0 -show_entries stream=width,height:format=duration -of json <file>` → WxH and duration in the run log — equals the asked WxH, duration within 1 s of length; on a mismatch stop with "export <format> has WxH, expected ...", do not publish, invent no conversion command; then the clips stop for approval (taste review)
+6. [GO] publish — destination and the full file list shown. The run stops here until the human types GO. No publish MCP or CLI exists on this machine, so the GO releases the hand-off: the files plus the caption in `renders/<project>/publish.md`; upload is manual unless the human named a tool in step 2 — hand-off file written
+
+Run log: `production_artifacts/pb-launch-video-<date>.md` in the start directory, never committed
+
+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.

package/skills/playbooks/pb-machine-setup/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pb-machine-setup
+description: >-
+  Bring a new machine to a verified AOS installation: read-only doctor
+  baseline, install after GO, MCP servers wired per harness with the configs
+  backed up first, memB and OpenWiki checks, and a second doctor run for the
+  delta. Use for "set up this machine", "onboard a new computer", "install AOS
+  on this laptop".
+category: bdb-core
+kind: playbook
+trigger: ["set up this machine", "onboard a new computer", "install AOS on this machine"]
+inputs: [machine_role, harnesses]
+requires:
+  skills: [aos-setup, mcp-manage, memb-skill, openwiki-skill, "node (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [install]
+outputs: ["production_artifacts/pb-machine-setup-<date>.md", "production_artifacts/pb-machine-setup-<date>/config-backup/"]
+verify: "second doctor run shows zero failing rows, or each remaining one is logged with its fix hint"
+difficulty: intermediate
+est_time: 30-60 min
+---
+
+# New machine to a verified AOS install
+What you get: a machine with AOS, MCP servers, hooks, memB and OpenWiki installed and checked by the doctor, with a before-and-after report and a backup of every harness config that was edited.
+
+## Inputs
+- machine_role — `dev`, `show` or `server`, asked if missing; a `server` skips the desktop-only rows (LaunchAgents, Synapse) and logs that choice
+- harnesses — the harnesses to wire (Claude Code, Antigravity, Codex, OpenCode, Cursor, Roo), asked if missing; only these are touched
+
+## Steps
+1. aos-setup (Measure) — `command -v node` (Node 22 or newer, else stop with an install hint), then the doctor read-only, exactly as the aos-setup skill gives it: `node skills/global_config/aos-setup/scripts/aos-doctor.mjs` from the AOS repo, or `node ~/.claude/skills/aos-setup/scripts/aos-doctor.mjs` from an installed copy → baseline table (failing rows with their fix commands) in the run log — doctor ran, exit code and failing-row count logged; nothing was installed or edited. Then the backup: copy every harness config of the chosen harnesses (for example `~/.claude.json`, `~/.gemini/config/mcp_config.json`, `~/.codex/config.toml`, `opencode.jsonc`) into `production_artifacts/pb-machine-setup-<date>/config-backup/` and log the copied paths; a config that is missing is logged, not created — backup files exist before step 2, because the installer itself rewrites the harness configs
+2. [GO] install — the install or update commands aos-setup section 3 gives for the harnesses chosen, for example `npx -y @hybridlabor-api/aos@latest` — the WAITING FOR GO line shows the exact command, the harness list and the backup path (and the installer's `--dry-run` output if aos-setup section 3 offers it). The run stops here until the human types GO. The hook does not guard npm installs, so this GO is the only guard; the installed `aos` binary is never run to inspect the version (it starts the full installer and rewrites harness configs).
+3. mcp-manage — chosen harnesses → wire the MCP servers the machine_role needs per harness → server list per harness in the run log — this step never edits a config that step 1 has not backed up; a missing config is logged, not created blind
+4. memb-skill and openwiki-skill — memB engine, MCP registration and ambient hook; OpenWiki CLI, `~/.openwiki/.env` credentials and refresh daemon → check results in the run log — each check passes or is logged with its fix hint from aos-setup; credentials are never written into the run log
+5. aos-setup (Verify) — the doctor again, same command as step 1 → delta (fixed, still failing, new) in the run log — zero failing rows, or each remaining one logged with its fix hint and a note whether it is deliberate for this machine_role
+
+Run log: `production_artifacts/pb-machine-setup-<date>.md` in the start directory, never committed; the config backups are never committed
+
+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.

package/skills/playbooks/pb-master/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: pb-master
+description: >-
+  Run one control session over several Claude Code, Codex or OpenCode
+  sessions: roster, status board, GO board, GO <session> tokens, idle
+  notices and a handover file. Use for "master session", "supervise my
+  sessions", "run several agents", "one control window".
+category: bdb-core
+kind: playbook
+trigger: ["master session", "supervise my sessions", "run several agents"]
+inputs: [plan?, workers?]
+requires:
+  skills: [master-session, agenttrail, stay-within-limits, "claude (external)", "aos-acp (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [spawn workers, "GO <session>"]
+outputs: ["docs/sessions/master-<date>.md", "production_artifacts/pb-master-<date>.md"]
+verify: "handover lists every roster session with open/closed GO state; no file older than 10 min in ~/.aos/go/ unless listed as stale in the handover"
+difficulty: advanced
+est_time: 15 min setup, then session-long
+---
+
+# One control session over several agents
+What you get: a live roster, status board and GO board for your agent sessions, GO tokens relayed per session, and a handover file.
+
+## Inputs
+- plan (optional) — a plan file for the trail board, e.g. `production_artifacts/00_execution_plan.md`
+- workers (optional) — sessions to spawn (name, cwd or worktree, model, prompt) or to adopt (already running)
+
+## Steps
+1. Preflight — `command -v claude`, `command -v aos-trail`, `command -v aos-acp` → run log header — claude and aos-trail present, else stop with an install hint; `aos-acp` missing → log "aos-acp not on PATH" and look for `bin/aos-acp.mjs`: `p="$(dirname "$(readlink -f "$(command -v aos-trail)")")/../../../../bin/aos-acp.mjs"; test -f "$p"` (or the repo path the human gives), run it as `node "$p"` in place of `aos-acp`; missing → Claude workers only (logged); read `docs/sessions/master-*.md` if one exists (the previous handover)
+2. master-session (Roster) — `ListAgents` minus self → roster table (name, repo@branch, adopted or spawned) in the run log — stops for approval (the human confirms scope)
+3. agenttrail — plan given → `aos-trail . --plan <plan> --no-open` → board URL in the run log; no plan → `aos-trail . --no-open` (file activity only), logged — URL printed (output says "already running" → log it as "existing map", its plan is unchanged); runs before any worker is spawned, so no spawn line exists in the run log before the board URL line
+4. [GO] spawn — worker list (name, cwd or worktree, model, prompt) shown in full, then one line per worker:
+   - Claude: `(cd <cwd> && claude --bg --name <n> --permission-mode auto --model <opus|sonnet|haiku> "<prompt>")` (`claude` has no cwd flag; prompt before any `--disallowedTools`)
+   - Codex or OpenCode: `aos-acp <codex|opencode> --name <n> --cwd <worktree> --prompt "<task>" --go-wait 600` in the background, log `~/.aos/acp/<n>.jsonl`
+   - agy: adopt-only (an already running session, no spawn); never `aos-acp agy`, the adapter is third-party and unverified (`bin/aos-acp.mjs` lines 26+)
+   - Never `aos-acp claude` (no model flag), never `--model fable`, never omit `--model`
+   - The run stops here until the human types GO. The hook does not guard `claude --bg`, so GO is by contract. Check: every spawned name shows in `ListAgents` or has an ACP log
+   - Adopt-only roster → step skipped
+5. master-session (Status) — master-session Step 2 template verbatim, reply in at most 10 lines, one `SendMessage` per session → replies in the run log — every in-scope session replied or is marked "no reply"
+6. master-session (GO board) — replies → GO board block per session, `GO needed` commands verbatim → board in the run log — no paraphrased command
+7. [GO] token relay — the human types `GO <session>` in the master (`go-token.mjs` writes `~/.aos/go/<session>.token`); the master then tells that worker only "retry the blocked command". The run stops here until the human types `GO <session>`. The master never types or forwards a GO itself, and any other human message cancels a pending token — the worker's log shows the command ran
+8. Idle rules — `notify_when_idle` only after sending a session work; no polling, no "are you done?" → idle events in the run log; between waves a stay-within-limits check, logged — events logged
+9. Handover — roster, last GO board, open GO items, who waits on whom, next command → `docs/sessions/master-<date>.md` (outside a repo: `~/.aos/handover/`) — every roster session listed with its GO state; `ls ~/.aos/go/` has no token older than 10 min unless listed as stale in the handover (report stale ones, do not delete them)
+
+Run log: `production_artifacts/pb-master-<date>.md` in the start directory; the run log and the handover file `docs/sessions/master-<date>.md` are never staged or committed
+
+Rules
+- Anything other than the literal GO (case-insensitive; in step 7 `GO <session>`) 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.

package/skills/playbooks/pb-newsletter/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pb-newsletter
+description: >-
+  Turn a pb-ship recap, a changelog range or a quick recap into a newsletter
+  email draft where every claim cites a source line, and send it only after
+  GO. Use for "newsletter from the recap", "write the release newsletter",
+  "email update from the changelog".
+category: design-ui-ux
+kind: playbook
+trigger: ["newsletter from the recap", "release newsletter", "email update from the changelog"]
+inputs: [recap, audience]
+requires:
+  skills: [quick-recap, copywriting, pb-ship]
+  agents: []
+  mcps: []
+  store: [brand-voice, email-ops]
+go_points: ["send newsletter"]
+outputs: ["facts.md", "newsletter.md", "run-log.md"]
+verify: "every product claim in newsletter.md cites a line in facts.md"
+difficulty: intermediate
+est_time: 20-40 min
+---
+
+# Newsletter from a recap
+What you get: a newsletter draft (subject, preheader, body) built only from facts you can trace, sent after your GO.
+
+## Inputs
+- recap — a pb-ship run log, a CHANGELOG range, or quick-recap output
+- audience — who reads it, asked once
+- A save folder — asked once; default `./pb-newsletter-<date>/`
+
+## Steps
+1. Check the store — `test -d ~/.claude/skills/brand-voice` and `test -d ~/.claude/skills/email-ops` → `run-log.md` (create the folder only after the recap file or range is confirmed readable) — an absent item is logged "Missing store item: <name>, install via aos-store" and the run continues with copywriting
+2. quick-recap — the recap → `facts.md`, one line per fact with its source line or file — every fact cites a source
+3. brand-voice if present, else copywriting — `facts.md` and the audience → `newsletter.md` with subject, preheader and body, no claim outside `facts.md` — stops for approval, edits applied until approved
+4. [GO] send newsletter — through a connector the human names (email-ops if present); the recipients or list, the subject and the full text shown first. The run stops here until the human types GO. Without a connector, the GO releases a hand-off file instead: `newsletter.md` with the recipient list, you send it yourself. A sending connector is not hook-guarded, so this GO is its only guard. The GO covers exactly the audience and message shown; a changed audience needs a fresh GO.
+
+Run log: `run-log.md` in the save folder, never committed
+
+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.

package/skills/playbooks/pb-offer/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pb-offer
+description: >-
+  Draft a client offer with line items priced only from your price list, and
+  send it only after your GO. Use for "write an offer", "quote for this
+  client", "draft a quote", "price this job".
+category: bdb-core
+kind: playbook
+trigger: ["write an offer", "quote for this client", "draft a quote"]
+inputs: [client_brief, price_list]
+requires:
+  skills: [bdb-eventagency-skill, copywriting]
+  agents: []
+  mcps: []
+  store: []
+go_points: [send offer]
+outputs: ["offer.md", "run-log.md"]
+verify: "every unit price exists in the price list; total recomputed from line items matches"
+difficulty: beginner
+est_time: 10-20 min
+---
+
+# Client offer
+What you get: a client offer with line items, priced only from your price list.
+
+## Inputs
+- A client brief — a text or document file
+- A price list file — item and unit price per line
+- A save folder — asked once; default `./pb-offer-<date>/`
+
+## Steps
+1. Ask once — save folder, client brief, price list; also the VAT rate and the offer validity → `run-log.md` — the files are readable
+2. bdb-eventagency-skill (section "2. Client & Project Intake") — brief → scope and line items; an item with no price in the list is marked `no price`, never priced by guess
+3. Write `offer.md`: items, quantity, unit price, line total, net total, VAT at the rate you gave, gross total, validity — every unit price exists in the price list; the net total recomputed from the line items matches
+4. copywriting — brief and `offer.md` → the cover text at the top of `offer.md`; no claims beyond the brief
+5. Show `offer.md` in full and apply your edits until you approve — approval logged
+6. [GO] Send the offer through a connector you name, or send it yourself — show the recipient (name + address, `?` blocks sending until you fill it) and the full text first. The run stops here until the human types GO. The GO covers exactly the recipient and message shown and nothing else; a different or added recipient needs a fresh GO. The go-gate hook does not guard sending: this [GO] is the only guard.
+
+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-open-source/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: pb-open-source
+description: >-
+  Prepare a project for open sourcing: a sanitized fork with secrets and
+  internal references stripped, a sanitizer verdict, README and LICENSE, then a
+  new PRIVATE GitHub repo created and pushed only after GO. The playbook never
+  makes the repo public. Use for "open source this project", "make a sanitized
+  fork", "prepare a public release".
+category: engineering-method
+kind: playbook
+trigger: ["open source this project", "sanitized fork", "prepare a public release"]
+inputs: [source_repo, target_name, owner, license]
+requires:
+  skills: [github-repo, readme, github, "gh (external)"]
+  agents: [opensource-forker, opensource-sanitizer]
+  mcps: []
+  store: []
+go_points: ["gh repo create", "git push"]
+outputs: ["<fork dir>", "<sanitizer report>", "production_artifacts/pb-open-source-<date>.md"]
+verify: "sanitizer verdict PASS or PASS-WITH-WARNINGS logged; gh repo view <owner>/<name> --json visibility -q .visibility == PRIVATE; LICENSE and README.md exist on the pushed default branch (gh api repos/<owner>/<name>/contents/LICENSE and README.md return 200)"
+difficulty: advanced
+est_time: 1-3 h
+---
+
+# Sanitized fork in a new private repo
+What you get: a sanitized copy of the project with README and LICENSE in a new private GitHub repo, with the sanitizer verdict logged. Going public stays your own action, outside this run.
+
+## Inputs
+- source_repo — the local checkout to fork, asked if missing
+- target_name — the new repo name, asked if missing
+- owner — the GitHub user or org for the new repo, asked if missing
+- license — the license id for the LICENSE file (for example MIT or Apache-2.0), asked if missing
+
+## Steps
+1. opensource-forker (agent) — source_repo → fork dir `<scratch>/<target_name>` (`<scratch>` = `mktemp -d`) and `.env.example`, secrets and internal references stripped, git history cleaned — fork dir exists; the source repo is untouched (`git -C <source_repo> status --short` is unchanged)
+2. opensource-sanitizer (agent) — fork dir → report with the verdict PASS, FAIL or PASS-WITH-WARNINGS in the run log — FAIL stops the run: the findings are logged, nothing is created or pushed
+3. github-repo + readme — fork dir, license → README.md and LICENSE in the fork dir following the repo standards — stops for approval (the human reads both files and the warnings from step 2)
+4. git — `git -C <fork dir> rev-parse --git-dir` (not a repo → `git -C <fork dir> init`), then `git -C <fork dir> add README.md LICENSE` plus each file the forker produced, listed by explicit path (never `-A` or `.`), then `git -C <fork dir> commit -m "Initial sanitized release"` → commit SHA in the run log — `git -C <fork dir> status --short` is empty and README.md and LICENSE are in `git -C <fork dir> ls-tree -r HEAD --name-only`
+5. [GO] gh repo create — `gh repo create <owner>/<target_name> --private` — the WAITING FOR GO line names owner, name and `--private`. The run stops here until the human types GO. (`gh repo create` is not hook-guarded; this GO is its only guard.)
+6. github — `gh repo view <owner>/<target_name> --json visibility -q .visibility` → run log line — equals `PRIVATE`, else stop
+7. [GO] git push — `git -C <fork dir> remote add origin <url>` is part of this step, then the push of the default branch to `origin` — the WAITING FOR GO line names the remote URL, the branch and the commit SHA from step 4. The run stops here until the human types GO. (The hook guards `git push`; the other commands here are not hook-guarded.)
+8. github — `gh repo view <owner>/<target_name> --json visibility -q .visibility`, then `gh api repos/<owner>/<target_name>/contents/LICENSE` and `.../contents/README.md` → final run log line — LICENSE and README.md both return 200 on the default branch, else stop; the run log ends with the sanitizer verdict and the line "visibility stays PRIVATE; flipping it is the human's own action"
+
+Run log: `production_artifacts/pb-open-source-<date>.md` in the start directory, never committed
+
+Rules
+- This playbook never runs `gh repo edit --visibility` or any other command that changes visibility.
+- 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.

package/skills/playbooks/pb-pcb-to-case/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pb-pcb-to-case
+description: >-
+  From a KiCad board to a parametric enclosure that fits it: ERC and DRC
+  clean, board dimensions extracted, an OpenSCAD case with your clearance,
+  Gerbers exported, fab hand-off only after GO. Use for "PCB to enclosure",
+  "case for this board", "KiCad to OpenSCAD case".
+category: engineering-hardware
+kind: playbook
+trigger: ["PCB to enclosure", "case for this board", "KiCad to OpenSCAD case"]
+inputs: [kicad_project, clearance_mm, mounting_style]
+requires:
+  skills: [godmode-hardware-pcb, "pcb-validation-dfm-signoff (external)", "pcb-constraint-definition (external)", "code-first-hardware-design (external)"]
+  agents: []
+  mcps: [kicad, openscad]
+  store: []
+go_points: [fab order]
+outputs: ["hw/<project>/dims.json", "hw/<project>/case.scad", "hw/<project>/case.stl", "hw/<project>/gerbers/", "hw/<project>/fab.md", "production_artifacts/pb-pcb-to-case-<date>.md"]
+verify: "run_drc zero errors; case inner dims >= board dims + clearance on every axis (recomputed from dims.json)"
+difficulty: advanced
+est_time: 1-3 h
+---
+
+# PCB to enclosure
+What you get: a DRC-clean board and a parametric enclosure that fits it, with Gerbers ready for a fab order that you place after your GO.
+
+## Inputs
+- kicad_project — path to the KiCad project (`.kicad_pro`, `.kicad_pcb`, `.kicad_sch`)
+- clearance_mm — gap between board and case wall on every axis
+- mounting_style — for example standoffs, rails or snap-fit
+
+## Steps
+1. Preflight — `get_pcb_statistics` on `kicad`; `get_capabilities` on `openscad`; `test -f ~/.claude/skills/<name>/SKILL.md` for `pcb-validation-dfm-signoff`, `pcb-constraint-definition` and `code-first-hardware-design`. MCP tools may be deferred in the harness: try to load the tool once via the harness tool search before declaring it missing. MCP tool not loaded or call errors → stop with "Missing MCP: `<server>` (`<tool>` unavailable). Check `mcpServers.<server>` in your harness config." A skill file absent → stop with "Missing skill: <name> (installed locally only, not shipped by AOS). Install it and rerun." Write nothing except the run log on a stop — all probes answered
+2. Ask — kicad_project, clearance_mm, mounting_style, project slug → run log and `hw/<project>/` — all answered, project files exist
+3. pcb-validation-dfm-signoff + godmode-hardware-pcb — `run_erc` and `run_drc` (details via `get_erc_violations` and `get_drc_violations`) → violation list in the run log — zero errors; any error stops the run, the board is not edited by this playbook
+4. pcb-constraint-definition — board outline, mounting holes and connector positions (`get_pcb_statistics`, `list_pcb_footprints`) → `hw/<project>/dims.json` (length, width, thickness, holes, connector edges, all in mm) — all values present; a missing value is asked of the human, never guessed
+5. code-first-hardware-design + openscad — dims.json, clearance_mm, mounting_style → `case.scad` (parameters at the top, driven by dims.json), then `create_model_from_scad` (returns the `model_id`), then STL and a preview via `export_model` and `get_model_preview` with that `model_id` → `case.stl` — inner dims >= board dims + clearance_mm on every axis, recomputed from dims.json and logged — stops for approval
+6. Gerbers — `export_gerber` → `hw/<project>/gerbers/` — files exist; `run_drc` again with zero errors on the exported state
+7. [GO] fab hand-off — `hw/<project>/fab.md` with the Gerber list, board dimensions, layer count and case STL, shown in full. The run stops here until the human types GO. No fab ordering tool exists: the GO releases only the hand-off file and the order is placed manually by the human. — fab.md written
+
+Run log: `production_artifacts/pb-pcb-to-case-<date>.md` in the start directory, never committed
+
+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.

package/skills/playbooks/pb-redesign-app/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pb-redesign-app
+description: >-
+  Overhaul one app's UI against an audit: UX audit and UI review of the
+  running app, current versus proposed design tokens, a before/after visual
+  plan, a startcycle build, point fixes, accessibility and browser tests,
+  delivered as a PR after GO. Use for "redesign this app", "design overhaul",
+  "audit and fix the UI", "give the app a new look".
+category: design-ui-ux
+kind: playbook
+trigger: ["redesign this app", "design overhaul", "audit and fix the UI"]
+inputs: [repo, app_url, scope]
+requires:
+  skills: [ux-audit, ui-review, ui-tokens, godmode-ui-ux, visual-plan, visual-edit, startcycle, wcag-audit-patterns, webapp-testing, github, "gh (external)"]
+  agents: [architect, techlead, reviewer]
+  mcps: [chrome-devtools]
+  store: []
+go_points: ["git push + gh pr create"]
+outputs: ["production_artifacts/pb-redesign-app-<date>.md", "production_artifacts/pb-redesign-app-<date>/audit.md", "production_artifacts/pb-redesign-app-<date>/tokens-diff.md"]
+verify: "repo test/lint scripts exit 0 on the pushed SHA; gh pr view <branch> --json state -q .state == OPEN; every audit finding marked fixed or deferred in the run log"
+difficulty: advanced
+est_time: 2-4 h
+---
+
+# Redesign one app
+What you get: one app's UI overhauled against a written audit, new design tokens and a before/after plan, delivered as a pull request after your GO.
+
+## Inputs
+- repo — the app's checkout, default the current directory
+- app_url — the running local dev URL (not a remote or production site)
+- scope — the screens or flows to redesign, asked once
+
+## Steps
+1. ux-audit and ui-review — `app_url` opened and screenshotted per screen in scope with chrome-devtools (`puppeteer_navigate`, `puppeteer_screenshot`) → `production_artifacts/pb-redesign-app-<date>/audit.md` with numbered findings — app_url unreachable or chrome-devtools unavailable → log it and stop; every finding has a screenshot or a file reference
+2. ui-tokens — current tokens read from the repo versus proposed DTCG tokens → `tokens-diff.md` in the same folder — diff written, nothing applied yet
+3. visual-plan — before/after per screen in scope → plan link or file in the run log — stops for approval
+4. startcycle (architect, techlead, reviewer) — the approved plan and audit → build on a new branch; godmode-ui-ux rules apply to the UI work — reviewer reports no open `blocking` finding
+5. visual-edit — point fixes the human picks in the running app, each after its diff plan is approved → edited files in the run log — only the picked files change
+6. wcag-audit-patterns and webapp-testing — accessibility pass plus a browser test of the changed screens, then the repo's lint and test scripts → results in the run log — all exit 0; each audit finding marked fixed or deferred
+7. [GO] git push -u origin <branch> and gh pr create — one combined GO; the WAITING FOR GO line names the branch, base branch, PR title and the head SHA. The run stops here until the human types GO. The hook guards `git push`; `gh pr create` is not hook-guarded, so this GO is its only guard. Afterwards `gh pr view <branch> --json state -q .state` equals `OPEN` and the PR URL is logged.
+
+Run log: `production_artifacts/pb-redesign-app-<date>.md` in the start directory, never committed
+
+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.

package/skills/playbooks/pb-release-aos/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: pb-release-aos
+description: >-
+  Release a new AOS version to npm through the release-please PR: check the
+  commit subjects, review and gate the release PR, merge it only after GO,
+  watch the release workflow and check version drift. Use for "release AOS",
+  "cut an AOS release", "merge the release PR", "publish a new AOS version".
+category: bdb-core
+kind: playbook
+trigger: ["release AOS", "cut an AOS release", "merge the release PR"]
+inputs: [repo?]
+requires:
+  skills: [github, pb-ship, bdb-shipping-skill, git-pr-review, visual-recap, godmode-shipping, quick-recap, "bdb-ecosystem-health (external)", "gh (external)"]
+  agents: [reviewer]
+  mcps: ["plan (optional)"]
+  store: []
+go_points: ["gh pr merge (release PR)"]
+outputs: ["production_artifacts/pb-release-aos-<date>.md"]
+verify: "npm view @hybridlabor-api/aos version == version in .release-please-manifest.json on main after merge"
+difficulty: advanced
+est_time: 30-60 min
+---
+
+# Release AOS to npm
+What you get: a new AOS version on npm through the release-please PR, never a hand bump, with the PR reviewed and gated before your GO.
+
+## Inputs
+- repo (optional) — the AOS checkout, default the current directory; `<owner/repo>` comes from `git -C <repo> remote get-url origin`
+
+## Steps
+1. Preflight — `gh auth status` and `test -f ~/.claude/skills/bdb-ecosystem-health/SKILL.md` → run log header — gh missing or unauthenticated → log it, give the `gh auth login` hint, stop; skill absent → log "Missing skill: bdb-ecosystem-health (installed locally only, not shipped by AOS). Drift report in step 7 skipped; the npm check still runs." and continue
+2. github — commits since the last tag (`git -C <repo> fetch --tags`, then `git -C <repo> describe --tags --abbrev=0`, then `git -C <repo> log <tag>..HEAD --format=%s`) → subject list in the run log, every non-Conventional subject flagged (release-please cannot see it, see AGENTS.md) — stops for approval
+3. github — `gh pr list -R <owner/repo> --state open --head release-please--branches--main --json number,title,headRefName` → the release PR number in the run log — none → stop with "no release PR"
+4. Review and gate on that PR, using these skills:
+   - git-pr-review — `gh pr view <n> -R <owner/repo> --json commits` → description draft in the run log — draft only, nothing posted
+   - visual-recap — `plan` connector present → recap link; absent → log "visual-recap skipped: no plan connector" and paste `gh pr diff <n> -R <owner/repo> --name-only` instead; no `npx` without approval
+   - reviewer (agent) — `gh pr diff <n> -R <owner/repo>`; the contract is the commit list from step 2, never the PR body → findings table — any open `blocking` finding stops the run
+   - bdb-shipping-skill — door class of the release PR (two-way or one-way; unclear counts as one-way) → class in the run log; one-way → ADR-lite `production_artifacts/decisions/<date>-<slug>.md` — class recorded
+   - godmode-shipping — `gh pr checks <n> -R <owner/repo>` all pass (pending, `gh pr checks` exit 8, counts as not passed), plus the local gate exactly as pb-ship step 8 gives it (scratch worktree from `pull/<n>/head`, lint, typecheck and test scripts that exist, a fork PR skips the local gate and is held, worktree removed without `--force`) → exit codes in the run log
+5. [GO] github — `gh pr merge <n> -R <owner/repo> --squash` — the WAITING FOR GO line names PR number, title, base branch, method and the version in `.release-please-manifest.json`. The run stops here until the human types GO. (The hook guards `gh pr merge`.) Never `npm version` or `npm publish` by hand.
+6. github — `<sha>` = the merge commit (`gh pr view <n> -R <owner/repo> --json mergeCommit -q .mergeCommit.oid`); `gh run list -R <owner/repo> --workflow release-please.yml --commit <sha> --limit 1 --json databaseId` (wait until a run exists), then `gh run watch <id> -R <owner/repo> --exit-status` → conclusion in the run log — exit 0
+7. npm check and drift — `npm view @hybridlabor-api/aos version` → run log — always run; equals the version in `.release-please-manifest.json` on main. bdb-ecosystem-health drift report only if step 1 found the skill
+8. quick-recap — run log → final line `🟢|🟡|🔴` with the released version — line written
+
+Run log: `production_artifacts/pb-release-aos-<date>.md` in the start directory, never committed
+
+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.

package/skills/playbooks/pb-security-sweep/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pb-security-sweep
+description: >-
+  Run a security sweep over one repo: secrets, dependencies and the diff,
+  a security review and a silent-failure hunt, one deduped and ranked findings
+  report, issues filed for blocking findings only after GO, each one handed to
+  pb-bug-fix. Use for "security sweep", "audit this repo", "check for leaked
+  secrets and vulnerable deps".
+category: engineering-method
+kind: playbook
+trigger: ["security sweep", "audit this repo", "check for leaked secrets"]
+inputs: [repo, scope]
+requires:
+  skills: [bdb-security-audit, pb-bug-fix, github, verification-before-completion, "gh (external)"]
+  agents: [security-reviewer, silent-failure-hunter]
+  mcps: []
+  store: []
+go_points: ["gh issue create"]
+outputs: ["production_artifacts/pb-security-sweep-<date>.md", "production_artifacts/pb-security-sweep-<date>/findings.md"]
+verify: "re-run shows zero open blocking findings, or each remaining one names its pb-bug-fix PR"
+difficulty: advanced
+est_time: 1-2 h
+---
+
+# Security sweep with ranked findings
+What you get: one ranked findings report for the repo (blocking, should, note), an issue per blocking finding filed after your GO on a private repo, and a before-and-after delta from the re-run.
+
+## Inputs
+- repo — the current directory, or the one the user names; `<owner/repo>` comes from `git -C <repo> remote get-url origin`
+- scope — `diff` (changes against the default branch) or `full` (the whole tree), asked if missing
+
+## Steps
+1. bdb-security-audit — repo, scope → secrets, dependency and diff findings in `production_artifacts/pb-security-sweep-<date>/findings.md` (optional scanners the skill cannot find are logged as skipped by the skill itself) — file written; secret values are never copied into the report, only file and line
+2. security-reviewer (agent) — same scope → findings appended to `findings.md` — each finding cites file and line
+3. silent-failure-hunter (agent) — same scope → findings appended to `findings.md` — each finding cites file and line
+4. Dedupe and rank — `findings.md` → one table, each finding `blocking`, `should` or `note`, with id, file, line, source step — stops for approval (the human confirms the ranking and which blocking findings get an issue)
+5. github — `gh repo view <owner/repo> --json visibility -q .visibility` → run log line — equals `PRIVATE`; `PUBLIC` or unknown → no issue is filed, the blocking findings stay in the report only (a secret in a public issue leaks it), logged, steps 6 and 7 skipped
+6. [GO] gh issue create — per approved blocking finding: `gh issue create -R <owner/repo> --title "<title>" --body-file <body>` with file, line and impact but no secret value — the WAITING FOR GO line names the finding id and the title. The run stops here until the human types GO. One GO = one issue. (`gh issue create` is not hook-guarded; this GO is its only guard.)
+7. pb-bug-fix — per filed issue → one pb-bug-fix run with its own GO for the push and the PR (nothing is pushed from this playbook) — each issue number is logged next to its PR URL or "deferred"
+8. bdb-security-audit — re-run as in step 1 → delta (fixed, still open, new) in the run log — every remaining blocking finding names its pb-bug-fix PR
+9. verification-before-completion — delta → run log line — zero open blocking findings, or each remaining one named with its PR; output pasted, not claimed
+
+Run log: `production_artifacts/pb-security-sweep-<date>.md` in the start directory, never committed; the findings file stays in `production_artifacts/` and is not staged
+
+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.

package/skills/playbooks/pb-ship/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pb-ship
+description: >-
+  Ship the day's work in one repo: triage new issues, review every open PR
+  (description, visual recap, adversarial reviewer, shipping pre-flight and
+  quality gate), merge only after GO, then post a status recap. Use for
+  "ship it", "ship day", "merge the ready PRs", "end of work block".
+category: engineering-method
+kind: playbook
+trigger: ["ship it", "ship day", "merge the ready PRs"]
+inputs: [repo, pr_numbers?]
+requires:
+  skills: [github, triage, git-pr-review, visual-recap, bdb-shipping-skill, godmode-shipping, quick-recap, "gh (external)"]
+  agents: [reviewer]
+  mcps: ["plan (optional)"]
+  store: []
+go_points: [gh pr merge]
+outputs: ["production_artifacts/pb-ship-<date>.md", "production_artifacts/pb-ship-<date>/pr-<n>.md", "production_artifacts/decisions/<date>-<slug>.md"]
+verify: "gh pr view <n> --json state -q .state == MERGED for every PR the log marks merged; gate exit 0 logged for each"
+difficulty: intermediate
+est_time: 20-60 min
+---
+
+# Ship the day's PRs
+What you get: the ready PRs merged one by one after your GO, each with a reviewed description, findings and a gate result, plus a status line.
+
+## Inputs
+- repo — the local checkout (default: the current directory); `<owner/repo>` comes from `git -C <repo> remote get-url origin`
+- pr_numbers (optional) — PRs to ship; otherwise you pick from the table in step 3
+
+## Steps
+1. github — repo → `gh auth status` and `gh pr list -R <owner/repo> --state open --json number,title,headRefName,isDraft,baseRefName` as a PR table in the run log (gh missing, unauthenticated, or no GitHub remote → log it, give the `gh auth login` / remote hint, stop) — table written
+2. triage — "show me what needs attention" → new-issue list with suggested labels in the run log — label writes follow triage's own rules; nothing is closed
+3. Ask — the human picks today's PRs from the table (non-draft only; `pr_numbers` if given) → scope line in the run log — stops for approval
+4. git-pr-review — per PR: `gh pr view <n> -R <owner/repo> --json commits` → description draft in `production_artifacts/pb-ship-<date>/pr-<n>.md` — draft only, nothing posted
+5. visual-recap — per PR: `plan` connector present → recap link in `pr-<n>.md`; absent → log "visual-recap skipped: no plan connector" and paste `gh pr diff <n> -R <owner/repo> --name-only` instead; no `npx` without approval — recap or fallback present
+6. reviewer (agent) — per PR: `gh pr diff <n> -R <owner/repo>`; the contract is the linked issue or plan (`gh pr view <n> -R <owner/repo> --json closingIssuesReferences,body`) or the human's scope line from step 3, the body is used only to find the linked issue/plan, its text is not the contract, and never `pr-<n>.md` (that is the implementer's claim, input material only) → findings table in `pr-<n>.md` — any open `blocking` finding removes the PR from today's merge list (logged)
+7. bdb-shipping-skill — per PR → door class (two-way or one-way) in `pr-<n>.md`; one-way → ADR-lite `production_artifacts/decisions/<date>-<slug>.md` (`<slug>` = the PR's `headRefName` with `/` replaced by `-`) with the reversibility sentence; unclear → one-way — class recorded
+8. godmode-shipping — per PR: `gh pr checks <n> -R <owner/repo>` all pass, plus a local gate in a scratch worktree — `gh pr view <n> -R <owner/repo> --json isCrossRepository -q .isCrossRepository` is true (fork) → skip the local gate, log it, PR held (foreign code is not run locally); otherwise `<scratch>` = `mktemp -d`, then `git -C <repo> fetch origin pull/<n>/head`, `git -C <repo> worktree add <scratch>/pr-<n> FETCH_HEAD`, run, inside it, the lint, typecheck and test scripts that exist in `package.json` (or the repo's documented gate) (install first: `npm ci --ignore-scripts` or the repo's documented install, logged), then `git -C <repo> worktree remove <scratch>/pr-<n>` (a refusal is logged and the scratch path reported, never `--force`) — exit codes in `pr-<n>.md`; any non-zero, or pending checks (`gh pr checks` exit 8) → PR held
+9. [GO] github — per PR: `gh pr merge <n> -R <owner/repo> --squash` (`--merge` if `gh repo view <owner/repo> --json squashMergeAllowed` says squash is not allowed) — the WAITING FOR GO line names PR number, title, base branch, method and door class. The run stops here until the human types GO. One GO = one PR. (The hook guards `gh pr merge`; the other commands here are not hook-guarded.)
+10. github — `gh pr view <n> -R <owner/repo> --json state -q .state` → run log line — equals `MERGED`
+11. quick-recap — run log → final line `🟢|🟡|🔴` with merged / held / skipped counts — line written
+
+Run log: `production_artifacts/pb-ship-<date>.md` in the start directory, never committed
+
+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.