bmad-module-skill-forge 1.1.0 → 1.3.0

package/src/skf-quick-skill/steps-c/step-04-compile.md

@@ -1,10 +1,15 @@
 ---
-nextStepFile: './step-05-validate.md'
+nextStepFile: './step-05-write-and-validate.md'
 skillTemplateData: 'assets/skill-template.md'
+quickMetadataRendererProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-render-quick-metadata.py'
+  - '{project-root}/src/shared/scripts/skf-render-quick-metadata.py'
 ---
 
 # Step 4: Compile
 
+Communicate with the user in `{communication_language}`. Compile generated content (descriptions, usage notes, summaries) in `{document_output_language}`.
+
 ## STEP GOAL:
 
 To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-aligned indexed format, and metadata.json with `source_authority: community` from the extraction inventory. Present compiled output for review before validation.
@@ -17,8 +22,6 @@ To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-alig
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Skill Template
 
 Load {skillTemplateData} to understand:
@@ -50,8 +53,8 @@ description: >
 
 **Required sections (after frontmatter):**
 - **Overview:** Package name, repository, language, source authority, generation date
-- **Description:** From extraction_inventory.description (README-derived)
-- **Key Exports:** From extraction_inventory.exports — list each with name, type, brief description
+- **Description:** From `{overrides.description}` if set (subject to the same length/voice checks as extracted descriptions); otherwise from extraction_inventory.description (README-derived)
+- **Key Exports:** From `{overrides.exports}` if set (comma-separated names parsed and trimmed; empty items skipped); otherwise from extraction_inventory.exports — list each with name, type, brief description
 - **Usage Patterns:** From extraction_inventory.usage_patterns (README examples)
 
 **Optional sections (include when data available):**
@@ -65,7 +68,9 @@ description: >
 
 ### 3. Generate Context Snippet
 
-Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
+**If `{overrides.skip_snippet}` is true** — skip generation and note in the §5 preview: "context-snippet.md skipped per `--skip-snippet` override." Step-05 §2 will skip the corresponding write; step-05 §5 advisory snippet validation will report a "skipped" entry.
+
+Otherwise, create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
 ```
 [{skill_name} v{version}]|root: skills/{skill_name}/
@@ -82,53 +87,37 @@ Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
 ### 4. Generate Metadata JSON
 
-Generate metadata.json following the exact structure defined in {skillTemplateData} metadata.json section. Populate fields from extraction_inventory:
-
-```json
-{
-  "name": "{skill_name}",
-  "version": "{extraction_inventory.version or 1.0.0}",
-  "description": "{brief description of the skill}",
-  "skill_type": "single",
-  "source_authority": "community",
-  "source_repo": "{resolved_url}",
-  "source_root": "{resolved_source_path}",
-  "source_commit": "{commit_sha_if_available}",
-  "source_package": "{package_name from manifest}",
-  "language": "{language}",
-  "generated_by": "quick-skill",
-  "generation_date": "{current ISO date}",
-  "confidence_tier": "Quick",
-  "spec_version": "1.3",
-  "exports": ["{export_1}", "{export_2}"],
-  "confidence_distribution": {
-    "t1": 0,
-    "t1_low": "{number of exports found — must be integer, not string}",
-    "t2": 0,
-    "t3": 0
-  },
-  "tool_versions": {
-    "ast_grep": null,
-    "qmd": null,
-    "skf": "{skf_version}"   // Resolution chain: _bmad/skf/package.json → npm require → _bmad/skf/VERSION → "unknown"
-  },
-  "stats": {
-    "exports_documented": "{number of exports found}",
-    "exports_public_api": "{number of exports found}",
-    "exports_internal": 0,
-    "exports_total": "{number of exports found}",
-    "public_api_coverage": 1.0,
-    "total_coverage": 1.0,
-    "scripts_count": 0,
-    "assets_count": 0
-  },
-  "dependencies": [],
-  "compatibility": "{semver-range or null}"
-}
+Run the shared renderer against the assembled state. The helper applies the constants, echoes input-derived fields, computes export counts and the ISO 8601 UTC timestamp, and emits the canonical envelope per `{skillTemplateData}` § "metadata.json Format".
+
+**Resolve `{quickMetadataRenderer}`** from `{quickMetadataRendererProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt rendering using the constants + input-derived rules previously documented in this section (the helper replaces but does not eliminate those rules — they live in the helper now).
+
+**Probe `tool_versions.skf` first** (the helper expects it as input — the filesystem walk stays here because the helper does no I/O):
+
+1. Read `{project-root}/_bmad/skf/package.json` → take `version`
+2. If absent, read `{project-root}/_bmad/skf/VERSION`
+3. If absent, set to `"unknown"`
+
+Build the input payload from the extraction inventory + step-01 resolution + the probed `tool_versions.skf` and pipe it to the renderer:
+
+```bash
+echo '{"name":"<name>","version":"<v>","description":"<desc>","language":"<lang>","source_repo":"<url>","source_root":"<path or empty>","source_commit":"<source_ref or empty>","source_package":"<package or name>","exports":[{"name":"...","type":"..."}],"dependencies":["..."],"compatibility":"<semver-range or empty>","language_hint":<hint or null>,"scope_hint":<hint or null>,"skf_version":"<probed>"}' \
+  | python3 {quickMetadataRenderer}
 ```
 
+The renderer emits the rendered metadata.json on stdout. Capture the output as `metadata` for the §5 preview and step-05 §2's deliverable write.
+
+**Schema is canonical in the renderer.** When `{skillTemplateData}` adds a field, the renderer is updated to populate it (constants gain a row; input-derived fields gain a payload key). Do not hand-edit the rendered envelope here — the helper is the single source of truth for the population logic.
+
 ### 5. Present Compiled Output for Review
 
+**If `{headless_mode}` is true** — skip the inline preview (no human reviewer reads it) and emit a one-line summary instead:
+
+"Compiled: SKILL.md ({section_count} sections, {export_count} exports), context-snippet.md (~{snippet_token_count} tokens), metadata.json (version {version}, confidence {confidence}). Auto-approving [C]."
+
+Then proceed directly to §6 — the GATE default action takes over.
+
+**Otherwise (interactive mode):**
+
 "**Compilation complete. Review before validation:**
 
 ---
@@ -154,25 +143,29 @@ Generate metadata.json following the exact structure defined in {skillTemplateDa
 **Extraction confidence:** {confidence}
 **Exports documented:** {count}
 
-Review the output above. When ready, continue to validation."
+Review the output above, then choose: [C] continue to validation, [E] edit the description, [S] adjust scope and re-extract, or [Q] quit without writing."
 
 ### 6. Present MENU OPTIONS
 
-Display: **Select:** [C] Continue to Validation
+Display: **Select:** [C] Continue to Validation · [E] Edit description · [S] Adjust scope and re-extract · [Q] Quit without writing
 
 #### Menu Handling Logic:
 
-- IF C: Load, read entire file, then execute {nextStepFile}
-- IF Any other: Help user adjust compiled output, then redisplay menu
+- **IF C** — Load, read entire file, then execute {nextStepFile}.
+- **IF E** — Ask the user for a replacement description ("New description (1–1024 chars):"). Update SKILL.md frontmatter `description` and `metadata.json.description` in the in-memory compiled output, then re-render the §5 preview and redisplay this menu. Do not re-run extraction.
+- **IF S** — Ask the user for an adjusted `scope_hint` ("New scope (e.g. `src/server/`, `packages/core/`):") and optionally a `language_hint`. Update the extraction context with the new hints, then load `./step-03-quick-extract.md` to re-extract. The new extraction returns to §1 of this step on completion. Discards the prior compiled output.
+- **IF Q** — HARD HALT with **exit code 6 (compile-cancelled)** per the SKILL.md exit-code map: "Compilation cancelled. No files written." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "compile"`, `error.code: "compile-cancelled"`, `skill_package: null`). Do not proceed to validation; do not write any artifacts.
+- **IF Any other** — Help the user adjust the compiled output (treated as a free-form revision request), then redisplay the menu.
 
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting compiled output
 - **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve compiled output"
