cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/mattpocock/skills/in-progress/README.md

@@ -0,0 +1,17 @@
+# In Progress
+
+Beta. These skills are public on purpose: try them and tell me what breaks. They're excluded from the plugin and the top-level README until they graduate to a stable bucket, they get no docs pages, and they can change or disappear without warning.
+
+The plugin won't give you these. Install one directly:
+
+```bash
+npx skills@latest add mattpocock/skills --skill=<name>
+```
+
+- **[loop-me](./loop-me/SKILL.md)**: Grill yourself into implementable workflow specs over multiple sessions, using the current directory as a stateful workspace. User-invoked.
+- **[writing-beats](./writing-beats/SKILL.md)**: Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end.
+- **[writing-fragments](./writing-fragments/SKILL.md)**: Grilling session that mines you for fragments (heterogeneous nuggets of writing) and appends them to a single document as raw material for a future article.
+- **[writing-shape](./writing-shape/SKILL.md)**: Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step.
+- **[claude-handoff](./claude-handoff/SKILL.md)**: Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked.
+- **[setup-ts-deep-modules](./setup-ts-deep-modules/SKILL.md)**: Wire dependency-cruiser into a TypeScript repo so each package is a deep module: implementation hidden in subfolders, reachable only through its entry-point files, tests exercising it through those. User-invoked.
+- **[software-factory](./software-factory/SKILL.md)**: Shared language for designing a software factory: the tasks it runs and the services it plugs into. Call it alongside a grilling session. User-invoked.

