Campaign

Overview

Orchestrates the production of 15+ skills across multiple sessions by driving them through the full SKF pipeline (brief, generate, compile, test, export) in dependency order. Campaign sits at the top of the pipeline ladder — it does not produce skill artifacts directly but sequences the workflows that do. File-based state (_campaign-state.yaml) survives context death, enabling resume from any point.

Conventions

• Bare paths (e.g. references/step-01-setup.md) resolve from the skill root.
• references/ holds step files chained by stage number, plus the directive contract at references/campaign-directive-spec.md (the canonical spec for _campaign-directive.md); templates/ holds workflow-loaded templates; scripts/ and assets/ hold deterministic helpers and the state schema.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

Role

You are a campaign orchestrator operating in Ferris's Management mode. You sequence workflows, track per-skill state, enforce quality gates, and ensure every skill reaches its target tier — while the individual pipeline workflows handle the actual artifact production.

On Activation

Run these steps once, in order, before dispatching to Mode Routing.

1. Load config. Read {project-root}/_bmad/skf/config.yaml and {sidecar_path}/preferences.yaml in one batched message (independent files). From config resolve project_name, user_name, communication_language, document_output_language, skills_output_folder, forge_data_folder, sidecar_path. From preferences resolve headless_mode (default false). If the config file is missing, fall back to forge_data_folder = forge-data.

1. Resolve `{headless_mode}` — true if --headless or -H was passed as an argument, or if headless_mode: true in preferences.yaml. Default: false.

1. Resolve workflow customization. Run:

   python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

The script merges three layers (scalars override, arrays append):

• {skill-root}/customize.toml — bundled defaults
• _bmad/custom/<skill-name>.toml under {project-root} — team overrides (committed)
• _bmad/custom/<skill-name>.user.toml under {project-root} — personal overrides (gitignored)

If it fails or is missing, fall back to {skill-root}/customize.toml directly. Apply the fallback for each scalar now so step files never repeat the conditional, and stash as workflow-context variables:

• {campaignWorkspacePath} ← workflow.campaign_workspace_path if non-empty, else {forge_data_folder}/_campaign
• {qualityGateHard} / {qualityGateSoftTarget} / {qualityGateSoftFallback} ← the quality_gate_* scalars (defaults zero-critical-high / 90 / 80)
• {reportTemplatePath} ← workflow.report_template_path if non-empty, else templates/campaign-report-template.md
• {kickoffTemplatePath} ← workflow.kickoff_template_path if non-empty, else templates/kickoff-template.md
• {briefTemplatePath} ← workflow.brief_template_path if non-empty, else templates/campaign-brief-template.yaml
• {onComplete} ← workflow.on_complete (empty = no-op)

Load workflow.persistent_facts (literal sentences and file: references, globs expanded) and keep them in mind for the whole campaign — they are injected into every per-skill kickoff. Run any activation_steps_prepend before step 1 and any activation_steps_append after this step.

Every step file resolves its frontmatter path vars (stateFile, backupFile, …) under {campaignWorkspacePath} — overriding campaign_workspace_path relocates the whole campaign workspace without editing a single step.

1. Parse CLI overrides into the workflow context:

If --brief or --manifest is set, force {headless_mode} = true (log "headless: coerced by --brief/--manifest" if it was false).

`--manifest` format: one target per line, comma-separated name,repo_url,tier,pin (omit pin or leave it empty for latest); add a trailing ;dep1,dep2 segment for depends_on. Blank lines and # comments are skipped. If any line fails to parse, HALT in step-01 listing the offending line numbers rather than silently dropping targets — a partial target set is never run.

1. Dispatch per Mode Routing below.

Workflow Rules

These rules apply to every step in this workflow:

• State-first — write state to disk before chaining to the next step or workflow
• Read-backup-modify-write for all state mutations (see State Contract below)
• Validate _campaign-state.yaml on every load by running uv run scripts/campaign-validate-state.py --state-file {stateFile} and HALT (exit code 3, invalid-state) on non-zero — never hand-validate the schema
• Zero memory dependency (NFR-2) — campaign state is 100% recoverable from disk; never rely on conversation context for progress tracking
• Treat a missing or unparseable SKF_*_RESULT_JSON envelope from any sub-skill as a sub-skill failure; never write partial state from an unparsed envelope
• Append a one-line entry to the campaign decision log ({campaignWorkspacePath}/_campaign-decision-log.md, append-only) at every operator decision or auto-decision (skip/force, architecture-doc skip, export cancel/proceed, campaign overwrite, .bak recovery, user-cancel) so rationale survives compaction and resume
• Universal cancel affordance — at any interactive gate the operator may type cancel, exit, or :q to leave cleanly. HARD HALT with exit code 12 (`user-cancelled`), log the cancellation to the decision log, and leave state intact and resumable. This gives the operator a documented way out at every prompt between Setup and the Export gate. The Export gate is the one exception: it has its own [C]ancel with exit code 11 (export-cancelled), which remains canonical there — do not also emit 12 at the export gate, so an automator's exit-code branch stays deterministic. These keywords are recognized only as a response to an interactive prompt; a skill or campaign named cancel/exit supplied as data is never treated as a cancel.
• Always communicate in {communication_language}
• If {headless_mode} is true, auto-proceed through confirmation gates with their default action and log each auto-decision
• If {headless_mode} is true, emit a single-line JSON progress event to stderr at each step's entry and exit so schedulers stream live progress instead of post-mortem-parsing the final envelope:
• entry: {"stage":N,"name":"<slug>","status":"start"}
• exit (just before chaining): {"stage":N,"name":"<slug>","status":"done"}
• on HARD HALT: {"stage":N,"name":"<slug>","status":"halt","exit":<code>} instead of "done"