-- ONLY proceed to validation when user selects 'C'
-- User can request changes to the compiled output before proceeding
+- ONLY proceed to validation when the user selects 'C' (or headless auto-approve)
+- [E] is local: re-renders the preview without re-running extraction
+- [S] is the heavy option: it discards the compiled output and re-runs step-03 with new hints
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN the user reviews the compiled output and selects 'C' will you load and read fully `{nextStepFile}` to execute validation.
+ONLY WHEN the user reviews the compiled output and selects 'C' (or [Q] HALTs / [S] re-runs / [E] redisplays) will you load and read fully `{nextStepFile}` to execute validation.
 

package/src/skf-quick-skill/steps-c/step-05-write-and-validate.md

@@ -0,0 +1,164 @@
+---
+nextStepFile: './step-06-finalize.md'
+frontmatterValidatorProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
+  - '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
+outputValidatorProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py'
+  - '{project-root}/src/shared/scripts/skf-validate-output.py'
+---
+
+# Step 5: Write & Validate
+
+Communicate with the user in `{communication_language}`. Validation reports are user-facing — render their narrative content in `{document_output_language}`.
+
+## STEP GOAL:
+
+To write the compiled SKILL.md, context-snippet.md, and metadata.json to the versioned skill package, then validate them on disk against the agentskills.io specification at community tier. Writing happens here (before step-06 finalization) because `skill-check` is a file-based CLI — it reads artifacts from disk — so the files must exist before validation runs. Report any gaps or issues. Validation is advisory — issues are reported but do not block the workflow.
+
+## Rules
+
+- Write exactly what was compiled — do not modify content during writing
+- Validation is advisory — report issues but never block output
+- Do not modify compiled content post-validation — report only
+- Community-tier validation (lighter than official requirements)
+
+## MANDATORY SEQUENCE
+
+### 1. Create Output Directory
+
+Resolve `{version}` from the extraction inventory's detected version, defaulting to `1.0.0` if not detected. Create the skill output directories:
+
+```
+{skill_group}                          # {skills_output_folder}/{repo_name}/
+{skill_package}                        # {skills_output_folder}/{repo_name}/{version}/{repo_name}/
+```
+
+If `{skill_package}` already exists, confirm with user before overwriting:
+
+"**Directory `{skill_package}` already exists.** Overwrite will replace the prior compiled output; validation results, result contracts, and any manual tweaks from the previous run will not be preserved. Overwrite existing files? [Y/N]"
+
+- **If user selects Y:** Proceed to section 2.
+- **If user selects N:** HARD HALT with **exit code 5 (overwrite-cancelled)** per the SKILL.md exit-code map: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "write-and-validate"`, `error.code: "overwrite-cancelled"`, `skill_package` set to the existing path that was preserved). Disk write of the `-latest.json` envelope is REQUIRED here since `{skill_package}` is known.
+
+**GATE [default: Y]** — If `{headless_mode}` is true, auto-proceed with Y and log: "headless: overwriting existing `{skill_package}`".
+
+### 2. Write Deliverables
+
+Write the three compiled artifacts to the skill package so that validation in sections 3–7 has files on disk to read:
+
+**File 1:** `{skill_package}/SKILL.md` — the compiled skill document
+**File 2:** `{skill_package}/context-snippet.md` — the compressed context snippet. **Skip this write** if `{overrides.skip_snippet}` was set; the artifact is omitted from `outputs`.
+**File 3:** `{skill_package}/metadata.json` — the machine-readable metadata
+
+Confirm after each write: "Written: SKILL.md" / "Written: context-snippet.md" / "Written: metadata.json". When `--skip-snippet` is active, log "Skipped: context-snippet.md (--skip-snippet)" instead of the snippet write confirmation.
+
+**If any write fails — HARD HALT (exit code 4, write-failure):** Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "write-and-validate"`, `error.code: "write-failure"`, `error.details: {failed_path: <path>, error: <details>}`, `skill_package` set, `outputs` listing any files that did write successfully before the failure).
+
+"**Write failed:** Could not write to `{file_path}`.
+
+Error: {error details}
+
+Check:
+- Does the output directory exist and is it writable?
+- Is there sufficient disk space?
+- Are there permission issues?"
+
+### 3. Check Tool Availability
+
+Run: `npx skill-check -h`
+
+- If succeeds (returns usage information): Continue to automated validation (section 4)
+- If fails (command not found or error): Skip to manual fallback in section 4
+
+**Important:** Use the verification command. Do not assume availability — empirical check required.
+
+### 4. Validate SKILL.md via skill-check (if available)
+
+**If `npx skill-check` is available**, run automated validation + security scan in one invocation against the skill package written in section 2 (security scan is enabled by default when `--no-security-scan` is omitted, so the same call covers §6 and avoids paying the npx startup cost twice):
+
+```bash
+npx skill-check check {skill_package} --fix --format json
+```
+
+This validates frontmatter, description, body limits, links, and formatting; runs the security scan; and auto-fixes deterministic issues (field ordering, slug format, required fields, trailing newlines).
+
+**Parse JSON output** to extract:
+- `qualityScore` — overall score (0-100)
+- `diagnostics[]` — remaining issues after auto-fix
+- `fixed[]` — issues automatically corrected
+- `security[]` (when present) — security findings, recorded as advisory warnings (security issues do not block output)
+
+Record quality score, remaining diagnostics, and security findings as validation issues.
+
+**If skill-check is NOT available**, run the shared frontmatter validator instead of an LLM-walked checklist. Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If no candidate exists, log a high-severity issue ("frontmatter validator unavailable — both `npx skill-check` and `skf-validate-frontmatter.py` missing") and skip frontmatter validation.
+
+```bash
+python3 {frontmatterValidator} {skill_package}/SKILL.md --skill-dir-name {repo_name}
+```
+
+The validator emits JSON with `status` (`pass`/`fail`), `issues[]` (each with `severity`, `code`, `message`), and `frontmatter` (the parsed name/description). It checks frontmatter delimiters, name format (Unicode letters + digits + hyphens, no consecutive/trailing hyphens), name-directory match, description presence and length, and unknown fields against the agentskills.io spec — the same shape this step would otherwise hand-walk. Record each `issues[]` entry as a validation issue with its reported severity. Missing frontmatter or missing required fields are high-severity — skills without valid frontmatter will fail `npx skills add` and `npx skill-check check`.
+
+### 5. Validate Body, Snippet, and Metadata via skf-validate-output.py
+
+Run the shared output validator against the on-disk skill package — it performs the body-structure, snippet-format, and metadata-shape checks that this step previously walked by hand. Pass `--skip-frontmatter` since §4 has already covered frontmatter.
+
+**Resolve `{outputValidator}`:** probe `{outputValidatorProbeOrder}` (installed first, dev fallback); first existing path wins. If neither candidate exists, log a high-severity issue ("output validator unavailable — `skf-validate-output.py` missing") and skip body/snippet/metadata validation.
+
+```bash
+python3 {outputValidator} {skill_package} --generated-by quick-skill --skip-frontmatter
+```
+
+The validator emits JSON with `result` (PASS/FAIL), `validation.skill_md.body[]`, `validation.context_snippet.issues[]`, `validation.metadata.issues[]`, and a severity-bucketed `summary`. Record each issue as a validation issue at its reported severity.
+
+Coverage replaces these former hand-walked checklists:
+
+- **Body structure** — Overview, Description, Key Exports, Usage sections present (medium when missing)
+- **Context snippet** — `[{name} v{version}]|root: ...` first line, `|IMPORTANT:` second line, ~80–120-token length
+- **Metadata** — required string fields (`name`, `version`, `source_authority`, `language`, `generation_date`), `source_repo`, `generated_by`, `confidence_tier`, and `stats` numerics (`exports_documented`, `exports_public_api`, `exports_total`, `public_api_coverage`, `total_coverage`)
+
+### 6. Security Scan (covered by §4)
+
+Security findings are already collected from the §4 invocation (no separate `npx` round trip needed — `skill-check check ... --fix --format json` runs the security scan by default). If skill-check was unavailable in §3, log "security scan skipped — skill-check unavailable" in validation results.
+
+### 7. Report Validation Results
+
+"**Validation complete:**
+
+**SKILL.md:** {pass/issues found} (quality score: {score}/100 if skill-check was available)
+{list any issues}
+{list any auto-fixed issues}
+
+**context-snippet.md:** {pass/issues found}
+{list any issues}
+
+**metadata.json:** {pass/issues found}
+{list any issues}
+
+**Security:** {pass/warn/skipped}
+{list any security findings}
+
+**Overall:** {pass / N issues found}
+
+{If issues found:}
+These issues are advisory for community-tier skills. You can proceed to finalize or go back to adjust.
+
+**Proceeding to finalize...**"
+
+Set `validation_result` with pass/fail status, quality score, and issues list.
+
+### 8. Auto-Proceed to Finalize
+
+#### Menu Handling Logic:
+
+- After validation report, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step — validation is advisory
+- Proceed directly to finalize step after reporting results
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN deliverables have been written to `{skill_package}` and validation checks are complete and results reported will you load and read fully `{nextStepFile}` to execute finalization.
+

