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:
- 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.
- 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.)
- 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.
- 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.
- 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.
- 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) |
1---2name: factory-runbook3description: 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).4metadata:5 source: https://skillmd.com/skills/tikalk/factory-runbook6---78# factory-runbook91011> **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).1213## What this skill does1415`factory-runbook` is the shared run mechanics of the software factory. It has16two halves:17181. **Publish procedure** (below) — the deterministic branch → commit → push →19 draft-MR/PR sequence every factory run ends with. Factory orchestrators20 invoke this skill for their publish step; it is also directly usable to21 post a run's changes.222. **Run contracts** (`references/`) — the executor loop, tracker23 integration, lanes, brief/provider templates, and run-context rules that24 factory skills borrow by path instead of copying.2526It never approves or merges. The engine's gate after the step is the approval.2728**Direct-invocation guard:** publishing needs a run context — `ADLC_RUN_ID`29(and usually `ADLC_ISSUE_REF` plus `ADLC_STEP_OUTPUT`) from a factory run, or30explicit orchestrator-provided args (orchestrator name, step id, output type,31paths). Never invent a branch name, a step, or paths to commit. Without a run32context and without them, state what is missing and stop.3334---3536## Publish procedure — read this first3738**Requires:** nothing — this skill is self-contained. (Borrowers declare the39reverse: `adlc-cli skills add tikalk/adlc-team-skills --skill factory-runbook`.)40411. **Start:** `bash scripts/bash/run-branch.sh [--kind <intent|code>]`42 — on Windows, the PowerShell twin (every helper has one under43 `scripts/powershell/`). Checks out the run branch (`factory/intent/<repo>-<iid>`44 from `ADLC_ISSUE_REF` for intent runs — the default; `factory/mission/<repo>-<iid>`45 with `--kind code` for mission code runs) in the project root, reusing it46 or continuing from `origin`. Shared by both intent lanes and with47 re-dispatches. Without `ADLC_RUN_ID` this is a no-op.482. Run the lifecycle steps. After **each** step that changed files:49 `bash scripts/bash/commit-step.sh --orchestrator <name> --step <id> --output-type50 <draft|decision|artifact-ref|findings> --summary "<one line, no issue text>"51 --records <IDs> -- <paths the step wrote, moved or deleted>`. Stages ONLY52 allowlisted paths; prints `sha: <sha>` or `sha: none` for the53 step's bus marker.543. **Before returning, always:** `bash scripts/bash/open-mr.sh [--kind <intent|code>]` —55 pushes the run branch only, finds or opens one draft MR (merge commit, no56 squash; Issue milestone applied inline, Issue assignees else the57 runner's own account, per `tracker-integration.md` Operation 11; the58 deterministic resolver `scripts/bash/resolve-mr-ownership.sh`59 itself runs at caller/completion, not inside `open-mr.sh`), and the60 `agent-authored` stamp likewise lives at completion (mission Phase 6,61 orchestrator §7 hygiene — not in this helper). It writes `mr_url` to62 `ADLC_STEP_OUTPUT`. Pass63 `--kind code` for code missions (`factory/mission/*` branch). Call it64 whatever the outcome — an empty run opens nothing and the gate shows no65 link. Also write a one-line `conclusion` into the same JSON object,66 preserving existing keys.674. **Never ask for approval** or wait for an answer here. A helper's non-zero68 exit (refused path, missing committer identity, tracker scope) stops the69 run — report it, do not work around it.7071Outside a factory run the helpers do nothing unless the user opted in72(`adlc.commit_steps: true` in `.adlc/init-options.json`, or `--commit`73forwarded to `commit-step.sh`); `run-branch.sh` and `open-mr.sh` never act74without `ADLC_RUN_ID`.7576Only an orchestrator-invoked runbook commits, pushes and opens the MR, and77only through these helpers; lifecycle skills never do.7879---8081## Run contracts (`references/`)8283| File | Borrowed by |84|--|--|85| `executor.md` | every Kind-A orchestrator (step schema, run state, lanes, gates, converge) |86| `tracker-integration.md` | tracker-integrated skills (comment bus, labels, lease, provider ops, MR ownership) |87| `lanes.md` | lane-based dispatch consumers |88| `mission-brief-template.md` | brief/milestone authors (queue, orchestrator) — canonical home `mission-brief/references/` |89| `issues-provider.yml` | provider resolution template (setup writes the repo copy) |90| `run-context.md` | run-mode vs local-session rules |91| `mission-template.yml` | run policy defaults (execution, supervision, budgets) |