bmad-module-skill-forge 0.2.0

package/src/workflows/setup-forge/steps-c/step-02-write-config.md

@@ -0,0 +1,141 @@
+---
+name: 'step-02-write-config'
+description: 'Write forge-tier.yaml, create preferences.yaml defaults, ensure forge-data/ exists'
+
+nextStepFile: './step-03-auto-index.md'
+---
+
+# Step 2: Write Configuration
+
+## STEP GOAL:
+
+Write the detected tool availability and calculated tier to forge-tier.yaml, create preferences.yaml with defaults if it does not exist, and ensure the forge-data/ directory is present.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step, ensure entire file is read
+- 🎯 Execute all operations autonomously — no user interaction
+
+### Role Reinforcement:
+
+- ✅ You are a system executor writing configuration files
+- ✅ File operations must be precise — correct paths, correct YAML structure
+- ✅ Preserve user data (preferences.yaml) — never overwrite existing
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on writing configuration files and creating directories
+- 🚫 FORBIDDEN to re-detect tools — use results from step-01
+- 🚫 FORBIDDEN to overwrite existing preferences.yaml
+- 💬 File write failures ARE errors — report clearly if they occur
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Write files to the forger-sidecar directory
+- 📖 Use context from step-01 (detected_tools, calculated_tier)
+- 🚫 FORBIDDEN to proceed if forge-tier.yaml write fails
+
+## CONTEXT BOUNDARIES:
+
+- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01
+- Focus: file I/O operations only
+- Limits: do not modify preferences.yaml if it exists
+- Dependencies: step-01 must have completed with tool detection results
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Write forge-tier.yaml
+
+Write to `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml`:
+
+```yaml
+# Ferris Sidecar: Forge Tier State
+# Written by setup-forge workflow
+
+# Tool availability (detected during [SF] Setup Forge)
+tools:
+  ast_grep: {true/false from detection}
+  gh_cli: {true/false from detection}
+  qmd: {true/false from detection}
+
+# Capability tier (derived from tool availability)
+# Quick = no tools | Forge = ast-grep | Deep = ast-grep + gh + qmd
+tier: {calculated_tier}
+tier_detected_at: {current ISO timestamp}
+```
+
+**This file is ALWAYS overwritten** on every run — it reflects current tool state.
+
+If the write fails, report the error and halt the workflow.
+
+### 2. Handle preferences.yaml
+
+Check if `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml` exists:
+
+**If it does NOT exist (first run):** Create with defaults:
+
+```yaml
+# Ferris Sidecar: User Preferences
+# Created by setup-forge workflow on first run
+# Edit this file to customize Ferris behavior
+
+# Override detected tier (set to Quick, Forge, or Deep to force a tier)
+tier_override: ~
+
+# Skill generation defaults
+default_source_authority: community
+default_confidence_threshold: 0.7
+```
+
+**If it DOES exist:** Do not modify. Preserve entirely.
+
+### 3. Ensure forge-data/ Directory
+
+Check if `{project-root}/forge-data/` directory exists:
+
+- If missing: create it
+- If exists: skip silently
+
+### 4. Auto-Proceed
+
+"**Proceeding to auto-index check...**"
+
+#### Menu Handling Logic:
+
+- After all file operations complete successfully, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Proceed directly to next step after configuration is written
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN forge-tier.yaml has been written successfully and preferences.yaml exists (created or pre-existing) will you load and read fully `{nextStepFile}` to execute the auto-index step.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- forge-tier.yaml written with accurate tool booleans, tier, and timestamp
+- preferences.yaml exists (created with defaults on first run, preserved on re-run)
+- forge-data/ directory exists (created or pre-existing)
+- Auto-proceeded to step-03
+
+### ❌ SYSTEM FAILURE:
+
+- forge-tier.yaml write fails and workflow continues
+- preferences.yaml overwritten when it already existed
+- Incorrect tool values written (not matching step-01 detection)
+- Missing tier_detected_at timestamp
+- Re-detecting tools instead of using step-01 results
+
+**Master Rule:** forge-tier.yaml must be written accurately. preferences.yaml must never be overwritten. These are the foundation for all downstream workflows.

