factory-runbook

factory-runbook

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 {REPO_ROOT}/.agents/skills/factory-runbook/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 {REPO_ROOT}/.agents/skills/factory-runbook/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 {REPO_ROOT}/.agents/skills/factory-runbook/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 {REPO_ROOT}/.agents/skills/factory-runbook/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)
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)