package/src/skf-quick-skill/steps-c/{step-06-write.md → step-06-finalize.md}

@@ -1,9 +1,14 @@
 ---
 nextStepFile: './step-07-health-check.md'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
 # Step 6: Finalize
 
+Communicate with the user in `{communication_language}`. Render the user-facing completion summary content in `{document_output_language}`.
+
 ## STEP GOAL:
 
 To finalize the skill by creating the active-version pointer, displaying the completion summary, and writing the result contract. Deliverables (SKILL.md, context-snippet.md, metadata.json) were already written in step-05 so that validation could run against files on disk; this step only performs the post-write finalization.
@@ -16,21 +21,23 @@ To finalize the skill by creating the active-version pointer, displaying the com
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Create Active Pointer (atomic flip, Windows-safe)
 
+**If `{overrides.no_active_pointer}` is true** — skip the helper invocation entirely. Log: "Active pointer: skipped per `--no-active-pointer` override." Do not update `{skill_group}/active`. Proceed to §2 with the active-pointer line omitted from the completion summary and the outputs payload.
+
 `{skill_group}` and `{skill_package}` were computed in step-05 §1 from `{skills_output_folder}`, `{repo_name}`, and `{version}`; `{version}` was resolved from the extraction inventory. Reuse the same values here — do not recompute.
 
 Create or update the `active` pointer at `{skill_group}/active` pointing to `{version}` using the shared atomic-flip helper. The helper acquires an `flock` on `{skill_group}/active.skf-lock`, refuses to replace a non-link at `{skill_group}/active` (protecting against accidental `rm -rf` of a real directory), and uses a rename-over-symlink pattern so the update is atomic from a concurrent reader's perspective. On Windows the helper automatically falls back to a directory junction (`mklink /J`) when `os.symlink` fails with `PRIVILEGE_NOT_HELD` / `ACCESS_DENIED` — junctions require no admin elevation and resolve identically for `skf-skill-inventory`'s consumers:
 
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists — the active-pointer flip MUST go through the atomic helper.
+
 ```bash
-python3 {project-root}/src/shared/scripts/skf-atomic-write.py flip-link \
+python3 {atomicWriteHelper} flip-link \
   --link {skill_group}/active \
   --target {version}
 ```
 
