bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/quick-skill → skf-quick-skill}/steps-c/step-04-compile.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-04-compile'
-description: 'Assemble best-effort SKILL.md, context-snippet.md, and metadata.json from extraction inventory'
-
 nextStepFile: './step-05-validate.md'
-skillTemplateData: '../data/skill-template.md'
+skillTemplateData: 'assets/skill-template.md'
 ---
 
 # Step 4: Compile
@@ -12,43 +9,11 @@ skillTemplateData: '../data/skill-template.md'
 
 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.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a rapid skill compiler assembling output documents
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Best-effort quality — populate what's available, mark gaps honestly
-- ✅ Follow template structure exactly from {skillTemplateData}
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on assembling the three output documents
-- 🚫 FORBIDDEN to write files to disk — that's step-06
-- 💬 Approach: Load template, populate from inventory, present for review
-- 📋 Mark any sections with insufficient data as best-effort
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Set state: skill_content, context_snippet, metadata_json
-- 📖 Load {skillTemplateData} for section structure and format specs
-- 🚫 Do not write files — only assemble content in memory
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Previous step provided: extraction_inventory (exports, description, manifest_data, confidence)
-- Also available: resolved_url, repo_name, language, scope_hint
-- Focus: compilation and assembly only
-- This step presents output for review — user gets a checkpoint before validation
+- Focus only on assembling the three output documents — do not write files to disk (that's step-06)
+- Follow template structure exactly from {skillTemplateData}
+- Mark any sections with insufficient data as best-effort
 
 ## MANDATORY SEQUENCE
 
@@ -203,6 +168,7 @@ Display: **Select:** [C] Continue to Validation
 #### 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
 
@@ -210,23 +176,3 @@ Display: **Select:** [C] Continue to Validation
 
 ONLY WHEN the user reviews the compiled output and selects 'C' will you load and read fully `{nextStepFile}` to execute validation.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- SKILL.md assembled with all available sections populated
-- context-snippet.md generated in correct Vercel-aligned indexed format
-- metadata.json generated with source_authority: community
-- Compiled output presented for user review
-- User confirms readiness before proceeding to validation
-
-### ❌ SYSTEM FAILURE:
-
-- Writing files to disk (that's step-06)
-- Skipping the review checkpoint
-- Not following template structure from {skillTemplateData}
-- Hallucinating exports or data not in extraction_inventory
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/quick-skill → skf-quick-skill}/steps-c/step-05-validate.md

@@ -1,73 +1,78 @@
 ---
-name: 'step-05-validate'
-description: 'Validate compiled SKILL.md, context-snippet, and metadata against agentskills.io spec'
-
 nextStepFile: './step-06-write.md'
 ---
 
-# Step 5: Validate
+# Step 5: Write & Validate
 
 ## STEP GOAL:
 
-To validate the compiled SKILL.md, context-snippet.md, and metadata.json against the agentskills.io specification at community tier. Report any gaps or issues. This is advisory validation — issues are reported but do not block output.
+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
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### Universal Rules:
+### 1. Create Output Directory
 
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+Resolve `{version}` from the extraction inventory's detected version, defaulting to `1.0.0` if not detected. Create the skill output directories:
 
-### Role Reinforcement:
+```
+{skill_group}                          # {skills_output_folder}/{repo_name}/
+{skill_package}                        # {skills_output_folder}/{repo_name}/{version}/{repo_name}/
+```
 
-- ✅ You are a rapid skill compiler performing quality checks
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Community-tier validation — lighter than official requirements
-- ✅ Report issues honestly but don't block output
+If `{skill_package}` already exists, confirm with user before overwriting:
 
-### Step-Specific Rules:
+"**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]"
 
-- 🎯 Focus only on validating the compiled output
-- 🚫 FORBIDDEN to modify the compiled content — report issues only
-- 💬 Approach: Check each requirement, report findings, proceed
-- 📋 Validation failures are advisory — user can proceed regardless
+- **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."
 
-## EXECUTION PROTOCOLS:
+**GATE [default: Y]** — If `{headless_mode}` is true, auto-proceed with Y and log: "headless: overwriting existing `{skill_package}`".
 
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Set state: validation_result (pass/fail, issues_list)
-- 📖 Check against community-tier requirements
-- 🚫 Do not block output on validation issues
+### 2. Write Deliverables
 
-## CONTEXT BOUNDARIES:
+Write the three compiled artifacts to the skill package so that validation in sections 3–9 has files on disk to read:
 
-- Previous step provided: skill_content (SKILL.md), context_snippet, metadata_json
-- Focus: validation only, not modification
-- Community tier has lighter requirements than official
-- Dependencies: compiled output from step-04
+**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
 
-## MANDATORY SEQUENCE
+Confirm after each write: "Written: SKILL.md" / "Written: context-snippet.md" / "Written: metadata.json".
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+**If any write fails — HARD HALT:**
 
-### 1. Check Tool Availability
+"**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 2)
-- If fails (command not found or error): Skip to manual fallback in section 2
+- 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.
 
-### 2. Validate SKILL.md via skill-check (if available)
+### 4. Validate SKILL.md via skill-check (if available)
 
-**If `npx skill-check` is available**, run automated validation with auto-fix:
+**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-dir> --fix --format json --no-security-scan
+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).
@@ -89,7 +94,7 @@ Record quality score and any remaining diagnostics as validation issues.
 
 **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`.
 
-### 3. Validate SKILL.md Body Structure
+### 5. Validate SKILL.md Body Structure
 
 Check that SKILL.md has these required sections populated:
 
@@ -100,18 +105,18 @@ Check that SKILL.md has these required sections populated:
 
 **For each missing or empty required section, log an issue.**
 
-### 4. Validate Context Snippet Format
+### 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/` or a platform root (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`)
+- [ ] **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.**
 
-### 5. Validate Metadata JSON
+### 7. Validate Metadata JSON
 
 Check metadata.json has required fields:
 
@@ -131,12 +136,12 @@ Check metadata.json has required fields:
 
 **For each missing or invalid field, log an issue.**
 
-### 6. Security Scan (if skill-check available)
+### 8. Security Scan (if skill-check available)
 
-Run security scan on the compiled skill:
+Run security scan on the compiled skill package:
 
 ```bash
-npx skill-check check <skill-dir> --format json
+npx skill-check check {skill_package} --format json
 ```
 
 (Security scan is enabled by default when `--no-security-scan` is omitted.)
@@ -145,7 +150,7 @@ Record any security findings as advisory warnings. Security issues do not block
 
 **If skill-check unavailable:** Skip with note in validation results.
 
-### 7. Report Validation Results
+### 9. Report Validation Results
 
 "**Validation complete:**
 
@@ -165,13 +170,13 @@ Record any security findings as advisory warnings. Security issues do not block
 **Overall:** {pass / N issues found}
 
 {If issues found:}
-These issues are advisory for community-tier skills. You can proceed to write output or go back to adjust.
+These issues are advisory for community-tier skills. You can proceed to finalize or go back to adjust.
 
-**Proceeding to write output...**"
+**Proceeding to finalize...**"
 
 Set `validation_result` with pass/fail status, quality score, and issues list.
 
-### 8. Auto-Proceed to Write
+### 10. Auto-Proceed to Finalize
 
 #### Menu Handling Logic:
 
@@ -180,34 +185,9 @@ Set `validation_result` with pass/fail status, quality score, and issues list.
 #### EXECUTION RULES:
 
 - This is an auto-proceed step — validation is advisory
-- Proceed directly to write step after reporting results
+- Proceed directly to finalize step after reporting results
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN validation checks are complete and results reported will you load and read fully `{nextStepFile}` to execute file writing.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- `npx skill-check check --fix --format json` executed if available (or manual fallback)
-- Quality score (0-100) captured when skill-check available
-- Auto-fix applied via `--fix` for deterministic issues
-- Security scan executed (or skipped with note)
-- All three outputs validated against requirements
-- Issues reported clearly with specific details
-- Community-tier validation applied (not official-tier strictness)
-- validation_result set with pass/fail, quality score, and issues list
-- Auto-proceeding to write step
-
-### ❌ SYSTEM FAILURE:
-
-- Modifying compiled content instead of just reporting
-- Blocking output on validation issues (advisory only)
-- Skipping validation checks
-- Not reporting found issues
-- Not recording quality score when skill-check is available
+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.
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/skf-quick-skill/steps-c/step-06-write.md

@@ -0,0 +1,73 @@
+---
+nextStepFile: './step-07-health-check.md'
+---
+
+# Step 6: Finalize
+
+## 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.
+
+## Rules
+
+- Do not rewrite deliverables — they were written and validated in step-05
+- Create the active pointer via the shared helper — never `rm` + `ln -s` manually
+- Result contract writing is mandatory (pipeline consumers depend on it)
+
+## 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)
+
+`{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:
+
+```bash
+python3 {project-root}/src/shared/scripts/skf-atomic-write.py 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.
+
+**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.
+
+Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{kind}` is `symlink` or `junction` as returned by the helper.
+
+### 2. Display Completion Summary
+
+"**Quick Skill complete.**
+
+**Skill:** {repo_name} v{version}
+**Language:** {language}
+**Source:** {resolved_url}
+**Authority:** community
+**Confidence:** {extraction confidence}
+
+**Files written:**
+- `{skill_package}/SKILL.md`
+- `{skill_package}/context-snippet.md`
+- `{skill_package}/metadata.json`
+- `{skill_group}/active` -> `{version}`
+
+**Exports documented:** {count}
+**Validation:** {pass / N issues (advisory)}
+
+---
+
+**Recommended next steps:**
+
+1. **test-skill** (advisory) — Run cognitive completeness verification on the generated skill
+2. **export-skill** — Package and distribute the skill with platform-aware context injection
+
+**Note:** This is a best-effort community skill. For deeper analysis with AST-verified exports and provenance tracking, use the full **create-skill** workflow with a skill brief."
+
+### 3. Result Contract
+
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skill_package}/quick-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include `SKILL.md`, `context-snippet.md`, and `metadata.json` paths in `outputs` and export count in `summary`.
+
+### 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.

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

@@ -0,0 +1,22 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 7: Workflow Health Check
+
+## 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.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-refine-architecture/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: skf-refine-architecture
+description: Improve architecture doc using verified skill data and VS feasibility findings. Use when the user requests to "refine skill architecture" or "improve architecture doc."
+---
+
+# Refine Architecture
+
+## Overview
+
+Takes an original architecture document + generated skills + optional VS feasibility report, and produces a refined architecture with gaps filled, issues flagged, and improvements suggested — all backed by specific API evidence from the generated skills. This workflow enhances the original architecture — it never deletes original content, only adds annotations, subsections, and suggestions.
+
+## Role
+
+You are an architecture refinement analyst operating in Ferris Architect mode. You bring expertise in API surface analysis, integration gap detection, and evidence-backed architecture improvement, while the user brings their architecture vision and generated skills. Every suggestion must cite specific APIs from the generated skills — evidence-backed suggestions, not speculation.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Never speculate — every gap, issue, or improvement must cite specific APIs, types, or function signatures from the generated skills
+- 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
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Initialize & Load Inputs | steps-c/step-01-init.md | No (confirm) |
+| 2 | Gap Analysis | steps-c/step-02-gap-analysis.md | Yes |
+| 3 | Issue Detection | steps-c/step-03-issue-detection.md | Yes |
+| 4 | Improvements | steps-c/step-04-improvements.md | Yes |
+| 5 | Compile Refined Architecture | steps-c/step-05-compile.md | No (review) |
+| 6 | Report | steps-c/step-06-report.md | Yes |
+| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | architecture_doc_path [required] |
+| **Gates** | step-01: Input Gate [use args] | step-05: Review Gate [C] |
+| **Outputs** | refined-architecture-{project_name}.md |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `output_folder`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.

package/src/{workflows/refine-architecture/data → skf-refine-architecture/references}/refinement-rules.md

@@ -19,11 +19,11 @@ Gaps are undocumented integration paths — library pairs that have compatible A
 
 ### Gap Classification
 
-| Gap Type | Description | Example |
-|----------|-------------|---------|
-| **Missing Integration Path** | Two libraries can connect but the architecture never describes how | Skill A exports JSON producer, Skill B accepts JSON input, no mention of A-to-B flow |
-| **Undocumented Data Flow** | Data moves between libraries but the flow is not described | Architecture mentions both libraries but not their data exchange mechanism |
-| **Absent Bridge Layer** | Cross-language or cross-protocol libraries need a bridge not mentioned | Rust library and TypeScript library with no IPC/FFI description |
+| Gap Type                     | Description                                                            | Example                                                                              |
+|------------------------------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| **Missing Integration Path** | Two libraries can connect but the architecture never describes how     | Skill A exports JSON producer, Skill B accepts JSON input, no mention of A-to-B flow |
+| **Undocumented Data Flow**   | Data moves between libraries but the flow is not described             | Architecture mentions both libraries but not their data exchange mechanism           |
+| **Absent Bridge Layer**      | Cross-language or cross-protocol libraries need a bridge not mentioned | Rust library and TypeScript library with no IPC/FFI description                      |
 
 ---
 
@@ -39,12 +39,12 @@ Issues are contradictions between architecture claims and verified API reality f
 
 ### Issue Classification
 
-| Issue Type | Description | Example |
-|------------|-------------|---------|
-| **API Mismatch** | Architecture describes an API that does not exist in the skill | "Library X exposes a streaming API" but skill shows only batch APIs |
-| **Protocol Contradiction** | Architecture assumes a protocol the library does not support | "Communicates via gRPC" but skill shows HTTP-only exports |
-| **Language Boundary Ignored** | Architecture assumes direct calls across language boundaries | "Calls Rust functions from TypeScript" with no FFI/IPC mechanism described |
-| **Type Incompatibility** | Architecture assumes type compatibility that does not hold | "Passes CRDT documents directly" but types are incompatible across libraries |
+| Issue Type                    | Description                                                    | Example                                                                      |
+|-------------------------------|----------------------------------------------------------------|------------------------------------------------------------------------------|
+| **API Mismatch**              | Architecture describes an API that does not exist in the skill | "Library X exposes a streaming API" but skill shows only batch APIs          |
+| **Protocol Contradiction**    | Architecture assumes a protocol the library does not support   | "Communicates via gRPC" but skill shows HTTP-only exports                    |
+| **Language Boundary Ignored** | Architecture assumes direct calls across language boundaries   | "Calls Rust functions from TypeScript" with no FFI/IPC mechanism described   |
+| **Type Incompatibility**      | Architecture assumes type compatibility that does not hold     | "Passes CRDT documents directly" but types are incompatible across libraries |
 
 ### VS Report Integration
 
@@ -67,11 +67,11 @@ Improvements are capability expansions — library features documented in skills
 
 ### Improvement Classification
 
-| Improvement Type | Description | Example |
-|------------------|-------------|---------|
-| **Unused Capability** | Library has a feature the architecture does not mention | "Loro supports document CRDTs but architecture only uses data sync" |
-| **Cross-Library Synergy** | Two libraries have complementary features not combined in architecture | "Library A's event system could feed Library B's stream processor" |
-| **Alternative Pattern** | Skill documents a better pattern than the one described in architecture | "Skill shows batch API is more efficient than the per-item approach described" |
+| Improvement Type          | Description                                                             | Example                                                                        |
+|---------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------|
+| **Unused Capability**     | Library has a feature the architecture does not mention                 | "Loro supports document CRDTs but architecture only uses data sync"            |
+| **Cross-Library Synergy** | Two libraries have complementary features not combined in architecture  | "Library A's event system could feed Library B's stream processor"             |
+| **Alternative Pattern**   | Skill documents a better pattern than the one described in architecture | "Skill shows batch API is more efficient than the per-item approach described" |
 
 ---
 

package/src/{workflows/refine-architecture → skf-refine-architecture}/steps-c/step-01-init.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-01-init'
-description: 'Load architecture doc, scan skills folder, load optional VS report, validate inputs'
-
 nextStepFile: './step-02-gap-analysis.md'
-refinementRulesData: '../data/refinement-rules.md'
+refinementRulesData: 'references/refinement-rules.md'
 ---
 
 # Step 1: Initialize Refinement
@@ -12,41 +9,10 @@ refinementRulesData: '../data/refinement-rules.md'
 
 Load the architecture document (required), scan the skills folder to build a skill inventory with metadata, load the optional VS feasibility report for context, validate that all inputs exist and meet minimum requirements, and present an initialization summary before auto-proceeding.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are an architecture refinement analyst operating in Ferris Architect mode
-- ✅ Execute with analytical precision — every loaded skill must be validated against actual files
-- ✅ You enforce the zero-hallucination principle: only report skills that physically exist on disk
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on loading inputs, scanning skills, and validating prerequisites
-- 🚫 FORBIDDEN to perform any gap analysis, issue detection, or improvement suggestions
-- 🚫 No A/P menu — this is an auto-proceed init step
-- 💬 Present a clear initialization summary so downstream steps have validated inputs
-
-## EXECUTION PROTOCOLS:
-
-- Collect and validate all input documents and skill artifacts
-- Load refinement rules from {refinementRulesData} for downstream step reference
-- Auto-proceed to next step after successful initialization
-- HALT with actionable error if minimum requirements not met
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- This is the first step — no prior workflow state exists
-- Requires skills to have been generated by create-skill or quick-skill workflows
-- User provides architecture document path (required) and optional VS report path
-- No dependency on forge-tier — this workflow operates on skill content only
-- Requires `forge_data_folder` from config.yaml for durability state (directory is created automatically if missing)
+- Focus only on loading inputs, scanning skills, and validating prerequisites — do not perform analysis
+- Present a clear initialization summary so downstream steps have validated inputs
 
 ## MANDATORY SEQUENCE
 
@@ -60,7 +26,7 @@ Please provide the following:
 1. **Architecture document path** (REQUIRED) — your project's architecture doc to refine
 2. **VS feasibility report path** (OPTIONAL) — from a previous [VS] Verify Stack run, for additional context"
 
-Wait for user input. Store the validated architecture document path as `architecture_doc`.
+Wait for user input. Store the validated architecture document path as `architecture_doc`. **GATE [default: use args]** — If `{headless_mode}` and architecture doc path was provided as argument: use that path and auto-proceed, log: "headless: using provided architecture path".
 
 **Validate architecture document:**
 - Confirm the file exists and is readable
@@ -74,7 +40,7 @@ Wait for user input. Store the validated architecture document path as `architec
 
 ### 2. Scan Skills Folder
 
-Read the `{skills_output_folder}` directory. Skills use a version-nested directory structure (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)).
+Read the `{skills_output_folder}` directory. Skills use a version-nested directory structure (see `knowledge/version-paths.md`).
 
 **Version-aware skill discovery:**
 1. Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports`, use `active_version` to resolve `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
@@ -168,26 +134,3 @@ Extract: gap detection rules, issue detection rules, improvement detection rules
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Architecture document loaded and validated
-- VS report loaded or absence recorded
-- Skills folder scanned with SKILL.md and metadata.json validation per skill
-- At least 1 valid skill in inventory
-- Refinement rules loaded from {refinementRulesData}
-- Initialization summary displayed with skill inventory table
-- Auto-proceeded to step 02
-
-### ❌ SYSTEM FAILURE:
-
-- Proceeding with no valid skills
-- Proceeding without a valid architecture document
-- Not validating SKILL.md and metadata.json existence per skill directory
-- Performing gap analysis, issue detection, or improvement suggestions in this step
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** This step validates inputs and initializes state. No analysis, no comparison, no refinement suggestions.