package/src/workflows/setup-forge/steps-c/step-03-auto-index.md

@@ -0,0 +1,116 @@
+---
+name: 'step-03-auto-index'
+description: 'Index current project as QMD collection (Deep tier only)'
+
+nextStepFile: './step-04-report.md'
+---
+
+# Step 3: Auto-Index Project
+
+## STEP GOAL:
+
+If the detected tier is Deep, index the current project as a QMD collection for knowledge search. For Quick and Forge tiers, skip silently and proceed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step, ensure entire file is read
+- 🎯 Execute all operations autonomously — no user interaction
+
+### Role Reinforcement:
+
+- ✅ You are a system executor performing conditional indexing
+- ✅ Graceful degradation is paramount — never fail the workflow over indexing
+- ✅ No negative messaging — do not mention what non-Deep tiers are missing
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on QMD indexing (Deep tier) or graceful skip (other tiers)
+- 🚫 FORBIDDEN to display "missing" or "skipped" messages for non-Deep tiers
+- 🚫 FORBIDDEN to fail the workflow if QMD indexing encounters errors
+- 💬 If indexing fails: log the issue, note that index can be retried, continue
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 QMD indexing operates on the project root directory
+- 📖 Use {calculated_tier} from step-01 context
+- 🚫 FORBIDDEN to attempt indexing for Quick or Forge tiers
+
+## CONTEXT BOUNDARIES:
+
+- Available: {calculated_tier} from step-01, forge-tier.yaml written in step-02
+- Focus: conditional QMD indexing only
+- Limits: only index if Deep tier
+- Dependencies: step-02 must have completed (forge-tier.yaml exists)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Check Tier
+
+Read `{calculated_tier}` from context.
+
+**If tier is NOT Deep:** Proceed directly to step 4 — auto-proceed with no output, no messaging.
+
+**If tier IS Deep:** Continue to section 2.
+
+### 2. Index Project with QMD (Deep Tier Only)
+
+Index the current project directory as a QMD collection for knowledge search.
+
+Use the QMD MCP server to create or update a collection for the current project:
+- Collection name: derive from project directory name
+- Source: project root directory
+- Scope: markdown files, source code, documentation
+
+**Timeout handling:** If indexing takes excessively long on a large project:
+- Log that indexing is in progress but may need more time
+- Note in context that index may be incomplete
+- Do NOT halt or fail the workflow
+
+**Error handling:** If QMD indexing fails:
+- Log the specific error
+- Note that indexing can be retried by re-running setup-forge
+- The forge-tier.yaml already records `qmd: true` — the tool is available even if indexing failed
+- Continue to step 4
+
+### 3. Auto-Proceed
+
+"**Proceeding to forge status report...**"
+
+#### Menu Handling Logic:
+
+- After indexing completes (or is skipped for non-Deep tiers), immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Proceed directly to next step after indexing or skip
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the tier check has been performed (and indexing completed or skipped accordingly) will you load and read fully `{nextStepFile}` to execute the report step.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Deep tier: QMD indexing attempted, succeeded or degraded gracefully
+- Quick/Forge tier: skipped silently with no negative messaging
+- Workflow continues regardless of indexing outcome
+- Auto-proceeded to step-04
+
+### ❌ SYSTEM FAILURE:
+
+- Attempting QMD indexing for Quick or Forge tiers
+- Displaying "skipped" or "missing" messages for non-Deep tiers
+- Halting the workflow due to QMD indexing failure
+- Not proceeding to step-04 after this step
+
+**Master Rule:** This step must NEVER fail the workflow. Deep tier indexing is best-effort. Non-Deep tiers skip silently.

package/src/workflows/setup-forge/steps-c/step-04-report.md

