bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/skf-create-skill/{steps-c/step-07-generate-artifacts.md → references/generate-artifacts.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-08-report.md'
+nextStepFile: 'report.md'
 forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
@@ -10,6 +10,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Generate Artifacts
 
 ## STEP GOAL:
@@ -24,8 +26,6 @@ To write all compiled content to disk — 4 deliverable files to `{skill_package
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Create Directory Structure
 
 Resolve `{version}` from the skill brief's `version` field. Create the following directories:
@@ -71,7 +71,7 @@ Write these 4 files from the compiled content:
 - One file per detected asset, copied from source with content preserved
 - Only created when `assets_inventory` is non-empty
 
-**Note on `file_type: "doc"` entries** (promoted authoritative docs from step-03 §2a):
+**Note on `file_type: "doc"` entries** (promoted authoritative docs from step 3 §2a):
 
 Promoted docs are tracked in `file_entries[]` with `file_type: "doc"` for drift detection but are **NOT** copied into the skill package. The source file remains at its original location outside `{skill_package}`. Step-07 must skip any `file_entries[]` row where `file_type == "doc"` when iterating for file copy — these entries exist only for provenance tracking, not bundling. Step-07 verification (§5) also does not check for doc files in the skill package.
 
@@ -87,7 +87,7 @@ Write these 3 files from the compiled content:
 
 **File 7:** `{forge_version}/extraction-rules.yaml`
 - Language and ast-grep schema used for this extraction (for reproducibility)
-- Note: This file is generated here from extraction data collected during steps 3-4, not assembled in step-05
+- Note: This file is generated here from extraction data collected during steps 3-4, not assembled in step 5
 
 ### 4. Create Active Symlink (atomic flip)
 
@@ -108,16 +108,16 @@ The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as
 After all files are written, verify:
 - All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, **and** either at least one file in `references/` **or** `references/` is empty AND Tier-2 content is inline in SKILL.md — see "Empty `references/` exception" below), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
 - The `active` symlink at `{skill_group}/active` resolves to `{version}`
-- Store `ref_count` = count of files written to `references/` for use in step-08 report
+- Store `ref_count` = count of files written to `references/` for use in step 8 report
 - List each file with its path and size
 
-**Empty `references/` exception (Tier-2 inline):** `ref_count == 0` is a valid completion state when step-06 kept Tier-2 content inline in SKILL.md — e.g., the body was already under the size limit, or `skill-check` was unavailable and the manual fallback (step-06 §3) skipped the split. In that case, append a single line to `{forge_version}/evidence-report.md` recording the inline state so downstream tooling and audits can distinguish "inline by design" from "split-body skipped due to error":
+**Empty `references/` exception (Tier-2 inline):** `ref_count == 0` is a valid completion state when step 6 kept Tier-2 content inline in SKILL.md — e.g., the body was already under the size limit, or `skill-check` was unavailable and the manual fallback (step 6 §3) skipped the split. In that case, append a single line to `{forge_version}/evidence-report.md` recording the inline state so downstream tooling and audits can distinguish "inline by design" from "split-body skipped due to error":
 
 ```
-ref_count: 0  # Tier-2 kept inline in SKILL.md (no split performed in step-06)
+ref_count: 0  # Tier-2 kept inline in SKILL.md (no split performed in step 6)
 ```
 
-When `ref_count > 0` is expected (because step-06 ran a split) but no files were written, halt with: "Split-body produced zero reference files. Investigate step-06 output before retrying — empty `references/` after a split is never a valid state."
+When `ref_count > 0` is expected (because step 6 ran a split) but no files were written, halt with: "Split-body produced zero reference files. Investigate step 6 output before retrying — empty `references/` after a split is never a valid state."
 
 **If any write failed:**
 Halt with: "Artifact generation failed: could not write `{file_path}`. Check permissions and disk space."
@@ -159,7 +159,7 @@ qmd embed --collection {name}-extraction  # generates vector embeddings for sema
 
 **Registry update:**
 
-Read `{forgeTierConfig}` and update the `qmd_collections` array **under an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`** (see step-03b §4 for the full pattern — acquire lock → read → modify → atomic write via `skf-atomic-write.py write` → release). If `flock` is unavailable, fall back to read-CAS-by-mtime.
+Read `{forgeTierConfig}` and update the `qmd_collections` array **under an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`** (see step 3b §4 for the full pattern — acquire lock → read → modify → atomic write via `skf-atomic-write.py write` → release). If `flock` is unavailable, fall back to read-CAS-by-mtime.
 
 If an entry with `name: "{name}-extraction"` already exists, replace it. Otherwise, append:
 
@@ -187,7 +187,7 @@ Ensure the source path used for extraction is indexed by ccc and registered in t
 
 **Index verification:**
 
-Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. This is a no-op if the source was already indexed during setup or step-02b.
+Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. This is a no-op if the source was already indexed during setup or step 2b.
 
 **Registry update:**
 

package/src/skf-create-skill/{steps-c/step-09-health-check.md → references/health-check.md}

@@ -5,6 +5,8 @@
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 9: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,9 +15,9 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-08
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 8
 - Delegate directly to `{nextStepFile}` with no additional commentary
-- In batch mode, this step is only reached after the final brief — step-08 loops back to step-01-load-brief for remaining briefs and skips chaining here
+- In batch mode, this step is only reached after the final brief — step 8 loops back to load-brief for remaining briefs and skips chaining here
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 
 ## MANDATORY SEQUENCE

package/src/skf-create-skill/{steps-c/step-01-load-brief.md → references/load-brief.md}

@@ -1,9 +1,19 @@
 ---
-nextStepFile: './step-02-ecosystem-check.md'
+nextStepFile: 'ecosystem-check.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 preferencesFile: '{sidecar_path}/preferences.yaml'
+# Resolve `{validateBriefSchemaHelper}` to the first existing path; HALT if
+# neither candidate exists. §3 relies on the helper for deterministic
+# schema-conformance checks (required fields, regex patterns, enum
+# membership, docs-only conditional rules) so this stage does not re-run
+# those checks in prose.
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Load Brief
 
 ## STEP GOAL:
@@ -17,8 +27,6 @@ To load and validate the skill-brief.yaml compilation config, resolve the source
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Forge Tier
 
 Load `{forgeTierFile}` completely.
@@ -30,14 +38,14 @@ Halt with: "Forge halted: No forge configuration found. Run [SF] Setup Forge fir
 Extract and report:
 - `tier`: Quick, Forge, Forge+, or Deep
 - `tools`: which tools are available (gh, ast-grep, ccc, qmd)
-- `ccc_index`: ccc index state (status, indexed_path, last_indexed) — needed by step-02b
+- `ccc_index`: ccc index state (status, indexed_path, last_indexed) — needed by step 2b
 
 **Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is one of the exact valid tier values (`Quick`, `Forge`, `Forge+`, `Deep`), use it instead of the detected tier. **If `tier_override` is set but is NOT one of those four values:** log a warning — "Unknown tier_override `{value}` in preferences.yaml; falling back to detected tier `{detected_tier}`. Valid values: Quick, Forge, Forge+, Deep." — and use the detected tier. Never silently apply an unknown override value, and never map it heuristically to a tier.
 
 **Record the decision:** append an entry to the in-context `headless_decisions[]` buffer (initialize to `[]` at the start of this step if absent) whenever a non-interactive choice is made automatically — both the valid-override path AND the rejected-override path:
 
-- Valid override applied: `{step: "step-01-load-brief", gate: "tier-override", decision: "apply", value: "{tier_override}", rationale: "explicit preferences.yaml tier_override", timestamp: {ISO}}`
-- Invalid override rejected: `{step: "step-01-load-brief", gate: "tier-override", decision: "reject-invalid", value: "{tier_override}", fallback: "{detected_tier}", rationale: "tier_override not in {Quick,Forge,Forge+,Deep}", timestamp: {ISO}}`
+- Valid override applied: `{step: "load-brief", gate: "tier-override", decision: "apply", value: "{tier_override}", rationale: "explicit preferences.yaml tier_override", timestamp: {ISO}}`
+- Invalid override rejected: `{step: "load-brief", gate: "tier-override", decision: "reject-invalid", value: "{tier_override}", fallback: "{detected_tier}", rationale: "tier_override not in {Quick,Forge,Forge+,Deep}", timestamp: {ISO}}`
 
 Step-05 §7 reads `headless_decisions[]` and emits an "Auto-Decisions" section into `evidence-report.md` so reviewers can audit every silent choice the workflow made.
 
@@ -53,7 +61,7 @@ Step-05 §7 reads `headless_decisions[]` and emits an "Auto-Decisions" section i
   - If `batch_active: true`: validate the checkpoint before trusting it. Both conditions below MUST hold:
     1. `0 <= current_index < len(brief_list)` — the index points inside the recorded list.
     2. `os.path.exists(brief_list[current_index])` — the brief file is still on disk.
-    If both hold, load the brief at `brief_list[current_index]` (resuming a batch loop from step-08). If **either** check fails, the checkpoint is stale (briefs renamed, moved, or deleted between runs; index off the end after a partial failure). Log a warning — "Stale batch checkpoint — current_index={i}, brief_list length={n}, brief_exists={bool}. Resetting and re-discovering." — then set `batch_active: false` in `batch-state.yaml` and fall through to the no-checkpoint branch below.
+    If both hold, load the brief at `brief_list[current_index]` (resuming a batch loop from step 8). If **either** check fails, the checkpoint is stale (briefs renamed, moved, or deleted between runs; index off the end after a partial failure). Log a warning — "Stale batch checkpoint — current_index={i}, brief_list length={n}, brief_exists={bool}. Resetting and re-discovering." — then set `batch_active: false` in `batch-state.yaml` and fall through to the no-checkpoint branch below.
   - If no checkpoint exists or `batch_active` is false: search specified directory for all `skill-brief.yaml` files, list discovered briefs with skill names, store list for batch loop processing, and load the FIRST brief
 
 **If no brief found:**
@@ -61,35 +69,35 @@ Halt with: "No skill brief found. Run [BS] Brief Skill to create one, or use [QS
 
 ### 3. Validate Brief Structure
 
-Check that the loaded skill-brief.yaml contains required fields:
+Run the deterministic schema validator — it checks required fields, regex patterns (`name`, `version`), enum membership (`source_type`, `source_authority`, `forge_tier`, `scope.type`), type correctness, the docs-only conditional rule (`doc_urls` ≥ 1 when `source_type == "docs-only"`), and the version-non-empty-or-whitespace rule:
+
+```bash
+uv run {validateBriefSchemaHelper} <path-to-skill-brief.yaml>
+```
+
+The helper emits:
 
-**Required fields:**
-- `name` — skill identifier (kebab-case)
-- `version` — source version to compile against
-- `source_repo` — GitHub owner/repo or local path (**optional when `source_type: "docs-only"`**)
-- `language` — primary source language
-- `scope` — what to extract. Accepts either a string (simple scope description, e.g., "all public exports") or an object with sub-fields: `type` (e.g., `"component-library"`), `include`, `exclude`, `notes`, and optionally `demo_patterns`, `registry_path`, `ui_variants` for component libraries
+```json
+{
+  "valid": <bool>,
+  "errors":   [{"field": "...", "message": "Brief validation failed: ..."}, ...],
+  "warnings": [{"field": "...", "message": "..."}, ...],
+  "halt_reason": "brief-missing" | "brief-malformed" | "brief-invalid" | null,
+  "brief": { ...parsed YAML when loadable... }
+}
+```
 
-**Optional fields:**
-- `source_type` — `"source"` (default) or `"docs-only"` (external documentation only)
-- `doc_urls` — array of `{url, label}` documentation URLs (required when `source_type: "docs-only"`)
-- `source_branch` — branch to use (default: main/master)
-- `source_authority` — official/community/internal (default: community; forced to `community` for docs-only)
-- `target_version` — specific version to compile against (triggers **explicit** tag resolution for remote repos; see source-resolution-protocols.md). When absent, the workflow falls back to **implicit** tag resolution from `brief.version` for remote sources — see below.
-- `include_patterns` — file glob patterns to include
-- `exclude_patterns` — file glob patterns to exclude
-- `description` — human description of the skill
-- `scripts_intent` — `"none"` to skip scripts detection, omit for default auto-detection
-- `assets_intent` — `"none"` to skip assets detection, omit for default auto-detection
+**If `valid` is false:** HALT and display the first error's `message` field verbatim — the helper already formats messages in the "Brief validation failed: ..." form the user expects. For halt-reasons:
 
-**Docs-only validation:** When `source_type: "docs-only"`, `source_repo` is not required but `doc_urls` must have at least one entry. `source_authority` is forced to `community`.
+- `brief-missing` — the brief path doesn't exist. Display the helper's message (it includes the `Run [BS] Brief Skill` redirect).
+- `brief-malformed` — the YAML failed to parse. Display the helper's message.
+- `brief-invalid` — schema or conditional-rule violation. Display the first `errors[].message`. Multiple errors may appear; the user typically fixes one source and re-runs.
 
-**If required fields missing:**
-Halt with specific error: "Brief validation failed: missing required field `{field}`. Update your skill-brief.yaml and re-run."
+**If `valid` is true:** continue with `brief` (the parsed object) for downstream sections. Surface any `warnings[]` to the user but do not halt.
 
-**Name format check (run after required-field check, before any path creation):** validate `brief.name` against the regex `^[a-z0-9][a-z0-9-]{0,63}$` — 1-64 characters, lowercase alphanumeric plus hyphens, must start with a letter or digit, no leading hyphen, no uppercase, no underscores, no slashes. This matches the agentskills.io skill-name rule and the directory-name constraint that `skill-check`'s `frontmatter.name_matches_directory` rule will later enforce. If validation fails, halt BEFORE any directory is created or any path is resolved: "Brief validation failed: `name` field `{value}` does not match required pattern `^[a-z0-9][a-z0-9-]{0,63}$`. Skill names must be 1-64 chars, lowercase alphanumeric plus hyphens, no leading hyphen, no underscores, no slashes. Update your skill-brief.yaml and re-run."
+**Field reference (for human readers):**
 
-**Version non-empty check:** reject `brief.version` if absent, empty, or whitespace-only (`version.strip() == ""`). Halt: "Brief validation failed: `version` field is required and must be non-empty. Update your skill-brief.yaml and re-run." This guards downstream directory resolution — an empty version would later create paths like `{skills_output_folder}/{name}//` with a stray double-slash, which is a nightmare to clean up.
+The complete contract — required fields, optional fields, types, and rules — lives in `src/shared/scripts/schemas/skill-brief.v1.json` and the prose mirror at `src/skf-brief-skill/assets/skill-brief-schema.md`. Read those if you need to explain a specific field; do NOT restate the rules here.
 
 ### 4. Resolve Source Code Location
 
@@ -98,8 +106,8 @@ Halt with specific error: "Brief validation failed: missing required field `{fie
 **If source_repo is a GitHub URL or owner/repo format:**
 - Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)` — **Tool resolution:** `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` or direct file listing if local; see `knowledge/tool-resolution.md`
 - If branch not specified, detect default branch
-- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is initially set to the remote URL (for detection and API access purposes) and then updated to the local workspace/clone path during step-03 source resolution
-- **Version-to-tag pinning intent:** If `brief.target_version` is absent but `brief.version` is present, record the intent to apply **implicit tag resolution** from `brief.version` when step-03 resolves the source. Do not resolve the tag here — tag resolution runs in step-03 alongside the clone. This step only notes the pinning intent so step-03 knows to attempt it. See `references/source-resolution-protocols.md` → "Implicit Tag Resolution".
+- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is initially set to the remote URL (for detection and API access purposes) and then updated to the local workspace/clone path during step 3 source resolution
+- **Version-to-tag pinning intent:** If `brief.target_version` is absent but `brief.version` is present, record the intent to apply **implicit tag resolution** from `brief.version` when step 3 resolves the source. Do not resolve the tag here — tag resolution runs in step 3 alongside the clone. This step only notes the pinning intent so step 3 knows to attempt it. See `references/source-resolution-protocols.md` → "Implicit Tag Resolution".
 
 **If source_repo is a local path:**
 - Verify path exists and contains source files

package/src/skf-create-skill/{steps-c/step-08-report.md → references/report.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-09-health-check.md'
+nextStepFile: 'health-check.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves.
@@ -8,6 +8,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 8: Report
 
 ## STEP GOAL:
@@ -22,8 +24,6 @@ To display the final compilation summary — skill name, version, source, export
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Display Forge Completion Banner
 
 "**Skill forged: {name} v{version} — {export_count} functions, {primary_confidence} confidence.**"
@@ -107,9 +107,9 @@ completed: [{list of completed skill names}]
 last_updated: {ISO timestamp}
 ```
 
