runcastle 0.2.0 → 1.0.0

package/package.json

@@ -1,40 +1,34 @@
 {
   "name": "runcastle",
-  "version": "0.2.0",
-  "description": "Install and publish Sandcastle workflow packages",
-  "license": "MIT",
+  "version": "1.0.0",
   "type": "module",
   "bin": {
-    "runcastle": "./dist/index.js"
+    "runcastle": "./bin/runcastle.js"
   },
-  "files": [
-    "dist"
-  ],
   "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --clean",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "bun": ">=1.3.14"
   },
+  "files": [
+    "index.js",
+    "bin",
+    "hook-client.ts",
+    "pty-host.cjs",
+    "drizzle",
+    "skills",
+    "web",
+    "sandcastle-template"
+  ],
   "dependencies": {
-    "@clack/prompts": "^1.6.0",
-    "commander": "^15.0.0",
-    "diff": "^9.0.0",
-    "picocolors": "^1.1.1",
-    "semver": "^7.8.5",
-    "ts-morph": "^28.0.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@castellan/schema": "workspace:*",
-    "@types/diff": "^8.0.0",
-    "@types/semver": "^7.7.1",
-    "execa": "^9.6.1",
-    "msw": "^2.14.6",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.9"
+    "@ai-hero/sandcastle": "0.12.0",
+    "@hono/mcp": "0.3.1",
+    "@hono/trpc-server": "0.4.2",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@trpc/server": "11.18.0",
+    "drizzle-orm": "0.45.2",
+    "hono": "4.12.30",
+    "nanoid": "6.0.0",
+    "node-pty": "^1.1.0",
+    "simple-git": "^3.36.0",
+    "zod": "4.4.3"
   }
 }

package/pty-host.cjs

