@rallycry/conveyor-skills 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @rallycry/conveyor-skills
+
+Shared [Claude Code skills](https://code.claude.com/docs) for projects managed
+with [Conveyor](https://github.com/rallycry/conveyor). Installing this package
+and linking it once gives every Claude Code session in your repo the Conveyor
+workflow skills (`/conveyor-plan`, `/conveyor-local-loop`, …), and updates
+arrive through normal dependency bumps — no git submodules, no manual syncing.
+
+## Install (once per repo)
+
+```bash
+bun add -d @rallycry/conveyor-skills     # or: pnpm add -D / npm i -D
+bunx conveyor-skills link                # or: pnpm exec / npx conveyor-skills link
+```
+
+Then make it stick:
+
+1. **Add the link step to your root `package.json` `prepare` script** so every
+   install refreshes the links (new skills in a version bump appear
+   automatically; `prepare` runs at the end of every `bun install` — nobody
+   ever runs it by hand):
+
+   ```jsonc
+   { "scripts": { "prepare": "conveyor-skills link" } }
+   ```
+
+   If you already have a `prepare` script, chain it: `"husky && conveyor-skills link"`.
+
+2. **Commit the symlinks** it created in `.claude/skills/`. They point into
+   `node_modules`, so on a fresh clone they are briefly broken — Claude Code
+   silently ignores broken symlinks — and come alive as soon as the first
+   install finishes. Committing them means CI agents and teammates get the
+   skills with zero extra setup.
+
+## How updates flow
+
+Skill content is read live from `node_modules`, so any dependency bump
+(`bun update @rallycry/conveyor-skills`, Renovate/Dependabot, a `^` range
+refresh) updates the skills with no further action. Re-linking is only needed
+when a version adds or removes a skill — which the `prepare` hook already
+covers.
+
+## What `link` does (and won't do)
+
+`conveyor-skills link` writes one relative symlink per skill into
+`<repo>/.claude/skills/`, pointing at the stable
+`node_modules/@rallycry/conveyor-skills/skills/<name>` path. It is idempotent
+and safe:
+
+- It only ever replaces or prunes symlinks it owns (target contains
+  `conveyor-skills/skills/`).
+- A real directory or a foreign symlink with the same name is left alone with
+  a warning — your local skills always win.
+- `conveyor-skills link --check` verifies the links without changing anything
+  (exit 1 when out of date) — useful in CI.
+
+## Versioning
+
+Versions are cut automatically from git tags on the Conveyor repo's `main`
+branch (`conveyor-skills-v<semver>`); every shipped-source change publishes a
+patch release. Consume with a `^` range and bump like any other dependency.

package/bin/cli.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// conveyor-skills — link this package's Claude Code skills into a consumer
+// repo's .claude/skills/ as relative symlinks. Claude Code follows symlinks
+// there and silently skips broken ones, so the links are safe to commit: they
+// are dead on a fresh clone and come alive after the first install.
+//
+// Usage:
+//   conveyor-skills link      (default) create/refresh links, prune stale ones
+//   conveyor-skills link --check   verify links; exit 1 if missing/stale
+//
+// Only links owned by this package (target path contains conveyor-skills/skills/)
+// are ever replaced or pruned. Real directories and foreign symlinks are left
+// alone with a warning.
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+
+const OWNED_MARKER = `conveyor-skills${sep}skills${sep}`;
+
+function fail(msg) {
+  process.stderr.write(`conveyor-skills: ${msg}\n`);
+  process.exit(1);
+}
+
+function warn(msg) {
+  process.stderr.write(`conveyor-skills: warning: ${msg}\n`);
+}
+
+/** Nearest ancestor of cwd that looks like a repo root (.git first, then package.json). */
+function findRepoRoot(startDir) {
+  for (const marker of [".git", "package.json"]) {
+    let dir = startDir;
+    for (;;) {
+      if (existsSync(join(dir, marker))) return dir;
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function ownedBy(linkPath) {
+  try {
+    return readlinkSync(linkPath).split("/").join(sep).includes(OWNED_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+const args = process.argv.slice(2);
+const checkOnly = args.includes("--check");
+const command = args.find((a) => !a.startsWith("-")) ?? "link";
+if (command !== "link")
+  fail(`unknown command '${command}' — only 'link' (with optional --check) exists`);
+
+// This package's own skills/ dir, resolved through any install symlink (bun
+// may install the package as a symlink into its store).
+const packageDir = realpathSync(dirname(dirname(fileURLToPath(import.meta.url))));
+const sourceSkillsDir = join(packageDir, "skills");
+if (!existsSync(sourceSkillsDir))
+  fail(`no skills directory at ${sourceSkillsDir} (broken install?)`);
+
+const repoRoot = findRepoRoot(process.cwd());
+if (!repoRoot)
+  fail("could not find a repo root (.git or package.json) above the current directory");
+
+const linkDir = join(repoRoot, ".claude", "skills");
+
+// Prefer the stable node_modules path as the link target so committed links
+// never embed package-store hashes; fall back to the real package location
+// (the monorepo dogfood case resolves to the same node_modules path).
+const stableSkillsDir = join(repoRoot, "node_modules", "@rallycry", "conveyor-skills", "skills");
+const targetSkillsDir = existsSync(stableSkillsDir) ? stableSkillsDir : sourceSkillsDir;
+
+const skillNames = readdirSync(sourceSkillsDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => entry.name)
+  .sort();
+if (skillNames.length === 0) fail(`no skills found in ${sourceSkillsDir}`);
+
+let problems = 0;
+let linked = 0;
+let pruned = 0;
+
+if (!checkOnly) {
+  try {
+    mkdirSync(linkDir, { recursive: true });
+  } catch (err) {
+    fail(`cannot create ${linkDir}: ${err?.message ?? err}`);
+  }
+}
+
+for (const name of skillNames) {
+  const linkPath = join(linkDir, name);
+  const desiredTarget = relative(linkDir, join(targetSkillsDir, name));
+
+  const linkExists = isSymlink(linkPath);
+  const upToDate = linkExists && readlinkSync(linkPath) === desiredTarget;
+
+  if (upToDate) continue;
+
+  if (checkOnly) {
+    warn(`link for '${name}' is ${linkExists ? "stale" : "missing"}`);
+    problems += 1;
+    continue;
+  }
+
+  if (existsSync(linkPath) && !linkExists) {
+    warn(`${linkPath} exists and is not a symlink — leaving it alone`);
+    continue;
+  }
+  if (linkExists && !ownedBy(linkPath)) {
+    warn(
+      `${linkPath} is a symlink owned by something else (${readlinkSync(linkPath)}) — leaving it alone`,
+    );
+    continue;
+  }
+
+  try {
+    rmSync(linkPath, { force: true });
+    symlinkSync(desiredTarget, linkPath);
+    linked += 1;
+    process.stdout.write(`linked .claude/skills/${name} -> ${desiredTarget}\n`);
+  } catch (err) {
+    // Symlink-hostile filesystems (e.g. Windows without developer mode) get a
+    // warning, not a broken install.
+    warn(`could not link '${name}': ${err?.message ?? err}`);
+  }
+}
+
+// Prune owned links whose skill no longer ships in the package.
+if (existsSync(linkDir)) {
+  for (const entry of readdirSync(linkDir)) {
+    const linkPath = join(linkDir, entry);
+    if (skillNames.includes(entry) || !isSymlink(linkPath) || !ownedBy(linkPath)) continue;
+    if (checkOnly) {
+      warn(`link for removed skill '${entry}' still present`);
+      problems += 1;
+      continue;
+    }
+    try {
+      rmSync(linkPath);
+      pruned += 1;
+      process.stdout.write(`pruned stale link .claude/skills/${entry}\n`);
+    } catch (err) {
+      warn(`could not prune '${entry}': ${err?.message ?? err}`);
+    }
+  }
+}
+
+if (checkOnly) {
+  if (problems > 0) fail(`${problems} link(s) out of date — run 'conveyor-skills link'`);
+  process.stdout.write(`conveyor-skills: all ${skillNames.length} links up to date\n`);
+} else {
+  const relLinkDir = relative(repoRoot, linkDir) || linkDir;
+  process.stdout.write(
+    `conveyor-skills: ${skillNames.length} skill(s) in ${relLinkDir} (${linked} updated, ${pruned} pruned)\n`,
+  );
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@rallycry/conveyor-skills",
+  "version": "0.1.0",
+  "description": "Shared Claude Code skills for Conveyor consumer repos, linked into .claude/skills via the conveyor-skills CLI",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "conveyor",
+    "skills"
+  ],
+  "license": "MIT",
+  "bin": {
+    "conveyor-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/conveyor-local-loop/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: conveyor-local-loop
+description: Run this machine as a serial local claudespace — pick the session owner's highest-priority Open Conveyor card, claim it, execute its plan to the PR finish line, repeat. One invocation = one iteration; run continuously with "/loop /conveyor-local-loop" (no interval) and it self-paces (~1-2 min between cards while the queue has work, ~25 min idle polls when empty). Use when the user says "/conveyor-local-loop", "start the local loop", "work my open cards locally", or wants planned cards executed with full local CPU/RAM instead of spawning claudespaces.
+---
+
+# Conveyor Local Loop
+
+Turn a queue of researched Open cards (usually authored via `/conveyor-plan`)
+into review-ready PRs using this machine, one card at a time. Behave exactly as
+a claudespace agent would: the card IS the spec, task chat is the log, and the
+host repo's CLAUDE.md governs gates, verification, and PR mechanics. This skill
+adds only selection, claiming, cadence, and local-machine hygiene.
+
+## Ground rules
+
+- **Conveyor is the state store.** The loop session spans days and gets
+  compacted; at each iteration re-derive state from MCP reads, never from
+  conversation memory.
+- **All Conveyor tools fully-qualified** (`mcp__conveyor__get_task`; bare names
+  fail).
+- **WIP = 1.** At most one card claimed by this loop at a time.
+- **Never `start_task`** — that boots a cloud pod and duplicates the work. Only
+  exception: the opt-in offload valve below.
+- **Never approve or merge your own PRs.** Finish line = card in ReviewPR with
+  green CI; the user takes it from there.
+- **Only cards created by the session owner** (match against
+  `mcp__conveyor__get_connection_context`), status Open, unassigned. Teammates'
+  cards and pod-claimed cards are off limits.
+- **Pack cards: parents never; children only while the pack is parked.** A
+  card with children is the coordinator itself — never claimable. A card with
+  a `parentTaskId` IS claimable, but only while the parent's status is neither
+  InProgress nor ReviewPR: the pack watchdog and the child-event notifier both
+  ignore parked parents, but an actively-orchestrating parent reads a headless
+  InProgress child as a dead agent environment and "recovers" it onto a cloud
+  pod (observed 2026-07-28 — duplicate implementation). Working a pack locally
+  means: leave the parent parked (never Build/start it), work the children
+  serially in dependency order, and the user merges each child PR into the
+  pack branch to unblock the next.
+- **Clean tree before any branch switch — hard rule.** Dirty `git status` at
+  iteration start → touch nothing, report, and idle: the cwd is probably the
+  user's interactive checkout. Recommend a dedicated checkout once
+  (`git worktree add ../<repo>-loop dev`) and running the loop session there.
+- **Push early.** There is no pod WIP-autosync locally; committed-and-pushed is
+  the only durable state. Push the branch (`-u origin`) as soon as it exists.
+
+## Iteration order
+
+Each invocation does the FIRST of these that produces work, then paces:
+
+1. **Recover** — a card with my `[local-loop] claimed` chat marker still
+   InProgress without a PR? Resume it. The branch may already exist locally or
+   on origin — check both before re-implementing anything.
+2. **Babysit** — my loop-opened PRs (ReviewPR cards): red CI → fix now;
+   request-changes or unanswered review comments → address now; green and
+   quiet → leave alone.
+3. **Claim** the next card (below).
+4. **Idle** — nothing claimable: pace long.
+
+## Claiming
+
+1. `mcp__conveyor__list_tasks` with `status: "Open"` — results are already
+   priority-then-newest ordered; board priority IS the intelligence, don't
+   invent your own ranking. Walk top-down, `mcp__conveyor__get_task` each until
+   one passes: created by me, no assignee or active session, an executable
+   plan, all `mcp__conveyor__get_dependencies` blockers Complete, no
+   `[local-loop] parked:` chat marker without a later human reply (a reply
+   un-parks), no child tasks of its own, and — if it has a `parentTaskId` —
+   the parent's status is neither InProgress nor ReviewPR (see ground rules).
+   Skip `followParentStatus` mirror children. A blocker counts as met only
+   when merged-or-beyond (ReviewDev/ReviewLive/Complete) or Cancelled — a
+   blocker sitting in ReviewPR is NOT met until its PR merges.
+2. Claim: re-confirm via `get_task` it is still Open, then
+   `mcp__conveyor__update_task` → `status: "InProgress"`, then
+   `mcp__conveyor__post_to_chat`: `[local-loop] claimed — working locally on
+   <hostname>`. Status changed under you → someone else took it; next
+   candidate.
+3. Plan missing or failing the context-free-reader bar → don't wing it: post
+   what's missing to chat, leave the card Open, skip it.
+
+## Execute and finish
+
+1. `mcp__conveyor__get_task` (full plan) + `mcp__conveyor__read_task_chat`
+   (addenda, user answers). The card must stand alone — if you find yourself
+   relying on loop-session memory, stop and re-read the card instead.
+2. Branch from the card's base, never blindly dev: `base` = the card's
+   `baseBranch` (a pack child's base is the PARENT's feature branch). If the
+   card already has a `githubBranch` with commits on origin, resume THAT
+   branch — a prior pod may have landed real work; audit it before
+   re-implementing anything. Else `git fetch origin <base> && git checkout -B
+   <feat|fix|chore>/<slug> origin/<base>`. Reinstall deps if the lockfile
+   changed.
+3. Work the plan. Post chat updates at real milestones only (claim, blocking
+   discovery, gates green, PR) — not play-by-play.
+4. Verify per the host repo's CLAUDE.md policy (scoped gates). UI-visible
+   change → capture screenshot/recording evidence with the repo's tooling and
+   attach via `mcp__conveyor__upload_attachment` before opening the PR.
+5. Refresh against the card's base (`git fetch origin <base> && git merge
+   origin/<base> --no-edit && git push`), then
+   `mcp__conveyor__create_pull_request` with `head:` your branch and `base:`
+   the card's base branch. Pack child: re-check the parent's status first —
+   if it went InProgress/ReviewPR, park instead (post `[local-loop] parked:
+   pack coordinator active — yielding`, leave the branch pushed) and let the
+   coordinator take over. The card moves to ReviewPR. Post a chat summary:
+   what shipped, how verified, what to look at.
+6. Confirm CI actually started (read-only `gh pr checks`); do NOT wait on it —
+   later iterations babysit.
+
+**Parked protocol** — after 2 genuinely different failed approaches, or on a
+decision only the user can make: post `[local-loop] parked: <reason + the
+specific question>`, set status back to `"Open"`, restore the tree
+(`git checkout dev`), move on. The user's next chat reply is the un-park
+signal.
+
+## Pacing (dynamic /loop only)
+
+Under `/loop` with no interval, end EVERY iteration with exactly one
+`ScheduleWakeup` (prompt = the original /loop input verbatim):
+
+| State | Delay | Reason should say |
+|-------|-------|-------------------|
+| A background gate/agent is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
+| ANY actionable work exists: claimable cards, a PR still to open, red/pending CI, review comments | 60–90s | queue depth / which item is next |
+| Queue enumerated as empty THIS iteration, all loop PRs green and quiet | 1200–1800s | queue empty, idle poll |
+| Loop-fatal: MCP dead after 2 tries, dirty tree, broken repo | notify the user (PushNotification if available), then 1800s — or `stop: true` if continuing is unsafe | what is wrong |
+
+The long idle tier is EARNED, never defaulted: it requires having enumerated
+the queue this very iteration and found zero actionable work. When unsure
+which tier applies, take the short one — a wasted 60s wake costs less than a
+30-minute stall on live work.
+
+Invoked bare (no /loop)? Run one iteration, report, and suggest
+`/loop /conveyor-local-loop` — don't self-schedule.
+
+## Offload valve (opt-in)
+
+Only with an explicit `offload=N` argument: when 4+ claimable cards queue up,
+`mcp__conveyor__start_task` up to N of the smallest into claudespaces and say
+so in the iteration summary. Without the argument, never — just report backlog
+depth each iteration so the user can offload manually.
+
+## What this is not
+
+- Not a reviewer: never `approve_task`, `approve_and_merge_pr`, or
+  `request_changes` on anything.
+- Not a pod: no sandbox, no WIP snapshots, and the dev DB + dev-server ports
+  are shared with the user's interactive sessions — no destructive
+  experiments, never reset the dev DB, reuse a running dev stack rather than
+  fighting over ports.
+- Not a parallel executor: one card at a time is the point (the full machine
+  per gate). Backlogged? That is what claudespaces — or the offload valve —
+  are for.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on the Conveyor project: the issue,
+evidence, and proposed fix.

package/skills/conveyor-plan/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: conveyor-plan
+description: Turn a raw feature or bug idea into a research-backed, immediately-buildable Conveyor card for a claudespace agent to execute later. Use when the user says "/conveyor-plan <idea>", "plan this as a conveyor card", "write this up for a claudespace agent", or wants deep planning that ends in a handoff card rather than local implementation. Runs plan-mode-quality research (codebase + prior Conveyor cards + prod logs), asks clarifying questions only when scope is genuinely ambiguous, then creates the card and moves it to Open so identification auto-fills story points, tags, icon, and agent.
+---
+
+# Conveyor Plan → Handoff Card
+
+Produce ONE artifact: a Conveyor card whose plan a fresh claudespace agent can
+execute with zero session context. Everything the executor needs must be ON the
+card — it never sees this conversation.
+
+The division of labor is fixed: **you research and recommend; Conveyor's
+identification decides.** Moving the card to Open fires identification
+automatically (story points, icon, agent, and tags if you set none). Never set
+icon or story points yourself, and never `start_task` unless the user asks.
+
+## Phase 0 — Resolve context
+
+1. `mcp__conveyor__get_connection_context` (all Conveyor tools fully-qualified;
+   bare names fail). No default project? `mcp__conveyor__list_projects` and
+   match `githubRepoOwner/Name` to the cwd's `git remote`. Ambiguous → ask.
+2. Copy project IDs exactly — a mistyped `projectId` surfaces as
+   "Insufficient permissions", not "not found". Verify the ID before
+   concluding you lack access.
+
+## Phase 1 — Research (parallelize)
+
+Scale to the idea's size; a one-file tweak needs minutes, not a survey.
+
+- **Codebase**: use a code-graph or architecture skill if the repo provides
+  one for architecture/flow questions; `rg` for exact strings. Fan out
+  Explore subagents for broad sweeps.
+- **Prior art**: `mcp__conveyor__search_tasks` on 2-3 keyword variants
+  (`typeFilters` to include incidents/suggestions when relevant), then
+  `mcp__conveyor__get_task` on the closest hits. You're looking for duplicates
+  (stop and surface), related shipped work (reuse its patterns), and
+  cancelled attempts (learn why before re-proposing).
+- **Prod signals** (only when the feature touches live behavior):
+  `mcp__conveyor__query_gcp_logs` / `mcp__conveyor__query_grafana_logs` for
+  error rates, actual usage, current behavior.
+- **Blast radius**: enumerate callers/consumers of every surface the plan
+  touches (shared packages, DB schema, published packages, webhooks, other
+  cards in flight on the same files). Unintended impact goes in the plan's
+  Notes, not in your head.
+
+## Phase 2 — Clarify (only if needed)
+
+Ask the user only decisions that change the plan's shape — scope cuts, UX
+choices, irreversible tradeoffs. Batch them in one round; never drip. Facts
+the repo can answer are yours to find, not theirs.
+
+## Phase 3 — Draft the plan
+
+Use the plan format in [references/plan-format.md](references/plan-format.md):
+Objective / Approach / Implementation Steps / Testing / Notes.
+
+Actionability bar — every step must survive a context-free reader:
+
+- Name exact repo-relative files and symbols, with the pattern to follow
+  ("mirror `apps/api/src/services/task/methods/mutations.ts`").
+- Testing = runnable commands + observable acceptance criteria.
+- Notes = risks, blast radius, dependencies, and decisions already made (so
+  the executor doesn't relitigate them).
+- No "as discussed", no links to this chat, no TODOs the executor must
+  research from scratch.
+
+Size it: 1 SP default, 2 multi-file, 3 complex patterns/design, 5 hard. Larger
+→ propose a pack (parent + `mcp__conveyor__create_subtask` children with
+`mcp__conveyor__add_dependency` edges) instead of one mega-card.
+
+Show the user title + description + plan + SP/tag recommendation before
+touching Conveyor, unless they asked you to just ship it.
+
+## Phase 4 — Create and hand off (order matters)
+
+Identification fires the moment the card lands beyond Planning and reads task
+chat for your recommendation — so chat BEFORE the status flip:
+
+1. `mcp__conveyor__create_task` — `status: "Planning"`, concise imperative
+   title, 2-4 sentence description (the board-card summary), full plan.
+   Optionally `tags`: only names from `mcp__conveyor__list_tags` that clearly
+   fit (unknown names are rejected; pre-set tags make identification skip tag
+   assignment — when unsure, omit and let it choose).
+2. `mcp__conveyor__post_to_chat` — one message: recommended SP + one-line
+   rationale, tag suggestion, any executor warnings.
+3. `mcp__conveyor__update_task` — `status: "Open"` (+ `risk` when the plan
+   touches critical surface). This triggers identification.
+4. Verify with `mcp__conveyor__get_task`: status Open, `agentId` set. SP and
+   tags are NOT in the `get_task` response — confirm on the board if needed.
+5. Report the card URL (`<project url>/cards/<slug>`), what identification
+   filled, and that it's ready for `start_task`. Park-in-Planning instead if
+   the user wants to review first; offer (don't run) `start_task`.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on the Conveyor project: the issue,
+evidence, and proposed fix.

package/skills/conveyor-plan/references/plan-format.md

@@ -0,0 +1,56 @@
+# Conveyor Plan Format & Sizing
+
+## Plan Format
+
+```markdown
+## Objective
+One sentence: what this task accomplishes and why.
+
+## Approach
+High-level strategy with relevant files/patterns/APIs.
+
+## Implementation Steps
+1. Concrete step.
+2. Concrete step.
+
+## Testing
+- Commands and manual checks.
+- Edge cases.
+
+## Notes
+- Dependencies, risks, blockers, or files likely touched.
+```
+
+## Sizing
+
+Default **1 SP**. Use **2 SP** for multi-file work, **3 SP** for complex
+patterns/design choices, **5 SP** only for hard work. Split anything larger.
+
+## Packs (parent + child tasks)
+
+A **pack** is Conveyor's bundle shape: a parent card with child cards.
+`create_subtask(parentTaskId, ...)` is the **only** way to parent a card —
+`create_task`/`update_task` have no parent field. Each child is a full card
+(own chat, plan, story points). Split into a pack only when the work is
+genuinely multiple independently buildable pieces (8-SP-tier); otherwise keep
+one card.
+
+- **Orchestration packs** (future work): `start_task` on the parent boots a
+  *pack runner* that starts each ready child's own build/PR, honoring
+  `add_dependency` edges (independent children run in parallel). Give each
+  child a detailed plan with a **Testing / Verification** section and a
+  `storyPointValue`. The parent's `featureBranch` toggle (default on) makes
+  children branch off and PR back into the parent's branch instead of dev.
+- **Mirror packs** (already-done work shipping in ONE PR on the parent's
+  branch): create children with **`followParentStatus: true`** — title and a
+  plain-language description only. A follower mirrors its parent's status
+  automatically through the whole pipeline, identification sizes it, and it
+  never posts its own Slack card. Evidence rolls up to the **parent**. Never
+  `start_task` a mirror pack's parent, and leave children's PR fields empty —
+  the parent owns the PR.
+
+## Status Flow
+
+`Planning -> Open -> InProgress -> ReviewPR -> ReviewDev -> ReviewLive -> Complete`
+
+`Cancelled` is terminal. A task must be `Open` before `start_task`.