# Factory Runbook

> Use when a factory run must post its changes — check out the run branch, commit a step's allowlisted paths, push only that branch, and open or reuse one draft MR/PR with milestone/assignee ownership. Also the shared home for factory run contracts (executor, tracker integration, lanes, brief and provider templates).

- Skill: `tikalk/factory-runbook` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx get-skill add tikalk/factory-runbook`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tikalk/factory-runbook/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tikalk (https://skillmd.com/u/tikalk)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/tikalk/factory-runbook

---


# factory-runbook


> **Scope rule**: scripts stay skill-local — never source a script from another skill. For another skill's operations, invoke that skill (e.g. `architect-clarify`, `product-clarify`, `team-boot`) via the Skill tool; for its documents, follow the `Requires` line. `scripts/` and `references/` below are relative to this skill. `{REPO_ROOT}` denotes the project root (where `.adlc/` lives).

## What this skill does

`factory-runbook` is the shared run mechanics of the software factory. It has
two halves:

1. **Publish procedure** (below) — the deterministic branch → commit → push →
   draft-MR/PR sequence every factory run ends with. Factory orchestrators
   invoke this skill for their publish step; it is also directly usable to
   post a run's changes.
2. **Run contracts** (`references/`) — the executor loop, tracker
   integration, lanes, brief/provider templates, and run-context rules that
   factory skills borrow by path instead of copying.

It never approves or merges. The engine's gate after the step is the approval.

**Direct-invocation guard:** publishing needs a run context — `ADLC_RUN_ID`
(and usually `ADLC_ISSUE_REF` plus `ADLC_STEP_OUTPUT`) from a factory run, or
explicit orchestrator-provided args (orchestrator name, step id, output type,
paths). Never invent a branch name, a step, or paths to commit. Without a run
context and without them, state what is missing and stop.

---

## Publish procedure — read this first

**Requires:** nothing — this skill is self-contained. (Borrowers declare the
reverse: `adlc-cli skills add tikalk/adlc-team-skills --skill factory-runbook`.)

1. **Start:** `bash scripts/bash/run-branch.sh [--kind <intent|code>]`
   — on Windows, the PowerShell twin (every helper has one under
   `scripts/powershell/`). Checks out the run branch (`factory/intent/<repo>-<iid>`
   from `ADLC_ISSUE_REF` for intent runs — the default; `factory/mission/<repo>-<iid>`
   with `--kind code` for mission code runs) in the project root, reusing it
   or continuing from `origin`. Shared by both intent lanes and with
   re-dispatches. Without `ADLC_RUN_ID` this is a no-op.
2. Run the lifecycle steps. After **each** step that changed files:
   `bash scripts/bash/commit-step.sh --orchestrator <name> --step <id> --output-type
   <draft|decision|artifact-ref|findings> --summary "<one line, no issue text>"
   --records <IDs> -- <paths the step wrote, moved or deleted>`. Stages ONLY
   allowlisted paths; prints `sha: <sha>` or `sha: none` for the
   step's bus marker.
3. **Before returning, always:** `bash scripts/bash/open-mr.sh [--kind <intent|code>]` —
   pushes the run branch only, finds or opens one draft MR (merge commit, no
   squash; Issue milestone applied inline, Issue assignees else the
   runner's own account, per `tracker-integration.md` Operation 11; the
   deterministic resolver `scripts/bash/resolve-mr-ownership.sh`
   itself runs at caller/completion, not inside `open-mr.sh`), and the
   `agent-authored` stamp likewise lives at completion (mission Phase 6,
   orchestrator §7 hygiene — not in this helper). It writes `mr_url` to
   `ADLC_STEP_OUTPUT`. Pass
   `--kind code` for code missions (`factory/mission/*` branch). Call it
   whatever the outcome — an empty run opens nothing and the gate shows no
   link. Also write a one-line `conclusion` into the same JSON object,
   preserving existing keys.
4. **Never ask for approval** or wait for an answer here. A helper's non-zero
   exit (refused path, missing committer identity, tracker scope) stops the
   run — report it, do not work around it.

Outside a factory run the helpers do nothing unless the user opted in
(`adlc.commit_steps: true` in `.adlc/init-options.json`, or `--commit`
forwarded to `commit-step.sh`); `run-branch.sh` and `open-mr.sh` never act
without `ADLC_RUN_ID`.

Only an orchestrator-invoked runbook commits, pushes and opens the MR, and
only through these helpers; lifecycle skills never do.

---

## Run contracts (`references/`)

| File | Borrowed by |
|--|--|
| `executor.md` | every Kind-A orchestrator (step schema, run state, lanes, gates, converge) |
| `tracker-integration.md` | tracker-integrated skills (comment bus, labels, lease, provider ops, MR ownership) |
| `lanes.md` | lane-based dispatch consumers |
| `mission-brief-template.md` | brief/milestone authors (queue, orchestrator) — canonical home `mission-brief/references/` |
| `issues-provider.yml` | provider resolution template (setup writes the repo copy) |
| `run-context.md` | run-mode vs local-session rules |
| `mission-template.yml` | run policy defaults (execution, supervision, budgets) |

