bmad-module-skill-forge 1.2.0 → 1.4.0

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-quick-skill/steps-c/step-05-validate.md

@@ -1,193 +0,0 @@
----
-nextStepFile: './step-06-write.md'
----
-
-# Step 5: Write & Validate
-
-## 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
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
-### 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:** Halt with: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually."
-
-**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–9 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
-**File 3:** `{skill_package}/metadata.json` — the machine-readable metadata
-
-Confirm after each write: "Written: SKILL.md" / "Written: context-snippet.md" / "Written: metadata.json".
-
-**If any write fails — HARD HALT:**
-
-"**Write failed:** Could not write to `{file_path}`.
-
-Error: {error details}
-
-Please 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 with auto-fix against the skill package written in section 2:
-
-```bash
-npx skill-check check {skill_package} --fix --format json --no-security-scan
-```
-
-This validates frontmatter, description, body limits, links, and formatting — 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
-
-Record quality score and any remaining diagnostics as validation issues.
-
-**If skill-check is NOT available**, perform manual frontmatter check:
-
-- [ ] **Frontmatter present** — file starts with `---` delimiter and has closing `---`
-- [ ] **`name` field** — present, non-empty, lowercase alphanumeric + hyphens only, 1-64 chars
-- [ ] **`name` matches directory** — frontmatter `name` matches the skill output directory name
-- [ ] **`description` field** — present, non-empty, 1-1024 characters
-- [ ] **No unknown fields** — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted
-
-**For each violation, log an issue.** Missing frontmatter or missing required fields are high-severity issues — skills without valid frontmatter will fail `npx skills add` and `npx skill-check check`.
-
-### 5. Validate SKILL.md Body Structure
-
-Check that SKILL.md has these required sections populated:
-
-- [ ] **Overview section** present with package name, repo, language, authority
-- [ ] **Description section** present with non-empty content
-- [ ] **Key Exports section** present (may be empty if confidence is low)
-- [ ] **Usage Patterns section** present (may have README fallback)
-
-**For each missing or empty required section, log an issue.**
-
-### 6. Validate Context Snippet Format
-
-Check context-snippet.md format compliance:
-
-- [ ] **Vercel-aligned indexed format** — pipe-delimited with version, retrieval instruction, section anchors
-- [ ] **First line** matches pattern: `[{name} v{version}]|root: {prefix}{name}/` where prefix is `skills/` (draft form) or any IDE skill root (`.{dir}/skills/`)
-- [ ] **Second line** starts with: `|IMPORTANT:`
-- [ ] **Approximate token count** is ~80-120 tokens
-
-**If format is wrong, log an issue.**
-
-### 7. Validate Metadata JSON
-
-Check metadata.json has required fields:
-
-- [ ] `name` — present, non-empty
-- [ ] `version` — present (auto-detected or "1.0.0")
-- [ ] `source_authority` — must be "community"
-- [ ] `source_repo` — present, valid GitHub URL
-- [ ] `language` — present, non-empty
-- [ ] `generated_by` — must be "quick-skill"
-- [ ] `generation_date` — present
-- [ ] `stats.exports_documented` — present, number
-- [ ] `stats.exports_public_api` — present, number
-- [ ] `stats.exports_total` — present, number
-- [ ] `stats.public_api_coverage` — present, number
-- [ ] `stats.total_coverage` — present, number
-- [ ] `confidence_tier` — present
-
-**For each missing or invalid field, log an issue.**
-
-### 8. Security Scan (if skill-check available)
-
-Run security scan on the compiled skill package:
-
-```bash
-npx skill-check check {skill_package} --format json
-```
-
-(Security scan is enabled by default when `--no-security-scan` is omitted.)
-
-Record any security findings as advisory warnings. Security issues do not block output.
-
-**If skill-check unavailable:** Skip with note in validation results.
-
-### 9. 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.
-
-### 10. 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.
-