version: "1.0.3" name: skf-setup description: Initialize forge environment, detect tools, and set capability tier (Quick/Forge/Forge+/Deep). Use when the user requests to "set up" or "initialize the forge".

Setup Forge

Overview

Initializes the forge environment by detecting available tools, determining the capability tier (Quick/Forge/Forge+/Deep), and writing persistent configuration to {project-root}/_bmad/_memory/forger-sidecar/. When ccc (cocoindex-code) is available, also augments .cocoindex_code/settings.yml with SKF exclusion patterns and creates or refreshes the project's semantic-search index. On Deep tier, reconciles the QMD collection registry; whenever ccc is available, reconciles the CCC index registry as well.

Conventions

• Bare paths (e.g. references/<name>.md) resolve from the skill root.
• references/ holds prompt content carved out of SKILL.md — workflow stages chained via frontmatter nextStepFile, plus static reference docs.
• Deterministic work is delegated to shared Python helpers under src/shared/scripts/ (installed as _bmad/skf/shared/scripts/). Each step's frontmatter declares a *ProbeOrder array for the helpers it needs: run the first path in the array that exists, and halt if none resolve — the script owns that logic, with no prose fallback.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives, if present).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

Role

You are a system executor performing environment resolution. Run each step in sequence, write configuration files, and report results at completion.

Workflow Rules

• Only load one step file at a time — never preload future steps.
• Communicate in {communication_language}.
• If {headless_mode} is true, or if {orphan_action} is non-null, auto-resolve the step 3 orphan-removal gate non-interactively and log the decision.

Stages

Invocation Contract

On Activation

Halt contract for headless/quiet runs. Any halt below must first emit a blocked envelope when {headless_mode} or {quiet_mode} is true, before printing the human diagnostic — a pipeline observer that sees no envelope treats the run as not-completed-cleanly. Pipe {"phase":"<phase>","reason":"<reason>","path":"<path>"} to python3 <helper> emit-blocked where <helper> is the first existing path of {project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py then {project-root}/src/shared/scripts/skf-emit-result-envelope.py. The emit-blocked subcommand declares zero dependencies (no uv, no pyyaml), so it works even when uv itself is the thing that's missing.

1. Parse invocation flags first (so every halt below knows whether to emit an envelope): {headless_mode} (true on --headless / -H), {require_tier} (--require-tier=<Quick|Forge|Forge+|Deep>, case-sensitive; null if absent or unparseable), {orphan_action} (--orphan-action=<keep|remove>; null if absent), {ccc_skip_index} (true on --ccc-skip-index), {quiet_mode} (true on --quiet).

1. Probe `uv` runtime. Run uv --version. Every step invokes shared Python helpers via uv run (PEP 723 inline metadata auto-resolves pyyaml). If uv is missing, halt with phase on-activation:uv-missing and the human diagnostic:

"Setup cannot proceed: `uv` is not installed. SKF helpers depend on uv to auto-resolve their Python dependencies. Install it from <https://docs.astral.sh/uv/getting-started/installation/> and re-run /skf-setup."

1. Load config from {project-root}/_bmad/skf/config.yaml and resolve project_name, output_folder, user_name, communication_language, document_output_language, skills_output_folder, forge_data_folder, sidecar_path. Halt with phase on-activation:config-missing if the file does not exist, or on-activation:config-malformed if the YAML is invalid, with the matching human diagnostic.

1. Reconcile `{headless_mode}` with preferences.yaml: OR the parsed flag with headless_mode: true from the YAML.

1. Resolve workflow customization. Run:

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

The script merges the three customization layers per bmad-customize's structural merge rules (scalars override, arrays append): {skill-root}/customize.toml (bundled defaults), _bmad/custom/<skill-name>.toml under {project-root} (team overrides, committed), and _bmad/custom/<skill-name>.user.toml under {project-root} (personal overrides, gitignored). If the script fails or is missing, fall back to reading {skill-root}/customize.toml directly.

Apply the resolved values so the surface is not a silent no-op: execute each entry in workflow.activation_steps_prepend in order now (org-wide pre-flight checks such as auth, network, or compliance); treat every entry in workflow.persistent_facts as standing context for the whole run (file:-prefixed entries are paths or globs whose contents load as facts); stash {onCompleteCommand} ← workflow.on_complete (empty string = no-op) for references/report.md §5 to invoke at the terminal stage. After activation completes, execute each entry in workflow.activation_steps_append in order, before the first stage runs.

1. Execute references/detect-and-tier.md.