belay-harness 0.1.0__tar.gz

belay_harness-0.1.0/.claude/skills/belay-begin/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: belay-begin
+description: Use when starting work on a Belay unit of work (a GitHub issue id or an inline brief) and you need stakeholder proposals (technical + non-technical PDFs with diagrams) before planning. Triggers on "belay-begin", "bb", "bb bug 12", "bb feat mcp-proxy-capture", "begin full".
+arguments: "type id"
+---
+
+# Belay Begin (Full Track)
+
+## Overview
+
+Same pipeline as `belay-begin-fast`, plus a **proposal phase**: after the PRD is approved, produce diagrams and two review PDFs (technical + non-technical) for stakeholders, get approval, then plan.
+
+**Invocation:** `bb <type> <id>` — e.g. `bb bug 12`, `bb feat mcp-proxy-capture`.
+Arguments and conventions (type set, `<type>/<id>/aliz` branch, descriptive slug, worktree from `master`, GitHub-issue-or-inline-brief source) are identical to `belay-begin-fast`.
+
+The two non-negotiables carry over from `belay-begin-fast`: **always work through the agents team** (every phase, including diagrams and the two proposals), and **implementation is test-first** via `superpowers:test-driven-development`, executed by the agents team.
+
+## Pipeline
+
+**REQUIRED SUB-SKILL:** Use `belay-begin-fast` for the base pipeline.
+
+Run its **Phase 0 → Phase 4 and the ⛔ PRD review gate exactly as written** (worktree → gather context → deep dig → `prd-interview` → `prd-generator` → stop for PRD approval).
+
+**Then, instead of going straight to tech-plan, insert Phase A below. Only after Phase A's approval gate do you run `belay-begin-fast`'s Phase 5 (tech-plan) and Phase 6 (implement — TDD via the agents team).**
+
+### Phase A — Proposals (diagrams → PDFs)
+
+Detailed steps, proposal structure, and `md-to-pdf` invocation: see `references/proposals.md`.
+
+1. **Diagram** — Use `excalidraw`. From the approved PRD, draw as many diagrams as the work needs (system/architecture, data flow, sequence, before/after, etc.). Save to `docs/planning/{slug}/diagrams/*.excalidraw`.
+2. **Export** — Use `excalidraw-to-svg` to render every diagram to `.svg` alongside the source.
+3. **Write two proposals** (markdown, in `docs/planning/{slug}/proposals/`), embedding the SVGs. Both filenames are prefixed with the type and id so stakeholders can identify the source at a glance:
+   - `<type>-<id>-technical-proposal.md` (e.g. `feat-mcp-proxy-capture-technical-proposal.md`) — for engineers: architecture, components, data flow, risks, effort.
+   - `<type>-<id>-non-technical-proposal.md` — for stakeholders: problem, value, what changes for users, timeline, plain language.
+   Generate the two in parallel (see Agents team).
+4. **PDF** — Use `md-to-pdf` to produce `<type>-<id>-technical-proposal.pdf` and `<type>-<id>-non-technical-proposal.pdf`.
+
+### ⛔ Approval gate — STOP
+
+Present both PDFs. **Wait for the user's explicit approval** of the proposals before planning. Do not auto-advance.
+
+### Final phases — Plan & implement
+
+Run `belay-begin-fast`'s **Phase 5 (tech-plan)** → `docs/planning/{slug}/{aspect}/plan_YYYYMMDD.md`, then its **Phase 6 (implement)** — strict TDD (`superpowers:test-driven-development`) executed through the agents team (`superpowers:subagent-driven-development`), one agent per plan task, branch kept green (`uv run pytest`, once the Python core exists).
+
+## Artifact layout (inside the worktree)
+
+```
+docs/planning/
+├── _card/issue.md                    ← gh dump or inline brief
+├── {slug}/prd.md                     ← PRD (approved at the first gate)
+├── {slug}/diagrams/*.excalidraw|.svg ← Phase A
+├── {slug}/proposals/<type>-<id>-technical-proposal.{md,pdf}
+├── {slug}/proposals/<type>-<id>-non-technical-proposal.{md,pdf}
+└── {slug}/{aspect}/plan_*.md         ← tech-plan
+```
+
+## Agents team (mandatory)
+
+Run **every** phase through the agents team — never serially in the main thread.
+
+**REQUIRED SUB-SKILL:** Use `superpowers:dispatching-parallel-agents`; use `superpowers:subagent-driven-development` for Phase 6.
+
+- Base pipeline: fan out context-gathering across related issues/PRs (as in `belay-begin-fast`).
+- Phase A: generate independent diagrams with parallel agents; write the technical and non-technical proposals concurrently (two agents, same PRD + SVGs).
+- Phase 6: one agent per independent plan task, each in strict TDD.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Writing proposals before the PRD is approved | Phase A starts only after the first ⛔ gate |
+| One proposal for both audiences | Always two: technical and non-technical |
+| Embedding `.excalidraw` instead of `.svg` | PDFs embed the exported SVGs |
+| Skipping the proposal approval gate | Proposals must be approved before tech-plan |
+| Diagrams/PDFs outside the worktree | Everything lives under the worktree's `docs/planning/{slug}/` |
+| Overstating what a verdict proves in a proposal | Say which axis (A1/A2/A3) checks it; `UNVERIFIED` is never drawn as `PASS` |
+| Implementing serially or test-after | Phase 6 is agents-team + strict TDD (RED before GREEN) |