@@ -0,0 +1,186 @@
+/**
+ * PTY sidecar host (UI-SPEC §5). Run with SYSTEM `node` (not Bun) — one process
+ * per terminal — because node-pty's Windows ConPTY backend writes keystrokes to
+ * the child through a Node `net.Socket` input pipe that is unusable under Bun
+ * (write() throws `ERR_SOCKET_CLOSED`, so INPUT is silently dropped). Output
+ * works under Bun, so only WRITE is broken; running node-pty under real `node`
+ * here fixes it. The server (`pty-sidecar.ts`) spawns this and talks a
+ * newline-delimited JSON protocol over stdio; binary payloads are base64 so they
+ * can never collide with the `\n` frame delimiter.
+ *
+ * PROTOCOL
+ *   inbound  (server → host, over this process's stdin, one JSON object per line):
+ *     { t:'spawn',  file, args, opts:{ cwd, cols, rows, useConpty, env } }  // first
+ *     { t:'write',  d:<base64 utf8 keystrokes> }
+ *     { t:'resize', cols, rows }
+ *     { t:'kill' }
+ *   outbound (host → server, over this process's stdout):
+ *     { t:'ready', pid }
+ *     { t:'data',  d:<base64> }        // raw PTY output bytes
+ *     { t:'exit',  code, signal }
+ *     { t:'error', message }           // spawn/host failure (fatal)
+ *
+ * argv[2] (optional): absolute path to node-pty's entry, resolved by the server
+ * so the child never has to re-resolve it. Falls back to bare require('node-pty').
+ */
+
+'use strict'
+
+/** Emit one framed JSON line on stdout. Swallow EPIPE if the server is gone. */
+function send(obj) {
+  try {
+    process.stdout.write(JSON.stringify(obj) + '\n')
+  } catch {
+    // server detached — nothing we can do
+  }
+}
+
+/** Diagnostics go to stderr so they never corrupt the stdout protocol stream. */
+function log(msg) {
+  try {
+    process.stderr.write(`[pty-host] ${msg}\n`)
+  } catch {
+    /* ignore */
+  }
+}
+
+function loadNodePty() {
+  const explicit = process.argv[2]
+  if (explicit) {
+    try {
+      return require(explicit)
+    } catch (e) {
+      log(`require(${explicit}) failed: ${e && e.message}; falling back to bare specifier`)
+    }
+  }
+  return require('node-pty')
+}
+
+let proc = null
+let spawned = false
+
+function handleSpawn(msg) {
+  if (spawned) {
+    log('ignoring second spawn message')
+    return
+  }
+  spawned = true
+  let pty
+  try {
+    pty = loadNodePty()
+  } catch (e) {
+    send({ t: 'error', message: `failed to load node-pty: ${e && e.message}` })
+    process.exit(1)
+    return
+  }
+
+  const opts = msg.opts || {}
+  const env = {}
+  const src = opts.env || process.env
+  for (const k of Object.keys(src)) {
+    if (typeof src[k] === 'string') env[k] = src[k]
+  }
+
+  try {
+    proc = pty.spawn(msg.file, msg.args || [], {
+      name: 'xterm-256color',
+      cols: Math.max(1, opts.cols || 80),
+      rows: Math.max(1, opts.rows || 24),
+      cwd: opts.cwd,
+      env,
+      useConpty: opts.useConpty !== false,
+    })
+  } catch (e) {
+    send({ t: 'error', message: `spawn failed: ${e && e.message}` })
+    process.exit(1)
+    return
+  }
+
+  send({ t: 'ready', pid: proc.pid })
+
+  proc.onData((d) => {
+    const buf = typeof d === 'string' ? Buffer.from(d, 'utf8') : d
+    send({ t: 'data', d: buf.toString('base64') })
+  })
+
+  proc.onExit((e) => {
+    send({ t: 'exit', code: e && typeof e.exitCode === 'number' ? e.exitCode : 0, signal: (e && e.signal) || null })
+    // Give stdout a tick to flush the framed exit line before we go.
+    setTimeout(() => process.exit(0), 20)
+  })
+}
+
+function handle(msg) {
+  switch (msg && msg.t) {
+    case 'spawn':
+      handleSpawn(msg)
+      break
+    case 'write':
+      if (proc && typeof msg.d === 'string') {
+        try {
+          proc.write(Buffer.from(msg.d, 'base64').toString('utf8'))
+        } catch (e) {
+          log(`write failed: ${e && e.message}`)
+        }
+      }
+      break
+    case 'resize':
+      if (proc && typeof msg.cols === 'number' && typeof msg.rows === 'number') {
+        try {
+          proc.resize(Math.max(1, msg.cols), Math.max(1, msg.rows))
+        } catch (e) {
+          log(`resize failed: ${e && e.message}`)
+        }
+      }
+      break
+    case 'kill':
+      if (proc) {
+        try {
+          proc.kill()
+        } catch {
+          /* already gone */
+        }
+      }
+      break
+    default:
+      log(`unknown message: ${JSON.stringify(msg)}`)
+  }
+}
+
+// --- stdin line reader (newline-delimited JSON) ------------------------------
+let acc = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  acc += chunk
+  let nl
+  while ((nl = acc.indexOf('\n')) !== -1) {
+    const line = acc.slice(0, nl)
+    acc = acc.slice(nl + 1)
+    if (!line) continue
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch (e) {
+      log(`bad JSON line: ${e && e.message}`)
+      continue
+    }
+    handle(msg)
+  }
+})
+
+// When the server closes our stdin (it detached / crashed), tear down the child.
+process.stdin.on('end', () => {
+  if (proc) {
+    try {
+      proc.kill()
+    } catch {
+      /* ignore */
+    }
+  }
+  process.exit(0)
+})
+
+process.on('uncaughtException', (e) => {
+  send({ t: 'error', message: `uncaught: ${e && e.message}` })
+  process.exit(1)
+})

package/sandcastle-template/Containerfile