-**Before writing:** validate the same two invariants that step-01 re-checks on resume — `0 <= current_index < len(brief_list)` AND `os.path.exists(brief_list[current_index])`. If either fails (e.g., the next brief file was deleted mid-batch, or arithmetic pushed the index off the end), set `batch_active: false` and write `batch_halt_reason: "invalid checkpoint at write time — index or file missing"` instead of the active record. The next run will re-discover rather than resume a broken index.
+**Before writing:** validate the same two invariants that step 1 re-checks on resume — `0 <= current_index < len(brief_list)` AND `os.path.exists(brief_list[current_index])`. If either fails (e.g., the next brief file was deleted mid-batch, or arithmetic pushed the index off the end), set `batch_active: false` and write `batch_halt_reason: "invalid checkpoint at write time — index or file missing"` instead of the active record. The next run will re-discover rather than resume a broken index.
 
-Then load and execute `steps-c/step-01-load-brief.md` for the next brief. Step-01 detects an active batch via `batch-state.yaml` and loads the brief at `current_index` only after re-validating the same invariants (belt and braces — the checkpoint may have been edited between runs).
+Then load and execute `references/load-brief.md` for the next brief. Step-01 detects an active batch via `batch-state.yaml` and loads the brief at `current_index` only after re-validating the same invariants (belt and braces — the checkpoint may have been edited between runs).
 
 **If all batch briefs complete:**
 