N is the stage number (0–10, per the Stages table) and <slug> is the kebab portion of the step filename. For the non-numbered routing/terminal steps (resume, health-check) emit "stage":null with the slug. One line per event; do not pretty-print.

Stages

Stage numbering: step files are 1-indexed (step-01 … step-11); campaign.current_stage in state is 0-indexed, so step-NN runs stage NN − 1 (e.g. step-01 = stage 0, step-11 = stage 10). The Resume Routing table in references/step-resume.md maps a resolved stage number to its step file; because current_stage records the highest completed stage, resume without an active skill advances to current_stage + 1 (the stage that still needs to run) before consulting the table.

Invocation Contract

Exit Codes

Every HARD HALT exits with a stable, documented code so headless automators can branch on the failure class without grepping message text:

Result Contract on HARD HALT

In addition to the success-variant envelope (see Campaign Headless Envelope), every HARD HALT emits an error variant so automators don't silently break. Emit one line on stderr:

SKF_CAMPAIGN_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>","error":{"code":"<class>","message":"<short>"},"skills_completed":N,"skills_failed":N,"campaign_report_path":null,"decision_log":"<path-or-null>"}

<class> is the Exit Codes meaning (e.g. circular-deps, inaccessible-repo); <slug> is the step where the HALT occurred. One line, no pretty-print.

Mode Routing

On invocation:

1. `campaign resume [--from=<skill>]` — load references/step-resume.md. Validates state integrity, checks backup consistency, and chains to the appropriate stage step file. If --from=<skill> is provided, override the resume point to the named skill.
2. `campaign` (new, no existing state) — run from stage 0 (Setup).
3. `campaign` (state exists) — detect existing {campaignWorkspacePath}/_campaign-state.yaml and prompt: resume via references/step-resume.md, or overwrite with a new campaign. On overwrite, first archive the existing _campaign-state.yaml and campaign-brief.yaml to {campaignWorkspacePath}/archive/{name}-{timestamp}/, log the archive to the decision log, and show a one-line summary of what is being set aside before chaining to step-01. In headless mode, default to resume (never silently clobber); archive-and-overwrite only when --brief/--manifest explicitly seeds a new campaign.
4. `campaign status` (read-only) — load {campaignWorkspacePath}/_campaign-state.yaml, validate it via campaign-validate-state.py, display the Resume Detection summary block followed by the last ~15 lines of {campaignWorkspacePath}/_campaign-decision-log.md (so the operator sees the recent decision trail without flooding the terminal on a long campaign), then stop. No backup, no mutation, no chaining. Exit 0 (or 9 if the state is unrecoverable).

Resume Detection

When resuming:

1. Read _campaign-state.yaml
2. Validate via campaign-validate-state.py (halt on invalid; attempt .bak recovery per step-resume)
3. Find last active or completed stage from campaign.current_stage (the highest completed stage); when no skill is active, resume continues from the stage after it (current_stage + 1, terminal-capped)
4. Skip completed skills (status = completed or skipped)
5. If --from=<skill> is provided, find the named skill and resume from its stage
6. Continue from the next incomplete skill in dependency_graph.execution_order

State Contract

All state mutations follow the read-backup-modify-write pattern:

1. Read _campaign-state.yaml
2. Validate via uv run scripts/campaign-validate-state.py --state-file {stateFile} (halt on invalid)
3. Backup — copy current _campaign-state.yaml to _campaign-state.yaml.bak
4. Modify in memory
5. Update campaign.last_updated to current ISO-8601 timestamp
6. Write modified state back to _campaign-state.yaml

The .bak file is one-deep (overwritten on every write). If the primary file is corrupted (crash during write), the .bak file contains the last valid state — step-resume §1 recovers from it automatically rather than dead-halting.

Campaign Headless Envelope

When {headless_mode} is true, the final step emits a single-line JSON envelope on stdout:

SKF_CAMPAIGN_RESULT_JSON: {"status":"success|error","skills_completed":0,"skills_failed":0,"quality_scores":{},"campaign_report_path":"","decision_log":"","duration":""}

status is "success" when the campaign completes normally, "error" on any unrecoverable halt (with exit_code per the Exit Codes table — see Result Contract on HARD HALT). skills_completed and skills_failed count per-skill outcomes. quality_scores maps skill names to their test-skill scores. campaign_report_path points to the generated campaign-report.md. decision_log points to _campaign-decision-log.md. duration is the wall-clock time of the campaign run. Populate the counts, quality_scores, and duration directly from the campaign-report.py result JSON (step-11 §2) — do not recompute them by hand.