@@ -0,0 +1,131 @@
+---
+name: 'step-04-report'
+description: 'Display forge status report with positive capability framing'
+
+tierRulesData: '../data/tier-rules.md'
+---
+
+# Step 4: Forge Status Report
+
+## STEP GOAL:
+
+Display the forge status report with positive capability framing, report tier changes on re-run, and optionally fetch the latest agentskills.io spec if flagged.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🎯 Execute all operations autonomously — display report and complete
+
+### Role Reinforcement:
+
+- ✅ You are Ferris reporting forge readiness
+- ✅ Frame ALL capabilities positively — describe what the tier GIVES
+- ✅ On re-run: explicitly report what changed (upgrade/downgrade/same)
+- ✅ Brief forge metaphor appropriate here — this is the completion moment
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on displaying the status report
+- 🚫 FORBIDDEN to use negative framing ("missing", "lacking", "unavailable")
+- 🚫 FORBIDDEN to list tools that are NOT available
+- 💬 Use tier capability descriptions from tier-rules.md
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Load tier-rules.md for capability descriptions and re-run messages
+- 📖 Use context from step-01 (detected_tools, calculated_tier, previous_tier)
+- 🚫 This is the final step — no next step to load
+
+## CONTEXT BOUNDARIES:
+
+- Available: {detected_tools}, {calculated_tier}, {previous_tier}, {tier_override} from step-01
+- Available: tool version strings from step-01
+- Focus: report display only — no file modifications
+- Dependencies: steps 01-03 must have completed
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Capability Descriptions
+
+Load and read {tierRulesData} for the tier capability descriptions and re-run messages.
+
+### 2. Display Forge Status Report
+
+**Format the report as follows:**
+
+```
+═══════════════════════════════════════
+  FORGE STATUS
+═══════════════════════════════════════
+
+  Tier:  {calculated_tier}
+  {tier capability description from tier-rules.md}
+
+  Tools Detected:
+  {for each tool that is available, show: tool name — version}
+
+{if tier_override is active:}
+  Note: Tier override active (set in preferences.yaml)
+
+{if re-run with tier change:}
+  {appropriate upgrade/downgrade message from tier-rules.md}
+
+{if re-run with same tier:}
+  {same-tier message from tier-rules.md}
+
+═══════════════════════════════════════
+  Forge ready. {calculated_tier} tier active.
+═══════════════════════════════════════
+```
+
+**Tool display rules:**
+- Only show tools that ARE available with their version strings
+- Do NOT list unavailable tools
+- Do NOT show a "missing" column or section
+
+### 3. Handle --update-spec Flag (Optional)
+
+**If `--update-spec` was passed:**
+- Attempt to fetch the latest agentskills.io specification schema
+- Use `gh` or `curl` to retrieve the spec
+- Store in `{project-root}/forge-data/agentskills-spec.json` (or appropriate format)
+- If fetch succeeds: display "agentskills.io spec updated."
+- If fetch fails: display "Could not fetch agentskills.io spec. Existing spec (if any) unchanged."
+- Do NOT fail the workflow over this — it is purely optional
+
+**If `--update-spec` was NOT passed:**
+- Skip silently
+
+### 4. Workflow Complete
+
+This is the final step. The setup-forge workflow is now complete.
+
+No next step to load. The workflow ends here.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Forge status report displayed with positive capability framing
+- Only available tools shown (no "missing" lists)
+- Tier capability description matches calculated tier
+- Re-run: tier change correctly reported (or same-tier confirmed)
+- --update-spec handled if flagged (success or graceful failure)
+- Workflow completes cleanly
+
+### ❌ SYSTEM FAILURE:
+
+- Negative framing in report ("missing", "unavailable", "lacking")
+- Listing tools that are NOT available
+- Not using tier capability descriptions from tier-rules.md
+- Not reporting tier change on re-run
+- Attempting to load a next step (this is the final step)
+
+**Master Rule:** The report must leave users feeling confident about their forge capabilities, not anxious about what they're missing. Positive framing only.