skf-setup

Imported from armelhbobdad/bmad-module-skill-forge (src/skf-setup/SKILL.md). Install upstream with npx skills add armelhbobdad/bmad-module-skill-forge --skill skf-setup. Copyright stays with the author.

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 prepares .cocoindex_code/settings.yml (running ccc init when it is missing), keeps its SKF exclusion patterns in line with the configured folders, 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. If none exists, halt through the On Activation halt contract with phase step <N>:helper-missing — 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 {orphan_action} is non-null, or {headless_mode} or {quiet_mode} is true, resolve the step 3 orphan-removal gate without prompting; step 3 records the decision for the envelope's warnings.
• When {headless_mode} or {quiet_mode} is true, the one line setup displays is the SKF_SETUP_RESULT_JSON: {…} envelope that step 4 builds, or the blocked envelope from a halt. In a standalone run that line is the run's final message, so it is all claude -p prints; step 4 holds its envelope until the health check has finished (or until the tier-miss halt) for that reason. Every display instruction in the step files carries this guard.
• When {headless_mode} or {quiet_mode} is true, write no assistant text at all between tool calls: no status, progress or step-transition notes, however brief.
• When {pipeline_mode} is true, the forger runs setup as one step of a pipeline: display the same envelope line, then return control to the forger, which keeps chaining. The final-message rule above is for a standalone run.

Stages

Invocation Contract

On Activation

Halt contract. Every halt in this workflow that names a phase, below and in the step files, follows this contract; the step 4 tier-miss halt names none and displays its tier_failure envelope instead. When {headless_mode} or {quiet_mode} is true, pipe {"phase":"<phase>","reason":"<reason>","path":"<path>"} to <runner> <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, and <runner> is uv run in the step files, which run after the uv probe below. The halts in this list can fire before uv is proven present, and many Windows installs have python or py but no working python3, so for them try the runners uv run, python3, python and py -3 in that order and stop at the first that exits 0 and prints a line starting SKF_SETUP_RESULT_JSON:. Display the helper's stdout line verbatim, and display nothing else: the envelope's error.reason carries the diagnostic, and a pipeline observer that sees no envelope treats the run as not-completed-cleanly. If neither path exists, or no runner exits 0 and prints that line, display the reason alone as that one line. Interactive runs display the human diagnostic and emit no envelope. The reason is the one-line diagnostic with no ' and no \ in it (use a backtick for a quote and / for a backslash), because it travels inside a single-quoted shell payload; write path with / as well. The helper is stdlib-only (its script header declares no dependencies), so a plain Python interpreter runs emit-blocked even when uv itself is the thing that is missing. --headless and --quiet are known at every halt; headless that comes only from preferences.yaml is known from the uv probe onward.

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, false otherwise), {quiet_mode} (true on --quiet; item 3 also sets it under headless). {pipeline_mode} is not a flag: it is true only when the forger invokes setup as one step of a pipeline and passes it, and false otherwise, including every direct /skf-setup run.

2. 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. Both halts here use path {project-root}/_bmad/skf/config.yaml, and an interactive run displays the reason as its diagnostic:

   • The file does not exist: halt with phase on-activation:config-missing and reason Setup cannot proceed: _bmad/skf/config.yaml was not found.
   • The YAML is invalid: halt with phase on-activation:config-malformed and reason Setup cannot proceed: _bmad/skf/config.yaml is not valid YAML: <first line of the parser error>.

3. Reconcile {headless_mode} with preferences.yaml: OR the parsed flag with headless_mode: true from the YAML. Then, if {headless_mode} is true, set {quiet_mode} to true: setup's headless output is the same envelope-only output, and shared/health-check.md reads {quiet_mode} alone.

4. 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, no path, and reason Setup cannot proceed: uv is not installed. Install it from https://docs.astral.sh/uv/getting-started/installation/ and re-run /skf-setup. An interactive run displays this diagnostic instead:

   "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."

5. Resolve workflow customization. Run:

   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 (when {headless_mode} or {quiet_mode} is true, add no narration of your own around these entries): 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.

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