@@ -0,0 +1,33 @@
+# Generic runcastle AFK burner image — Bun + Node + git toolchain for unattended agents.
+# runcastle scaffolds this into a build context on demand (issue #50); nothing
+# runcastle-specific is baked in — per-project deps install at sandbox start via the
+# project's own .sandcastle config. Generalized from this repo's dogfood .sandcastle
+# Dockerfile. Both `docker build` and `podman build` use the enclosing dir as the
+# build context; the image tag is passed by the caller (--image-name), never derived.
+FROM node:22-bookworm
+
+# Toolchain: git (worktrees/commits), curl (installers), jq, plus common unpack deps.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git curl ca-certificates jq unzip \
+  && rm -rf /var/lib/apt/lists/*
+
+# Bun (the agent toolchain default) — installed system-wide before the user switch.
+ENV BUN_INSTALL=/usr/local
+RUN curl -fsSL https://bun.sh/install | bash
+
+# Rootless-podman invariant (research #32): the in-container agent user MUST be at
+# UID/GID 1000 so bind-mounted host files share an owner. Sandcastle passes the host
+# uid/gid as build args (defaulting here to 1000); rename the stock `node` user to match.
+ARG AGENT_UID=1000
+ARG AGENT_GID=1000
+RUN groupmod -o -g "$AGENT_GID" node \
+  && usermod -o -u "$AGENT_UID" -g "$AGENT_GID" -d /home/agent -m -l agent node
+USER ${AGENT_UID}:${AGENT_GID}
+
+# Claude Code CLI (the agent runtime) — authenticated at runtime via CLAUDE_CODE_OAUTH_TOKEN.
+RUN curl -fsSL https://claude.ai/install.sh | bash
+ENV PATH="/home/agent/.local/bin:$PATH"
+
+# Sandcastle bind-mounts the git worktree here and runs the agent in it.
+WORKDIR /home/agent/workspace
+ENTRYPOINT ["sleep", "infinity"]

package/sandcastle-template/Dockerfile

@@ -0,0 +1,33 @@
+# Generic runcastle AFK burner image — Bun + Node + git toolchain for unattended agents.
+# runcastle scaffolds this into a build context on demand (issue #50); nothing
+# runcastle-specific is baked in — per-project deps install at sandbox start via the
+# project's own .sandcastle config. Generalized from this repo's dogfood .sandcastle
+# Dockerfile. Both `docker build` and `podman build` use the enclosing dir as the
+# build context; the image tag is passed by the caller (--image-name), never derived.
+FROM node:22-bookworm
+
+# Toolchain: git (worktrees/commits), curl (installers), jq, plus common unpack deps.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git curl ca-certificates jq unzip \
+  && rm -rf /var/lib/apt/lists/*
+
+# Bun (the agent toolchain default) — installed system-wide before the user switch.
+ENV BUN_INSTALL=/usr/local
+RUN curl -fsSL https://bun.sh/install | bash
+
+# Rootless-podman invariant (research #32): the in-container agent user MUST be at
+# UID/GID 1000 so bind-mounted host files share an owner. Sandcastle passes the host
+# uid/gid as build args (defaulting here to 1000); rename the stock `node` user to match.
+ARG AGENT_UID=1000
+ARG AGENT_GID=1000
+RUN groupmod -o -g "$AGENT_GID" node \
+  && usermod -o -u "$AGENT_UID" -g "$AGENT_GID" -d /home/agent -m -l agent node
+USER ${AGENT_UID}:${AGENT_GID}
+
+# Claude Code CLI (the agent runtime) — authenticated at runtime via CLAUDE_CODE_OAUTH_TOKEN.
+RUN curl -fsSL https://claude.ai/install.sh | bash
+ENV PATH="/home/agent/.local/bin:$PATH"
+
+# Sandcastle bind-mounts the git worktree here and runs the agent in it.
+WORKDIR /home/agent/workspace
+ENTRYPOINT ["sleep", "infinity"]

package/skills/burner/implement-ticket.md

@@ -0,0 +1,42 @@
+<!-- Forked from Matt Pocock's implement + tdd + code-review skills, 2026-07-14, adapted for runcastle's unattended burner. Rendered per ticket; the placeholder tokens are filled in by the ticket-burner workflow. -->
+
+# Implement this ticket — unattended
+
+You are a single agent in a sandbox on branch `feature/<slug>`. You have **one ticket**. There is **no human to ask** — no follow-up questions are possible. Everything you need is in this prompt and in the repo. Work carefully, commit only green work, and stop when the ticket is done.
+
+## The ticket
+
+```json
+{{TICKET_JSON}}
+```
+
+## Feature context
+
+{{FEATURE_BRIEF}}
+
+## Feature docs (spec / decisions digest)
+
+{{DOCS_DIGEST}}
+
+## How to work
+
+1. **Orient.** Read the ticket's `goal`, `context`, `acceptanceCriteria`, and `seams`. Read the files its `context` names and the existing patterns it points to. Match the conventions of the surrounding code — you are extending this codebase, not starting a new one.
+
+2. **Test at the seams (forked tdd).** The ticket's `seams` are the public interfaces to test at — test *there*, at the boundary where behaviour is observable, never against internals or private helpers. A good test reads like a spec ("user can X"), uses the public API only, and survives refactors. Mock only true system boundaries (network, clock, external services); never mock your own modules.
+
+3. **Red → green, one criterion at a time.** Where a test framework exists in the repo: for each acceptance criterion, write the failing test at the seam first, then the minimal code to pass it, then move on. One slice per cycle — do not bulk-write tests for imagined behaviour, and do not recompute the expected value the way the code does (use known-good literals). Where the repo has **no** test framework: verify each criterion by actually running the code / driving the demoable path, and state what you ran.
+
+4. **Guard every commit.** Before each commit, run typecheck and the relevant tests (the full suite at least once at the end). **Never commit red.** Commit in small logical steps using the convention:
+
+   `{{COMMIT_CONVENTION}}`
+
+5. **Self-review before you finish (forked code-review — two axes).** When all acceptance criteria pass, review your own diff along both axes, then fix what you find and re-run typecheck + tests:
+   - **Standards** — does the diff follow the conventions of the surrounding code? Watch for the smells: duplicated logic (extract it), mysterious names (rename), primitive obsession (give the concept a type), speculative generality (delete anything the ticket did not ask for), feature envy, data clumps.
+   - **Spec = this ticket** — is every acceptance criterion actually met, and is there **nothing in the diff the ticket did not ask for**? Missing and extra both count.
+   Commit the fixes.
+
+## Hard rules
+
+- **Never expand scope beyond the ticket.** If you notice adjacent work, worthwhile refactors, or another ticket's territory, leave it. Note it in your final commit body if it matters; do not do it.
+- **No questions, no guessing into the void.** Resolve ambiguity from the ticket context and the code. If two readings both satisfy the acceptance criteria, take the smaller one.
+- **If genuinely blocked** (a dependency ticket's output is not there, the environment fails, or a requirement truly cannot be resolved from context + code): **commit nothing for the blocked part**, write `BLOCKED.md` at the repo root stating precisely what blocked you and what is needed to unblock, and stop. Green, complete parts may still be committed; the blocked part must not be. The orchestrator reads your exit state from the commits — a part with no commits is read as not done.

package/skills/burner/research-waypoint.md

@@ -0,0 +1,45 @@
+<!-- Forked from Matt Pocock's research + grilling skills, 2026-07-15, adapted for runcastle's unattended research-waypoint runner (SPEC §13.2). Rendered per research waypoint; the placeholder tokens are filled in by the research workflow. -->
+
+# Research this waypoint — unattended
+
+You are a single agent in a sandbox on branch `feature/<slug>`. You have **one research question**. There is **no human to ask** — no follow-up questions are possible. Everything you need is in this prompt, on the web, and in the repo. Research carefully, write one focused summary, commit it, and stop.
+
+## The waypoint
+
+```json
+{{WAYPOINT_JSON}}
+```
+
+## Feature context
+
+{{FEATURE_BRIEF}}
+
+## Feature docs (spec / decisions digest)
+
+{{DOCS_DIGEST}}
+
+## How to work
+
+1. **Understand the question.** Read the waypoint's `title` and `question`. This is a *research* node: its job is to produce a well-sourced answer that later ideation/spec sessions can build on — not to change product code.
+
+2. **Research web + repo.** Search the web for authoritative, current sources (official docs, primary references, well-regarded write-ups) and read the parts of *this* repo the question bears on. Prefer primary sources; note version/date where it matters. Reconcile conflicts rather than papering over them.
+
+3. **Write ONE summary doc** at exactly:
+
+   `{{RESEARCH_DOC_PATH}}`
+
+   Create the `research/` directory if it does not exist. The doc is the deliverable — structure it so a reader who never saw this prompt can act on it:
+   - a one-line **answer** up top,
+   - the **findings** with reasoning,
+   - a short **sources** list (links/titles), and
+   - any **open questions** the research could not close.
+
+   Keep it tight and honest. If the question cannot be answered from available material, say so plainly in the doc and record what would be needed.
+
+4. **Commit the doc to the feature branch.** Stage only your new/changed doc under `docs/features/<slug>/` and commit with a clear message, e.g. `research(<seq>): <summary>`. The run reads your exit state from the commit — **a doc with no commit is read as no research landed.**
+
+## Hard rules
+
+- **Stay in scope.** Answer this one question. Do not touch product code, other docs, or other waypoints' territory. If you surface adjacent questions worth their own waypoint, note them in the doc's *open questions* — do not chase them.
+- **No questions, no guessing into the void.** Resolve ambiguity from the question, the feature docs, and reputable sources. If two readings both fit, take the narrower one and say which you took.
+- **Cite what you rely on.** Every non-obvious claim in the summary should trace to a source or to code you read.

package/skills/packs/README.md

@@ -0,0 +1,50 @@
+# Skill packs
+
+**Packs** are runcastle-owned Claude Code *plugin directories* — vendored, adapted forks of Matt Pocock's methodology skills, wired to runcastle's MCP contracts. They are injected into each launched terminal via `--plugin-dir`, so the human's Claude Code needs nothing preinstalled, and upstream changes to Matt's skills can never break us. (Every fork keeps a provenance header crediting the original.)
+
+## The `runcastle` pack
+
+Four phase-scoped skills, each namespaced `/runcastle:<skill>`:
+
+| Skill | Invoked | Does |
+|---|---|---|
+| `/runcastle:ideate` | entry for `kind=ideation` | grills the human, locks decisions incrementally, drives spec + tickets out of one unbroken window |
+| `/runcastle:spec` | by ideate (size=full) | synthesizes `spec.md`, completes the `spec` phase |
+| `/runcastle:tickets` | by ideate | emits tracer-bullet tickets via MCP, completes the `tickets` phase |
+| `/runcastle:qa` | entry for `kind=qa` | read-only Q&A over an existing feature; never advances phases |
+
+Layout (the verified plugin format — only `plugin.json` lives inside `.claude-plugin/`; `skills/` is a sibling at the plugin root):
+
+```text
+packs/
+├── README.md
+└── runcastle/
+    ├── .claude-plugin/
+    │   └── plugin.json        # name: "runcastle" → sets the /runcastle: namespace
+    └── skills/
+        ├── ideate/SKILL.md
+        ├── spec/SKILL.md
+        ├── tickets/SKILL.md
+        └── qa/SKILL.md
+```
+
+## How the launcher consumes a pack
+
+The session launcher spawns Claude Code with the pack's **root** directory (the folder that directly contains `.claude-plugin/`) passed to `--plugin-dir`:
+
+```bash
+claude ... --plugin-dir "<abs path>/packages/skills/packs/runcastle" ...
+```
+
+The `name` field in `plugin.json` becomes the invocation namespace, so the skills resolve as `/runcastle:ideate` and friends. The injected system prompt tells each session which entry skill to invoke for its kind (`/runcastle:ideate` for ideation, `/runcastle:qa` for Q&A). All four skills carry `disable-model-invocation: false`, so the model may also reach for them by description.
+
+## Adding a pack
+
+1. Create `packs/<pack-name>/.claude-plugin/plugin.json` with at least `{ "name": "<pack-name>" }` — `name` sets the `/<pack-name>:` namespace.
+2. Add skills at `packs/<pack-name>/skills/<skill>/SKILL.md` (folder name = skill name; frontmatter needs `description` + `disable-model-invocation`).
+3. If you are forking an upstream skill, keep the provenance header and rewire its steps to runcastle's MCP tools (`get_feature_context`, `emit_tickets`, `record_event`, `complete_phase`).
+4. Pass another `--plugin-dir` for it at launch.
+
+## Not a pack: `../burner/`
+
+The sibling `packages/skills/burner/` holds **prompt templates**, not skills — e.g. `implement-ticket.md`, rendered per ticket by the AFK ticket-burner workflow (placeholders `{{TICKET_JSON}}`, `{{FEATURE_BRIEF}}`, `{{DOCS_DIGEST}}`, `{{COMMIT_CONVENTION}}`). It is never passed to `--plugin-dir`.

package/skills/packs/runcastle/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "runcastle",
+  "description": "Runcastle phase-scoped skills — forks of Matt Pocock's grilling, to-spec, and to-tickets adapted to runcastle's MCP feature pipeline (ideate, spec, tickets, qa).",
+  "version": "0.1.0",
+  "author": { "name": "runcastle" }
+}

package/skills/packs/runcastle/skills/converge/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: converge
+description: Close a mapped feature. Read ONLY the compressed knowledge (map.md + decisions.md, never the waypoint transcripts), then drive spec and tickets out of that one unbroken window. Entry skill for kind=converge sessions.
+disable-model-invocation: false
+---
+<!-- Forked from Matt Pocock's grilling/to-spec/to-tickets discipline, via https://github.com/mattpocock/skills, 2026-07-15, adapted for runcastle mapped ideation -->
+
+# Converge — close a mapped feature
+
+A mapped feature was too big for one window, so it was charted into a map and its waypoints were worked in their own sessions. Every waypoint is now terminal, the human clicked **Converge**, and the feature has already crossed G1 into the `spec` phase (or `tickets` for a `collapsed` feature). Your job: turn the compressed knowledge into a spec and tickets — the exact output an unbroken ideation session produces.
+
+## Context hygiene is the whole game
+
+Everything happens in this one window. **Never compact. Never `/clear`. Never suggest either.** The map plus the decisions ARE the compression — that is the whole point of charting a map. Read them once, hold them, and let spec and tickets fall out of the same conversation.
+
+## 0. Read ONLY the compressed knowledge
+
+1. Call `mcp__runcastle__get_feature_context`. It returns the feature (`slug`, `title`, `oneLiner`, `size`), current `phase`, and the docs on disk.
+2. Read **only** these two files under `docs/features/<slug>/`:
+   - `map.md` — the destination, notes, and out-of-scope decisions.
+   - `decisions.md` — every decision the waypoint sessions locked.
+   **Do NOT read the waypoint session transcripts.** The map and decisions are the compression; trust them. If a decision is genuinely missing you may check the codebase for a *fact*, but never re-grill the human and never reopen a resolved waypoint — converge, do not re-ideate.
+3. `mcp__runcastle__record_event({ type: "converge.started", message: "<feature title>" })`.
+
+## 1. Size branch — run the pipeline in this window
+
+Read `feature.size` from step 0:
+
+- **`full`** → invoke `/runcastle:spec` (it writes `spec.md` and completes the `spec` phase); when it returns, invoke `/runcastle:tickets`.
+- **`collapsed`** → skip spec entirely; invoke `/runcastle:tickets` directly (it works from `decisions.md` + `map.md`).
+
+**Re-convergence** — you may be a fresh session continuing a converge that crashed
+or was closed mid-way (the feature is past G1 but has no tickets). Pick up from
+whatever already exists on disk:
+
+- If `docs/features/<slug>/spec.md` **already exists**: read it, do **not**
+  rewrite it, and proceed straight to `/runcastle:tickets`. (If the current
+  `phase` is still `spec`, call `complete_phase` for spec first — the spec work
+  is already done.)
+- If it does not exist (or the feature is `collapsed`), run the size branch
+  above as normal.
+
+Do not open a new session for these. They run here, on top of the compressed knowledge you just read.
+
+## 2. Close — hand off to the human
+
+`/runcastle:tickets` ends by emitting tickets to the runcastle store. When it returns, your job is **done**. Tell the human plainly:
+
+> Converged. Tickets are in the runcastle UI — review the ticket cards and click **Burn** to start the AFK agents. I'll stop here.
+
+Do **not** implement anything. Do **not** start burning. The two human clicks (Burn, then Merge after test-drive) are the only gates left, and they belong to the human.

package/skills/packs/runcastle/skills/ideate/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ideate
+description: The runcastle ideation session. Grill the human relentlessly about a feature, lock decisions incrementally into decisions.md, then drive spec and tickets out of the same unbroken context. Entry skill for kind=ideation sessions.
+disable-model-invocation: false
+---
+<!-- Forked from Matt Pocock's grilling + grill-with-docs skills, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
+
+# Ideate — runcastle's ideation session
+
+You are the front of the runcastle pipeline. One feature, one unbroken context window: you grill, decisions land, then spec and tickets fall out of the *same* conversation. After you, the human's only job is to click **Burn**. Do it right.
+
+## Context hygiene is the whole game
+
+Everything happens in this one window. **Never compact. Never `/clear`. Never suggest either.** Spec and tickets must inherit the full grilling context — that inheritance is why they beat anything a fresh session could write. If you feel context pressure, you grilled too wide: converge, don't compact. (Matt Pocock's rule; it is load-bearing here.)
+
+## 0. Orient
+
+1. Call `mcp__runcastle__get_feature_context`. It returns the feature (`slug`, `title`, `oneLiner`, `size`), current `phase`, the docs already on disk (`brief.md`, and any `decisions.md` — **this may be a resumed session; read what is already locked and do not re-ask it**), and any tickets.
+2. Decisions live at `docs/features/<slug>/decisions.md` in this worktree. The injected system prompt carries the slug and paths; trust `get_feature_context` for the live state.
+3. `mcp__runcastle__record_event({ type: "ideation.started", message: "<feature title>" })`.
+
+## 1. Grill relentlessly
+
+Interview the human about every aspect of the feature until you reach a genuinely shared understanding. Walk each branch of the design tree, resolving dependencies between decisions one at a time.
+
+- **One question at a time.** Wait for the answer before the next. Asking several at once is bewildering.
+- **Always recommend an answer.** Never ask a bare question — put your recommended answer to it and say why. The human corrects or confirms.
+- **Look up facts; ask only for decisions.** If a fact is discoverable in the codebase — how something currently works, what a type looks like, whether a pattern already exists — read/grep the repo and find it. Never make the human be your grep. *Decisions* are theirs: put each one to them and wait.
+- **Model the domain as you go** (forked from domain-modeling): challenge terms that conflict with existing usage, sharpen fuzzy words to one canonical meaning ("you said 'account' — Customer or User?"), invent concrete edge-case scenarios that force precision, and cross-check claims against the actual code ("your code cancels whole Orders, but you just said partial — which is right?").
+
+Do not move on until the human confirms you have reached shared understanding.
+
+## 2. Lock decisions incrementally
+
+The moment a decision locks, append it to `docs/features/<slug>/decisions.md` — **immediately, one at a time, never batched at the end.** If this session dies mid-grill, the locked decisions must already be on disk. Append entries in this shape:
+
+```markdown
+## <n>. <short decision title>
+**Decision:** <the choice, in the project's domain vocabulary>
+**Why:** <the reason / the trade-off chosen over the alternatives>
+```
+
+Keep `decisions.md` free of implementation minutiae — it is the record of *what was decided and why*, the raw material spec and tickets are built from. `complete_phase` checkpoints the file into git for you; you just write it.
+
+Every few locked decisions, `mcp__runcastle__record_event({ type: "decision.locked", message: "<n> decisions locked" })`.
+
+## 3. Escalation branch — when the feature outgrows this window
+
+Some features are too big for one unbroken context. The tells: you are rabbit-holing into one corner while whole branches sit untouched; decisions keep hanging on material nobody has read yet (a prototype to build, a dependency to research, an area to grill on its own); the design tree has grown wider than you can hold and converge in this session. When that happens, **do not compact and do not grind on** — chart a map instead:
+
+1. `mcp__runcastle__escalate_to_map({ destination: "<the one-line north star>", notes: "<what's locked / constraints so far>" })`. This flips the feature to *mapped* and scaffolds `docs/features/<slug>/map.md`. If it warns that the feature is already mapped, that is fine — the map already exists; just proceed to chart the first batch.
+2. `mcp__runcastle__emit_waypoints({ waypoints: [...] })` for the **first batch** — the questions worth branching now. Each waypoint: `title`, `type` (`grilling` | `research` | `prototype` | `task`), `question` (what that session must answer), and `blockedBy` (1-based positions within this batch, and/or ids of already-stored waypoints) for ordering. Charting the first frontier is enough; later sessions branch the map further (any mapped session may `emit_waypoints`).
+3. `mcp__runcastle__record_event({ type: "map.charted", message: "<n> waypoints charted" })`.
+4. Tell the human plainly:
+
+   > This feature is bigger than one session. I've charted it into a map — its first waypoints are in the runcastle UI. Work them from there (each opens its own session); converge when the frontier clears. I'll stop here.
+
+5. **End the session.** Charting is one session's work — do **not** claim or work a waypoint yourself (claiming is never agent-driven), and do **not** carry on grilling. Stop.
+
+## 4. Converge
+
+When the human confirms shared understanding and the open questions are answered or explicitly deferred:
+
+`mcp__runcastle__complete_phase({ phase: "ideation" })` → returns `{ ok, nextPhase }`. If `ok: false`, it names what the gate wants (e.g. `decisions.md` missing) — fix it and retry. Then `record_event({ type: "phase.completed", message: "ideation" })`.
+
+## 5. Size branch — stay in this window
+
+Read `feature.size` from step 0:
+
+- **`full`** → invoke `/runcastle:spec` (it writes `spec.md` and completes the `spec` phase); when it returns, invoke `/runcastle:tickets`.
+- **`collapsed`** → skip spec entirely; invoke `/runcastle:tickets` directly (it works from `decisions.md`).
+
+Do not open a new session for these. They run here, on top of everything you just learned.
+
+## 6. Close — hand off to the human
+
+`/runcastle:tickets` ends by emitting tickets to the runcastle store. When it returns, your job is **done**. Tell the human plainly:
+
+> Tickets are in the runcastle UI. Review the ticket cards and click **Burn** to start the AFK agents. That is the next step — I will stop here.
+
+Do **not** implement anything. Do **not** start burning. The two human clicks (Burn, then Merge after test-drive) are the only gates left, and they belong to the human.

package/skills/packs/runcastle/skills/qa/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: qa
+description: Answer questions about an existing (possibly shipped) feature from its docs and the codebase. Read-only — never advances phases, never emits tickets. Entry skill for kind=qa sessions.
+disable-model-invocation: false
+---
+<!-- Forked from Matt Pocock's grilling + domain-modeling skills, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
+
+# Q&A
+
+This is a "come back and ask questions" session about a feature that already exists — often already shipped. Your job is to **answer**, accurately, from the record. Nothing here changes state.
+
+## Do
+
+- Call `mcp__runcastle__get_feature_context` first: it returns the feature, its phase, and all docs under `docs/features/<slug>/` (brief, decisions, spec). That, plus the codebase, is your source of truth.
+- Answer from the docs and the actual code. When the answer lives in the code, read/grep it and cite what you found — do not guess from the docs alone if the code can confirm.
+- When something notable surfaces that the record should keep (a clarification, a discovered discrepancy between docs and code), you MAY log it: `mcp__runcastle__record_event({ type: "qa.note", message: "..." })`.
+
+## Do NOT
+
+- **Never advance a phase.** No `complete_phase`. This session has no gates to cross.
+- **Never emit tickets.** No `emit_tickets`.
+- **Never implement changes** to the feature.
+
+## When the human wants a change
+
+A Q&A session is the wrong place to change the feature. If the conversation turns into "let's change X" or "this is a bug, fix it," name it and point them at the right move:
+
+> That is a change, not a question — it needs its own feature. Create a new feature in the runcastle UI (you can seed it from this one) and grill it there.
+
+Then, if useful, `record_event` a one-line note capturing the change request so it is not lost.