mcpField
F
factory-runbook

factory-runbook

github.com/tikalkOther1446 installsUpdated 1d ago
Repository

About factory-runbook

factory-runbook is a skill that standardizes publishing steps and shared run contracts for software-factory orchestrators. It manages run branches, allowlisted commits, and draft merge requests or pull requests, but does not approve or merge them.

Key features

  1. 01Deterministic branch and publish flow
  2. 02Allowlisted per-step commits
  3. 03Draft MR or PR creation
  4. 04Reusable executor and tracker contracts
  5. 05Run-context safeguards

Use cases

  1. 01Publishing changes from a factory run
  2. 02Committing only approved paths after each step
  3. 03Providing shared contracts to factory skills

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/tikalk/adlc-team-skills --skill factory-runbook

After installing, type/factory-runbookin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

mission-template.yml
references/
executor.md
issues-provider.yml
lanes.md
mission-brief-template.md
run-context.md
tracker-integration.md
scripts/bash/
commit-step.sh
open-mr.sh
resolve-mr-ownership.sh
run-branch.sh
scripts/powershell/
commit-step.ps1
open-mr.ps1
resolve-mr-ownership.ps1
run-branch.ps1

Details

From the project README

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/)

FileBorrowed by
executor.mdevery Kind-A orchestrator (step schema, run state, lanes, gates, converge)
tracker-integration.mdtracker-integrated skills (comment bus, labels, lease, provider ops, MR ownership)
lanes.mdlane-based dispatch consumers
mission-brief-template.mdbrief/milestone authors (queue, orchestrator)
issues-provider.ymlprovider resolution template (setup writes the repo copy)
run-context.mdrun-mode vs local-session rules
mission-template.ymlrun policy defaults (execution, supervision, budgets)

Comments

Markdown supported