armelhbobdad 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 frontmatternextStepFile, 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*ProbeOrderarray 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 (wherecustomize.tomllives, 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
| # | Step | File |
|---|---|---|
| 1 | Detect Tools & Set Tier | references/detect-and-tier.md |
| 1b | CCC Index (only when ccc is available) | references/ccc-index.md |
| 2 | Write Config | references/write-config.md |
| 3 | QMD + CCC Registry Hygiene | references/auto-index.md |
| 4 | Report | references/report.md |
| 5 | Workflow Health Check | references/health-check.md |
Invocation Contract
| Aspect | Detail |
|---|---|
| Inputs | (none) |
| Flags | --headless / -H (skip prompts, auto-resolve gates to defaults); --require-tier=<Quick|Forge|Forge+|Deep> (halt with failure if calculated tier does not satisfy the requirement); --orphan-action=<keep|remove> (resolve the orphan-removal gate non-interactively, even outside --headless); --ccc-skip-index (skip CCC indexing; envelope ccc_index.status becomes "skipped" — the fast re-probe lane for an expert re-running only to refresh the detected tier without paying the full ccc re-index cost); --quiet (suppress the human-readable FORGE STATUS banner — pipelines and expert re-runners get the envelope only) |
| Gates | One optional: orphaned QMD collection removal (step 3, Deep tier only; default: Keep, or whatever --orphan-action set) |
| Outputs | forger-sidecar/forge-tier.yaml, forger-sidecar/preferences.yaml, {forge_data_folder}/; when ccc is available, .cocoindex_code/settings.yml (exclusion patterns merged) and the project ccc index |
| Headless | All gates auto-resolve with default action when {headless_mode} is true. Under --headless or --quiet, step 4 emits a single-line SKF_SETUP_RESULT_JSON: {…} envelope as the only stdout line — the FORGE STATUS banner is suppressed. Branch on the envelope's top-level status field: success, tier_failure (require-tier miss), or blocked (any pre-report halt — the error.phase names the cause). skf-emit-result-envelope.py derives status from the payload, so pipelines never compose it from require_tier_satisfied + error. Schema in references/report.md §4. |
| Failure modes | --require-tier not satisfied → status tier_failure, the envelope sets "require_tier_satisfied": false, and the workflow halts before step 5 (interactive runs also print a "REQUIRED TIER NOT MET" block). A write failure (forge-tier.yaml or preferences.yaml could not be written) halts step 2 with a blocked envelope whose error.phase (step 2:write-tools or step 2:init-prefs) and error name the path and reason. |
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>"}topython3 <helper> emit-blockedwhere<helper>is the first existing path of{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.pythen{project-root}/src/shared/scripts/skf-emit-result-envelope.py. Theemit-blockedsubcommand declares zero dependencies (nouv, nopyyaml), so it works even whenuvitself is the thing that's missing.
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).Probe
uvruntime. Runuv --version. Every step invokes shared Python helpers viauv run(PEP 723 inline metadata auto-resolvespyyaml). Ifuvis missing, halt with phaseon-activation:uv-missingand the human diagnostic:"Setup cannot proceed:
uvis not installed. SKF helpers depend onuvto auto-resolve their Python dependencies. Install it from https://docs.astral.sh/uv/getting-started/installation/ and re-run/skf-setup."Load config from
{project-root}/_bmad/skf/config.yamland resolveproject_name,output_folder,user_name,communication_language,document_output_language,skills_output_folder,forge_data_folder,sidecar_path. Halt with phaseon-activation:config-missingif the file does not exist, oron-activation:config-malformedif the YAML is invalid, with the matching human diagnostic.Reconcile
{headless_mode}withpreferences.yaml: OR the parsed flag withheadless_mode: truefrom the YAML.Resolve workflow customization. Run:
python3 {project-root}/_bmad/scripts/resolve_customization.py \ --skill {skill-root} --key workflowThe 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>.tomlunder{project-root}(team overrides, committed), and_bmad/custom/<skill-name>.user.tomlunder{project-root}(personal overrides, gitignored). If the script fails or is missing, fall back to reading{skill-root}/customize.tomldirectly.Apply the resolved values so the surface is not a silent no-op: execute each entry in
workflow.activation_steps_prependin order now (org-wide pre-flight checks such as auth, network, or compliance); treat every entry inworkflow.persistent_factsas 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) forreferences/report.md§5 to invoke at the terminal stage. After activation completes, execute each entry inworkflow.activation_steps_appendin order, before the first stage runs.Execute
references/detect-and-tier.md.