Lifecycle Orchestrator

Runs one slice to a merged PR. It does not need project-init to have run: on a project with no plan documents the scope comes from what the user described at start, and SCOPE is the gate that pins it down. Use project-init only when what to build has not been decided.

Routing

status (or no arguments): execute INLINE — read .lifecycle-state.json and display the status table directly. Do NOT launch an agent. See "Status display" section below.

This skill's directory (its reference files live here) — resolved at runtime: !echo ${CLAUDE_SKILL_DIR}

The plugin's scripts directory — resolved at runtime: !echo ${CLAUDE_PLUGIN_ROOT}/scripts

Both paths must be substituted into the agent prompt as literal absolute paths. Reference files are read as raw bytes: a ${CLAUDE_PLUGIN_ROOT} written inside steps.md arrives at the model unexpanded and runs as bash "/scripts/detect-project.sh", which does not exist.

skip-compact: execute INLINE. Do NOT launch an agent — the compact gate blocks agent launches, and this command exists to lift that block, so routing it through an agent means the only way out of the gate is itself gated.

Write the state with jq through Bash, which is the one tool the compact gate does not match:

jq '.awaitingCompact = false
    | .compactSkippedAt = (now | todate)
    | .compactSkippedBefore = (.currentStep // "unknown")' .lifecycle-state.json > .lifecycle-state.json.tmp \
  && mv .lifecycle-state.json.tmp .lifecycle-state.json

This is the single exception to the "always write state with the Write tool" rule below, and it exists only because Write is gated too. Run it only when the user asked for it in so many words. Then tell them the gate is lifted and which step it was lifted before. If .bergant-workflow.json does not say "compactGate": true, add that the gate is off for this project, so nothing was blocking; the write is still harmless.

All other commands (start, adopt, next, advance, complete, recover): launch Agent(general-purpose) with the prompt below. Replace SKILL_DIR and SCRIPTS_DIR_LITERAL with the absolute paths printed just above:

Read these files in order:
1. SKILL_DIR/references/state-schema.md — state file structure
2. SKILL_DIR/references/project-config.md — the project's commands and plan location
3. SKILL_DIR/references/steps.md — find the section for the CURRENT step only

SCRIPTS_DIR is SCRIPTS_DIR_LITERAL. Wherever steps.md says SCRIPTS_DIR, use that path.

On `start`, do things in this order and no other: git preflight, then ADOPT if
`.bergant-workflow.json` is missing, then the task branch, then write the state file.
Set `awaitingCompact: true` ONLY when `.bergant-workflow.json` has `"compactGate": true`;
writing that flag before ADOPT blocks the agent ADOPT needs. With the gate off (the default,
also when the field is missing) write `awaitingCompact: false`, never print "Run /compact",
and go straight on to the next step — stop only at real user gates.

Before anything else: read `.bergant-workflow.json` at the project root if it exists — it holds
the command overrides and `planGlob` that rules 6 and 8 depend on. If it does NOT exist, or has
no `commands` object (project-init writes only the planned `projects`), the project has not been
adopted: run the ADOPT section of steps.md first, whatever the requested command was.

Execute lifecycle command: $ARGUMENTS
State file: .lifecycle-state.json

Critical rules:
1. NEVER skip a step. Order: CONTEXT_CHECK → SCOPE → PLAN → COMPONENTS → IMPLEMENT → VERIFY → TEST → REVIEW → DOCUMENT → CLOSE.
2. NEVER advance past a user gate without `/bergant-workflow:lifecycle complete <step>`.
3. Always update state file after every transition.
4. Always read state file before any action.
5. Use Agent tool for heavy work (IMPLEMENT subtasks, REVIEW).
6. Task context comes from the plan files named by `planGlob` in `.bergant-workflow.json` (default `docs/plan/slice-*.md`) — do NOT use Jira MCP. Read the relevant plan file to understand task scope and dependencies. If `planGlob` is `null`, the project has no plan documents and the scope comes from what the user described at `start`; SCOPE is then the gate that pins it down.
7. GitHub operations via the `gh` CLI (`gh pr create`, `gh pr merge`). Never use interactive
   flags — pass `--title`/`--body` explicitly. If `gh` is missing or unauthenticated, fall back
   to GitHub MCP (`mcp__github__*`).
8. **Never assume the toolchain.** Build, lint and test run through
   `bash "SCRIPTS_DIR/project-commands.sh" run <build|lint|test|e2e>`, which rediscovers every
   project in the repository (root and sub-projects) and applies `commands`, `projects` and
   `exclude` from `.bergant-workflow.json` on top. Never compose the commands yourself and never
   run only `commands.*`: a sub-project nobody listed still has tests. A project without a
   command is a reported skip. Never fall back to `npm run <anything>` on a project that never
   asked for it.
9. **Never mutate Git beyond what the current step prescribes.** No `stash`, no `checkout -f`,
   no `clean`, no `add -A`, no `branch -D`, no force push. If the tree is not what the step
   expects, stop and ask.
10. When a task is completed, tick its checkbox in the corresponding plan file (the one `planGlob` matched).
11. **Live checklist, if the session has one.** If a checklist tool such as `TodoWrite` is
    available, mirror the step statuses into it so progress renders in the UI. It is a mirror,
    never the record — `.lifecycle-state.json` is the record, and `status` reads from it. Some
    builds do not expose the tool at all; when it is missing, skip this silently.

When you hit a user gate (STOP HERE), return the gate message. Return a concise summary of what was done and what the user needs to do next.

IMPORTANT: When writing or updating .lifecycle-state.json, ALWAYS use the Write tool — NEVER use Bash with cat/heredoc/echo redirect. Heredoc commands trigger permission prompts. The sole exception is `skip-compact`, documented above: `Write` is blocked by the very gate that command lifts.

If the agent returns an error, display it to the user without re-running.

When the agent finishes CLOSE, its report ends with a /clear suggestion and a next-session prompt in a fenced block. Relay that block to the user verbatim, as a fenced block they can copy, and don't summarize it. The agent's report is not shown to the user, so a prompt you leave out is lost.

Status display

Read .lifecycle-state.json. If no file exists, say "No active lifecycle. Use /bergant-workflow:lifecycle start <task-name> to begin."

Display a formatted table:

• Each step with status emoji (⏳ pending, 🔄 in_progress, ✅ completed)
• Current step highlighted
• User gates marked with 🚧
• Subtask progress for IMPLEMENT step
• What the next action should be

Commands (summary)

State File Location

.lifecycle-state.json — in the project root (NOT under .claude/, which would trigger a write-permission prompt on every update). This file is gitignored and deleted on CLOSE.

Optional dependencies

These power specific steps. The first time a step needs one and it's missing, offer the user a one-time choice — install it now or skip the step (note the skip). Never hard-block the lifecycle on a missing optional tool.