@@ -135,11 +135,11 @@ End workflow. No further steps.
 
 ONLY WHEN the compilation report, warnings (if any), recommended next steps, and result contract have been handled 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 report reads as final.
 
-**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `steps-c/step-01-load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
+**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `references/load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md` (unless batch mode loops back to step-01). After the health check completes, the create-skill workflow is fully done.
+This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md` (unless batch mode loops back to step 1). After the health check completes, the create-skill workflow is fully done.
 
-For batch mode: load and execute `steps-c/step-01-load-brief.md` for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.
+For batch mode: load and execute `references/load-brief.md` for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.
 

package/src/skf-create-skill/references/source-resolution-protocols.md

@@ -43,9 +43,9 @@ When `brief.target_version` is absent but `brief.version` is present AND `source
 3. **Resolution outcomes:**
    - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands. Do not warn — this is the expected path.
    - **Multiple matches:** Present the matching tags to the user — "Multiple tags match `brief.version` ({brief.version}): {list}. Which one should I use, or fall back to HEAD?" Wait for selection.
-   - **Zero matches:** ⚠️ Warn: "No git tag found matching `brief.version` ({brief.version}). Falling back to default branch — **extracted code may not match the declared version.** If you intended to pin a specific version, set `target_version` explicitly in the brief." Set `source_ref` to `HEAD` and proceed with default branch. Append `tag_resolution: {status: "fallback-head", requested: "{brief.version}", reason: "no-matching-tag"}` to the in-context evidence-report payload so step-05 §7 surfaces the fallback in the evidence report. This turns the warning into a persistent audit trail a reviewer can grep later, not just a one-shot stderr line.
+   - **Zero matches:** ⚠️ Warn: "No git tag found matching `brief.version` ({brief.version}). Falling back to default branch — **extracted code may not match the declared version.** If you intended to pin a specific version, set `target_version` explicitly in the brief." Set `source_ref` to `HEAD` and proceed with default branch. Append `tag_resolution: {status: "fallback-head", requested: "{brief.version}", reason: "no-matching-tag"}` to the in-context evidence-report payload so step 5 §7 surfaces the fallback in the evidence report. This turns the warning into a persistent audit trail a reviewer can grep later, not just a one-shot stderr line.
 
-4. **Do not halt on zero matches.** Unlike the explicit path, implicit resolution never blocks compilation — `brief.version` is an auto-populated hint, and some repositories simply do not tag releases. The warning is sufficient notice; the evidence report in step-08 will surface the HEAD fallback for reviewers.
+4. **Do not halt on zero matches.** Unlike the explicit path, implicit resolution never blocks compilation — `brief.version` is an auto-populated hint, and some repositories simply do not tag releases. The warning is sufficient notice; the evidence report in step 8 will surface the HEAD fallback for reviewers.
 
 5. **Store `source_ref`** in context exactly as in the explicit path. It flows through to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-clone from the same ref.
 
@@ -65,7 +65,7 @@ Implicit resolution via `brief.version` is **not applied to local sources** —
 
 ## Remote Source Resolution
 
-**Note:** Quick-tier remote sources do not use the workspace/clone protocol described below. Quick tier accesses remote files via the `gh_bridge.read_file` path described in step-03 section 4.
+**Note:** Quick-tier remote sources do not use the workspace/clone protocol described below. Quick tier accesses remote files via the `gh_bridge.read_file` path described in step 3 section 4.
 
 If `source_repo` is a local path: proceed with the tier-appropriate strategy as normal.
 
@@ -84,7 +84,7 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
 3. **Workspace check — resolve the source locally:**
 
-   **Concurrency guard:** all of the operations below (fetch, checkout, rev-parse, and the extraction read that follows in step-03) must be wrapped in an exclusive `flock` on `{workspace_repo_path}/.skf-workspace.lock`. Acquire the lock before the workspace-hit check, hold it across fetch + checkout + rev-parse, AND keep holding it through the extraction-time read of the working tree. Two concurrent batch runs that target the same workspace clone but different `source_ref` values would otherwise race — one would `checkout` while the other was reading files mid-extraction, corrupting the inventory. The lock makes the per-workspace-repo unit of work serial. Use `flock -x {lockfile} -c "..."` or `fcntl.flock(LOCK_EX)`. If `flock` is unavailable, log a warning ("Concurrency guard unavailable — concurrent forges against the same workspace repo may produce inconsistent extraction inventories") and proceed.
+   **Concurrency guard:** all of the operations below (fetch, checkout, rev-parse, and the extraction read that follows in step 3) must be wrapped in an exclusive `flock` on `{workspace_repo_path}/.skf-workspace.lock`. Acquire the lock before the workspace-hit check, hold it across fetch + checkout + rev-parse, AND keep holding it through the extraction-time read of the working tree. Two concurrent batch runs that target the same workspace clone but different `source_ref` values would otherwise race — one would `checkout` while the other was reading files mid-extraction, corrupting the inventory. The lock makes the per-workspace-repo unit of work serial. Use `flock -x {lockfile} -c "..."` or `fcntl.flock(LOCK_EX)`. If `flock` is unavailable, log a warning ("Concurrency guard unavailable — concurrent forges against the same workspace repo may produce inconsistent extraction inventories") and proceed.
 
    **If `{workspace_repo_path}/.git/` exists (workspace hit):**
 
@@ -217,7 +217,7 @@ Also store `source_ref` in context (from tag resolution above, or `HEAD` if no t
 
 **If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
 
-After the source path is accessible (local path from step-01, or workspace/ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
+After the source path is accessible (local path from step 1, or workspace/ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
 
 - Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
 - JavaScript/TypeScript: `package.json` (`"version"`). **Monorepo resolution:** When multiple `package.json` files exist (workspace root + packages), resolve version using this priority:
@@ -232,7 +232,7 @@ After the source path is accessible (local path from step-01, or workspace/ephem
 
 ⚠️ Warn the user: "Brief version ({brief.version}) differs from source version ({source_version}). Using source version ({source_version})."
 
-Update the working version in context to the source version. Record the mismatch in context for the evidence report (step-08).
+Update the working version in context to the source version. Record the mismatch in context for the evidence report (step 8).
 
 **If no version file is found or version cannot be extracted:** keep `brief.version` as-is. No warning needed.
 

package/src/skf-create-skill/{steps-c/sub/step-02b-ccc-discover.md → references/sub/ccc-discover.md}

@@ -1,12 +1,14 @@
 ---
-nextStepFile: '../step-03-extract.md'
+nextStepFile: '../extract.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2b: CCC Semantic Discovery
 
 ## STEP GOAL:
 
-If tier is Forge+ or Deep AND ccc is available, perform a semantic discovery pass over the source code to identify the most relevant files for the skill being created. Store ranked discovery results in context to pre-rank the file extraction queue in step-03.
+If tier is Forge+ or Deep AND ccc is available, perform a semantic discovery pass over the source code to identify the most relevant files for the skill being created. Store ranked discovery results in context to pre-rank the file extraction queue in step 3.
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
@@ -18,8 +20,6 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Tier Eligibility
 
 **If tier is Quick or Forge:**
@@ -32,7 +32,7 @@ Check `tools.ccc` from forge-tier.yaml. If `tools.ccc` is false, set `{ccc_disco
 
 If `tools.ccc` is true, check the remote source guard **before** proceeding to section 2:
 
-**Remote source guard:** If `source_root` is a remote URL (GitHub repository — workspace clone or ephemeral clone happens in step-03), CCC cannot operate yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after clone in step-03." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the resolved clone (workspace or ephemeral) before AST extraction begins.
+**Remote source guard:** If `source_root` is a remote URL (GitHub repository — workspace clone or ephemeral clone happens in step 3), CCC cannot operate yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after clone in step 3." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the resolved clone (workspace or ephemeral) before AST extraction begins.
 
 If `source_root` is a local path, continue to section 2.
 

package/src/skf-create-skill/{steps-c/sub/step-03c-fetch-docs.md → references/sub/fetch-docs.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: '../step-04-enrich.md'
+nextStepFile: '../enrich.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves.
@@ -8,6 +8,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3c: Fetch Remote Documentation
 
 ## STEP GOAL:
@@ -23,13 +25,11 @@ Fetch remote documentation from brief-specified URLs using whatever web fetching
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Eligibility
 
 Evaluate the following conditions. **If the condition fails, skip silently to section 7 (auto-proceed) with no output:**
 
-1. **`doc_urls` is present in the brief data:** Check that `doc_urls` contains at least one URL entry from step-01 context. If `doc_urls` is absent or empty, skip silently.
+1. **`doc_urls` is present in the brief data:** Check that `doc_urls` contains at least one URL entry from step 1 context. If `doc_urls` is absent or empty, skip silently.
 
 No tier gate — if `doc_urls` are present, this step runs at Quick, Forge, and Deep tiers alike.
 
@@ -84,12 +84,28 @@ If neither trigger fires, keep the page content as-is and do NOT trigger subpage
 
 2. **Filter discovered URLs by relevance and origin:** Restrict candidates to the same **registrable domain** as the root URL — strip the URL down to its eTLD+1 (e.g., for root `https://docs.example.com/intro`, accept any subdomain of `example.com` such as `api.example.com` or `docs.example.com`, but reject `example.org` or `cdn.partner.io`). Cross-origin links must be discarded before any fetch. The same-registrable-domain rule prevents Mintlify/Docusaurus link clouds from pulling in tracking pixels, doc-site CDNs, or third-party embeds as if they were canonical docs. From the surviving same-domain candidates, select the most relevant pages by searching for API-related terms in the URL path or title (e.g., `api`, `reference`, `quickstart`, `setup`, `config`, `getting-started`, `guide`, `sdk`, `methods`, `functions`). Exclude pages that are clearly non-API content (e.g., `blog`, `changelog`, `pricing`, `about`, `careers`).
 
-3. **Fetch top subpages:** Fetch up to **10** of the most relevant subpages. For each:
+3. **Fetch top subpages (in parallel):** Fetch up to **10** of the most relevant subpages **concurrently** — subpage fetches are independent and network-bound, so wall-clock benefits substantially from parallel execution. Bound concurrency to **4 in flight** at a time to stay polite to documentation hosts (Mintlify/Docusaurus typically allow more, but conservatism here protects against unrecognized rate limits).
+
+   The parallel pattern depends on the fetch tool:
+
+   - **LLM-driven tools** (Firecrawl `firecrawl_scrape`, `WebFetch`, MCP fetch, browser tools): issue up to 4 tool calls **in a single message**. The agent runtime executes parallel tool calls concurrently; collect results from the batch before issuing the next set of up to 4. Repeat until all up-to-10 subpages have been attempted or rate limiting halts the batch.
+   - **Bash-driven tools** (`curl`, `wget`): use `xargs -P 4 -n 1` to fan out from a newline-separated subpage list. Example:
+
+     ```bash
+     printf '%s\n' "${subpages[@]}" | xargs -P 4 -n 1 -I {} bash -c '
+       url="{}"
+       safe=$(echo -n "$url" | sha256sum | cut -c1-12)
+       curl -sSL --max-time 30 "$url" > "{staging}/subpage-$safe.md" \
+         || echo "fetch failed: $url" > "{staging}/subpage-$safe.md"
+     '
+     ```
+
+   For each subpage (regardless of tool):
    - Use the same web fetching tool as the root URL
    - Store with the subpage URL as provenance: `[EXT:{subpage-url}]`
-   - If a subpage fetch fails, skip it and continue
+   - If a subpage fetch fails, skip it and continue with the rest of the batch — do not halt the whole stage
 
-4. **Rate limiting:** If rate limiting (HTTP 429) is encountered during subpage fetching, stop discovery for this root URL. Keep results collected so far. Log: "Subpage discovery stopped due to rate limiting."
+4. **Rate limiting:** If rate limiting (HTTP 429) is encountered during subpage fetching, stop discovery for this root URL. Keep results collected so far. Log: "Subpage discovery stopped due to rate limiting." For the parallel-tool-call pattern, drop any not-yet-issued tool calls from subsequent batches; for the `xargs` pattern, interrupt the pipeline (set `--max-procs 0` is **not** a graceful stop — the simplest stop is to kill the xargs PID and let in-flight writers complete naturally).
 
 **If ALL URLs fail (including any subpage fetches):** Log warning: "No documentation could be fetched. Proceeding without T3 content." Skip to section 7 (auto-proceed).
 
@@ -110,8 +126,8 @@ Parse the successfully fetched markdown for:
 
 **Mode determines merge behavior:**
 
-- **`source_type: "docs-only"`** — The doc-fetch inventory IS the extraction inventory. It replaces the empty inventory from step-03, since there was no source code to extract from.
-- **`source_type: "source"` (supplemental mode)** — Merge T3 items into the existing extraction inventory from step-03.
+- **`source_type: "docs-only"`** — The doc-fetch inventory IS the extraction inventory. It replaces the empty inventory from step 3, since there was no source code to extract from.
+- **`source_type: "source"` (supplemental mode)** — Merge T3 items into the existing extraction inventory from step 3.
 
 **Conflict rule:** T3 items NEVER override existing T1, T1-low, or T2 items for the same export. When an export already has a higher-confidence entry, the T3 item is discarded. T3 has the lowest priority.
 
@@ -131,7 +147,7 @@ Parse the successfully fetched markdown for:
 1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/`
 2. Index into QMD with atomic replace + rollback: if a `{skill-name}-docs` collection already exists, run `qmd collection remove {skill-name}-docs` first, then `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`. **If `qmd collection add` fails after a successful `remove`:** remove any matching `{skill-name}-docs` entry from `forge-tier.yaml` → `qmd_collections[]` to keep the registry consistent with QMD's actual state, warn in evidence-report, and skip the embed — docs enrichment degrades gracefully.
 3. Generate embeddings scoped to this collection (only if step 2 `add` succeeded): `qmd embed --collection {skill-name}-docs` (required for semantic `type:'vec'` and HyDE `type:'hyde'` sub-queries within the QMD `query` tool). If the installed `qmd` CLI does not accept `--collection`, gate the embed behind a freshness check: skip re-embedding if the existing `{skill-name}-docs` registry entry is within 24 hours, and log the skip in the evidence report to prevent unbounded batch-mode re-embedding.
-4. Register in forge-tier.yaml `qmd_collections` array — **acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` for the read-modify-write** (see the locking pattern documented in step-03b §4). Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`. If `flock` is unavailable, fall back to read-CAS-by-mtime (capture `st_mtime` before, re-check after; refuse to clobber if a concurrent run wrote in between).
+4. Register in forge-tier.yaml `qmd_collections` array — **acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` for the read-modify-write** (see the locking pattern documented in step 3b §4). Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`. If `flock` is unavailable, fall back to read-CAS-by-mtime (capture `st_mtime` before, re-check after; refuse to clobber if a concurrent run wrote in between).
 
 ```yaml
 - name: "{skill-name}-docs"
@@ -190,7 +206,7 @@ ONLY WHEN documentation is fetched and T3 items are merged into the extraction i
 - Existing T1/T1-low/T2 items never overridden by T3 data
 - Docs-only mode: doc-fetch inventory correctly replaces empty extraction inventory
 - Supplemental mode: T3 items merged into existing inventory respecting conflict rule
-- Auto-proceeded to step-04
+- Auto-proceeded to step 4
 
 ### SYSTEM FAILURE:
 
@@ -199,6 +215,6 @@ ONLY WHEN documentation is fetched and T3 items are merged into the extraction i
 - Overriding existing higher-confidence extractions (T1, T1-low, T2) with T3 data
 - Hardcoding a specific fetching tool instead of being tool-agnostic
 - Hallucinating API details not found in the fetched content
-- Beginning compilation in this step (that is step-05)
+- Beginning compilation in this step (that is step 5)
 
 **Master Rule:** Documentation fetching is best-effort T3 enrichment. Fetch what you can, cite everything as `[EXT:{url}]`, never override higher-confidence data, and move on. Failures degrade gracefully — they never block the skill compilation pipeline.