@hybridlabor-api/aos 4.14.1 → 4.16.0

package/skills/playbooks/pb-health-weekly/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pb-health-weekly
+description: >-
+  Weekly health report over the BDB repos: git and npm version drift and CI
+  status as an HTML report with auto-remediation off, red CI routed to
+  pb-ci-fix, non-release remediation steps run one at a time after GO. Use for "weekly
+  health check", "ecosystem health", "are all repos green and in sync".
+category: saas-ops
+kind: playbook
+trigger: ["weekly health check", "ecosystem health", "are all repos green"]
+inputs: [repo_list?]
+requires:
+  skills: [pb-ci-fix, quick-recap, github, "bdb-ecosystem-health (external)", "gh (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [remediation]
+outputs: ["production_artifacts/pb-health-weekly-<date>.md", "<the skill's HTML report>"]
+verify: "report lists every repo with CI conclusion and version drift; each red repo names a pb-ci-fix run or a deferral"
+difficulty: intermediate
+est_time: 15-30 min
+---
+
+# Weekly ecosystem health
+What you get: an HTML health report with git and npm drift and CI status for every repo, red repos handed to pb-ci-fix, and a one-line status.
+
+## Inputs
+- repo_list (optional) — the repos to check; default is the list the bdb-ecosystem-health skill carries
+
+## Steps
+1. Preflight — `test -f ~/.claude/skills/bdb-ecosystem-health/SKILL.md`, `gh auth status` → run log header — skill absent → stop with "Missing skill: bdb-ecosystem-health (installed locally only, not shipped by AOS). Install it under `~/.claude/skills/` or run this playbook on the machine that has it." and write nothing except the run log; gh missing or unauthenticated → log it, give the `gh auth login` hint, stop
+2. bdb-ecosystem-health (external) — repo_list → HTML report with auto-remediation OFF (the report only proposes remediation) → report path in the run log — report exists; no remediation command was run
+3. github — report → table of every repo with version drift and CI conclusion in the run log (`gh run list -R <owner/repo> --limit 1 --json conclusion,headSha` per repo) — every repo listed; stops for approval (the human confirms which red repos to fix and which to defer)
+4. pb-ci-fix — per approved red repo → one pb-ci-fix run, with its own GO for the push — each red repo names its run log or "deferred: <reason>"
+5. [GO] remediation — per step the skill proposes in its report, except version bumps, tags, changelog edits and publishes, which are never run here: npm or git version drift is routed to pb-release-aos (or the repo's own release PR) and logged as a proposal; the exact command shown in the WAITING FOR GO line with the repo and what it changes. The run stops here until the human types GO. One GO = one remediation step. The playbook cannot know in advance whether a proposed command is hook-guarded: a `git push`, `npm publish` or `npm version` is guarded by the hook, any other command (an `npm install -g`, a `gh` write, an `rsync`) is not, and for those this GO is the only guard. No proposed steps → step skipped
+6. quick-recap — run log → final line `🟢|🟡|🔴` with green, red-fixed, red-deferred and drift counts — line written
+
+Run log: `production_artifacts/pb-health-weekly-<date>.md` in the start directory, never committed; the HTML report stays where the skill writes it 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-idea-to-launch/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: pb-idea-to-launch
+description: >-
+  Turn an idea into a deployed prototype: a spec from brainstorming, a visual
+  plan of the ComfyUI workflow, a prototype built with startcycle, one hero
+  image, green CI, then push and deploy after separate GOs. Use for "idea to
+  launch", "from idea to a live prototype", "build and deploy this idea".
+category: engineering-method
+kind: playbook
+trigger: ["idea to launch", "from idea to live prototype", "build and deploy this idea"]
+inputs: [idea, repo_or_new_project, comfy_workflow, deploy_target]
+requires:
+  skills: [bdbrainstorm, grill-me, visual-plan, prototype, startcycle, pb-ci-fix, bdb-deploy, github, "gh (external)"]
+  agents: [architect, techlead, reviewer]
+  mcps: [comfyui-mcp]
+  store: []
+go_points: ["git push", "deploy"]
+outputs: ["production_artifacts/pb-idea-to-launch-<date>.md", "production_artifacts/pb-idea-to-launch-<date>/spec.md", "production_artifacts/pb-idea-to-launch-<date>/plan.md", "production_artifacts/pb-idea-to-launch-<date>/hero.png"]
+verify: "gh run list --commit <sha> conclusion == success; curl -sI <url> returns 200"
+difficulty: advanced
+est_time: 2-6 h
+---
+
+# Idea to deployed prototype
+What you get: an idea turned into a deployed prototype with green CI and one hero image, pushed and deployed only after your GO.
+
+## Inputs
+- idea — a short description, asked once
+- repo_or_new_project — an existing checkout, or a name for a new project
+- comfy_workflow — path to a ComfyUI API-format workflow JSON, required, never invented
+- deploy_target — the host and path or the target the human names, asked once
+
+## Steps
+1. Preflight — one probe `check_comfyui_health` on `comfyui-mcp` (MCP tools may be deferred in the harness: try to load the tool once via the harness tool search before declaring it missing) → run log header — tool not loaded, call errors, or `status` is not `"online"` → log "Missing MCP: `comfyui-mcp` (`check_comfyui_health` unavailable). Start ComfyUI and check `mcpServers.comfyui-mcp` in your harness config." and mark step 5 to stop; steps 2 to 4 still run
+2. bdbrainstorm or grill-me — idea → `production_artifacts/pb-idea-to-launch-<date>/spec.md` — spec written, open questions listed
+3. visual-plan — the workflow and the planned prototype screens → `plan.md` in the same folder — stops for approval
+4. prototype, then startcycle (architect, techlead, reviewer) — spec and plan → prototype in the repo (a new project: a new local directory, no remote yet) — reviewer reports no open `blocking` finding
+   - Commit: a new project gets `git init` first; the reviewed prototype files are staged by explicit path (never `git add -A`) and committed — SHA in the run log; the working tree has no uncommitted product files afterwards
+5. ComfyUI — the workflow file's text (prompt filled in) as the JSON string for `queue_prompt` → `get_history <prompt_id>` status success → `get_output_media_info` path copied to `hero.png` in the run folder — one image; `local_path` is only set when `COMFYUI_DIR` is set, so if `local_path` is empty or `exists_locally` is false, stop with a clear message and copy nothing; preflight failed in step 1 → stop with the "Missing MCP" message and write nothing except the run log
+6. pb-ci-fix (setup path) — run its steps up to and including the commit, but not its push step → workflow files committed, SHA in the run log — validator zero errors, commit hook passes; the push is covered by step 7, so pb-ci-fix's own push GO is skipped here
+7. [GO] git push — SHA → remote branch (name the branch in the WAITING FOR GO line). A new project without a remote: `gh repo create <owner>/<name> --private --source . --remote origin` runs in the same GO, never public, never any other visibility; the line names owner and name. The run stops here until the human types GO. The hook guards `git push`; `gh repo create` is not hook-guarded, so this GO is its only guard.
+8. 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 pb-ci-fix's debugging steps, at most 2 cycles, each push behind a fresh GO as in step 7, then stop and escalate
+9. [GO] bdb-deploy — build from the committed tree only (a clean checkout of the pushed SHA, e.g. `git worktree add <scratch> <sha>`, removed with `git worktree remove <scratch>` (no `--force`) when the deploy ends or the run stops) and rsync to `deploy_target`, the target, the file list and the command shown in full. The run stops here until the human types GO. The rsync deploy is not hook-guarded, so this GO is its only guard.
+10. Check — `curl -sI <url>` → status line in the run log — returns 200
+
+Run log: `production_artifacts/pb-idea-to-launch-<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 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-image-to-3d/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pb-image-to-3d
+description: >-
+  Turn one reference image into a cleaned, scaled 3D asset: your own
+  image-to-3D ComfyUI workflow makes the mesh, Blender decimates it to a poly
+  budget, fixes scale, origin and material, and exports a .glb. Use for
+  "image to 3D", "make a 3D model from this picture", "photo to glb".
+category: media-eventtech
+kind: playbook
+trigger: ["image to 3D", "3D model from this picture", "photo to glb"]
+inputs: [image, comfy_workflow, poly_budget, project]
+requires:
+  skills: [bdb-blender-mcp, godmode-3d-creation]
+  agents: []
+  mcps: [comfyui-mcp, bdb_blender_mcp]
+  store: []
+go_points: []
+outputs: ["renders/<project>/asset.glb", "renders/<project>/preview.png", "production_artifacts/pb-image-to-3d-<date>.md"]
+verify: "asset.glb exists; Blender reports face count <= budget and non-zero dimensions"
+difficulty: advanced
+est_time: 30-90 min
+---
+
+# Image to 3D asset
+What you get: a cleaned, scaled `.glb` from one reference image, with a preview you approved.
+
+## Inputs
+- image — the reference image path
+- comfy_workflow — path to a ComfyUI API-format workflow JSON that contains the image-to-3D nodes; required, never invented (no TripoSR or TRELLIS server ships with AOS)
+- poly_budget — maximum face count
+- project — a slug for `renders/<project>/`
+
+## Steps
+1. Preflight — one probe per server, before any file is written: `check_comfyui_health` on `comfyui-mcp`; `get_scene_info` on `bdb_blender_mcp`. MCP tools may be deferred in the harness: try to load the tool once via the harness tool search before declaring it missing. Tool not loaded, call errors, or ComfyUI `status` is not `"online"` → stop with "Missing MCP: `<server>` (`<tool>` unavailable). Start <ComfyUI|Blender and click Connect to Claude in the BlenderMCP sidebar tab> and check `mcpServers.<server>` in your harness config." and write nothing except the run log — both probes answered
+2. Ask — image, comfy_workflow path, poly_budget, project slug, target size in metres → run log and `renders/<project>/` — all answered, image and workflow files exist
+3. ComfyUI — the workflow file's text with the image filled in as the JSON string for `queue_prompt` → `get_history <prompt_id>` status success → `get_output_media_info` path of the mesh file — a mesh file exists; `local_path` is only set when `COMFYUI_DIR` is set, so if `local_path` is empty or `exists_locally` is false, stop with a clear message and import nothing
+4. Blender (bdb-blender-mcp, godmode-3d-creation) — mesh file → via `execute_blender_code`: import, Decimate modifier down to poly_budget, scale to the target size, origin to base centre, one material, and report face count and dimensions; `get_scene_info` as the cross-check — face count <= poly_budget and non-zero dimensions; save the Blender project first, since scripted code can crash the session
+5. Preview — a viewport render saved to `renders/<project>/preview.png` via `execute_blender_code` — file exists — stops for approval (taste review); changes loop back to step 4
+6. Export — `execute_blender_code` runs the glTF binary export → `renders/<project>/asset.glb` — file exists and is larger than 0 bytes; re-import the file or read the exported object stats and log face count and dimensions again
+
+Run log: `production_artifacts/pb-image-to-3d-<date>.md` in the start directory, never committed
+
+Rules
+- 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 APPROVAL: <step>` at each stop.
+- This playbook has no GO step: it writes only under `renders/<project>/` and publishes nothing.

package/skills/playbooks/pb-inbox-zero/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pb-inbox-zero
+description: >-
+  Sort an email backlog into reply, delegate, archive and ignore, and draft
+  the replies. Nothing is sent without your GO. Use for "inbox zero", "sort
+  my mail", "clear my email backlog", "draft replies to my mail".
+category: bdb-core
+kind: playbook
+trigger: ["inbox zero", "sort my mail", "email backlog"]
+inputs: [mail_export_folder, connector?]
+requires:
+  skills: [memb-skill]
+  agents: []
+  mcps: []
+  store: [email-ops]
+go_points: [send replies]
+outputs: ["triage.md", "drafts.md", "run-log.md"]
+verify: "every mail in the export appears exactly once in triage.md"
+difficulty: beginner
+est_time: 10-20 min
+---
+
+# Inbox zero
+What you get: your email backlog sorted into reply / delegate / archive / ignore, with reply drafts. Nothing is sent without your GO.
+
+## Inputs
+- A mail export folder (.eml or .mbox) — exported from your mail app; there is no mail connector configured by default
+- A connector for sending — optional, you name it
+- A save folder — asked once; default `./pb-inbox-zero-<date>/`
+
+## Steps
+1. Ask once — save folder, mail export folder, optional sending connector (email-ops if `test -d ~/.claude/skills/email-ops` passes; absent → logged "Missing store item: email-ops, install via aos-store" and the run continues with the connector the human names, or none) → `run-log.md` — the export folder holds at least one .eml or .mbox; if you have neither an export nor a connector, stop with `Missing mail source: export your inbox to .eml/.mbox` and write nothing but the run log
+2. Read every mail → `triage.md`, one row per mail: sender, subject, date, class (reply / delegate / archive / ignore), one-line reason, source file — every mail in the export appears exactly once; the row count equals the mail count
+3. memb-skill — optional, ask first: search open commitments to the senders to inform the class — skipped and logged if memB is not installed
+4. For each reply row → `drafts.md`: recipient as name + address (`?` blocks sending until you fill it), subject, body — draft only, nothing is sent
+5. Show `triage.md` and `drafts.md` in full and apply your edits until you approve — approval logged
+6. [GO] Send the replies through the connector you named — 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 `drafts.md`. The go-gate hook does not guard sending: this [GO] is the only guard. Without a connector you copy the drafts yourself and the hand-off is 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-invoice-check/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: pb-invoice-check
+description: >-
+  Check invoices and receipts line by line against your offers and list what
+  matches, what differs and what has no offer. Nothing is paid or sent. Use
+  for "check my invoices", "match invoices to offers", "does this invoice
+  match the quote".
+category: bdb-core
+kind: playbook
+trigger: ["check my invoices", "match invoices to offers", "invoice check"]
+inputs: [invoices_folder, offers_folder]
+requires:
+  skills: [pb-offer]
+  agents: []
+  mcps: []
+  store: []
+go_points: []
+outputs: ["invoices.csv", "check.md", "run-log.md"]
+verify: "every PDF in the folder has exactly one row; every total recomputed from its lines"
+difficulty: beginner
+est_time: 10-20 min
+---
+
+# Invoice check
+What you get: invoices and receipts sorted and checked line by line against the matching offers.
+
+## Inputs
+- An invoices folder with PDFs
+- An offers folder — the `offer.md` files from pb-offer
+- A save folder — asked once; default `./pb-invoice-check-<date>/`
+
+## Steps
+1. Ask once — save folder, invoices folder, offers folder → `run-log.md`; list the PDFs. `pdftotext` is not installed, so you read each PDF with the harness PDF read; a PDF it cannot read becomes a row with status `unread` and the run continues — you may paste its text later
+2. Per readable PDF → `invoices.csv`, columns file, vendor, date, number, net, VAT, total, status — a field that is not on the invoice is `?`; every PDF in the folder has exactly one row
+3. Match each invoice to an offer by vendor, client and items → matched offer named in `invoices.csv`; no offer found → status `no offer`
+4. Write `check.md`: per invoice match / mismatch (which line, how much it differs) / no offer / unread — every total recomputed from its lines; the recomputed value and the printed value are both shown
+5. Show `invoices.csv` and `check.md` in full and apply your edits until you approve — approval logged
+
+Nothing is paid or sent, so there is no GO step. The run only reads the two folders and writes into the save folder.
+
+Run log: `run-log.md` in the save folder. One line per step as it completes (`N. done|skipped|failed — file — check result`). If a check fails, stop, write the failure into the log and tell the user.

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-meeting-actions/SKILL.md

@@ -19,7 +19,6 @@ outputs: ["notes.md", "decisions.md", "actions.md", "followup-draft.md", "run-lo
 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

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.