belay_harness-0.1.0/.claude/skills/belay-begin/references/proposals.md

@@ -0,0 +1,96 @@
+# Phase A — Diagrams & proposal PDFs
+
+Runs after the PRD approval gate. Everything is written inside the worktree under
+`docs/planning/{slug}/`.
+
+## 1. Diagrams (`excalidraw`)
+
+Use the `excalidraw` skill. Decide how many diagrams the work actually needs —
+don't pad. Typical set for Belay:
+
+| Diagram | When to include |
+|---|---|
+| System / architecture | Almost always — where the change lives relative to the MCP tool-call proxy that sits between the agent and its MCP servers |
+| Data flow | Data moves across steps (agent → proxy → tool call → captured trace → replay → verdict) |
+| Sequence | A multi-turn interaction matters (capture, then re-execute the call in the sandbox and diff observed vs claimed state) |
+| Before / after | Behavior or structure changes visibly |
+| State machine | A run/turn lifecycle or a verdict transition changes |
+
+Save sources to `docs/planning/{slug}/diagrams/`, descriptive names
+(e.g. `architecture.excalidraw`, `replay-flow.excalidraw`).
+
+**Every text element must set `fontFamily: 2` (Helvetica)** — the excalidraw default is hand-drawn (Virgil/Excalifont) and unreadable in stakeholder PDFs. See the excalidraw skill's Rule 5.
+
+**Diagram the verdict honestly.** If a diagram shows verdicts, keep the four states distinct (`PASS` / `WARN` / `FAIL` / `UNVERIFIED`) and never collapse `UNVERIFIED` into `PASS` for visual tidiness. Where an axis is shown, label which one it is: **A1** invariant (deterministic, sandbox policy), **A2** replay (deterministic, result-equivalence + effect-conformance), **A3** claim re-derivation (LLM writes the check, execution decides; **never emits PASS**).
+
+## 2. Export to SVG (`excalidraw-to-svg`)
+
+Use the `excalidraw-to-svg` skill to render every `.excalidraw` to a sibling `.svg`.
+Batch-export the whole `diagrams/` directory. SVG (not PNG) keeps text crisp in the PDF.
+
+## 3. Write the two proposals
+
+Markdown, in `docs/planning/{slug}/proposals/`. Embed the SVGs with **relative** paths
+(`../diagrams/architecture.svg`) so `md-to-pdf` inlines them. Generate the two
+concurrently — same PRD + diagrams, different audience.
+
+### `<type>-<id>-technical-proposal.md` (engineers)
+
+Filename is prefixed with the type and id (e.g. `feat-mcp-proxy-capture-technical-proposal.md`) so stakeholders can identify which unit of work a proposal belongs to at a glance.
+
+- **Summary** — one paragraph: what we're building and why.
+- **Current state** — how it works today (link before/after diagram).
+- **Proposed design** — architecture + components (embed architecture/data-flow/sequence SVGs).
+- **Data & interface changes** — trace format, sandbox boundaries, tool-call/verdict contracts.
+- **Risks & trade-offs** — failure modes, replay-determinism impact, alternatives considered.
+- **Effort & sequencing** — rough phases, dependencies. Reference the capability (`C1`..`C9`) and phase it belongs to.
+- **Open questions** — carried from the PRD.
+
+### `<type>-<id>-non-technical-proposal.md` (stakeholders)
+
+Same naming convention (e.g. `feat-mcp-proxy-capture-non-technical-proposal.md`).
+
+- **The problem** — in plain language, no jargon.
+- **What we'll do** — the solution at a high level (embed a simplified diagram).
+- **Why it matters** — value to teams running agents unattended.
+- **What changes for users** — visible impact.
+- **Timeline** — rough, in weeks, not story points.
+- **Risks** — stated honestly, in plain terms.
+
+Keep the non-technical version free of stack names, code, and acronyms unless defined. Don't claim the harness proves more than it checks: if a step can only reach `UNVERIFIED`, say so in plain words rather than implying it passed.
+
+## 4. Convert to PDF (`md-to-pdf`)
+
+Use the `md-to-pdf` skill. On macOS, point Puppeteer at system Chrome. Output lands
+next to the input as `<name>.pdf`.
+
+⚠️ **The proposals embed `../diagrams/*.svg`, which sits ABOVE the `proposals/` folder.**
+md-to-pdf's file server is rooted at the markdown's own directory by default, so `../` paths
+**silently render as broken images**. You MUST pass `--basedir ..` (the `{slug}` dir, which
+contains both `proposals/` and `diagrams/`):
+
+```bash
+cd docs/planning/{slug}/proposals
+PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  md-to-pdf <type>-<id>-technical-proposal.md --basedir ..
+PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  md-to-pdf <type>-<id>-non-technical-proposal.md --basedir ..
+```
+
+Result: `<type>-<id>-technical-proposal.pdf` and `<type>-<id>-non-technical-proposal.pdf`.
+
+**Verify before the approval gate (do not skip):** a missing image does NOT fail the command,
+so you must *look* at the output. Render a page to an image and inspect it:
+
+```bash
+pdftoppm -png -r 70 -f 1 -l 1 <type>-<id>-technical-proposal.pdf /tmp/check   # then Read /tmp/check-1.png
+```
+
+Both PDFs must exist, be non-trivial in size, and show the diagrams (not broken-image icons).
+If an image is broken, the path escaped the basedir — fix `--basedir`/filenames (URL-encode
+spaces as `%20`) and re-run.
+
+## 5. Approval gate
+
+Present both PDFs to the user and **stop**. Only after explicit approval continue to the
+`tech-plan` phase.

