pb-harness-work

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

SKILL.md

GitHub

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); go-gate firing unverified
    • OpenCode plugin .opencode/plugins/bdb-aos.js loads the go-gate
    • Cursor, Kimi: rules text only, no hook
    • 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 — commit succeeds (any hook failure is reported, never bypassed with --no-verify)
  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. Where the hook runs, it covers the push only; the PR create is not hooked, so this GO is its only guard.

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.
  • GO is by contract in every harness. The go-gate hook is only a backstop on Claude Code, OpenCode and agy (Codex: unverified; Cursor, Kimi: none). A missing hook is never permission to proceed.
  • 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.