@hybridlabor-api/aos 4.15.0 → 4.17.0

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

@@ -0,0 +1,48 @@
+---
+name: pb-bug-fix
+description: >-
+  Turn a GitHub issue into a tested fix on a branch with an open PR: read the
+  issue as the contract, find the root cause, write the failing test first,
+  fix, prove it, review the diff against the issue, push and open the PR only
+  after GO. Merging stays with pb-ship. Use for "fix issue 42", "bug fix from
+  this issue", "turn this issue into a PR".
+category: engineering-method
+kind: playbook
+trigger: ["fix issue", "bug fix from issue", "issue to PR"]
+inputs: [repo, issue_number]
+requires:
+  skills: [github, deja-memory, systematic-debugging, test-driven-development, verification-before-completion, git-pr-review, "gh (external)"]
+  agents: [reviewer]
+  mcps: []
+  store: []
+go_points: ["git push + gh pr create"]
+outputs: ["production_artifacts/pb-bug-fix-<date>.md"]
+verify: "new test fails on the base SHA and passes on the branch SHA; gh pr view <branch> --json closingIssuesReferences contains <n>"
+difficulty: intermediate
+est_time: 30-90 min
+---
+
+# GitHub issue to tested fix and PR
+What you get: a branch with a failing-then-passing test and the fix, reviewed against the issue, and an open PR that closes it. Merging is a separate run (pb-ship).
+
+## Inputs
+- repo — the current directory, or the one the user names; `<owner/repo>` comes from `git -C <repo> remote get-url origin`
+- issue_number — the GitHub issue to fix, asked if missing
+
+## Steps
+1. github — repo, issue_number → `gh auth status`, then `gh issue view <n> -R <owner/repo> --json title,body,labels,state` as the contract (acceptance points as a list) in the run log (gh missing, unauthenticated, no GitHub remote, or the issue is closed → log it, give the `gh auth login` / remote hint, stop) — contract written
+2. deja-memory — error text or symptom from the issue → `deja fix` result in the run log — prior fix found, or "none"
+3. systematic-debugging — contract → root cause and a local repro command in the run log — repro fails locally on the base SHA (base SHA logged), or the reason it cannot run locally
+4. test-driven-development — root cause → failing test first (run, red, output pasted), then the minimal fix on a new branch `fix/<n>-<slug>` — the new test fails on the base SHA and passes after the fix; no unrelated edits
+5. verification-before-completion — repro command and the repo's test, lint and typecheck scripts that exist → fresh passing output pasted in the run log — output pasted, not claimed
+6. reviewer (agent) — `git diff <base>...HEAD`; the contract is the issue from step 1, never the run log and never the implementer's claim (input material only) → findings table in the run log — any open `blocking` finding sends the run back to step 4, at most 2 cycles, then stop and escalate
+7. git-pr-review — `git log <base>..HEAD` → PR body draft in the run log, ending in `Fixes #<n>` — draft only, nothing posted
+8. [GO] git push + gh pr create — `git push -u origin <branch>` then `gh pr create -R <owner/repo> --base <base> --head <branch> --title "<title>" --body-file <draft>` — the WAITING FOR GO line names branch, base, title and issue number. The run stops here until the human types GO. One GO covers the push and the PR creation, one time. (The hook guards the push only; `gh pr create` is not hook-guarded, so this GO is its only guard.)
+9. github — `gh pr view <branch> -R <owner/repo> --json url,closingIssuesReferences` → PR URL in the run log — `closingIssuesReferences` contains `<n>`
+
+Run log: `production_artifacts/pb-bug-fix-<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-clip-from-moodboard/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: pb-clip-from-moodboard
+description: >-
+  Turn a look brief and reference images into a finished social clip:
+  concept, TouchDesigner look and palette, ComfyUI stills, a recorded take,
+  a cut in DaVinci Resolve or Remotion, 9:16 and 16:9 exports, publish only
+  after GO. Use for "moodboard to clip", "make a social clip from these
+  references", "look brief to video".
+category: media-eventtech
+kind: playbook
+trigger: ["moodboard to clip", "social clip from references", "look brief to video"]
+inputs: [brief, reference_images, project, comfy_workflow, cut_tool, formats?]
+requires:
+  skills: [bdbmediastorm, bdb-touchdesigner-mcp, bdb-davinci-mcp, remotion, "ffprobe (external)"]
+  agents: []
+  mcps: [bdb_td_minddesigner, comfyui-mcp, bdb_davinci_mcp]
+  store: []
+go_points: [publish]
+outputs: ["renders/<project>/concept.md", "renders/<project>/look.tox", "renders/<project>/stills/", "renders/<project>/clip_9x16.mp4", "renders/<project>/clip_16x9.mp4", "production_artifacts/pb-clip-from-moodboard-<date>.md"]
+verify: "ffprobe shows 1080x1920 and 1920x1080 at the asked duration; comfyui get_history status success; get_td_node_errors empty"
+difficulty: advanced
+est_time: 1-3 h
+---
+
+# Moodboard to social clip
+What you get: a 9:16 and a 16:9 clip built from your look brief and references, checked with ffprobe, handed off for publishing after your GO.
+
+## Inputs
+- brief — the look brief, asked in step 2
+- reference_images — a folder of reference images, asked in step 2
+- project — a slug for `renders/<project>/`, asked in step 2
+- comfy_workflow — path to a ComfyUI API-format workflow JSON, required, never invented
+- cut_tool — `davinci` or `remotion` (remotion needs an existing Remotion project)
+- formats (optional) — default 9:16 and 16:9
+
+## Steps
+1. Preflight — ask cut_tool first; then one probe per server, before any file is written: `get_td_info` on `bdb_td_minddesigner`; `check_comfyui_health` on `comfyui-mcp`; `get_resolve_status` on `bdb_davinci_mcp` (only if cut_tool = davinci); `command -v ffprobe`. 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 the payload fails its pass condition (TD `get_td_info`: `connected: true`; ComfyUI `check_comfyui_health`: `status` is `"online"`; Resolve `get_resolve_status`: no `error` key) → stop with "Missing MCP: `<server>` (`<tool>` unavailable). Start <TouchDesigner|ComfyUI|DaVinci Resolve> and check `mcpServers.<server>` in your harness config." and write nothing except the run log; davinci missing while cut_tool = remotion → continue, logged — all probes answered
+2. Ask — brief, reference image folder, project slug, ComfyUI workflow JSON path, cut_tool, formats (default 9:16 and 16:9), length → run log and `renders/<project>/` — all answered, workflow path exists
+3. bdbmediastorm — brief → `renders/<project>/concept.md` (look, palette intent, shot list, length) — stops for approval
+4. bdb-touchdesigner-mcp — references → `moodboard_to_system` / `extract_palette` → network and palette; `get_td_node_errors` empty, `get_preview` shown (stops for approval), then `export_look_tox` → `renders/<project>/look.tox` — errors empty
+5. ComfyUI — the workflow file's text (palette and prompt filled in) as the JSON string for `queue_prompt` → `get_history <prompt_id>` status success → `get_output_media_info` paths copied to `renders/<project>/stills/` and loaded into the TD network (e.g. as a `moviefilein` TOP feeding the look) before step 6, then `get_td_node_errors` empty again — at least 1 still; `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
+6. Record — TD `record_movie` → `renders/<project>/raw.mov` — `ffprobe` duration > 0
+7. Cut — either way the output is the two clips, and `ffprobe` shows the asked width, height and duration per file:
+   - davinci: `create_project` → `import_media` → `create_timeline` → `append_to_timeline` → `set_render_settings` per format → `add_render_job` → `start_rendering` → `get_render_job_status` complete
+   - remotion: from the Remotion project dir, copy `raw.mov` into its `public/`, then `npx remotion render <Composition> <out>` per format (network/npm on first run needs approval; the skill's Stitch steps do not apply)
+   - `ffprobe` is the gate, since nothing proves `set_render_settings` sets 1080x1920: on a width/height mismatch stop with "export <format> has WxH, expected ...", log it, do not publish, invent no conversion command, and tell the human what to change in Resolve
+   - then the clips stop for approval (taste review)
+8. [GO] publish — the 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-clip-from-moodboard-<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-crew-call-sheet/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: pb-crew-call-sheet
+description: >-
+  Build a crew call sheet and a load-in / load-out plan for one show day from
+  your event tracker or brief and your crew list, and send it to the crew only
+  after your GO. Use for "call sheet", "crew call times", "load-in plan",
+  "load-out schedule".
+category: media-eventtech
+kind: playbook
+trigger: ["call sheet", "crew call times", "load-in plan"]
+inputs: [tracker_csv_or_event_brief, crew_list]
+requires:
+  skills: [bdb-eventagency-skill, pb-event-tracker]
+  agents: []
+  mcps: []
+  store: []
+go_points: [send to crew]
+outputs: ["call-sheet.md", "load-plan.md", "run-log.md"]
+verify: "every crew member has a call time; load-in ends before doors; load-out starts after show end"
+difficulty: beginner
+est_time: 10-20 min
+---
+
+# Crew call sheet
+What you get: a call sheet and a load-in / load-out plan for one show day.
+
+## Inputs
+- The `tracker.csv` from pb-event-tracker, or an event brief — a text or document file
+- A crew list — a file with name, role and contact for each person
+- A save folder — asked once; default `./pb-crew-call-sheet-<date>/`
+
+## Steps
+1. Ask once — save folder, tracker or brief, crew list → `run-log.md` — the files are readable; no tracker yet: run pb-event-tracker first or give the brief
+2. Read the tracker or brief and the crew list → show date, venue, doors time, show start and end, per crew member name, role, contact — missing times are `?`, never guessed
+3. bdb-eventagency-skill (section "5.1 Pre-production", run-of-show and day-minus milestones) — the read data → `call-sheet.md`, one row per crew member: who, role, call time, contact — every crew member has a call time
+4. bdb-eventagency-skill (section "5.1 Pre-production") — the read data → `load-plan.md` with load-in, line check, doors, show, load-out, each with a start and end time — load-in ends before doors; load-out starts after show end
+5. Show `call-sheet.md` and `load-plan.md` in full and apply your edits until you approve — approval logged
+6. [GO] Send the call sheet to the crew through a connector you name, or send it yourself — show every recipient (name + address, `?` blocks sending until you fill it) 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 `call-sheet.md`. 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-deploy-saas/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pb-deploy-saas
+description: >-
+  Deploy a SaaS app to the BDB fleet: preflight of the fleet skills, a guardrail plan, green CI, the deploy after GO (Incus via
+  Forgejo CI, or direct rsync), and a health URL check. Use for "deploy this to the
+  fleet", "deploy the SaaS app", "ship to the Incus instance".
+category: saas-ops
+kind: playbook
+trigger: ["deploy this to the fleet", "deploy the SaaS app", "deploy to the Incus instance"]
+inputs: [repo, target_instance, path, version_source?]
+requires:
+  skills: [bdb-deploy, pb-ci-fix, "bdbsaashost (external)", "deploy-incus (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [deploy]
+outputs: ["production_artifacts/pb-deploy-saas-<date>.md"]
+verify: "curl -sI <health_url> returns 200; the version marker read in step 5 equals the deployed commit SHA, or the run log says marker absent: unverified"
+difficulty: advanced
+est_time: 30-90 min
+---
+
+# Deploy a SaaS app to the fleet
+What you get: the app deployed to the chosen fleet instance after your GO, with a health check logged.
+
+## Inputs
+- repo — the current directory, or the one the user names
+- target_instance — the fleet instance to deploy to, asked if missing
+- path — `incus-ci` (push to Forgejo, the runner deploys to Incus) or `direct` (rsync over SSH), asked if missing
+- version_source (optional) — where the app exposes its commit SHA: a `/version`-style URL or a response header name of the health URL, taken from the deploy plan; none given means the app exposes none
+
+## Steps
+1. Preflight — `test -f ~/.claude/skills/bdbsaashost/SKILL.md`; `test -f ~/.claude/skills/deploy-incus/SKILL.md` (needed only for path = incus-ci) → run log header — a skill absent → stop with "Missing skill: <name> (installed locally only, not shipped by AOS). Install it under `~/.claude/skills/` or run this playbook on the machine that has it."; write nothing except the run log — all probes answered
+2. bdbsaashost (external) — repo, target_instance → deploy plan with target, guardrails and the health URL in the run log — stops for approval (the human confirms target, path and health URL)
+3. pb-ci-fix — only if `gh run list --commit <HEAD sha> --limit 1 --json conclusion` for the repo is not `success` (a repo with no GitHub CI is logged and skipped) → one pb-ci-fix run, with its own GO for the push — latest run is green, else stop
+4. [GO] deploy — path = incus-ci: deploy-incus pushes the repo to the Forgejo remote, the push command is hook-guarded; path = direct: bdb-deploy runs `rsync` over SSH to the target, which is not hook-guarded (the same goes for `incus` commands), so this GO is the only guard there — RemoteOS approval does not cover a Forgejo push or an rsync, only actions run through its own tools (for example container manage), which this step does not use. The WAITING FOR GO line names the path, target_instance, the exact command, and the commit SHA. The run stops here until the human types GO. One GO = one deploy.
+5. Health check — `curl -sI <health_url>` for the status line; then the marker from `version_source` (`curl -s <version_url>` for a URL, or the named header in the `curl -sI` output) → status line and marker in the run log — status 200 and the marker equals the SHA from the step 4 GO line; if `version_source` is empty or returns no marker, log "marker absent: unverified" and accept the 200 alone; a marker that differs from the SHA, or any other status, stops the run and reports, no automatic rollback
+
+Run log: `production_artifacts/pb-deploy-saas-<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-docs-site/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pb-docs-site
+description: >-
+  Publish a project's docs as a static HTML manual on GitHub Pages: check
+  that Pages is enabled, bring the wiki up to date, list the doc gaps, build
+  the site, preview it locally and push it after GO. Use for "publish the
+  docs", "docs site", "put the manual on GitHub Pages".
+category: design-ui-ux
+kind: playbook
+trigger: ["publish the docs", "docs site", "manual on GitHub Pages"]
+inputs: [repo, source]
+requires:
+  skills: [openwiki-skill, readme, documentation, bdbhtmlmanueldocs, github, "gh (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: ["git push"]
+outputs: ["docs/", "production_artifacts/pb-docs-site-<date>.md"]
+verify: "gh api repos/<owner>/<repo>/pages -q .status == built; curl -sI <pages_url> returns 200"
+difficulty: intermediate
+est_time: 30-90 min
+---
+
+# Publish a docs site
+What you get: the project's docs as a static HTML manual on GitHub Pages, pushed only after your GO.
+
+## Inputs
+- repo — the local checkout, default the current directory; `<owner/repo>` comes from `git -C <repo> remote get-url origin`
+- source — where the content lives: OpenWiki pages, the README, or `docs/`
+
+## Steps
+1. Preflight — `gh auth status`, then `gh api repos/<owner>/<repo>/pages` → run log header — gh missing, unauthenticated or no GitHub remote → log it, give the `gh auth login` / remote hint, stop; 404 → stop with "Pages not enabled: enable it in repo settings", this playbook does not enable Pages; a private repo whose Pages call is refused for plan reasons → stop with "Pages on a private repo needs a paid plan", and never change the repo's visibility. Then openwiki-skill — wiki refreshed or confirmed current → log line — Pages answered and the wiki is current
+2. readme and documentation — `source` against the code → list of doc gaps in the run log — stops for approval
+3. bdbhtmlmanueldocs — approved content → site files in `docs/` (or the Pages source path the step 1 response names) — files written, nothing committed; the skill's Pages build-type switch (`gh api -X PUT .../pages`) and its Pages deploy workflow are NOT run here, only the site files are written
+4. Preview — a local preview link or the path to the built `index.html` in the run log — link or path given
+5. [GO] git push — the site files committed to the branch and path the step 1 response names as the Pages source; the WAITING FOR GO line names the branch and the file list. The WAITING FOR GO line also says: a Pages site of a private repo is public. The run stops here until the human types GO. The hook guards `git push`; it does not guard `gh api` settings writes, so no Pages setting or workflow is changed in this playbook.
+6. github — `gh api repos/<owner>/<repo>/pages -q .status` equals `built` (poll, at most 5 minutes), then `curl -sI <pages_url>` → status line in the run log — returns 200
+
+Run log: `production_artifacts/pb-docs-site-<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-focus-chunks/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: pb-focus-chunks
+description: >-
+  Split one big task into chunks of at most 25 minutes, each with a
+  done-check, and place the demanding ones in your high-energy hours. Use for
+  "split this task", "break it into chunks", "I can't start this", "focus
+  plan". Nothing leaves your computer.
+category: bdb-core
+kind: playbook
+trigger: ["split this task", "break it into chunks", "focus plan"]
+inputs: [task, energy_pattern]
+requires:
+  skills: [concise-planning]
+  agents: []
+  mcps: []
+  store: []
+go_points: []
+outputs: ["chunks.md", "run-log.md"]
+verify: "every chunk is <= 25 min and has a done-check; sum of chunks equals the estimate"
+difficulty: beginner
+est_time: 5-10 min
+---
+
+# Focus chunks
+What you get: one big task split into 25-minute chunks, ordered by your energy level, each with a done-check.
+
+## Inputs
+- One task, in your own words, with your total time estimate
+- Your energy pattern — asked once, e.g. morning high / afternoon low
+- A save folder — asked once; default `./pb-focus-chunks-<date>/`
+
+## Steps
+1. Ask once — save folder, task, total estimate, energy pattern → `run-log.md` — all answered
+2. concise-planning — task and estimate → `chunks.md`: numbered chunks of at most 25 minutes, each with minutes, a done-check and an energy tag (high / low) — every chunk is <= 25 min and has a done-check; the minutes add up to your estimate
+3. Order `chunks.md` so high-energy chunks fall into your high-energy slots and low-energy chunks into the rest → slot named per chunk — no high-energy chunk sits in a low slot
+4. Show `chunks.md` in full and apply your edits until you approve — approval logged
+
+Nothing in this plan is sent anywhere, so there is no GO step. It only 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-handover/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: pb-handover
+description: >-
+  Write a handover note for a colleague from the state of a project folder:
+  what is done, what is open, what is risky, the next 3 steps and where
+  things live. Sent only after your GO. Use for "handover note", "hand this
+  project over", "I'm going on leave, brief my colleague".
+category: bdb-core
+kind: playbook
+trigger: ["handover note", "hand this project over", "brief my colleague"]
+inputs: [project_folder, colleague_name]
+requires:
+  skills: [quick-recap, memb-skill, github, "gh (external)"]
+  agents: []
+  mcps: []
+  store: []
+go_points: [send handover]
+outputs: ["handover.md", "run-log.md"]
+verify: "every open item cites a file, commit or PR"
+difficulty: beginner
+est_time: 10-20 min
+---
+
+# Handover note
+What you get: a handover note for a colleague from the state of a project folder.
+
+## Inputs
+- A project folder
+- The colleague's name
+- A save folder — asked once; default `./pb-handover-<date>/`
+
+## Steps
+1. Ask once — save folder, project folder, colleague name → `run-log.md` — the folder exists
+2. Read the folder and its git log (read-only); github — only if `gh (external)` is installed: your open pull requests for this repo → list of files, recent commits and open PRs in `run-log.md` — if gh is missing, skipped and logged
+3. quick-recap — folder state and recent commits → what is done, what is in progress — each point cites a file or commit
+4. memb-skill — search open commitments for this project → added tagged `[memB]` — skipped and logged if memB is not installed
+5. Write `handover.md`: done, open, risks, next 3 steps, where things live — every open item cites a file, commit or PR; nothing invented, unknown is `?`
+6. Show `handover.md` in full and apply your edits until you approve — approval logged
+7. [GO] Send the handover 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-harness-work/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: pb-harness-work
+description: >-
+  Change the agent harness itself (AOS, AO or CBS hooks, gates, memory,
+  permissions, delegation, plugins, bootstrap) the safe way: look up the
+  matching harness pattern, design against its gotchas, build with
+  /startcycle and a live trail, check every harness, open a PR after GO.
+  Use for "change a hook", "fix the go-gate", "harness work", "plugin change".
+category: bdb-core
+kind: playbook
+trigger: ["harness work", "change a hook", "fix the go-gate", "plugin change"]
+inputs: [goal, repo, area]
+requires:
+  skills: [agentic-harness-patterns, startcycle, agenttrail, verification-before-completion, git-pr-review, github, "gh (external)"]
+  agents: [architect, techlead, reviewer]
+  mcps: []
+  store: []
+go_points: [git push + gh pr create]
+outputs: ["production_artifacts/00_execution_plan.md", "production_artifacts/pb-harness-work-<date>.md"]
+verify: "npm test exit 0 on the pushed SHA; gh pr view <branch> --json state -q .state == OPEN"
+difficulty: advanced
+est_time: 1-3 h
+---
+
+# Change the harness safely
+What you get: a harness change that was designed against the known gotchas, built and reviewed, tested on every harness, and opened as a PR after your GO.
+
+## Inputs
+- goal — what should change, asked in step 1
+- repo — the local checkout, asked in step 1
+- area — memory, permissions, hooks, delegation, context, skills/plugins, tools or bootstrap, asked in step 1
+
+## Steps
+1. Ask + preflight (run everything from `<repo>`) — goal, repo, area → run log; default branch: `default=$(git -C <repo> symbolic-ref --short refs/remotes/origin/HEAD); default=${default#origin/}` (the command prints `origin/main`); if `git -C <repo> branch --show-current` equals it, `git -C <repo> switch -c feat/<slug>` — on a feature branch (gh missing or unauthenticated → log it, give the `gh auth login` hint, stop)
+2. agentic-harness-patterns — area → section and reference file, named in the run log; files live in `skills/global_config/agentic-harness-patterns/references/` (installed copy: the matching directory):
+   - memory → `memory-persistence-pattern.md`
+   - permissions → `permission-gate-pattern.md`
+   - hooks → `hook-lifecycle-pattern.md`
+   - delegation → `agent-orchestration-pattern.md` and `task-decomposition-pattern.md`
+   - context → `context-engineering-pattern.md`
+   - skills/plugins → `skill-runtime-pattern.md`
+   - tools → `tool-registry-pattern.md`
+   - bootstrap → `bootstrap-sequence-pattern.md`
+   - check: the gotcha titles that apply are listed as a checklist (titles only, no copied content)
+3. startcycle (Architect) — goal and gotcha checklist → `production_artifacts/00_execution_plan.md` with agenttrail components, each with a `files:` line — every listed gotcha is marked addressed or n/a with a reason; a component without `files:` → back to Architect
+4. agenttrail — `aos-trail . --plan production_artifacts/00_execution_plan.md --no-open` → URL in the run log, before the build nodes start — URL printed; a no-op if startcycle already started the trail (it is safe to run twice)
+5. startcycle (TechLead → build → Reviewer) — the dispatcher is the main session; the agents never call each other → code and review file — no open `blocking` finding
+6. Cross-harness check → table in the run log, one row per harness (affected yes/no, file, evidence):
+   - Claude: `.claude/hooks/*.mjs`, settings hooks
+   - agy: `hooks.json` via installer `mergeAntigravityHooks`
+   - OpenCode: `.opencode/plugins/bdb-aos.js`
+   - Codex: `.codex/agents/*.toml`, `~/.codex/hooks` and `[features] hooks` in `~/.codex/config.toml` (both written by `installer.js`)
+   - check: every "yes" row has a test in `npm test` or a named manual check
+7. verification-before-completion — `npm test` (and `node scripts/validate-skills.mjs` if skills changed) → fresh output pasted in the run log — exit 0
+8. git commit — compare `git -C <repo> status --porcelain` with the plan's `files:` lines; unlisted changes outside `production_artifacts/` → stop and ask; stage only the listed files (never the run log or `production_artifacts/`) → SHA in the run log — the commit hook passes
+9. git-pr-review — commits → PR body in `production_artifacts/pb-harness-work-<date>-pr.md` — body written, nothing posted
+10. [GO] github — `git -C <repo> push -u origin <branch>`, then `gh pr create -R <owner/repo> --base <default> --head <branch> --title "<title>" --body-file <body>` (`<owner/repo>` from `git -C <repo> remote get-url origin`) — the WAITING FOR GO line names branch, base and title. The run stops here until the human types GO. The hook guards the push only; the PR create is GO by contract.
+
+Run log: `production_artifacts/pb-harness-work-<date>.md` in the repo's 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-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.