belay_harness-0.1.0/.claude/skills/belay-begin-fast/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: belay-begin-fast
+description: Use when starting work on a Belay unit of work (a GitHub issue id or an inline brief) and you want the fast path straight to an implementation plan. Triggers on "belay-begin-fast", "bbf", "bbf bug 12", "bbf feat mcp-proxy-capture", "begin fast".
+arguments: "type id"
+---
+
+# Belay Begin (Fast Track)
+
+## Overview
+
+Turn a single unit of work into shipped, test-driven code. The fast track is: **isolate → gather → dig → PRD → plan → implement (TDD).** No proposal/diagram deliverables (use `belay-begin` / `bb` when you need those).
+
+**Two non-negotiables for this whole pipeline:**
+- **Always work through the agents team.** Every phase with independent units of work is dispatched to agents and synthesized — never done serially in the main thread. See *Agents team (mandatory)*.
+- **Implementation is always test-first**, via `superpowers:test-driven-development`, and is itself executed by the agents team. See Phase 6.
+
+**Invocation:** `bbf <type> <id>` — e.g. `bbf bug 12`, `bbf feat mcp-proxy-capture`, `bbf chore pin-uv-version`.
+
+- `type` ∈ `bug | feat | feature | task | chore` (normalize `feature` → `feat`).
+- `id` = a **GitHub issue number** when one exists, otherwise a short descriptive **slug** for the work.
+- Owner is `aliz`.
+
+## Task source: GitHub issue, tolerate absence
+
+Belay's tracker is GitHub Issues, but the repo/issues may not be reachable (`gh` unauthenticated, Issues disabled, or the work was never filed). The pipeline degrades gracefully:
+
+- If `id` is numeric and `gh issue view <id>` succeeds → use it as the source (Phase 1).
+- Otherwise → ask the user for a one-paragraph **inline brief** and treat that as the source. Skip the `gh` fetch; everything else is identical.
+
+## Pipeline
+
+Run phases in order. **Do not skip the review gate.** Every phase runs through the agents team, and Phase 6 is strict TDD — never do parallelizable work or implementation serially in the main thread.
+
+### Phase 0 — Isolate in a worktree
+
+**REQUIRED SUB-SKILL:** Use `belay-worktrees`.
+
+- Branch name: `<type>/<id>/aliz` (e.g. `bug/12/aliz`, `feat/mcp-proxy-capture/aliz`).
+- Worktree dir: `.claude/worktrees/<type>-<id>` (e.g. `.claude/worktrees/bug-12`).
+- Create from `origin/master` — Belay's base branch is **`master`**, never `main`. Belay has no `.worktreeinclude` files to copy today.
+- **Greenfield:** `origin/master` exists (planning docs are pushed), but there is still no `pyproject.toml`, so `uv sync` will fail. Run `uv sync` in the worktree only once the Python core is scaffolded — if your work *is* the scaffolding, the failing test comes first. See `belay-worktrees`.
+- All subsequent work (context dump, PRD, plan) happens **inside this worktree.**
+
+### Phase 1 — Gather context (`gh`, or inline brief)
+
+Pull what's available and save a raw dump to `docs/planning/_card/issue.md` in the worktree so later phases (and the PRD) have a single source. (Filename is id-free on purpose — the id lives in the branch/PR; the worktree is already dedicated to one unit of work.)
+
+Gather: the issue body, labels, linked/related issues and PRs, and **comments**. If there's no reachable issue, write the user's inline brief into the same file under a "Brief" heading.
+
+**Commands and parsing:** see `references/gather-context.md`.
+
+### Phase 2 — Deep dig
+
+Before any PRD work, understand the real problem and the code it touches.
+
+- Read the saved dump.
+- Map the relevant code paths. Belay is **greenfield** — today only `CLAUDE.md`, `VISION.md`, and `docs/` exist, so for most work the "code paths" are the design docs plus whatever has landed since. Read `docs/technical/CAPABILITY_ROADMAP.md` (the C1..C9 capabilities) and `docs/ROADMAP.md` (the phases) to place the work. Once the engine exists it will live under `src/belay/`; if a `graphify-out/` graph is ever added, query it first per `CLAUDE.md`, then read the files it points to.
+- Produce a short written "understanding" note: what the work is really asking, affected areas, ambiguities, and open questions.
+- Surface contradictions between the issue/brief and the code/docs — flag them, don't paper over them.
+- Honor the strategic constraints in `CLAUDE.md`. The moat is the **sandbox / replay / execution-grounded verification** engine plus the compounding failure corpus — **not** an agent framework, and **not** a bare LLM judge. If the work drifts into Belay authoring or orchestrating the agent, or into scoring by an LLM's opinion instead of by re-execution, flag it before planning.
+- Place the work on the verdict axes: **A1 invariant** (deterministic, sandbox policy), **A2 replay** (deterministic, result-equivalence + effect-conformance), **A3 claim re-derivation** (LLM writes the check, execution decides the verdict; **A3 can never emit PASS**). If the work touches verdicts, say which axis it changes.
+
+### Phase 3 — Requirements interview
+
+**REQUIRED SUB-SKILL:** Use `prd-interview`.
+
+- Feed it the Phase 1 dump + Phase 2 understanding as the product brief.
+- Answer from the gathered context where you can; ask the user only what the context can't resolve.
+- Confirm a **descriptive** feature slug (kebab-case, e.g. `mcp-proxy-capture`) for `docs/planning/{slug}/`. Do **not** name the slug `<type>-<id>` — the id lives in the branch and PR, not in committed doc paths.
+- Output: `docs/planning/{slug}/prd.md` (+ aspect `spec.md` files if decomposed).
+
+### Phase 4 — Generate & self-critique the PRD
+
+**REQUIRED SUB-SKILL:** Use `prd-generator`.
+
+- Refine `prd.md`, run its self-critique, and surface the 🔴/🟡 gaps.
+
+### ⛔ Review gate — STOP
+
+Present the PRD and its flagged gaps. **Wait for the user's explicit approval** before planning. Do not auto-advance to tech-plan.
+
+### Phase 5 — Implementation plan
+
+**REQUIRED SUB-SKILL:** Use `tech-plan`.
+
+- Plan one aspect at a time from `prd.md` (+ `spec.md`).
+- Output: `docs/planning/{slug}/{aspect}/plan_YYYYMMDD.md`.
+
+### Phase 6 — Implement (TDD, agents team)
+
+Start only after the plan is approved. Implementation is **always test-first** and **always run through the agents team** — never hand-written serially in the main thread.
+
+**REQUIRED SUB-SKILL:** Use `superpowers:test-driven-development` — strict RED → GREEN → REFACTOR; no production code before a failing test.
+**REQUIRED SUB-SKILL:** Use `superpowers:subagent-driven-development` to execute the plan — dispatch one agent per independent task from `plan_YYYYMMDD.md`; parallelize independent tasks with `superpowers:dispatching-parallel-agents`.
+
+- Each dispatched agent owns one task and follows the TDD cycle inside it: write the failing test, make it pass, refactor.
+- Run the suite after each task and keep the branch green: `uv run pytest` for the Python core; the dashboard's test/build commands for UI work once it exists. If the suite doesn't exist yet, the first task's failing test creates it.
+- Commit per task on the `<type>/<id>/aliz` branch (id lives in the commit/PR, never in code).
+- You stay the integrator: sequence dependent tasks, synthesize agent results, and surface blockers at each checkpoint.
+
+## Artifact layout (inside the worktree)
+
+```
+docs/planning/
+├── _card/issue.md                 ← gh dump or inline brief (Phase 1)
+├── {slug}/prd.md                  ← prd-interview / prd-generator
+└── {slug}/{aspect}/plan_*.md      ← tech-plan
+```
+
+Phase 6 produces **code commits** on the `<type>/<id>/aliz` branch — not documents.
+
+## Agents team (mandatory)
+
+This pipeline is **always** run through a team of agents, never serially in the main thread. For each phase, dispatch agents for the independent units of work and synthesize their results yourself.
+
+**REQUIRED SUB-SKILL:** Use `superpowers:dispatching-parallel-agents` for independent work, and `superpowers:subagent-driven-development` for executing plan tasks in Phase 6.
+
+- **Phase 1–2:** one agent per related issue/PR (5-line summary + relevance) + one agent to map the affected area (the roadmap docs today; `src/belay/` once it exists). Keep the `gh` calls themselves batched in a single message.
+- **Phase 6:** one agent per independent plan task; each agent works in strict TDD.
+
+Gates, user-facing summaries, and integration stay with you — the agents do the fan-out work.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Working in the primary checkout | Always create the Phase 0 worktree first |
+| Branching from `main` | Belay's base branch is `master`; `main` doesn't exist |
+| Slug = `bug-12` | Use a descriptive slug; the id stays in branch/PR |
+| Treating a `gh` failure as fatal | Fall back to an inline brief, keep going |
+| Treating a missing `pyproject.toml` / `origin/master` as fatal | Belay is greenfield — see `belay-worktrees` for both fallbacks |
+| Skipping the review gate | PRD must be approved before tech-plan |
+| Building an agent framework (Belay authoring/orchestrating the agent) | Stop and flag — that's the crowded layer we wrap, not the moat |
+| Verdicts from an LLM's opinion instead of re-execution | Stop and flag — verification is execution-grounded; A3 can never emit PASS |
+| Rendering `UNVERIFIED` as `PASS` | Never — the verdict contract is honest by design |
+| Inventing requirements the issue doesn't support | Flag as open question in the PRD instead |
+| Implementing serially in the main thread | Execute the plan through the agents team (subagent-driven-development) |
+| Writing code before a failing test | Implementation is strict TDD — RED before GREEN, always |