-The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a link — in that case, halt with: "Refusing to flip `{skill_group}/active` — existing path is not a symlink or junction. Investigate manually; expected a link pointing at a version directory." A common cause on Windows is a prior run that executed `ln -s` under git-bash without Developer Mode enabled, which silently wrote a full directory copy; remove that copy and retry.
+The helper returns non-zero (helper exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a link — in that case, HARD HALT the workflow with **exit code 7 (finalize-blocked)** per the SKILL.md exit-code map: "Refusing to flip `{skill_group}/active` — existing path is not a symlink or junction. Investigate manually; expected a link pointing at a version directory." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "finalize"`, `error.code: "finalize-blocked"`, `skill_package` set, `outputs` listing the deliverables already on disk from step-05). A common cause on Windows is a prior run that executed `ln -s` under git-bash without Developer Mode enabled, which silently wrote a full directory copy; remove that copy and retry.
 
 **Never `rm` + `ln -s` the active pointer manually.** The bare-rm pattern has two failure modes: (1) a concurrent reader sees a missing `active` mid-flip, and (2) a bug or typo that replaces `{skill_group}/active` with a plain directory turns the next manual `rm -rf {skill_group}/active` into data loss. The helper encapsulates both guards and the Windows junction fallback.
 
@@ -45,12 +52,13 @@ Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{ki
 **Source:** {resolved_url}
 **Authority:** community
 **Confidence:** {extraction confidence}
+{If `scope_hint` is non-empty, add:} **Scope:** {scope_hint}
 
 **Files written:**
 - `{skill_package}/SKILL.md`
-- `{skill_package}/context-snippet.md`
+- `{skill_package}/context-snippet.md` (omit this line when `--skip-snippet` was set)
 - `{skill_package}/metadata.json`
-- `{skill_group}/active` -> `{version}`
+- `{skill_group}/active` -> `{version}` (omit this line when `--no-active-pointer` was set)
 
 **Exports documented:** {count}
 **Validation:** {pass / N issues (advisory)}
@@ -70,4 +78,4 @@ Write the result contract per `shared/references/output-contract-schema.md`: the
 
 ### 4. Chain to Health Check
 
-ONLY WHEN the active pointer has been created and the completion summary and result contract have been written will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
+ONLY WHEN the active pointer has been created and the completion summary and result contract have been written will you then load, read the full file, and proceed to `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.

package/src/skf-quick-skill/steps-c/step-07-health-check.md

@@ -1,12 +1,14 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
 # Step 7: Workflow Health Check
 
+Communicate with the user in `{communication_language}`.
+
 ## STEP GOAL:
 
 Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of quick-skill — after the shared health check completes, the workflow is fully done.
@@ -19,4 +21,4 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## MANDATORY SEQUENCE
 
-Load `{nextStepFile}`, read it fully, then execute it.
+Load `{nextStepFile}`, read it fully, then proceed to execute it.

package/src/skf-setup/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize forge environment, detect tools, and set capability tier
 
 ## Overview
 
-Initializes the forge environment by detecting available tools, determining the capability tier (Quick/Forge/Forge+/Deep), writing persistent configuration, and optionally indexing the project for deep search. This is a fully autonomous workflow — no user interaction is required during execution.
+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. The workflow is autonomous with one optional gate — orphaned QMD collection removal in step 3 (Deep tier only; default action: Keep) — which auto-resolves to the default when `{headless_mode}` is true.
 
 ## Role
 
@@ -17,7 +17,7 @@ You are a system executor performing environment resolution. Run each step in se
 
 These rules apply to every step in this workflow:
 
-- Fully autonomous — all steps auto-proceed with no user interaction until the final report
+- Autonomous with one optional gate (step 3 orphan-removal prompt; default: Keep) — all other steps auto-proceed with no user interaction until the final report
 - Read each step file completely before taking any action
 - Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
@@ -29,9 +29,9 @@ These rules apply to every step in this workflow:
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 1 | Detect Tools & Set Tier | steps-c/step-01-detect-and-tier.md | Yes |
-| 1b | CCC Index | steps-c/step-01b-ccc-index.md | Yes |
+| 1b | CCC Index (only when ccc is available) | steps-c/step-01b-ccc-index.md | Yes |
 | 2 | Write Config | steps-c/step-02-write-config.md | Yes |
-| 3 | QMD Hygiene | steps-c/step-03-auto-index.md | Yes |
+| 3 | QMD + CCC Registry Hygiene | steps-c/step-03-auto-index.md | Yes |
 | 4 | Report | steps-c/step-04-report.md | Yes |
 | 5 | Workflow Health Check | steps-c/step-05-health-check.md | Yes |
 
@@ -39,17 +39,32 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | (none — fully autonomous) |
+| **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) |
 | **Gates** | One optional: orphaned QMD collection removal (step 3, Deep tier only; default: Keep) |
