contig 0.1.0__tar.gz

contig-0.1.0/.claude/skills/contig-begin/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: contig-begin
+description: Use when starting work on a Contig 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 "contig-begin", "cb", "cb bug 12", "cb feat verify-layer", "begin full".
+arguments: "type id"
+---
+
+# Contig Begin (Full Track)
+
+## Overview
+
+Same pipeline as `contig-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:** `cb <type> <id>` — e.g. `cb bug 12`, `cb feat verify-layer`.
+Arguments and conventions (type set, `<type>/<id>/aliz` branch, descriptive slug, worktree, GitHub-issue-or-inline-brief source) are identical to `contig-begin-fast`.
+
+The two non-negotiables carry over from `contig-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 `contig-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 `contig-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-verify-layer-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 `contig-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`).
+
+## 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 `contig-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}/` |
+| Implementing serially or test-after | Phase 6 is agents-team + strict TDD (RED before GREEN) |

contig-0.1.0/.claude/skills/contig-begin/references/proposals.md

@@ -0,0 +1,94 @@
+# 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 Contig:
+
+| Diagram | When to include |
+|---|---|
+| System / architecture | Almost always — where the change lives in the orchestrate→run→verify stack |
+| Data flow | Data moves across steps (ingest → pipeline → artifacts → verification) |
+| Sequence | A multi-step run/self-heal/verify interaction matters |
+| Before / after | Behavior or structure changes visibly |
+| State machine | A run/step lifecycle or failure-recovery flow changes |
+
+Save sources to `docs/planning/{slug}/diagrams/`, descriptive names
+(e.g. `architecture.excalidraw`, `verify-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.
+
+## 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-verify-layer-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** — artifacts, CLI surface, run/verification contracts.
+- **Risks & trade-offs** — failure modes, reproducibility impact, alternatives considered.
+- **Effort & sequencing** — rough phases, dependencies.
+- **Open questions** — carried from the PRD.
+
+### `<type>-<id>-non-technical-proposal.md` (stakeholders)
+
+Same naming convention (e.g. `feat-verify-layer-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 researchers / the business.
+- **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.
+
+## 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.

contig-0.1.0/.claude/skills/contig-begin-fast/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: contig-begin-fast
+description: Use when starting work on a Contig unit of work (a GitHub issue id or an inline brief) and you want the fast path straight to an implementation plan. Triggers on "contig-begin-fast", "cbf", "cbf bug 12", "cbf feat verify-layer", "begin fast".
+arguments: "type id"
+---
+
+# Contig 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 `contig-begin` / `cb` 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:** `cbf <type> <id>` — e.g. `cbf bug 12`, `cbf feat verify-layer`, `cbf chore pin-nextflow`.
+
+- `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
+
+Contig'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 `contig-worktrees`.
+
+- Branch name: `<type>/<id>/aliz` (e.g. `bug/12/aliz`, `feat/verify-layer/aliz`).
+- Worktree dir: `.claude/worktrees/<type>-<id>` (e.g. `.claude/worktrees/bug-12`).
+- Create from `origin/master`. Contig has no `.worktreeinclude` files to copy today; run `uv sync` in the worktree before working.
+- 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. **Contig has a `graphify-out/` graph — query it first** (`graphify query "..."`, `graphify explain "X"`) per CLAUDE.md, then read the files it points to. Relevant areas usually live under `src/contig/` (CLI in `contig.cli`, the orchestrator/agent layer, detector, verification) and `dashboard/` for UI work.
+- 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 — flag them, don't paper over them.
+- Honor the strategic constraints in `CLAUDE.md` (the moat is the run/verify/reproduce layer, **not** Layer 1 workflow generation). If the work drifts into building Layer 1 as the product, flag it before planning.
+
+### 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. `verify-layer`) 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; `npm test` / `npm run build` in `dashboard/` for UI work.
+- 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 code area (graphify-first). 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 |
+| 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 |
+| Skipping the review gate | PRD must be approved before tech-plan |
+| Building Layer 1 (NL → workflow) as the product | Stop and flag — that's a dependency we consume, not the moat |
+| 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 |

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

@@ -0,0 +1,94 @@
+# 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/contig`. The current checkout's `origin` is this repo, so `gh`
+  commands run from the worktree pick it up automatically.
+
+## 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 (unlike the old Azure HTML).
+
+## 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/contig/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/contig/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 (same convention as before). If a non-image file link is
+relevant (a log, a `.txt`), download it:
+
+```bash
+curl -sSL "$URL" -o "docs/planning/_card/attachments/$NAME"   # mkdir -p first
+```
+
+## 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 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.

contig-0.1.0/.claude/skills/contig-end/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: contig-end
+description: Use when finishing local work on a Contig unit of work after the PR is merged and you also need a completion report on Desktop. Triggers on "contig-end", "ce", "ce bug 12", "ce feat verify-layer", "end full".
+arguments: "type id"
+---
+
+# Contig End (Full Track)
+
+## Overview
+
+Same cleanup as `contig-end-fast`, **plus** a completion report at the end via `contig-report`.
+
+**Invocation:** `ce <type> <id>` — e.g. `ce bug 12`, `ce feat verify-layer`.
+Arguments and conventions are identical to `contig-end-fast`.
+
+## Pipeline
+
+**REQUIRED SUB-SKILL:** Use `contig-end-fast` for the cleanup pipeline.
+
+Run its **Phase 0 → Phase 2 exactly as written** (safety check → master + pull → remove worktree → delete branch). Only proceed to Phase 3 once cleanup verification passes.
+
+### Phase 3 — Completion report
+
+**REQUIRED SUB-SKILL:** Use `contig-report` with the unit-of-work id and the corresponding type.
+
+The two skills use slightly different type vocabularies — map before invoking:
+
+| `ce` arg | `contig-report` arg |
+|---|---|
+| `bug` | `bug` |
+| `task` | `task` |
+| `chore` | `task` |
+| `feat` | `feature` |
+| `feature` | `feature` |
+
+Example: `ce bug 12` → invoke `contig-report` with `bug` + `12` → writes `/Users/aliz/Desktop/bug-12-completion.md`.
+
+`contig-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 4 — Comment on the issue (optional)
+
+Same approach as `contig-end-fast` Phase 3 — 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 `contig-end-fast` / `cef` instead |
+| Passing the wrong type to `contig-report` | Apply the mapping table (`feat`/`feature` → `feature`, `chore` → `task`) |
+| Posting the issue comment before the report | Phase 4 comes after Phase 3; the report's plain-English summary is good source material |
+| Posting the comment without confirmation | Draft first, confirm with the user, then post |

contig-0.1.0/.claude/skills/contig-end-fast/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: contig-end-fast
+description: Use when finishing local work on a Contig unit of work after the PR is merged and you want to clean up without generating a completion report. Triggers on "contig-end-fast", "cef", "cef bug 12", "cef feat verify-layer", "end fast".
+arguments: "type id"
+---
+
+# Contig End (Fast Track)
+
+## Overview
+
+Closes out a unit of work's local state after the PR has merged: **master → pull → remove worktree → delete branch.** No report (use `contig-end` / `ce` for that).
+
+**Invocation:** `cef <type> <id>` — e.g. `cef bug 12`, `cef feat verify-layer`.
+
+- `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>`
+
+Contig is a single repo, so this runs once.
+
+## 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-verify-layer
+BRANCH="<type>/<id>/aliz"     # e.g. bug/12/aliz, feat/verify-layer/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 — 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 verification layer. Runs now self-check their outputs and flag mismatches before returning a result. 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 |
+| 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 3 — it came from an inline brief |

contig-0.1.0/.claude/skills/contig-report/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: contig-report
+description: Use when a Contig unit of work (bug, task, feature) is done and you want a brief, friendly, non-technical completion note saved on Desktop to share with the team.
+allowed-tools: Read, Grep, Glob, Bash, Write
+arguments: "type id"
+---
+
+# Contig Completion Note
+
+A short, friendly, non-technical heads-up that a unit of work is done. Written like a teammate would write it — no jargon, no commit hashes, no checklists. Just one plain-English sentence about what changed, plus a link and a screenshot.
+
+## Arguments
+
+- `type` ∈ `bug | task | feature`
+- `id` = the GitHub issue number, or the slug used at begin time
+
+Usage: `/contig-report bug 12` or `/contig-report feature verify-layer`.
+
+## When to use
+
+- A unit of work is finished and you want to let the team know in a human way.
+- You've closed (or are about to close) a GitHub issue, or merged its PR.
+
+## Output
+
+Markdown file saved to `/Users/aliz/Desktop/{type}-{id}-completion.md`.
+
+Examples:
+- `/Users/aliz/Desktop/bug-12-completion.md`
+- `/Users/aliz/Desktop/task-pin-nextflow-completion.md`
+- `/Users/aliz/Desktop/feature-verify-layer-completion.md`
+
+## The template
+
+One template, three small verb tweaks. Keep it warm, short, and free of technical detail.
+
+```markdown
+## #{id} - {Feature or area} - {Short Title}
+
+Hey! Quick note that this one's {verb}.
+
+**What changed (in plain words):**
+{One or two friendly sentences. What's different for the user now. No jargon. No em dashes.}
+
+**See it live:** {link to the PR, the dashboard area, or the CLI command}
+**Screenshot/video:** {attached, or link}
+
+If anything looks off or you'd like a tweak, just say the word.
+```
+
+Verb per type:
+
+| Type | Verb |
+|---|---|
+| `bug` | fixed |
+| `task` | done |
+| `feature` | shipped |
+
+## Tone rules
+
+- Write like you're messaging a teammate, not filing a ticket.
+- Plain English only. Swap out words like *deduplicated, refactored, idempotent, artifact, schema, pipeline DAG, contig, orchestrator* for everyday phrasing.
+- No checklists, no testing matrices, no commit hashes, no branch names, no file paths — those live in the PR, not in this note.
+- Two or three short paragraphs max. If it reads like docs, trim again.
+- **Never use the em dash character `—` in the note.** It's a tell that an AI wrote it. Use a comma, a period, or a regular hyphen with spaces (`-`) instead.
+- A friendly closer is welcome ("Let me know what you think.", "Happy to revisit if needed.").
+
+## Workflow
+
+1. **Get the context.** Prefer the GitHub issue if reachable; otherwise use the merged PR or what we just did:
+   ```bash
+   gh issue view "$ID" 2>/dev/null || gh pr view "$PR" 2>/dev/null
+   ```
+   If neither resolves, write the note from the work you just completed in this session.
+2. **Distill** the change into one or two plain sentences. Resist the urge to add detail.
+3. **Pick the "See it live" target** that fits the work: the merged PR link, the dashboard page (e.g. `http://localhost:3000/...` or the deployed URL), or the exact CLI command a teammate would run (`uv run contig ...`).
+4. **Ask the user for a screenshot or short video** if one isn't already on hand.
+5. **Write** the note to `/Users/aliz/Desktop/{type}-{id}-completion.md` and tell the user it's ready.
+
+## Optional: cross-check
+
+Only include if the user explicitly asks for it. Append one short, friendly line:
+
+```markdown
+**Also checked:** {a couple of related areas you peeked at, in plain words}
+```
+
+Don't add this by default — it makes the note look like an audit.
+
+## Example (feature)
+
+```markdown
+## #34 - Verification - Output self-check
+
+Hey! Quick note that this one's shipped.
+
+**What changed (in plain words):**
+Runs now double-check their own results before handing them back, so if something looks off it gets flagged instead of slipping through.
+
+**See it live:** run `uv run contig run sample.fastq` and watch the verify step at the end
+**Screenshot/video:** attached
+
+If anything looks off or you'd like a tweak, just say the word.
+```