belay_harness-0.1.0/.claude/skills/belay-begin-fast/references/gather-context.md

@@ -0,0 +1,103 @@
+# Gathering context with `gh` (tolerate absence)
+
+Goal: dump the issue, its linked issues/PRs, and comments into
+`docs/planning/_card/issue.md` inside the worktree. If nothing is reachable,
+fall back to an inline brief from the user.
+
+## Prerequisites
+
+- GitHub CLI authenticated: `gh auth status`. If it errors, you're not logged in.
+- Repo: `haqaliz/belay`. The current checkout's `origin` is this repo, so `gh`
+  commands run from the worktree pick it up automatically.
+- **Greenfield note:** the repo has no pushed commits yet, so Issues may be empty
+  or disabled. A `FALLBACK` result below is the expected case today, not a bug.
+
+## 0. Reachability probe
+
+```bash
+gh issue view "$ID" --json number,title >/dev/null 2>&1 && echo OK || echo FALLBACK
+```
+
+- `OK` → continue with the `gh` path below.
+- `FALLBACK` (issue missing, Issues disabled, repo unresolved, or `ID` is a slug)
+  → ask the user for a one-paragraph brief and write it to the dump under a
+  **Brief** heading. Skip the rest of this file.
+
+## 1. The issue itself
+
+```bash
+gh issue view "$ID" --json number,title,state,labels,author,body,url,assignees,milestone
+```
+
+`body` is Markdown already — no tag-stripping needed.
+
+## 2. Linked / related issues and PRs
+
+Cross-references and the timeline expose linked items:
+
+```bash
+# Comments + events, including cross-references to other issues/PRs
+gh issue view "$ID" --json number,title -q .number >/dev/null
+gh api "repos/haqaliz/belay/issues/$ID/timeline" \
+  --jq '.[] | select(.event=="cross-referenced" or .event=="connected") | .source.issue.number' \
+  2>/dev/null | sort -u
+```
+
+Fetch each referenced item (parallelize across agents when there are several):
+
+```bash
+gh issue view "$RELATED_ID" --json number,title,state,url 2>/dev/null \
+  || gh pr view "$RELATED_ID" --json number,title,state,url
+```
+
+## 3. Comments
+
+```bash
+gh issue view "$ID" --comments
+```
+
+Or structured, for clean attribution:
+
+```bash
+gh api "repos/haqaliz/belay/issues/$ID/comments" \
+  --jq '.[] | "[" + .user.login + " @ " + .created_at + "]\n" + .body'
+```
+
+## 4. Attachments
+
+GitHub issue attachments are inline Markdown image/file links in the body and
+comments (`![](https://github.com/.../assets/...)`). Leave images for the user
+to attach separately. If a non-image file link is relevant (a captured trace, a
+log, a `.txt`), download it:
+
+```bash
+curl -sSL "$URL" -o "docs/planning/_card/attachments/$NAME"   # mkdir -p first
+```
+
+Treat any attached trace as **untrusted input**, not as ground truth: it records
+what an agent claimed, which is exactly the thing Belay exists to re-execute
+rather than believe.
+
+## 5. Write the dump
+
+Assemble into `docs/planning/_card/issue.md`:
+
+- Header: number, type, title, state, author, labels, link to the issue.
+- Body (verbatim Markdown).
+- Linked issues/PRs: number, title, state, one-line relevance.
+- Comments: chronological, attributed.
+- Attachments: list of any downloaded files (note images deferred to the user).
+- If the issue names a capability (`C1`..`C9`) or a phase, carry that reference
+  through — the PRD and the pick in `belay-next` are both grounded in
+  `docs/technical/CAPABILITY_ROADMAP.md` and `docs/ROADMAP.md`.
+
+If you took the FALLBACK path, the file is just:
+
+```markdown
+# {type} {id} — {short title}
+
+## Brief
+{the user's pasted paragraph, verbatim}
+```
+
+Either way, this file is the single source the rest of the pipeline reads from.