package/skills/mattpocock/skills/in-progress/chief-of-staff/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: chief-of-staff
+description: Pursue a long-running goal in a single session by co-ordinating subagents.
+disable-model-invocation: true
+---
+
+You are a chief of staff, co-ordinating subagents and schedules to pursue a long-running goal. This session will run for a long time, accruing tribal knowledge and helping you make long-term strategic decisions.
+
+You are the Directly Responsible Individual for this goal. You are empowered to think much longer-term than you're used to. You must think on two tracks simultaneously:
+
+- Tactical: how do I complete the immediate task?
+- Strategic: how do I modify the environment to improve the outcomes of the _next_ task?
+
+## Schedules
+
+Harness-permitting, you will suggest recurring schedules which can help in achieving the goal.
+
+## Subagents
+
+All work should be done in subagents. Protect your context window.
+
+Use background agents so you can stay in active dialogue with the user. Start every subagent with a fresh context window.
+
+Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: research notes, previous commits, wiki pages, and others. Don't duplicate information already available via pointers.
+
+## Wiki
+
+Keep your memory in a **wiki**: a folder of interlinked markdown pages that outlives this session. Tribal knowledge that lives only in your context is lost at compaction; the wiki is how it reaches the next session. Look for a shared wiki first, one the user or other agents already keep, and write your pages into it, following its conventions where they differ from the ones below. Only if there is none, agree a location with the user before the first write.
+
+- `index.md` lists every page with a link and a one-line summary, grouped by category.
+- Each other page covers one thing: a decision, a recurring problem, a subsystem, a user preference. Link related pages to each other.
+- Sources (issues, PRs, transcripts, subagent reports) are never copied in or edited. Pages cite them.
+
+Three operations keep it alive:
+
+- **Ingest.** When you learn something durable (a decision, a user correction, a subagent's finding), update every page it touches and the index, not only a new page.
+- **Query.** Before a decision, read `index.md` and the pages it points to. If the answer you build is worth keeping, file it as a page.
+- **Lint.** Periodically look for contradictions, orphan pages, missing links and claims newer sources have overtaken. Suggest this as a schedule.
+
+### Write history, not the present
+
+The wiki is a historical record. It never claims to describe how things are now, because it cannot keep up with the code.
+
+- Date every claim: "On 2026-10-13, Matt decided..."
+- When a claim concerns code, cite the commit it was true at, with its repo: "As of `mattpocock/skills@abc1234`, `retro` loads `writing-for-agents` in step 1."
+- Never write "currently", "now" or "is" about code without a date or commit beside it.
+- When something changes, add a new dated claim and mark the old one superseded. Don't rewrite the old one.
+
+## Procedures
+
+Some procedures you run live in other skills, installed beside this one. To run one, read its `SKILL.md` at the path below, relative to this skill's directory, and follow it.
+
+- **Retro** (`../retro/SKILL.md`): run a retro on about one in five of your subagents' sessions, including those an `implement-spec` run dispatches. Pick first the ones where something went wrong. In place of retro's last step, decide yourself which candidates are worth pursuing, then pursue them.
+- **Large chunks of work**: write a spec with `../to-spec/SKILL.md`, break it into tickets with `../to-tickets/SKILL.md`, publish both to the issue tracker, then implement them with `../implement-spec/SKILL.md`.
+
+## Strategic View
+
+As part of any and all work, FIRST consider how the environment the agents operate in might be improved. Agents thrive in the **pit of success**:
+
+- API's and functions which are extremely constrained and limited
+- Lint rules which force correctness
+- CODING_STANDARDS.md files which let code reviewers enforce best practices
+
+They also need relevant **data sources** to succeed:
+
+- Logs from critical running processes, like dev servers (or production logs)
+- Access to test environment databases
+- Access to the browser (when necessary) for clicking around and taking screenshots
+
+Finally, create environments (and codebases) that obey the **"no workarounds"** rule:
+
+- No one-off workarounds, or hacks that bypass established processes
+- Any deviations from conventions must be fixed proactively, before feature work is done
+
+Be relentless in improving the environment. Use every user message as an excuse to search for these improvements.

package/skills/mattpocock/skills/in-progress/chief-of-staff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Chief Of Staff"
+  short_description: "Pursue a long-running goal in a single session by co-ordinating subagents"
+policy:
+  allow_implicit_invocation: false

package/skills/mattpocock/skills/in-progress/claude-handoff/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: claude-handoff
+description: Hand the current conversation off to a fresh background agent that picks up the work immediately.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff summary of the current conversation so a fresh agent can continue the work. Save it to the temporary directory of the user's OS, then launch a background agent seeded with it as its prompt: `claude --bg --name "<descriptive name>" -- "$(cat <summary file>)"`. Passing the file keeps the shell from running backticks or expanding `$` in the summary. It starts in the current working directory and returns immediately; the user manages it with `claude agents`.
+
+Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"`); it sets the display name shown in the job list, session picker, and terminal title.
+
+Include a "suggested skills" section in the summary, naming which skills the next agent should call the Skill tool for.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information, since the summary becomes the agent's prompt.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the summary accordingly.

package/skills/mattpocock/skills/in-progress/claude-handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Claude Handoff"
+  short_description: "Hand off to a background agent"
+policy:
+  allow_implicit_invocation: false

package/skills/mattpocock/skills/in-progress/loop-me/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: loop-me
+description: Grill me about specs for the workflows I want to build, within this workspace.
+disable-model-invocation: true
+argument-hint: "A workflow to design, or nothing to go find one"
+---
+
+Run a stateful `/grilling` session whose only output is **workflow** specs. Use the grilling discipline (relentless, a round of questions at a time, a recommended answer attached to each) aimed at the vocabulary and goal below. Create, edit, and delete specs as the grilling resolves things.
+
+## The loop lens
+
+A **loop** is a recurring pattern in the user's life: their career, their week, their morning, a single repeated activity. Picturing a life as loops within loops reveals how predictable its activities really are, which is what makes them worth **delegating**. Use the lens to find loops worth specifying, and propose ones the user hasn't noticed.
+
+A **workflow** is the spec of one loop, made real. You run a workflow on a loop: the loop is its running instantiation. Workflows live in `workflows/*.md` and are the source of truth.
+
+## Vocabulary
+
+A shared language, reached for only when a workflow calls for it: never a checklist. **Mandate nothing structural**: a workflow needs no AI, no checkpoint, and no schedule unless the grilling shows it does.
+
+- **Trigger**: what fires each run, an **event** (a new email, a new issue) or a **schedule** (every morning). Event-triggering is usually the more efficient.
+- **Checkpoint**: a human-in-the-loop point where the user is asked to verify or decide. Some workflows have none and run autonomously; some use no AI at all.
+- **Push right**: defer the checkpoint as far as it will go. Do maximal work before involving the human, so they are asked once, late, with everything prepared.
+- **Brief**: what a checkpoint presents, a tight, decision-ready summary (what was produced, why, and a link down to the asset itself), never the raw output. The user reads a brief, not a draft. Speed of review is imperative.
+
+## Definition of done
+
+A workflow spec is done when an implementer agent could build it without asking a single question. Grill until then; nothing is done while a question remains.
+
+## The workspace
+
+- `workflows/*.md`: one spec per workflow.
+- `NOTES.md`: raw notes on the user's world, the tools they use, the channels they process, and their own terminology for both. When it is empty or thin, interview them about their world before specifying anything. Sharpen fuzzy terms into canonical ones as they surface, and record them here.

package/skills/mattpocock/skills/in-progress/loop-me/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Loop Me"
+  short_description: "Spec the workflows you want to build"
+policy:
+  allow_implicit_invocation: false

package/skills/mattpocock/skills/in-progress/setup-ts-deep-modules/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: setup-ts-deep-modules
+description: Wire dependency-cruiser into a TypeScript repo so each package is a deep module, with implementation hidden in subfolders and reachable only through its entry-point files. User-invoked.
+disable-model-invocation: true
+---
+
+# Setup TS Deep Modules
+
+Make every package in this repo a **deep module**: a lot of behaviour behind a small interface. A package's public surface is its **entry points** (the files at the package root), and everything in its subfolders is hidden. This skill installs [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) and the rules that make the entry points the only way in, then proves the rules bite.
+
+For the vocabulary (deep module, interface, seam, depth), call the Skill tool with "codebase-design" and use its language throughout.
+
+## The shape this enforces
+
+```
+src/packages/
+  <name>/
+    index.ts        ← an entry point (public). Import this from outside.
+    client.ts       ← another entry point. Packages may expose SEVERAL.
+    lib/            ← implementation: hidden from outside, free to import each other.
+    tests/          ← co-located tests + fixtures (a subfolder, so private).
+```
+
+The public surface is the package's **root files**, not one designated `index.ts`. By convention implementation lives in `lib/` and tests in `tests/`, giving every package the same two-folder shape. The rule itself is general, though: *anything* in *any* subfolder is private, so you never extend the config to add a folder.
+
+Four rules, all `error`:
+
+1. **Entry-point boundary**: code outside a package (app code or another package) may import only that package's entry points (its root files), never anything in its subfolders.
+2. **Intra-package freedom**: a package's own files import each other freely.
+3. **Tests through the entry points**: files under `<pkg>/tests/` may import any package's entry points and their own `tests/` fixtures, but never any package's subfolder internals (not even their own). Integration tests across packages are fine; deep imports are not.
+4. **No cycles**: no dependency cycles.
+
+**Entry points, not a barrel.** Because the public surface is *every* root file, a package can expose several small entry points (`index.ts`, `client.ts`, `server.ts`) instead of funnelling everything through one giant `index.ts`. Barrel files that re-export a whole subtree are discouraged; keep entry points small and hide implementation in subfolders.
+
+Layering (which packages may depend on which) is a *different* concern and is left as a commented stub in the config for this repo to fill in.
+
+## Steps
+
+### 1. Detect the environment
+
+- **Package manager**: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, else npm. Use it for every command below (`pnpm`/`yarn`/`npm run`/`bunx`).
+- **Packages root**: if `src/` exists use `src/packages`, else `packages`. Confirm the choice with the user if the repo already has a different obvious convention.
+- **Existing config**: check for a `.dependency-cruiser.*` file. If one exists, do **not** overwrite it: merge the four rules and the options in, and tell the user what you added.
+
+**Done when:** package manager, packages root, and existing-config status are all known.
+
+### 2. Install dependency-cruiser
+
+Install `dependency-cruiser` as a devDependency with the detected package manager.
+
+**Done when:** `dependency-cruiser` is in `devDependencies`.
+
+### 3. Write the config
+
+Copy [`dependency-cruiser.config.cjs`](./dependency-cruiser.config.cjs) to the repo root as `.dependency-cruiser.cjs`. Set `PACKAGES_ROOT` to the root detected in step 1. The rules are path-depth based and extension-agnostic, so nothing else needs adapting.
+
+**Done when:** `.dependency-cruiser.cjs` exists with the correct `PACKAGES_ROOT`, and the four forbidden rules are present.
+
+### 4. Wire it into the checks
+
+- Add a `lint:boundaries` script: `depcruise <packages-root>` (or `depcruise src`).
+- Fold it into the repo's umbrella check command, the one that already runs typecheck (e.g. a `check` / `ci` / `validate` script). Do **not** touch `tsconfig` or add path aliases.
+- If there is no umbrella script, add `lint:boundaries` and tell the user to include it in CI.
+
+**Done when:** `lint:boundaries` exists and runs as part of the same command as typecheck.
+
+### 5. Scaffold the example package
+
+Create a committed `<packages-root>/example/` as a copy-me template:
+
+- `index.ts` is an entry point. Export one function that delegates to an internal file (so the package is visibly *deep*, not a pass-through).
+- `lib/impl.ts`: an internal file in a **subfolder**, imported by `index.ts`, not reachable from outside.
+- `tests/example.test.ts` imports **only** `../index` (an entry point) and asserts against the public function.
+
+Tell the user this is a starter template to copy or delete.
+
+**Done when:** the example package exists, exposes its behaviour through a root entry point, and hides `impl` in a subfolder.
+
+### 6. Prove the rules bite
+
+This is the completion criterion for the whole skill: a config that doesn't fail on a violation is worthless.
+
+1. Run `lint:boundaries`. It must **pass** on the clean example.
+2. Temporarily add a deep import to `tests/example.test.ts` (e.g. `import { thing } from "../lib/impl"`). Run `lint:boundaries` again; it must **fail** with `tests-through-entrypoints`.
+3. Revert the deep import. Run once more, and it must **pass**.
+
+**Done when:** you have observed a pass, then a fail on the deep import, then a pass again. If step 2 does not fail, the rules are not wired correctly, so fix before finishing.
+
+### 7. Document the convention
+
+Write a `README.md` **in the packages folder** (`<packages-root>/README.md`, next to the packages it governs) covering: the `src/packages/<name>/` layout (entry points at the root, `lib/` for implementation, `tests/` for tests), "import only through a package's entry points (its root files)", and how to run `lint:boundaries`. **Discourage barrel files** explicitly: expose several small entry points instead of re-exporting a whole subtree through one index. Keep it to the copy-me snippet plus the four rules in one paragraph each.
+
+Then add a **context pointer** to it from the repo's agent-instructions file (`CLAUDE.md` if present, else `AGENTS.md`, creating `AGENTS.md` if neither exists). One line is enough, e.g. `Packages are deep modules: see [src/packages/README.md](./src/packages/README.md) before adding or importing one.` This is what makes an agent discover the boundary rule instead of tripping over it.
+
+**Done when:** `<packages-root>/README.md` exists and discourages barrels, and the repo's `CLAUDE.md`/`AGENTS.md` links to it.
+
+## Notes
+
+- The config's `$1` back-references (dependency-cruiser's group matching) are what let a package reach its own internals while outsiders can't. Don't flatten them into separate per-package rules.
+- Public vs private is decided by **depth**: a package's root files are entry points; anything in a subfolder is private. The conventional subfolders are `lib/` (implementation) and `tests/`, but the rule doesn't hardcode them: any subfolder is private, so a new folder never needs a config change. Adding an entry point is just adding a root file (no barrel).
+- Packages are **flat**: one tier of immediate children under the root. A package's internals may nest as deep as you like; a package may not contain another package.
+- Use `.cjs` (not `.js`) so the config's `module.exports` works even in `"type": "module"` repos.