-| **Outputs** | forge-tier.yaml, preferences.yaml, forge-data directories |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **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. step-04 emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope after the human-readable banner so pipelines can parse the outcome without reading forge-tier.yaml. Schema documented in `steps-c/step-04-report.md` §4. |
+| **Failure modes** | `--require-tier` not satisfied → step-04 prints a "REQUIRED TIER NOT MET" block, the JSON envelope sets `"require_tier_satisfied": false`, and the workflow halts before step-05. |
+| **Exit codes** | The workflow runs as an LLM-driven sequence rather than a CLI process, so "exit code" describes the agent's terminal state for a calling pipeline that reads `SKF_SETUP_RESULT_JSON`. **0 — success** (no JSON `error` field, all writes completed, `require_tier_satisfied` is `true` or `null`). **1 — required-tier failure** (`require_tier_satisfied` is `false`; envelope still emitted with full state for diagnosis). **2 — write failure** (forge-tier.yaml or preferences.yaml could not be written; envelope `error` field names the path and reason). Pipelines should branch on the JSON `require_tier_satisfied` and `error` fields rather than process exit codes. |
 
 ## On Activation
 
-1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+1. **Probe `uv` runtime.** Run `uv --version`. Every step in this workflow invokes shared Python helpers via `uv run` (PEP 723 inline metadata is what auto-resolves `pyyaml` for the helpers that need it — see `docs/getting-started.md`). If `uv` is missing, halt now with a single cohesive diagnostic rather than letting five separate steps each fail with `uv: command not found`:
+
+   "**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`. (See the Prerequisites section in <https://docs.astral.sh/uv/getting-started/installation/> or the SKF docs at `docs/getting-started.md` for details.)"
+
+2. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name` (from installer-generated config.yaml, not module.yaml), `output_folder`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+   **If the file does not exist**, halt with a single cohesive "wrong directory" diagnostic rather than failing later with a generic file-read error from a downstream step:
+
+   "**Setup cannot proceed: `{project-root}/_bmad/skf/config.yaml` was not found.** This directory does not appear to be an SKF-initialised project. From the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module — see `docs/getting-started.md`), then re-run `/skf-setup`. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer."
+
+   **If the file exists but is malformed YAML**, halt and surface the parser error along with the file path so the user can fix it directly: "**Setup cannot proceed: `{project-root}/_bmad/skf/config.yaml` is not valid YAML.** Parser error: {error_message}. Open the file and repair the YAML, or restore from version control."
+
+3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+4. **Resolve `{require_tier}`**: parse `--require-tier=<value>` from the invocation arguments. Accept exactly `Quick`, `Forge`, `Forge+`, or `Deep` (case-sensitive). If absent or unparseable, leave as null (no tier requirement).
 
-3. Load, read the full file, and then execute `./steps-c/step-01-detect-and-tier.md` to begin the workflow.
+5. Load, read the full file, and then execute `./steps-c/step-01-detect-and-tier.md` to begin the workflow.

package/src/skf-setup/references/tier-rules.md

@@ -7,9 +7,9 @@
 | ast-grep | `ast-grep --version` | Returns version string without error |
 | gh | `gh --version` | Returns version string without error |
 | qmd | `qmd status` | Returns status indicating initialized and operational |
-| ccc | Step A: `ccc --help` Step B: `ccc doctor` | Step A: exits 0 (binary exists). Step B: daemon running, version string, model check OK |
+| ccc | Step A: `ccc --help` Step B: `ccc doctor` | Step A: exits 0 AND help output identifies the binary as cocoindex-code. Step B: daemon healthy. See `steps-c/step-01-detect-and-tier.md` §7 for the full identity-marker procedure. |
 
-**Important:** Use verification commands, not existence checks (`which`, `command -v`). A tool must be functional, not just present on PATH. For daemon-based tools (ccc), verify both binary existence and daemon health.
+**Important:** Use verification commands, not existence checks (`which`, `command -v`). A tool must be functional, not just present on PATH. For daemon-based tools (ccc), verify both binary identity and daemon health — a binary with the right name but the wrong implementation is a false positive, not a tool.
 
 ## Tier Calculation