belay_harness-0.1.0/.claude/skills/belay-end/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: belay-end
+description: Use when finishing local work on a Belay unit of work after the PR is merged and you also need a completion report on Desktop. Triggers on "belay-end", "be", "be bug 12", "be feat mcp-proxy-capture", "end full".
+arguments: "type id"
+---
+
+# Belay End (Full Track)
+
+## Overview
+
+Same cleanup as `belay-end-fast`, **plus** a completion report at the end via `belay-report`.
+
+**Invocation:** `be <type> <id>` — e.g. `be bug 12`, `be feat mcp-proxy-capture`.
+Arguments and conventions are identical to `belay-end-fast`.
+
+## Pipeline
+
+**REQUIRED SUB-SKILL:** Use `belay-end-fast` for the cleanup and release pipeline.
+
+Run its **Phase 0 → Phase 3 exactly as written** (safety check → master + pull → remove worktree → delete branch, then the **optional** new-version release). Belay's base branch is **`master`**, never `main`. The release in its Phase 3 is a no-op today (Belay has no release machinery yet) and opt-in once it exists: ask, and default to skipping. Only proceed to the report once cleanup verification passes.
+
+### Phase 4 — Completion report
+
+**REQUIRED SUB-SKILL:** Use `belay-report` with the unit-of-work id and the corresponding type.
+
+The two skills use slightly different type vocabularies — map before invoking:
+
+| `be` arg | `belay-report` arg |
+|---|---|
+| `bug` | `bug` |
+| `task` | `task` |
+| `chore` | `task` |
+| `feat` | `feature` |
+| `feature` | `feature` |
+
+Example: `be bug 12` → invoke `belay-report` with `bug` + `12` → writes `/Users/aliz/Desktop/bug-12-completion.md`.
+
+`belay-report` fetches the issue via `gh` when reachable (otherwise works from the merged PR / what we just did) and produces the standard template. If it asks for a screenshot/video, provide one (or hand it to the user to attach), then confirm the file landed on Desktop.
+
+### Phase 5 — Comment on the issue (optional)
+
+Same approach as `belay-end-fast` Phase 4 — ask the user, draft (using the issue + the just-generated report as source material), confirm, then `gh issue comment <id>`. Skip if there's no reachable issue.
+
+The comment can mirror the report's plain-English summary in a sentence or two. Same tone rules: no em dashes, no jargon, no commit hashes. Skip entirely if the user declines.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Running the report before cleanup | Phases 0–2 first; the report is last |
+| Skipping the report on purpose | Use `belay-end-fast` / `bef` instead |
+| Passing the wrong type to `belay-report` | Apply the mapping table (`feat`/`feature` → `feature`, `chore` → `task`) |
+| Posting the issue comment before the report | The comment (Phase 5) comes after the report (Phase 4); the report's plain-English summary is good source material |
+| Cleaning up against `main` | Belay's base branch is `master` |
+| Auto-releasing during end | The release is `belay-end-fast` Phase 3: a no-op today, opt-in later, and it belongs to haqaliz not playdolphia |
+| Posting the comment without confirmation | Draft first, confirm with the user, then post |