package/skills/mattpocock/skills/in-progress/setup-ts-deep-modules/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Setup TS Deep Modules"
+  short_description: "Enforce deep TypeScript modules"
+policy:
+  allow_implicit_invocation: false

package/skills/mattpocock/skills/in-progress/setup-ts-deep-modules/dependency-cruiser.config.cjs

@@ -0,0 +1,95 @@
+// @ts-check
+// Deep-module enforcement for dependency-cruiser.
+//
+// Each package under the packages root is a DEEP MODULE: a lot of behaviour
+// behind a small interface. A package's PUBLIC SURFACE is its ENTRY POINTS:
+// the files at the package root. Implementation lives in SUBFOLDERS and is
+// private (by convention `lib/` for implementation and `tests/` for tests,
+// though any subfolder is private). A package may expose several small entry
+// points (index.ts, client.ts, server.ts, …); prefer that over one giant
+// barrel index.
+//
+// The only thing you should ever need to edit here is PACKAGES_ROOT.
+
+/** Where packages live. One immediate child dir per package (flat, no nesting). */
+const PACKAGES_ROOT = "src/packages";
+
+// --- derived patterns (no need to edit) -------------------------------------
+const R = PACKAGES_ROOT;
+/**
+ * A package's private internals: anything nested inside a package subfolder.
+ * The package's root files are its entry points and are NOT matched here:
+ * they stay importable from outside.
+ */
+const PACKAGE_INTERNALS = `^${R}/[^/]+/[^/]+/`;
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: "entrypoint-boundary-from-app",
+      comment:
+        "App/root code may import a package's entry points (its root files), but nothing inside its subfolders.",
+      severity: "error",
+      from: { pathNot: `^${R}/` }, // importer is NOT inside any package
+      to: { path: PACKAGE_INTERNALS },
+    },
+    {
+      name: "entrypoint-boundary-across-packages",
+      comment:
+        "A package's own files import each other freely, but may reach OTHER packages only through their entry points, never their internals.",
+      severity: "error",
+      // importer is inside a package ($1), but is not a test file
+      from: { path: `^${R}/([^/]+)/`, pathNot: `^${R}/[^/]+/tests/` },
+      to: {
+        path: PACKAGE_INTERNALS,
+        pathNot: `^${R}/$1/`, // same package → intra-package freedom
+      },
+    },
+    {
+      name: "tests-through-entrypoints",
+      comment:
+        "A package's tests exercise it through its entry points like everyone else: they may import any package's entry points and their own tests/ fixtures, but never any package's internals, not even their own.",
+      severity: "error",
+      from: { path: `^${R}/([^/]+)/tests/` }, // a test file, in package $1
+      to: {
+        path: PACKAGE_INTERNALS,
+        pathNot: `^${R}/$1/tests/`, // own tests/ fixtures → allowed
+      },
+    },
+    {
+      name: "tests-folder-is-private",
+      comment:
+        "A package's tests/ folder is reachable only from tests: nothing else may import fixtures.",
+      severity: "error",
+      from: { pathNot: `^${R}/[^/]+/tests/` }, // importer is not itself a test
+      to: { path: `^${R}/[^/]+/tests/` },
+    },
+    {
+      name: "no-circular",
+      comment: "No dependency cycles. Scope to `^${R}/` if you want to allow cycles outside packages.",
+      severity: "error",
+      from: {},
+      to: { circular: true },
+    },
+
+    // --- Layering (optional, off by default) ----------------------------------
+    // Interface-hiding controls HOW you import (through the entry points).
+    // Layering controls WHICH packages may depend on which. Add your own rules
+    // here, e.g.:
+    //
+    // {
+    //   name: "ui-may-not-depend-on-billing",
+    //   severity: "error",
+    //   from: { path: `^${R}/ui/` },
+    //   to:   { path: `^${R}/billing/` },
+    // },
+  ],
+  options: {
+    doNotFollow: { path: "node_modules" },
+    tsConfig: { fileName: "tsconfig.json" },
+    enhancedResolveOptions: {
+      extensions: [".ts", ".tsx", ".js", ".jsx", ".json"],
+    },
+  },
+};

