@mlangroman/sdlc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Lang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# sdlc
+
+**Ticket → plan → implement → land** — an agentic software development pipeline packaged as [agent skills](https://skills.sh), with a one-command project setup.
+
+Work is defined in a `thoughts/` folder as reviewable markdown artifacts (tickets and plans) with explicit human gates between every phase. Execution state lives in [beads](https://github.com/gastownhall/beads), implementation happens in isolated git worktrees, and every change gets a persisted code review before it merges.
+
+## Quick start
+
+Full project setup (thoughts folder + skills + `AGENTS.md`/`CLAUDE.md` symlinks + beads):
+
+```bash
+npx @mlangroman/sdlc setup
+```
+
+Skills only, for any of the 40+ agents the [skills CLI](https://www.npmjs.com/package/skills) supports (Claude Code, Cursor, Codex, …):
+
+```bash
+npx skills add MJLang/sdlc            # all nine skills
+npx skills add MJLang/sdlc --skill ticket --skill plan   # a subset
+```
+
+## The pipeline
+
+| Skill | Transition | Gate |
+|---|---|---|
+| `/ticket <idea>` | new ticket (`draft`) | — |
+| — (hand-edit `Status: approved`) | ticket `draft` → `approved` | **human** |
+| `/plan <NNN>` | ticket `approved` → plan (`review`) | — |
+| `/approve <NNN>` | plan `review` → `approved`; creates beads epic + step issues | **human** |
+| `/implement <NNN>` | executes the plan in its own worktree; ends with a review verdict | — |
+| `/land <NNN>` | squash-merge to main; plan → `merged`, ticket → `implemented` | **human** |
+| `/chore <idea>` | lightweight lane: small change end-to-end in one pass | **human** |
+| `/cancel <NNN> [plan]` | cancel a line of work (or just the plan, to re-plan) | **human** |
+| `/queue` | read-only dashboard: in flight, stalled, awaiting a human | — |
+| `/next` | one autonomous pipeline iteration — pair with `/loop` | — |
+
+Design principles:
+
+- **Artifacts over chat.** Tickets say *what and why*; plans say *how*, step by step with an explicit dependency graph. Both are markdown files you review and approve.
+- **Humans hold the gates.** Approving a ticket is a deliberate hand-edit. `/approve`, `/land`, `/chore`, and `/cancel` never run on the agent's initiative.
+- **Frontmatter records gates; beads records reality.** A file's `Status` only changes at hand-offs. Live progress is always a beads query, never a file edit.
+- **Worktree isolation.** Every plan is implemented on its own branch in `.worktrees/<plan-name>`, one commit per step, pushed as each step closes — a crashed session strands nothing.
+- **Reviews are artifacts.** Full reviewer output persists to `thoughts/reviews/` and travels with the branch; `/land` refuses to merge without an `APPROVED` verdict for the exact HEAD it is merging.
+- **Autonomy without gate-crossing.** `/loop /next` keeps planning and implementing whatever is legal, and queues everything that needs a human.
+
+The full workflow contract lives in [`template/thoughts/AGENTS.md`](template/thoughts/AGENTS.md) — `setup` copies it to `thoughts/AGENTS.md` in your project, and the skills treat it as the source of truth.
+
+## What `setup` does
+
+Run inside your project directory:
+
+1. `git init` if the directory is not a repository (the pipeline needs branches and worktrees)
+2. Creates `thoughts/{tickets,plans,designs,docs,reviews}/` and `thoughts/AGENTS.md`, with a `thoughts/CLAUDE.md → AGENTS.md` symlink
+3. Creates a starter root `AGENTS.md` (or adopts an existing root `CLAUDE.md` as `AGENTS.md`) and symlinks root `CLAUDE.md → AGENTS.md`
+4. Installs the nine skills into `.claude/skills/`
+5. Runs `bd init` if [beads](https://github.com/gastownhall/beads) is installed
+
+Flags: `--force` (overwrite existing files), `--skip-skills`, `--skip-beads`.
+
+## After setup
+
+1. Edit the **Project Configuration** section of `thoughts/AGENTS.md` — this is the one place the skills read per-project values from:
+   - **Targets** — the areas of your repo work can land in (e.g. `cms | jobs | web | utils` for a monorepo)
+   - **Quality gates** — the commands that must pass after every implementation step (e.g. `pnpm check`)
+   - **Reviewers** — map targets to reviewer agents if you have them; otherwise a general code review is used
+   - **Product docs** — where tickets ground their summaries (default `thoughts/docs/`)
+   - **Frontend constraints** — e.g. "no new pages until the design system exists"
+2. Drop your product/vision docs into `thoughts/docs/`
+3. Start: `/ticket <your first idea>`
+
+## Requirements
+
+- **git** — worktrees, branches, and (ideally) a remote
+- **[beads](https://github.com/gastownhall/beads)** (`bd`) — issue tracking, dependency graphs, and the claim mutex that keeps parallel sessions off the same plan
+- An agent that supports skills — built for [Claude Code](https://claude.com/claude-code), installable anywhere the [skills CLI](https://skills.sh) reaches
+
+## Repository layout
+
+```
+skills/           one folder per skill (SKILL.md) — what `npx skills add` installs
+template/         files copied into your project by `setup`
+  thoughts/AGENTS.md   the pipeline contract (workflow instructions)
+  AGENTS.root.md       starter root AGENTS.md (beads conventions, session protocol)
+bin/sdlc.mjs      the zero-dependency setup CLI
+```
+
+## License
+
+MIT

package/bin/sdlc.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * @mlangroman/sdlc — project bootstrapper for the ticket → plan → implement → land pipeline.
+ *
+ * Usage:
+ *   npx @mlangroman/sdlc setup [--force] [--skip-skills] [--skip-beads]
+ */
+
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const cwd = process.cwd();
+
+const tty = process.stdout.isTTY;
+const c = (code, s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : s);
+const ok = (s) => console.log(`  ${c('32', '✓')} ${s}`);
+const skip = (s) => console.log(`  ${c('90', '•')} ${s}`);
+const warn = (s) => console.log(`  ${c('33', '!')} ${s}`);
+const head = (s) => console.log(`\n${c('1', s)}`);
+
+const args = process.argv.slice(2);
+const command = args.find((a) => !a.startsWith('-'));
+const flags = new Set(args.filter((a) => a.startsWith('-')));
+const force = flags.has('--force') || flags.has('-f');
+
+const SKILLS_DIR = join(pkgRoot, 'skills');
+const THOUGHTS_SUBDIRS = ['tickets', 'plans', 'designs', 'docs', 'reviews'];
+
+function help() {
+  console.log(`
+${c('1', '@mlangroman/sdlc')} — ticket → plan → implement → land pipeline for agentic development
+
+Usage:
+  npx @mlangroman/sdlc setup [options]     Set up the pipeline in the current directory
+
+Options:
+  --force, -f      Overwrite existing thoughts/AGENTS.md, root AGENTS.md, and skills
+  --skip-skills    Do not install skills into .claude/skills/
+  --skip-beads     Do not run bd init
+
+What setup does:
+  1. git init (if not already a repository)
+  2. Creates thoughts/{${THOUGHTS_SUBDIRS.join(',')}} + thoughts/AGENTS.md (+ CLAUDE.md symlink)
+  3. Creates a root AGENTS.md (if missing) and a root CLAUDE.md → AGENTS.md symlink
+  4. Installs the pipeline skills into .claude/skills/
+  5. Initializes beads (bd init), if bd is installed
+
+Skills can also be installed on their own, for any supported agent, via the skills CLI:
+  npx skills add MJLang/sdlc
+`);
+}
+
+// Symlink CLAUDE.md → AGENTS.md (relative). Falls back to a copy where symlinks are unavailable.
+function linkClaudeMd(dir, label) {
+  const link = join(dir, 'CLAUDE.md');
+  if (existsSync(link) || (lstatSync(link, { throwIfNoEntry: false })?.isSymbolicLink())) {
+    const st = lstatSync(link);
+    if (st.isSymbolicLink()) skip(`${label}/CLAUDE.md symlink exists`);
+    else warn(`${label}/CLAUDE.md exists as a regular file — leaving it; consider merging it into AGENTS.md and symlinking`);
+    return;
+  }
+  try {
+    symlinkSync('AGENTS.md', link);
+    ok(`${label}/CLAUDE.md → AGENTS.md symlink`);
+  } catch {
+    cpSync(join(dir, 'AGENTS.md'), link);
+    warn(`${label}/CLAUDE.md created as a copy (symlinks unavailable on this system)`);
+  }
+}
+
+function copyIfMissing(src, dest, label) {
+  if (existsSync(dest) && !force) {
+    skip(`${label} exists (use --force to overwrite)`);
+    return;
+  }
+  cpSync(src, dest);
+  ok(label);
+}
+
+function setup() {
+  console.log(c('1', '\nSetting up the sdlc pipeline in ') + cwd);
+
+  head('git');
+  if (existsSync(join(cwd, '.git'))) {
+    skip('already a git repository');
+  } else {
+    const r = spawnSync('git', ['init'], { cwd, stdio: 'pipe' });
+    if (r.status === 0) ok('git init (the pipeline uses worktrees and branches)');
+    else warn('git init failed — run it yourself; the pipeline requires git');
+  }
+
+  head('thoughts/');
+  for (const d of THOUGHTS_SUBDIRS) {
+    const p = join(cwd, 'thoughts', d);
+    if (existsSync(p)) skip(`thoughts/${d}/ exists`);
+    else {
+      mkdirSync(p, { recursive: true });
+      writeFileSync(join(p, '.gitkeep'), '');
+      ok(`thoughts/${d}/`);
+    }
+  }
+  copyIfMissing(join(pkgRoot, 'template', 'thoughts', 'AGENTS.md'), join(cwd, 'thoughts', 'AGENTS.md'), 'thoughts/AGENTS.md (pipeline instructions)');
+  linkClaudeMd(join(cwd, 'thoughts'), 'thoughts');
+
+  head('root instructions');
+  const rootAgents = join(cwd, 'AGENTS.md');
+  const rootClaude = join(cwd, 'CLAUDE.md');
+  if (!existsSync(rootAgents) && existsSync(rootClaude) && lstatSync(rootClaude).isFile()) {
+    // Adopt an existing CLAUDE.md as the canonical AGENTS.md, then symlink back.
+    renameSync(rootClaude, rootAgents);
+    ok('moved existing CLAUDE.md → AGENTS.md (canonical file)');
+  }
+  copyIfMissing(join(pkgRoot, 'template', 'AGENTS.root.md'), rootAgents, 'AGENTS.md (root agent instructions)');
+  linkClaudeMd(cwd, '.');
+
+  if (!flags.has('--skip-skills')) {
+    head('skills → .claude/skills/');
+    for (const name of readdirSync(SKILLS_DIR)) {
+      const src = join(SKILLS_DIR, name);
+      const dest = join(cwd, '.claude', 'skills', name);
+      if (existsSync(dest) && !force) {
+        skip(`${name} exists (use --force to overwrite)`);
+        continue;
+      }
+      mkdirSync(dest, { recursive: true });
+      cpSync(src, dest, { recursive: true, force: true });
+      ok(name);
+    }
+    console.log(`    ${c('90', 'other agents (cursor, codex, …): npx skills add MJLang/sdlc')}`);
+  }
+
+  if (!flags.has('--skip-beads')) {
+    head('beads');
+    const bd = spawnSync('bd', ['--version'], { stdio: 'pipe' });
+    if (bd.error || bd.status !== 0) {
+      warn('bd (beads) not found — install it from https://github.com/gastownhall/beads, then run: bd init');
+    } else if (existsSync(join(cwd, '.beads'))) {
+      skip('.beads/ exists');
+    } else {
+      const r = spawnSync('bd', ['init'], { cwd, stdio: 'inherit' });
+      if (r.status === 0) ok('bd init');
+      else warn('bd init failed — run it yourself');
+    }
+  }
+
+  console.log(`
+${c('1', 'Done. Next steps:')}
+  1. Edit the ${c('1', 'Project Configuration')} section in thoughts/AGENTS.md
+     (targets, quality gates, reviewers, product docs)
+  2. Drop your product/context docs into thoughts/docs/
+  3. In your agent: ${c('1', '/ticket <your first idea>')}
+
+Pipeline: /ticket → approve by hand → /plan → /approve → /implement → /land
+Dashboard: /queue    Autonomous: /loop /next    Small fixes: /chore
+`);
+}
+
+if (command === 'setup') setup();
+else help();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mlangroman/sdlc",
+  "version": "0.1.0",
+  "description": "Ticket → plan → implement → land: an agentic SDLC pipeline as installable agent skills, with one-command project setup (thoughts/ folder, AGENTS.md/CLAUDE.md symlinks, beads issue tracking).",
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "sdlc",
+    "beads",
+    "workflow",
+    "agents"
+  ],
+  "license": "MIT",
+  "author": "Martin Lang <martin@mercator.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MJLang/sdlc.git"
+  },
+  "type": "module",
+  "bin": {
+    "sdlc": "bin/sdlc.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "template/"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/approve/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: approve
+description: Human gate — approve a reviewed plan (creates its beads epic + step issues), or re-sync an amended, already-approved plan into its epic.
+argument-hint: <plan number, e.g. 003>
+disable-model-invocation: true
+---
+
+Approve or re-sync plan $ARGUMENTS. This is a human gate: it runs only on explicit user invocation.
+
+Two modes, chosen by the plan's current state:
+- **First approval** — `Status: review`, no `Beads Epic`.
+- **Amendment re-sync** — `Status: approved` with `Beads Epic` set, and the plan file has been edited. This is the sanctioned way to change a plan after approval — including adding scope while `/implement` is running.
+
+If the plan is `draft`, refuse: it is not finished. If it does not exist, refuse.
+
+## Amendment rules — enforced in both modes
+
+- Step numbers are immutable — never renumber. New steps get fresh numbers and place themselves via `Depends on:`.
+- Removed steps stay in the file, marked `~~Step N~~ — removed: <why>`.
+- A dependency on an already-closed issue is simply satisfied, so appending steps mid-flight is safe.
+
+## Mode: first approval
+
+1. Read the plan in full. Unresolved **Open Questions** → list them and ask the user to resolve them before approving.
+2. Create the epic:
+
+   ```bash
+   bd create "<plan title>" --type=epic --priority=2 \
+     --description="Epic for plan <plan filename>. Ticket: <ticket filename>."
+   ```
+
+3. Create one child issue per step (parallel subagents are fine when there are many):
+
+   ```bash
+   bd create "<step title>" --type=task --parent=<epic-id> --priority=2 \
+     --description="Step N of <plan filename>: <what, files touched>"
+   ```
+
+4. Wire step ordering from the plan's `Depends on:` lines: `bd dep add <later-step-id> <earlier-step-id>`.
+5. Update the plan file atomically — the one place frontmatter and beads are synced: set `Beads Epic: <epic-id>`, set `Status: approved`, and append a **Beads** section mapping steps ↔ issue ids.
+6. Report: the epic id, the issue ids, what `bd ready` shows unblocked, and that `/implement {NNN}` may now run.
+
+## Mode: amendment re-sync
+
+1. Read the plan and the epic's children (`bd show <epic-id>`). Diff plan steps against issues using the **Beads** section mapping:
+   - a step with no issue → create it (`--parent=<epic-id>`) and wire its `Depends on:` deps;
+   - a step marked removed whose issue is still open → `bd close <id> --reason="superseded by plan amendment"`;
+   - closed issues for unchanged steps → leave untouched.
+2. Update the plan's **Beads** section with the new mapping; record the amendment in both places: a line in the plan body, and `bd update <epic-id> --append-notes="amended: +<n> steps, -<m> steps — <one-line why>"`.
+3. Report what changed. A running `/implement` needs no restart — it re-derives its issue set from beads every iteration, so new issues simply join its queue.
+
+This skill is idempotent in both modes: re-running with nothing to sync changes nothing and says so.

package/skills/cancel/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: cancel
+description: Human gate — cancel a line of work (ticket + plan + epic + worktree), or just the plan to re-plan against the same ticket.
+argument-hint: <number> [plan]
+disable-model-invocation: true
+---
+
+Cancel work for $ARGUMENTS. This is a human gate: it runs only on explicit user invocation.
+
+Scope comes from the second word of the arguments:
+- **(default)** — cancel the whole line of work: ticket, plan, epic, worktree, branch.
+- **`plan`** — cancel only the plan, to re-plan differently: the ticket returns to `approved`, and `/plan {NNN}` may then write a fresh plan (its precondition permits replacing a `cancelled` one).
+
+## Before destroying anything
+
+1. Resolve what exists for {NNN}: ticket, plan, `Beads Epic`, worktree `.worktrees/<plan-name>`, branch (local and remote).
+2. Show the blast radius and, if there is unmerged work, confirm with the user before proceeding:
+   - worktree: `git -C .worktrees/<plan-name> status --short` and `git log main..<plan-name> --oneline`
+   - epic: open issues (`bd show <epic-id>`)
+
+## Steps
+
+1. **Beads:** close the epic and all open child issues: `bd close <ids...> --reason="cancelled: <short why>"`.
+2. **Git** (only after the confirmation above):
+
+   ```bash
+   git worktree remove --force .worktrees/<plan-name>
+   git branch -D <plan-name>
+   git push origin --delete <plan-name>   # if it was published
+   ```
+
+3. **Statuses** (the gate flip):
+   - scope `plan`: plan → `Status: cancelled`; ticket stays `approved`.
+   - default: plan → `cancelled` (if one exists), ticket → `cancelled`.
+4. **Push — mandatory:** commit the status flips (`cancel: <ticket title> (ticket NNN) — <short why>`), then `git push` and `bd dolt push`.
+5. **Report:** what was cancelled, what was destroyed, and — for scope `plan` — that `/plan {NNN}` is the next step.
+
+Handle partial states gracefully: a ticket with no plan (just flip the ticket), a plan with no epic yet (no beads work), an epic with no worktree (no git work). Cancel what exists, skip what doesn't, report both.

package/skills/chore/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: chore
+description: Human gate — the lightweight lane. Take a small, low-risk change (typo, doc fix, config tweak, dep bump) end-to-end in one pass — chore ticket → worktree → gates + one review → merge — without a plan or epic.
+argument-hint: <short description of the small change>
+disable-model-invocation: true
+---
+
+Run the chore lane for: $ARGUMENTS. This is a human gate: invocation IS the approval — which is why this skill may merge to main at the end, and why it runs only on explicit user invocation.
+
+## Lane guard — refuse and point to /ticket if any of these fail
+
+- The change is small and low-risk: typo, docs, config tweak, dependency bump, tiny bugfix.
+- No new feature surface, no schema/contract changes, no new patterns being established.
+- Expected diff ≲ 5 files / ~150 lines. If the diff outgrows this during implementation, STOP: keep the ticket, tell the user it needs a real plan (`/plan {NNN}`), and leave the worktree in place for it.
+
+## Steps
+
+1. **Ticket (audit trail):** allocate the next number and write `thoughts/tickets/{NNN}-{slug}.md` as usual, with `Type: chore` and `Status: approved` (invocation is approval). Note in the body: "Chore lane — no plan."
+2. **Bead:** one task, no epic: `bd create "<title>" --type=task --priority=3 --description="Chore {NNN}: <what>"`, then claim it.
+3. **Worktree:** from up-to-date main (`git pull --rebase`): `git worktree add .worktrees/{NNN}-c-{slug} -b {NNN}-c-{slug}`, publish with `git push -u origin {NNN}-c-{slug}`.
+4. **Implement** the change in the worktree. Commit and push.
+5. **Gates:** the gate commands defined in `thoughts/AGENTS.md` (Project Configuration), plus the target's `test` / `typecheck` scripts where defined.
+6. **Review — one pass:** dispatch the reviewer mapped to the change's lane in `thoughts/AGENTS.md` (or a general code-review subagent if none is configured). Persist the output to `thoughts/reviews/{NNN}-round1.md` in the worktree and commit it. MUST FIX → fix, re-run gates, one re-review. Still blocked → stop and report; do not merge.
+7. **Merge** (squash, as `/land` does): in the main checkout, `git pull --rebase`, `git merge --squash {NNN}-c-{slug}`, flip the ticket → `Status: implemented` in the same commit. Message: `chore: <title> (ticket NNN)`.
+8. **Close out:** `bd close <id>`; `git push` + `bd dolt push` (mandatory); remove the worktree and branch (local + remote).
+9. **Report:** merge commit, diff stat, review verdict.

package/skills/implement/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: implement
+description: Implement an approved plan in its own git worktree — claim the beads epic, execute steps via subagents in dependency order, run quality gates per step, then one full code review. Use when a plan is approved and its beads epic exists.
+argument-hint: <plan number, e.g. 003>
+---
+
+Implement plan $ARGUMENTS per the pipeline in `thoughts/AGENTS.md`.
+
+## Preconditions — refuse with the specific failure if unmet
+
+1. The plan exists, has `Status: approved`, and `Beads Epic:` is set. If `review` → needs `/approve` first. If `merged` → already done.
+2. **Claim the epic as the very first action** — this is the concurrency mutex:
+
+   ```bash
+   bd update <epic-id> --claim
+   ```
+
+   If it is already claimed / in_progress by another session, STOP: another loop or session owns this plan.
+
+## Setup
+
+1. From an up-to-date main (`git pull --rebase`), create the worktree — path and branch are both the plan name (plan filename without `.md`):
+
+   ```bash
+   git worktree add .worktrees/<plan-name> -b <plan-name>
+   ```
+
+   If the worktree or branch already exists, resume it — do not recreate. On resume with a dirty worktree: diff the uncommitted changes against the in-progress step and either finish or reset them; never blindly commit.
+2. Publish the branch immediately: `git push -u origin <plan-name>` — from here on, nothing exists only locally. (Skip only if the repo has no remote; note it in the report.)
+
+## Execution loop
+
+Repeat until every issue in the epic is closed. **Re-derive the issue set from beads at the top of every iteration** — plans can be amended mid-flight (`/approve` re-sync), and newly added issues simply join the queue.
+
+1. `bd ready` → pick unblocked issues belonging to the epic. Claim each before working: `bd update <id> --claim`.
+2. For each claimed issue, spawn an implementer subagent (Agent tool) working **inside the worktree directory**, giving it: the ticket, the plan, the step's text, and the instruction to follow existing repo conventions. Steps the plan marks parallelizable (disjoint file sets) may run as concurrent subagents; otherwise serialize — parallel edits to overlapping files in one worktree will conflict.
+3. After each step, run the plan's quality gates inside the worktree: the gate commands defined in `thoughts/AGENTS.md` (Project Configuration), plus the target's own `test` / `typecheck` scripts where defined. Gates fail → fix before proceeding.
+4. Gates pass → commit in the worktree (one commit per step: `step N: <title> (<issue-id>)`), `bd close <issue-id>`, and `git push` — every finished step is on the remote branch the moment it closes; a crashed session strands nothing.
+5. Blocked on something only a human can decide → flag it (`bd update <issue-id> --add-label human`), leave the issue open, and continue with other unblocked steps. If nothing else can proceed, stop and report.
+
+## Review — once per plan, at the end
+
+1. Dispatch the reviewer mapped to the plan's `Target` in `thoughts/AGENTS.md` (Project Configuration) — both lanes' reviewers if the diff spans lanes; a thorough general code-review subagent if no reviewer is configured. Pass the ticket and plan paths.
+2. Persist each round's full reviewer output verbatim to `thoughts/reviews/{NNN}-round{n}.md` inside the worktree and commit it — the review is an artifact that travels with the branch; its NITs are fodder for later chore tickets.
+3. MUST FIX findings → fix in the worktree, re-run gates, commit, re-review (next round, next file). Cap at 3 rounds; if still blocked, flag the epic (`bd update <epic-id> --add-label human`) and report.
+4. On APPROVED: commit the final review file first, then record the verdict against the resulting HEAD and push:
+
+   ```bash
+   bd update <epic-id> --append-notes="review: APPROVED sha=<worktree HEAD sha> rounds=<n>"
+   git push
+   ```
+
+## Never
+
+- Never merge to main — that is `/land`, a human gate.
+- Never edit files outside the worktree. Plan and ticket frontmatter are untouched here; live progress lives in beads.
+- Never ask the user questions mid-run — use the `human` label and keep going where possible.
+
+**Report:** steps completed, gate results, review verdict, worktree path, and that `/land {NNN}` is the next (human) step.

package/skills/land/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: land
+description: Human gate — merge an implemented plan's worktree into main, flip plan/ticket statuses, close the beads epic, clean up, and push.
+argument-hint: <plan number, e.g. 003>
+disable-model-invocation: true
+---
+
+Land plan $ARGUMENTS. This is a human gate: it runs only on explicit user invocation.
+
+## Preconditions — verify ALL; refuse with the specific failure otherwise
+
+1. The plan exists with `Status: approved` and `Beads Epic:` set; the worktree `.worktrees/<plan-name>` exists.
+2. Every issue in the epic is closed. Open `human`-labeled issues block landing unless the user explicitly waives them — list them and confirm.
+3. The epic's notes contain `review: APPROVED sha=<sha>`, and that sha either equals the worktree's current HEAD or is connected to it by an unbroken chain of `rebased: <old>→<new> gates=pass` notes (written in step 1). Any other commits after the verdict mean the review phase of `/implement` must re-run first.
+4. The review artifact exists in the worktree: `thoughts/reviews/{NNN}-round*.md`.
+
+## Steps
+
+1. **Freshness.** In the worktree: `git fetch`; if main has moved, rebase onto latest main.
+   - Rebase **conflicts** → STOP. Conflict resolution is semantic risk: resolve in the worktree, then re-run `/implement`'s review phase (new HEAD ⇒ new verdict) before landing.
+   - Rebase **clean** → re-run the quality gates (the gate commands in `thoughts/AGENTS.md` + target tests), then record the hop: `bd update <epic-id> --append-notes="rebased: <old-sha>→<new-sha> gates=pass"`. Gate failures block landing.
+2. **Merge** — default is squash: one ticket = one reviewable unit = one commit on main.
+
+   ```bash
+   git pull --rebase          # in the main checkout
+   git merge --squash <plan-name>
+   ```
+
+   Before committing, flip the state files **in the same commit**: plan → `Status: merged`, ticket → `Status: implemented`. Commit message: `<type>: <ticket title> (ticket NNN)`, body referencing the plan file and epic id.
+3. **Close beads:** `bd close <epic-id>` plus any straggler step issues (`--reason` where non-obvious).
+4. **Push — mandatory** where the root `AGENTS.md` grants git authority (skip only if the repo has no remote; note it in the report):
+
+   ```bash
+   git push
+   bd dolt push
+   git status   # MUST show "up to date with origin"
+   ```
+
+5. **Clean up:**
+
+   ```bash
+   git worktree remove .worktrees/<plan-name>
+   git branch -D <plan-name>
+   git push origin --delete <plan-name>
+   ```
+
+6. **Report:** the merge commit, statuses flipped, epic closed, cleanup done.

package/skills/next/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: next
+description: Autonomous loop dispatcher — perform exactly one legal pipeline transition (plan an approved ticket, or implement an approved plan) and queue the human gates. Designed to be driven by /loop.
+disable-model-invocation: true
+---
+
+Run ONE iteration of the ticket → plan → implement pipeline (`thoughts/AGENTS.md`). Strictly non-interactive: never ask the user anything; flag decisions with the `human` label (`bd update <id> --add-label human`).
+
+## Derive state — from disk and beads only, never from memory of past sessions
+
+Spawn ONE read-only subagent (Explore, cheapest available model tier — mechanical parsing) to collect the snapshot and return it as a compact table, no prose. Do not gather inline: in loop mode this runs every iteration, and the driver's context must stay small for the `/implement` that may follow.
+
+1. Plans: `Status` + `Beads Epic` of every file in `thoughts/plans/`.
+2. Tickets: `Status` of every file in `thoughts/tickets/`.
+3. Live: `bd ready`, `bd list --status=in_progress`, `bd human list`, and per in-flight epic: claim holder + last-activity times.
+4. In-flight file sets: for every plan that is `approved` with open epic issues, the union of the files its steps declare.
+
+The subagent gathers facts only. The transition decision below — legality, overlap, claim semantics — is made HERE, by you, from the snapshot.
+
+## Pick the highest-priority legal transition — first match wins, execute exactly one
+
+1. **Implement**: a plan with `Status: approved`, an epic recorded, open issues in the epic, the epic NOT claimed/in_progress by another session, **and no overlap between its declared file set and any in-flight plan's** → invoke `/implement {NNN}`. It claims first; if the claim fails, treat the plan as owned elsewhere and fall through to the next candidate. Candidates skipped for file overlap are reported, never silently dropped.
+2. **Plan**: a ticket with `Status: approved` and no plan file with its number → invoke `/plan {NNN}`.
+3. **Idle**: no legal transition → report idle immediately and stop. Keep this path cheap — no research, no subagents.
+
+## Never
+
+- Never perform `/approve`, `/land`, `/cancel`, or `/chore` — those are human gates. Instead, end every report with the **human queue**:
+  - plans in `Status: review` (awaiting `/approve`),
+  - plans whose epic notes carry an APPROVED review verdict (awaiting `/land`),
+  - anything in `bd human list`,
+  - **stale claims** — epics claimed/in_progress with no beads or git activity for >24h: likely a crashed session; a human should unclaim, after which `/implement` resumes cleanly.
+- Never ask questions. On ambiguity, flag the nearest issue with the `human` label and move on.
+
+One transition per invocation. When it completes (or refuses), report and stop — the outer `/loop` schedules the next iteration.

package/skills/plan/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: plan
+description: Write an implementation plan for an approved ticket. Use when a ticket in thoughts/tickets is approved and needs a concrete plan before implementation.
+argument-hint: <ticket number, e.g. 003>
+---
+
+Write the plan for ticket $ARGUMENTS — the instruction artifact of the pipeline in `thoughts/AGENTS.md`.
+
+## Preconditions — refuse with the specific failure if unmet
+
+1. The ticket `thoughts/tickets/{NNN}-*.md` exists.
+2. The ticket has `Status: approved`. If `draft`, tell the user to review and approve the ticket first.
+3. No plan with number {NNN} exists in `thoughts/plans/` (unless its `Status` is `cancelled`). If one exists, stop and report it — plans are revised, not duplicated.
+
+## Steps
+
+1. **Research first.** Read the ticket in full, the product docs in `thoughts/docs/`, and the code of the ticket's Target. Understand existing conventions before proposing anything — the plan must follow the repo's grain, and the code reviewers will hold the implementation to it.
+2. **Frontend constraint.** If the plan includes frontend work, check `thoughts/AGENTS.md` (Project Configuration) for design-system constraints (e.g. no new pages until the design system exists) and honor any configured design skill for on-brand implementation. Note both in the plan.
+3. **Write** `thoughts/plans/{NNN}-{t}-{kebab-case-title}.md` — `t` = first letter of Type, `NNN` = same number as the ticket:
+
+   ```yaml
+   ---
+   Status: review
+   Tags: []
+   Type: <type>
+   Target: <target>
+   Ticket Origin: <ticket filename>
+   Beads Epic:
+   ---
+   ```
+
+   (`Beads Epic` stays empty — `/approve` fills it.)
+
+   Body sections:
+   - **Context** — why this work exists, link to the ticket, the relevant existing code.
+   - **Implementation Steps** — numbered. Each step states: what to do, files touched, and an explicit `Depends on: step N` line (or `Depends on: none`). Steps must be independently completable and gate-checkable. Mark steps whose file sets are disjoint as parallelizable. These `Depends on:` lines become beads issue dependencies at approval — they are the machine-readable form; a mermaid diagram of the step graph is optional, for human readability only.
+   - **Quality Gates** — what must pass after every step: the gate commands defined in `thoughts/AGENTS.md` (Project Configuration), plus the target's own `test` / `typecheck` / `build` scripts where defined.
+   - **Verification** — how to exercise the finished work end-to-end, mapped to the ticket's acceptance criteria.
+   - **Open Questions** — anything unresolved.
+
+4. **Stop at `review`.** Do NOT create beads issues, worktrees, or code. Report the plan path and that it awaits human review → `/approve {NNN}`.
+
+If something is ambiguous and no user is available (unattended run), do not guess silently: record it under **Open Questions** — the human resolves it at review time.

package/skills/queue/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: queue
+description: Read-only dashboard of the ticket → plan → implement → land pipeline — what is in flight, what is stalled, and what awaits a human decision. Use when the user asks what needs them, what's in progress, or for overall pipeline status.
+---
+
+Build the pipeline dashboard. Strictly read-only — no mutations to files, beads, or git.
+
+## Gather — delegate to a cheap subagent
+
+Spawn ONE read-only subagent (Explore, cheapest available model tier — this is mechanical parsing) to collect the snapshot below and return it as a compact table, no prose. Do not gather inline: delegation keeps this session's context clean.
+
+1. Tickets: `Status` of every file in `thoughts/tickets/`.
+2. Plans: `Status` + `Beads Epic` of every file in `thoughts/plans/`.
+3. Beads: `bd ready`, `bd list --status=in_progress`, `bd human list`, and per in-flight epic: open/closed child counts, last-activity times, and any `review:` / `rebased:` notes.
+4. Worktrees: `git worktree list`; branches ahead of main.
+5. Recently landed: the last ~5 main commits referencing tickets.
+
+Interpretation of the snapshot (staleness, what needs a human) happens here, not in the subagent.
+
+## Report — human queue first
+
+1. **Needs you now**
+   - plans in `Status: review` → awaiting `/approve`
+   - epics whose notes carry `review: APPROVED` for the worktree's HEAD → awaiting `/land`
+   - `bd human list` flags
+   - **stale claims** — epics claimed/in_progress with no beads or git activity for >24h: likely a crashed session; note the recovery (unclaim, then `/implement` resumes)
+2. **In flight** — plans `approved` with open epic issues: N/M steps closed, claim holder, last activity, worktree path
+3. **Ready to start** — plans `approved` awaiting `/implement`; tickets `approved` without a plan (→ `/plan`)
+4. **Drafts** — tickets in `draft` awaiting your approval
+5. **Recently landed** — the last few merges
+
+Keep it compact — one line per item, with ids and the next command inline. Omit empty sections.

package/skills/ticket/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ticket
+description: Create a new work ticket in thoughts/tickets from an idea. Use when the user describes a new feature, bug, refactor, or chore that should enter the ticket → plan → implement pipeline.
+argument-hint: <one-line idea or description>
+---
+
+Create a new ticket — the intent artifact of the pipeline described in `thoughts/AGENTS.md`.
+
+Input: $ARGUMENTS
+
+## Steps
+
+1. **Allocate the number.** Next number = the highest number used by any file in `thoughts/tickets/` or `thoughts/plans/`, plus one, zero-padded to 3 digits.
+2. **Classify.** Type: `feature | bug | refactor | chore`. Target: one of the targets defined in `thoughts/AGENTS.md` (Project Configuration). Infer both from the idea and the product docs in `thoughts/docs/`. If the target is genuinely ambiguous, ask the user; when running unattended, pick the best fit and record the assumption under Open Questions.
+3. **Write** `thoughts/tickets/{NNN}-{kebab-case-title}.md`:
+
+   ```yaml
+   ---
+   Status: draft
+   Tags: []
+   Type: <type>
+   Target: <target>
+   ---
+   ```
+
+   Body sections:
+   - **Summary** — what and why, grounded in the product docs in `thoughts/docs/` (user journeys, goals).
+   - **Scope** — explicitly in scope / out of scope.
+   - **Acceptance Criteria** — checkable outcomes, not implementation steps.
+   - **Open Questions** — if any; empty section is fine.
+
+4. **Stay high-level.** A ticket describes WHAT and WHY — never implementation steps; that is the plan's job. A ticket must fit a single reviewable unit of work: if the idea is bigger than that, split it into multiple tickets and tell the user how you split it.
+5. **Report** the file path and remind the user: the ticket stays `draft` until they approve it (flip `Status: approved`), which is what makes it eligible for `/plan`.
+
+Do NOT create beads issues, plans, or code here.

package/template/AGENTS.root.md

@@ -0,0 +1,52 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking — run `bd prime` for full workflow context.
+
+> **Architecture:** Issues live in a local Dolt DB (`.beads/dolt/`); sync uses `bd dolt push/pull` over `refs/dolt/data` on your git remote (separate from `refs/heads/*`). `.beads/issues.jsonl` is a passive export, not the source of truth — see [SYNC_CONCEPTS.md](https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md) for anti-patterns.
+
+## Folder Structure
+
+- Use the `thoughts/` folder to define work — the ticket → plan → implement → land pipeline is described in `thoughts/AGENTS.md`.
+- `thoughts/docs/` holds product/context docs that tickets are grounded in.
+
+## Beads Issue Tracker
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+## Quality Gates
+
+<!-- Define the commands that must pass before work merges, and keep them in sync
+     with the "Quality gates" line in thoughts/AGENTS.md (Project Configuration). -->
+
+```bash
+npm test
+```
+
+## Session Completion
+
+**When ending a work session:**
+
+1. **File issues for remaining work** — create beads issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) — tests, linters, builds
+3. **Update issue status** — close finished work, update in-progress items
+4. **Push to remote** — both code and beads data:
+   ```bash
+   git pull --rebase
+   git push
+   bd dolt push
+   ```
+5. **Verify** — all changes committed AND pushed
+6. **Hand off** — provide context for next session

package/template/thoughts/AGENTS.md

@@ -0,0 +1,96 @@
+# Workflow Setup
+
+- Do not edit files outside of the ticket-plan tree of the current task
+
+The pipeline is **ticket → plan → implement → land**. This file describes the artifacts and their states. Every state transition is owned by a skill — run the skill, never flip a `Status` by hand. The one exception: approving a ticket (`draft` → `approved`) is a deliberate hand-edit by the human — that edit *is* the gate:
+
+| Skill | Transition | Gate |
+|---|---|---|
+| `/ticket <idea>` | new ticket (`draft`) | — |
+| — (hand-edit, the one exception) | ticket `draft` → `approved` | **human** |
+| `/plan <NNN>` | ticket `approved` → plan (`review`) | — |
+| `/approve <NNN>` | plan `review` → `approved`; creates beads epic + issues. Re-run on an approved plan = **amendment re-sync** | **human** |
+| `/implement <NNN>` | executes approved plan in its worktree; ends with a review verdict | — |
+| `/land <NNN>` | merge to main; plan → `merged`, ticket → `implemented` | **human** |
+| `/chore <idea>` | lightweight lane: chore ticket → worktree → gates + one review → merge, in one pass | **human** |
+| `/cancel <NNN> [plan]` | cancel the line of work (or just the plan, to re-plan); closes epic, removes worktree | **human** |
+| `/queue` | read-only dashboard: in flight, stalled, awaiting a human | — |
+| `/next` | one autonomous iteration (for `/loop`); never crosses human gates | — |
+
+**State rule:** frontmatter `Status` records the last gate an artifact passed and changes only at hand-offs. Live execution state (what is in progress *right now*) lives in beads only — look it up via the plan's `Beads Epic` id (`bd show <id>`, `bd list --status=in_progress`), never by editing frontmatter.
+
+**Chore lane:** small, low-risk changes (typo, docs, config tweak, dep bump) skip the plan: `/chore` runs the whole lane in a single human-invoked pass. If the diff outgrows ~5 files / ~150 lines, the change leaves the lane and gets a real plan.
+
+## Project Configuration
+
+> Edit this section for your project — the pipeline skills read these values.
+
+- **Targets:** `app` <!-- the areas of the repo work can land in, e.g. cms | jobs | web | utils for a monorepo, or a single name for a simple repo -->
+- **Quality gates:** `npm test` <!-- the command(s) that must pass after every implementation step, e.g. root `pnpm check` plus workspace test/typecheck scripts -->
+- **Reviewers:** general code review <!-- map targets to reviewer agents if you have them, e.g. cms|jobs|utils → backend-code-reviewer, web → frontend-code-reviewer -->
+- **Product docs:** `thoughts/docs/` <!-- where tickets ground their Summary; add your product/vision doc here -->
+- **Frontend constraints:** none <!-- e.g. "no new pages until the design system in apps/web is established; route UI design through impeccable" -->
+
+## Tickets
+
+Tickets are the originating point of most of the work in this system. They are the starting artifacts of work, laying out the ideas and overall feature/work definition to be implemented. They are *not* concrete implementations, but rather high-level descriptions of what needs to be done.
+Each ticket is a self-contained unit of work and should be able to fit into a single reviewable unit of work.
+
+- They live in [./tickets].
+
+Frontmatter Includes:
+- Status: 'draft' | 'approved' | 'implemented' | 'cancelled'
+  - `draft` → `approved` is a human decision; it makes the ticket eligible for `/plan`.
+  - `approved` → `implemented` is flipped by `/land` when the plan's worktree merges.
+- Tags: A list of tags associated with the ticket.
+- Type: 'feature' | 'bug' | 'refactor' | 'chore'
+- Target: one of the targets defined in Project Configuration above
+
+Naming Conventions:
+- {NUMBER}-{KEBAB-CASE-TITLE} / Example: `001-setup-test-harness`
+
+## Plans
+
+Plans are the concrete steps to take to complete a ticket. They are written by `/plan` based on the ticket's target and any other relevant context. If they include frontend work, they also honor the project's frontend constraints (Project Configuration) for on-brand implementation.
+
+- They live in [./plans]
+- They include an implementation plan broken down in steps. Each step carries an explicit `Depends on:` line; steps with disjoint file sets are marked parallelizable.
+- The `Depends on:` lines are the machine-readable dependency graph — they become beads issue dependencies at approval. A mermaid diagram of the step graph is optional, for human readability only.
+- Plans include a beads list. Each plan is its own beads epic.
+- Beads epics (and their step issues) are created by `/approve` when the plan is approved.
+
+**Amendments** — plans change after approval; the sanctioned path is: edit the plan file, then re-run `/approve {NNN}` to re-sync the epic. Rules:
+- Step numbers are immutable — never renumber. New steps get fresh numbers and place themselves via `Depends on:`.
+- Removed steps stay in the file, marked `~~Step N~~ — removed: <why>`.
+- Amending mid-flight is safe: a running `/implement` re-derives its issue set from beads each iteration, so added steps join its queue automatically.
+
+Frontmatter Includes:
+- Status: 'draft' | 'review' | 'approved' | 'merged' | 'cancelled'
+  - `review` = awaiting human review. `review` → `approved` only via `/approve`; `approved` → `merged` only via `/land`.
+  - There is deliberately no `in progress` status — live progress is a beads query, not frontmatter.
+- Tags: A list of tags associated with the ticket.
+- Type: 'feature' | 'bug' | 'refactor' | 'chore'
+- Target: one of the targets defined in Project Configuration above
+- Ticket Origin: The ticket that this plan is associated with
+- Beads Epic: The beads epic that this plan is associated with (set by `/approve`)
+
+Naming Conventions:
+- {NUMBER}-{TYPE-FIRST-LETTER}-{KEBAB-CASE-TITLE} / Example: `001-f-setup-test-harness`
+- The Number is always the same number as the ticket number.
+
+## Reviews
+
+Full review output is persisted verbatim to `thoughts/reviews/{NNN}-round{n}.md`, written inside the worktree during the review phase and merged to main at `/land` — the audit trail travels with the change. The machine-checked verdict (`review: APPROVED sha=...`) lives on the epic's notes; the file holds the complete findings, including NITs (fodder for later chore tickets).
+
+## Implementation
+
+Implementation is owned by `/implement` and happens only after a plan is `approved`. Its first action is claiming the epic (`bd update <epic-id> --claim`) — the concurrency mutex that keeps parallel sessions and loops off the same plan.
+
+Each plan is implemented within its own git worktree at `.worktrees/<plan-name>` (worktree and branch are both named after the plan) so it stays separate from the main branch. The branch is published immediately, and implementer subagents execute the steps in beads dependency order — one commit per step, pushed as soon as the step closes, so a crashed session strands nothing.
+After each step, the quality gates run inside the worktree: the gate commands in Project Configuration plus the target's own `test` / `typecheck` scripts where defined. A step is closed in beads only when its gates pass.
+
+`/next` schedules around declared file sets: it will not start a plan whose files overlap a plan already in flight.
+
+## After Implementation
+
+One full code review per plan, at the end (not per step — the per-step check is the mechanical gates). The reviewer is dispatched by the plan's `Target` using the reviewer mapping in Project Configuration; both lanes' reviewers if the diff spans lanes, a thorough general code review if none is configured. MUST FIX findings are fixed and re-reviewed until APPROVED; each round is persisted to `thoughts/reviews/` and the verdict is recorded on the epic's notes (`review: APPROVED sha=...`), which is the precondition `/land` checks. Merging to main is `/land`, a human gate.