belay_harness-0.1.0/.claude/skills/belay-end-fast/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: belay-end-fast
+description: Use when finishing local work on a Belay unit of work after the PR is merged and you want to clean up without generating a completion report. Triggers on "belay-end-fast", "bef", "bef bug 12", "bef feat mcp-proxy-capture", "end fast".
+arguments: "type id"
+---
+
+# Belay End (Fast Track)
+
+## Overview
+
+Closes out a unit of work's local state after the PR has merged: **master → pull → remove worktree → delete branch**, with an **optional new-version release**. No report (use `belay-end` / `be` for that).
+
+**Invocation:** `bef <type> <id>` — e.g. `bef bug 12`, `bef feat mcp-proxy-capture`.
+
+- `type` ∈ `bug | feat | feature | task | chore` (normalize `feature` → `feat`)
+- `id` = the GitHub issue number, or the slug used at begin time
+- Owner is `aliz`
+- Branch: `<type>/<id>/aliz`; worktree dir: `.claude/worktrees/<type>-<id>`
+
+Belay is a single repo, so this runs once. The base branch is **`master`**, never `main`.
+
+## Pipeline
+
+### Phase 0 — Safety check
+
+Before removing anything:
+
+- **Worktree clean?** `git -C <worktree> status --porcelain` must be empty. If not, stop — commit or stash first.
+- **Branch merged?** Confirm the PR is merged (`gh pr view <PR> --json state,mergedAt` if reachable). `git branch -d` will refuse an unmerged branch on purpose; do not bypass with `-D` without explicit user OK.
+- **You may be inside the worktree being removed.** Resolve the primary checkout first (Phase 1) and run all commands from there.
+
+### Phase 1 — Master, pulled
+
+Resolve the **primary** checkout (not the worktree). The first line of `git worktree list` is the primary:
+
+```bash
+PRIMARY=$(git worktree list | head -1 | awk '{print $1}')
+```
+
+Switch and pull, fast-forward only:
+
+```bash
+git -C "$PRIMARY" checkout master
+git -C "$PRIMARY" pull --ff-only origin master
+```
+
+### Phase 2 — Remove worktree, delete branch
+
+```bash
+WORKTREE_NAME="<type>-<id>"   # e.g. bug-12, feat-mcp-proxy-capture
+BRANCH="<type>/<id>/aliz"     # e.g. bug/12/aliz, feat/mcp-proxy-capture/aliz
+
+git -C "$PRIMARY" worktree remove ".claude/worktrees/$WORKTREE_NAME"
+git -C "$PRIMARY" branch -d "$BRANCH"
+```
+
+If `worktree remove` refuses due to uncommitted/untracked files, go back to Phase 0 — don't pass `--force` silently.
+
+If `branch -d` refuses because the branch isn't merged into master, surface the message — the PR may not be merged, or there are unpushed commits. Don't use `-D` silently.
+
+After both succeed, verify:
+
+```bash
+git -C "$PRIMARY" worktree list           # the worktree should be gone
+git -C "$PRIMARY" branch --list "$BRANCH" # should print nothing
+```
+
+### Phase 3 — Release a new version (optional)
+
+⚠️ **Belay has no release machinery today.** There is no `pyproject.toml`, no `CHANGELOG.md`, no `RELEASING.md`, no release workflow, and no publish channel (no PyPI package, no container image, no tap). **Until those exist, this phase is a no-op: say so and go to Phase 4.** Do not invent a release process, do not hand-craft a tag as a substitute, and do not `gh release create` by hand.
+
+Once release machinery lands, `RELEASING.md` becomes the source of truth and this phase follows it from the **primary** checkout on `master` (the merged work is already there after Phase 1). The rules that will apply then, stated now so they aren't lost:
+
+- **Opt-in, default to skipping.** Most units of work do not release on their own (fixes batch into a later version). Ask: *"Cut and publish a new version for this, or batch it for later?"* Default to **skipping**.
+- **Release identity, do not get this wrong:** the release belongs to the **haqaliz** account (`git@github.com:haqaliz/belay.git`), never `playdolphia`. Any manual asset upload must run with `gh` active as haqaliz (`gh auth switch --user haqaliz`).
+- **Version from the work type:** `feat` → minor, `bug`/`chore`/`task` → patch. Confirm the exact `vX.Y.Z` with the user.
+- **Verify each channel is live before calling it done.** Report which channels published and surface any job that failed; never claim a channel shipped without checking it. This is the same honesty rule the product enforces — an unchecked channel is `UNVERIFIED`, not `PASS`.
+
+### Phase 4 — Comment on the issue (optional)
+
+Optional, and only if there's a reachable GitHub issue. Ask first: *"Want me to post a short comment on the issue explaining what we did?"* If the user declines, there's nothing meaningful to say, or there's no issue (the work came from an inline brief), skip.
+
+Otherwise:
+
+1. **Draft a short note** (2–4 sentences). Sources, in order of preference:
+   - What the user tells you to say.
+   - The merged PR's title + description (`gh pr view <PR>`), if accessible.
+   - A best-effort summary from the issue title and the change verb.
+
+   Keep it friendly, light on jargon, no em dashes, no commit hashes, no file paths. The change verb matches the type: `bug → fixed`, `task → done`, `feat`/`feature → shipped`, `chore → done`. Example: *"Shipped the tool call recorder. Every call an agent makes through the proxy is now captured exactly, so a run can be replayed later instead of taken on trust. Let me know if anything looks off."*
+
+2. **Confirm the draft** with the user before posting.
+
+3. **Post it** via `gh`:
+
+   ```bash
+   gh issue comment "$ID" --body "<confirmed comment text>"
+   ```
+
+   On success `gh` prints the comment URL. Tell the user it landed. If `gh` errors (not authenticated, Issues disabled), surface it and stop — don't retry blindly.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Running from inside the worktree being removed | Resolve `PRIMARY` first, run commands from there |
+| Checking out / pulling `main` | Belay's base branch is `master`; `main` doesn't exist |
+| Using `git pull` (allowing merge) | Use `--ff-only` |
+| Forcing branch delete with `-D` | Only after explicit user OK — `-d` refuses unmerged for a reason |
+| Forcing worktree remove with `--force` | Same — never silently discard uncommitted work |
+| Worktree dir vs branch confusion | Worktree dir is `<type>-<id>` (e.g. `bug-12`); branch is `<type>/<id>/aliz` |
+| Posting the issue comment without confirmation | Draft first, show the user, only post after explicit OK |
+| Trying to comment when the work has no issue | Skip Phase 4 — it came from an inline brief |
+| Inventing a release process because Phase 3 exists | Belay has no release machinery yet; the phase is a no-op until `RELEASING.md` does |
+| Cutting a future release as `playdolphia` | The release is haqaliz's; switch with `gh auth switch --user haqaliz` |