package/skills/mattpocock/skills/in-progress/software-factory/EXAMPLE-TASKS.md

@@ -0,0 +1,80 @@
+# Example tasks
+
+Tasks grouped by the problem they solve. Each names the trigger that starts its runs, what a run does, and what it triggers next. Most factories start as one of these and grow by chaining the next.
+
+## Untriaged tickets pile up
+
+**Explore task**
+- Trigger: a ticket is created, or a human labels it.
+- Does: checks the ticket against the codebase and sorts it into a category (easy call, needs a human, not a bug).
+- Triggers: an implementer run for easy calls. Anything else ends with the ticket labelled as waiting for a human.
+
+## Ready tickets wait for someone to build them
+
+**Implementer task**
+- Trigger: a ticket is labelled ready, by a human or an explore run.
+- Does: builds the ticket until the automated checks pass, and opens a draft PR.
+- Triggers: an automated review run.
+
+## PRs wait for review
+
+**Automated review task**
+- Trigger: a PR opens with no automated review yet, or a human labels it.
+- Does: reviews the diff against the codebase's standards and the ticket it came from.
+- Triggers: a rework run on a fail. On a pass it ends, and the PR waits for human review before a human merges it.
+
+## Failed automated reviews sit unfixed
+
+**Rework task**
+- Trigger: an automated review run fails a PR.
+- Does: fixes only what the automated review named, and pushes.
+- Triggers: an automated review run. After a set number of fails, it ends with the PR labelled as waiting for a human.
+
+## Specs are too big for one run
+
+**Decompose task**
+- Trigger: a spec ticket is labelled.
+- Does: splits the spec into tickets, each recording which tickets it depends on.
+- Triggers: an implementer run.
+
+The implementer run here picks the next ticket whose dependencies are all closed, and triggers itself again until no ticket is left.
+
+## Migrating to a stricter automated check
+
+A new lint rule (or a stricter type setting) is switched on, but only some files pass it. The rule enforces on the passing files, and the failing ones sit on an exception list.
+
+**Ratchet task**
+- Trigger: a daily clock.
+- Does: takes one file off the exception list, fixes it until the stricter check passes, and opens a PR.
+- Triggers: an automated review run. Once the exception list is empty, the ratchet run has nothing to take and the migration is done.
+
+One small PR a day keeps human review cheap, and the check only ever gets stricter.
+
+## Users report bugs nobody reads
+
+A feedback button in the app is a ticket source: it files each report as a ticket with the explore label already on it. The explore run does the rest.
+
+## Production problems are found late
+
+A monitor (slow queries, error rates) is a ticket source. It files a ticket per problem, and comments on the open ticket instead when it sees the same problem again. After a fix merges, it reopens the ticket if the problem persists.
+
+## The factory's own runs fail
+
+**Fix task**
+- Trigger: the orchestrator reports a failed run.
+- Does: files the failing log as a ticket, and attempts a fix as a PR when the failure is fixable.
+- Triggers: an automated review run. A failure in a fix run's own work triggers nothing, so fixes never chain. Because the fix changes the factory itself, it always gets human review.
+
+## The codebase drifts
+
+**Architecture task**
+- Trigger: a nightly clock.
+- Does: scans recent changes for refactoring candidates and files them as one ticket.
+- Triggers: nothing. A human picks a candidate and labels it, which starts the usual chain.
+
+## The same mistakes keep coming back
+
+**Retro task**
+- Trigger: a PR merges, throttled to one merged PR in ten.
+- Does: reads the PR, its ticket, its automated reviews and its run logs, and proposes changes to the factory's own instructions as a PR.
+- Triggers: an automated review run.

package/skills/mattpocock/skills/in-progress/software-factory/GIT-HOSTS.md

@@ -0,0 +1,84 @@
+# Git hosts
+
+> Surveyed 2026-10, and not guaranteed to be up to date. Use it to get oriented, then research the current options yourself: products, prices, limits and betas change fast.
+
+## The types
+
+### All-in-one platforms
+
+The git host bundled with a ticket tracker, a CI system that serves as orchestrator, and hosted runners, all sharing one event stream and one permission model. One product fills git host, ticket tracker, orchestrator and runner, and its CI run pages often cover the observability platform too. Every PR, review, label and check event is both a webhook and a native trigger, so this type has the richest trigger catalogue.
+
+**Pick it when** the factory starts small, the code already lives there, or the user wants one bill and one login. This is the "All on GitHub" design in [SKILL.md](SKILL.md). The vendors also ship their own agents, which either compete with the user's runs or slot in as one of them.
+
+- [GitHub](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api): the default; Issues, Actions, Apps and the largest integration ecosystem.
+- [GitLab](https://about.gitlab.com/pricing/): issues, merge requests, CI/CD and runners in one product, SaaS or self-managed.
+
+### Suite git hosts
+
+A git host sold as one module of a wider suite, where the ticket tracker is a sibling product (Jira, Azure Boards) joined by links and webhooks. Tracker events arrive on a second stream, so the orchestrator joins two event sources.
+
+**Pick it when** the organisation already runs the suite and its humans live in Jira or Azure Boards. The factory inherits that tracker as its human interface.
+
+- [Bitbucket Cloud](https://support.atlassian.com/bitbucket-cloud/docs/api-request-limits/): Atlassian's git host, paired with Jira and Bitbucket Pipelines.
+- [Azure DevOps (Azure Repos)](https://learn.microsoft.com/en-us/azure/devops/integrate/concepts/rate-limits): Repos, Boards, Pipelines and Entra identities in one organisation, so it fills all four slots.
+- [AWS CodeCommit](https://aws.amazon.com/blogs/devops/aws-codecommit-returns-to-general-availability/): a bare git host with IAM identities; pair it with an external tracker and CI.
+
+### Self-hosted git hosts
+
+A git host the user runs on their own infrastructure, often beside the orchestrator and runners on the same network. The operator sets the rate limits, so the ceiling is the hardware. The user owns upgrades, backups and uptime for every slot it fills.
+
+**Pick it when** code must stay on-premises or air-gapped, the user wants zero per-seat cost, or a SaaS API budget throttles a busy factory. Forgejo and Gitea suit small teams and bundle issues plus GitHub-Actions-compatible CI; GitLab self-managed and GitHub Enterprise Server suit organisations and keep their Apps and service accounts.
+
+- [Forgejo](https://forgejo.org/2026-10-release-v17-0/): community-governed, lightweight, with Forgejo Actions.
+- [Gitea](https://about.gitea.com/): lightweight with Gitea Actions; also sold managed.
+- [GitLab self-managed](https://about.gitlab.com/install/) and [GitHub Enterprise Server](https://docs.github.com/en/enterprise-server@latest): the full platforms on the user's own infrastructure.
+
+### Review-first and decentralised git hosts
+
+Git hosts whose review model departs from the branch-and-PR shape: per-commit patchsets with voted labels, or repositories federated across user-run nodes. Most factory tooling assumes PRs, so expect to build more of the glue. In Gerrit, an automated check run votes `Verified` from a bot account and a human votes `Code-Review`.
+
+**Pick it when** the user's team already reviews this way, or values federation over ecosystem.
+
+- [Gerrit](https://www.gerritcodereview.com/): patchset review with label votes; the Android and Chromium model.
+- [Tangled](https://blog.tangled.org/ci/): git hosting on the AT Protocol with stacked PRs and its own CI runner.
+
+### Agent-native git hosts
+
+New git hosts built around agents as the main authors: high commit throughput, server-side reads in place of clones, and per-agent attribution. The whole type is early (as of 2026-10), so gates and rate limits may be unpublished: ask the vendor.
+
+**Pick it when** the factory runs many concurrent runs against one large repository and clone time or API limits dominate. Pilot one on a mirror of a single repository, keeping GitHub as the fallback.
+
+- [Cursor Origin](https://cursor.com/origin): from the Graphite team, with GitHub sync and signed PR, review and push webhooks.
+- [GitLab next-gen SCM](https://about.gitlab.com/blog/gitlab-next-gen-scm/): rebuilt GitLab backend with clone-free agent APIs.
+
+### Git storage for runs
+
+Headless, API-first git repositories created by the thousand: branches, commits and diffs, with no PRs, reviews or gates. They fill half the slot, with short-lived per-repository tokens minted per run.
+
+**Pick it when** runs need cheap per-run scratch repositories or forks (a fork per ticket, an agent's working state) and the PR still lands on a full git host from the types above.
+
+- [Cloudflare Artifacts](https://www.cloudflare.com/product/artifacts/): git-compatible storage on Workers; fork a baseline per task.
+- [Pierre code.storage](https://code.storage/docs): white-label git API with ephemeral branches.
+
+## Researching further
+
+Check each candidate against these questions:
+
+1. **Triggers**: which events (PR opened, push, review submitted, label added, check finished) reach the orchestrator as webhooks, and are deliveries signed?
+2. **Identity**: can a run act as a dedicated bot or app identity? That keeps runs attributable, lets an automated review run approve a PR another identity authored, and decides whether a run's own pushes trigger the next run.
+3. **Gates**: are required checks, required approvals and branch protection available on the user's plan and repository visibility, and can a bot sit on a bypass list?
+4. **Rate limits**: what API budget does every run on every runner share, per what unit (installation, token, user, workspace), and how does it scale?
+5. **Slots filled**: which of ticket tracker, orchestrator, runner and observability platform does the same product cover?
+
+Find the answers in primary sources: the REST API and webhook reference, the rate-limit page, the pricing and plan comparison page, the access-token or app docs, and the changelog or release notes.
+
+The fastest to go stale: beta and preview status (the whole agent-native and git-storage types), rate-limit numbers, which plan unlocks gates, and availability after acquisitions, shutdowns and reopenings. As of 2026-10, for example, AWS CodeCommit had reopened to new customers and Bitbucket Data Center was sold only as a hybrid licence with Cloud.
+
+## Durable gotchas
+
+Verify each still holds before the design relies on it.
+
+- **GitHub `GITHUB_TOKEN` ends chains.** Events caused by the built-in Actions token start no new workflow runs (except `workflow_dispatch` and `repository_dispatch`), so a run pushing with it silently stops the next run. Give runs a GitHub App identity from day one.
+- **Gates often sit behind a paid plan.** As of 2026-10, GitHub rulesets on private repositories need Pro, Team or Enterprise, GitLab approval rules need Premium, and enforced Bitbucket merge checks need Premium.
+- **Rate limits are per identity, and the bot's type changes them.** As of 2026-10, a GitHub App installation gets 5,000 requests/hour against 1,000 for `GITHUB_TOKEN`; Bitbucket user tokens stay at the base rate while access tokens scale; Azure DevOps raises a bot's budget with its access level.
+- **Suite trackers mean two event streams.** The orchestrator joins git host and ticket tracker events itself.

package/skills/mattpocock/skills/in-progress/software-factory/OBSERVABILITY-PLATFORMS.md

@@ -0,0 +1,75 @@
+# Observability platforms
+
+> Surveyed 2026-10, and not guaranteed to be up to date. Use it to get oriented, then research the current options yourself: products, prices, limits and betas change fast.
+
+Orientation for filling the observability platform slot, or deciding on a deliberate none. The types split by **what the human needs to see inside a run**: its log, its agent trace (each model call and tool call as a span), or that trace joined to the rest of the user's system. Self-hosted vs SaaS cuts across the last three types. When a run should act on what the platform sees, make the platform a ticket source: a monitor files the ticket, and a run reads it.
+
+## How runners hook in
+
+Every type receives data through one of five hooks. Name the hook alongside the product when filling the slot.
+
+- **Harness OTel**: the agent harness exports OpenTelemetry itself. Claude Code and the Claude Agent SDK take `CLAUDE_CODE_ENABLE_TELEMETRY=1` plus `OTEL_*` variables, with prompts and tool output opt-in; Codex CLI takes an `[otel]` block in `config.toml`. ([Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/observability), [Claude Code](https://code.claude.com/docs/en/monitoring-usage), [Codex config](https://developers.openai.com/codex/config-advanced))
+- **Platform push**: the model platform sends traces for you, as Claude Managed Agents do to an OTLP destination set in the Claude Console. ([Claude docs](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api))
+- **SDK wrapper**: one call in the runner's code, such as LangSmith's `configure_claude_agent_sdk()`.
+- **Hook plugin**: a Claude Code hook reads the session transcript at each Stop and ships it, as in Langfuse's Claude Code plugin.
+- **Gateway**: the runner's model base URL points at a logging proxy. Zero runner code, and it sees model calls only: tool calls inside the harness stay invisible.
+
+OpenTelemetry is the common wire: harness OTel and platform push land in any OTLP backend. The GenAI semantic conventions (`invoke_agent`, `chat`, `execute_tool` spans) are still settling, so expect span names to drift. ([OTel GenAI agent spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans))
+
+## Type 1: None (the runner or orchestrator product shows enough)
+
+**What it is**: the human reads each run where the runner or orchestrator already shows it: the CI run page, the sandbox dashboard, the agent's transcript saved as a run artifact. No hook to build, as self-hosted as the runner, and bundled with its cost.
+
+**When a factory picks it**: few runs a day, one human watching, and the question is "did it fail, and what did it print?" Most factories start here, and grow out of it when they need search across runs, a token or cost rollup per run, or retention longer than the runner keeps.
+
+**Starting points**: [GitHub Actions run logs](https://docs.github.com/en/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization), [E2B sandbox logs and metrics](https://e2b.dev/docs), [Daytona sandbox telemetry](https://www.daytona.io/docs/en/observability/otel-collection/), [OpenAI Agents SDK traces](https://openai.github.io/openai-agents-python/tracing/). Sandbox products often forward the same data over OTLP, which is the path out to Type 2.
+
+**Verify**: retention days per runner product; some sandboxes keep very little (Daytona: 3 days, as of 2026-10).
+
+## Type 2: LLM and agent tracing platform
+
+**What it is**: a backend built around the agent trace: each run as a tree of model calls and tool calls, with token cost, prompts and sessions, usually with evals and datasets on top.
+
+**When a factory picks it**: the human asks "why did the agent do that?" across many runs; a retro run or a human compares runs; token spend needs a per-run rollup. Self-hosting an open-source one keeps transcripts in-house.
+
+**Traits of the type**: takes harness OTel, an SDK wrapper or a hook plugin, often the platform push too. Billed by volume, and agent runs are span-heavy (one span per tool call), so budget per run rather than per request.
+
+**Starting points**: [Langfuse](https://langfuse.com/pricing) and [Arize Phoenix](https://phoenix.arize.com) (open source, self-hostable), [LangSmith](https://www.langchain.com/pricing-langsmith), [Braintrust](https://www.braintrust.dev/pricing).
+
+**Verify**: free-tier limits, the billing unit (trace, span, unit or GB; Braintrust moved to GB in 2026-03), which tier unlocks self-hosting, and current ownership.
+
+## Type 3: General APM and logging backend
+
+**What it is**: the user's existing observability stack (logs, metrics, distributed traces for every service), with an agent or LLM view added.
+
+**When a factory picks it**: the team already pays for one; runs need joining to the app's own traces (the Agent SDK propagates `TRACEPARENT`, so a run nests inside its caller's trace); or a monitor ticket source already reads from it.
+
+**Traits of the type**: harness OTel goes straight to the vendor's OTLP endpoint. Priced per GB, event or host, so a factory's volume is a rounding error on an existing bill and a surprise on a new one.
+
+**Starting points**: [Datadog Agent Observability](https://www.datadoghq.com/product/llm-observability/), [Grafana Cloud](https://grafana.com/pricing/), [Honeycomb](https://www.honeycomb.io/pricing), [SigNoz](https://signoz.io/pricing/) (open source).
+
+**Verify**: whether the agent view is GA or preview, which harnesses have a setup guide, and free-tier volumes.
+
+## Type 4: LLM gateway with request logging
+
+**What it is**: a proxy between the runner and the model provider that logs every request and response, with routing, keys, budgets and caching alongside.
+
+**When a factory picks it**: the user wants per-run spend caps or one key vault for many runners, and logging comes with it; or the harness has no export of its own. It sees model calls only, so pair it with Type 2 or 3 for tool calls.
+
+**Starting points**: [LiteLLM Proxy](https://docs.litellm.ai/docs/proxy/logging) (open source, forwards logs to Langfuse or OTel), [Portkey](https://portkey.ai/pricing).
+
+**Verify**: per-request pricing on SaaS, and whether the product is still actively developed (Helicone went into maintenance mode after an acquisition, as of 2026-10).
+
+## Researching further
+
+Check each candidate against the questions that decide this slot:
+
+1. **Does the runner or orchestrator already show enough?** Compare what the human needs (cross-run search, per-run cost, retention) with what the run page or sandbox dashboard gives. A yes here means a deliberate none.
+2. **How does the agent harness export traces?** Find which of the five hooks the harness supports, then which the product accepts. Confirm tool calls arrive as spans, and whether prompts and tool output need an opt-in.
+3. **Is it self-hostable?** Licence, which tier allows it, and what it runs on. Decisive when transcripts must stay in-house.
+4. **What is the cost shape?** The billing unit, the free tier, and an estimate per run given one span per tool call, multiplied by runs per day.
+5. **How long is retention?** Days kept on each tier, against how far back the human looks when a run goes wrong.
+
+**Where the answers live**: the vendor's pricing page (units, tiers, retention); the vendor's integration doc for the specific harness; the harness's own monitoring docs (what it exports, which flags are beta); the OpenTelemetry GenAI semantic conventions; the product's repo for licence and release activity; the vendor's changelog or blog for ownership changes.
+
+**What goes stale fastest**: free-tier limits and prices; beta and preview flags (Claude Code trace export, Console platform push, vendor agent views); ownership and maintenance status; billing units; retention days; GenAI span names.