bmad-module-skill-forge 0.2.0

package/src/workflows/quick-skill/workflow-plan-quick-skill.md

@@ -0,0 +1,405 @@
+---
+conversionFrom: 'src/workflows/quick-skill/quick-skill.spec.md'
+originalFormat: 'Workflow Specification (spec.md)'
+stepsCompleted: ['step-00-conversion', 'step-02-classification', 'step-03-requirements', 'step-04-tools', 'step-05-plan-review', 'step-06-design', 'step-07-foundation', 'step-08-build-step-01', 'step-09-build-steps-02-06']
+created: 2026-02-26
+status: VALIDATED
+approvedDate: 2026-02-27
+confirmationDate: 2026-02-27
+confirmationType: conversion
+coverageStatus: complete
+validationDate: 2026-02-27
+validationStatus: COMPLETE
+validationReport: './validation-report.md'
+---
+
+# Workflow Creation Plan
+
+## Conversion Source
+
+**Original Path:** src/workflows/quick-skill/quick-skill.spec.md
+**Original Format:** Workflow Specification (spec.md) — pre-designed blueprint with step table, inputs/outputs, and agent integration
+**Detected Structure:** Single specification document defining a 6-step create-only workflow for brief-less skill generation from package names or GitHub URLs
+
+---
+
+## Original Workflow Analysis
+
+### Goal (from source)
+
+Brief-less fast skill with package-to-repo resolution. The fastest path to a skill — accepts a GitHub URL or package name, resolves to source, reads exports via source reading (no AST required), and produces a best-effort SKILL.md. No brief needed. Package-to-repo resolution handles npm/PyPI/crates.io names.
+
+### Original Steps (Complete List)
+
+**Step 1:** resolve-target - Resolve package name or URL to GitHub repo
+**Step 2:** ecosystem-check - Search if official skill already exists
+**Step 3:** quick-extract - Read source, extract public API surface
+**Step 4:** compile - Assemble best-effort SKILL.md
+**Step 5:** validate - Validate against spec
+**Step 6:** write - Write skill files
+
+### Output / Deliverable
+
+Document-producing workflow generating three files:
+- `{skills_output_folder}/{name}/SKILL.md` — Best-effort skill document
+- `{skills_output_folder}/{name}/context-snippet.md` — Passive context for platform injection
+- `{skills_output_folder}/{name}/metadata.json` — With `source_authority: community`
+
+### Input Requirements
+
+**Required:**
+- GitHub URL or package name (npm/PyPI/crates.io)
+
+**Optional:**
+- Language hint
+- Scope hint (specific directories)
+
+### Key Instructions to LLM
+
+- Uses Ferris agent persona (Architect mode) as primary agent
+- No brief needed — this is a speed-first entry point
+- Package-to-repo resolution via `manifest_reader` internal utility
+- Source reading approach (no AST required) — reads exports directly
+- Best-effort output quality — not full-depth skill analysis
+- `source_authority: community` designation for all outputs
+
+---
+
+## Conversion Notes
+
+**What works well in original:**
+- Clear 6-step pipeline with well-defined boundaries between steps
+- Smart input flexibility (URL or package name from multiple registries)
+- Explicit output file list with metadata conventions
+- Ecosystem-aware (checks for existing official skills before duplicating work)
+
+**What needs improvement:**
+- Spec only — no step-level implementation details exist yet
+- No menu structures or user interaction points defined
+- No data files or templates specified
+- Step granularity may need adjustment during build (e.g., resolve-target could be complex)
+
+**Compliance gaps identified:**
+- No step files exist (need full creation, not conversion)
+- No frontmatter definitions for steps
+- No workflow.md entry point
+- No data/ folder templates
+- No validation mode steps defined (spec says create-only, which is valid)
+- Need to define critical path and state tracking across steps
+
+---
+
+## Memory-Informed Discovery Notes
+
+**Preserve:**
+- 6-step linear pipeline matches proven create-skill pattern
+- Ecosystem-check advisory gate pattern (5s timeout, graceful degradation, P/I/A menu only on match)
+- `source_authority: community` correctly positions output in SKF authority hierarchy
+- No-brief differentiator — alternative entry point to create-skill pipeline
+
+**Address:**
+- `manifest_reader` utility doesn't exist — need self-contained resolution logic or clear tool requirements
+- No tier awareness needed — operates at fixed Quick-tier equivalent (best-effort)
+- Need explicit error handling table (hard halt, graceful degradation, silent skip patterns)
+- Step 03 "source reading" needs clear definition: README, manifest files, top-level exports
+
+**Add:**
+- Graceful fallback chain for resolution: GitHub URL direct > registry API lookup > web search > fail gracefully
+- Advisory ecosystem-check following create-skill step-02 exact pattern
+- Lighter validation for community source_authority tier
+- Ferris Architect mode with tier-aware acknowledgment
+
+**Audience:** Same SKF users — developers wanting fast community skill generation without full brief-skill > create-skill pipeline. Phase 1b (Entry Points) build priority.
+
+---
+
+## Classification Decisions
+
+**Workflow Name:** quick-skill
+**Target Path:** {project-root}/_bmad/skf/workflows/quick-skill/
+**Build Path:** {bmb_creations_output_folder}/workflows/quick-skill/
+
+**4 Key Decisions:**
+1. **Document Output:** true — produces SKILL.md, context-snippet.md, metadata.json
+2. **Module Affiliation:** skf — part of Skills Knowledge Framework module
+3. **Session Type:** single-session — speed-first, 6 focused steps, best-effort output
+4. **Lifecycle Support:** create-only — steps-c/ only, no edit/validate modes
+
+**Structure Implications:**
+- Needs `steps-c/` directory only (no steps-e/ or steps-v/)
+- Standard `step-01` init (no continuation logic, no step-01b-continue)
+- Document-producing: steps contribute progressively to output files
+- Module-based: has access to SKF-specific variables (skills_output_folder, forge-tier, etc.)
+- No stepsCompleted tracking needed in output document (single-session)
+
+---
+
+## Requirements
+
+**Flow Structure:**
+- Pattern: linear
+- Phases: resolve input (01), dedup check (02), extraction (03), compilation (04), validation (05), output (06)
+- Estimated steps: 6
+- Conditional branch: step-02 ecosystem-check shows P/I/A menu only if match found, otherwise auto-proceeds
+
+**User Interaction:**
+- Style: mostly autonomous
+- Decision points: step-01 (user provides input), step-02 (conditional — only if ecosystem match), step-04 (optional checkpoint to review compiled SKILL.md)
+- Checkpoint frequency: minimal — speed-first design, most steps auto-proceed (P3)
+
+**Inputs Required:**
+- Required: GitHub URL or package name (npm/PyPI/crates.io)
+- Optional: language hint, scope hint (specific directories)
+- Prerequisites: none — this is the brief-less entry point, no setup-forge or brief-skill needed
+
+**Output Specifications:**
+- Type: multi-file document output
+- Files:
+  - `{skills_output_folder}/{name}/SKILL.md` — structured template following agentskills.io spec sections
+  - `{skills_output_folder}/{name}/context-snippet.md` — strict two-line format per ADR-L (~30 tokens)
+  - `{skills_output_folder}/{name}/metadata.json` — strict JSON with `source_authority: community`
+- Format: structured (SKILL.md), strict (context-snippet.md, metadata.json)
+- Frequency: single run per skill
+
+**Success Criteria:**
+- Package/URL successfully resolved to GitHub repo source
+- Public exports documented (best-effort, may be incomplete)
+- Valid SKILL.md with core sections populated
+- context-snippet.md in correct two-line format
+- metadata.json with `source_authority: community` and required fields
+- No ecosystem duplicate if official skill already exists (user chose to proceed)
+
+**Instruction Style:**
+- Overall: prescriptive
+- Notes: mechanical pipeline with exact operations per step. Ferris Architect mode provides precision execution. Matches Tax Organizer / SOP Writer pattern — focused questions, specific operations, no creative facilitation.
+
+---
+
+## Tools Configuration
+
+**Core BMAD Tools:**
+- **Party Mode:** excluded — prescriptive pipeline, no creative facilitation needed
+- **Advanced Elicitation:** excluded — mechanical steps, no deep exploration needed
+- **Brainstorming:** excluded — no ideation phases
+
+**LLM Features:**
+- **Web-Browsing:** included — critical for step-01 (registry API lookups, package-to-repo resolution), step-02 (ecosystem search), step-03 (reading GitHub source)
+- **File I/O:** included — step-03 reads source files, step-06 writes three output files
+- **Sub-Agents:** excluded — linear pipeline, no parallelization needed
+- **Sub-Processes:** excluded — linear pipeline, no parallelization needed
+
+**Memory:**
+- Type: single-session
+- Tracking: none — no complex state management needed
+
+**External Integrations:**
+- None required — web-browsing handles registry lookups and GitHub access
+
+**Installation Requirements:**
+- None — all selected tools are built-in
+
+**Workflow Structure Preview:**
+
+| Phase | Step | Name | Purpose | Menu |
+|-------|------|------|---------|------|
+| 1 | 01 | resolve-target | Accept input, resolve package/URL to GitHub repo | Init — user provides input |
+| 2 | 02 | ecosystem-check | Query agentskills.io for existing official skill | Conditional P/I/A (match only) |
+| 3 | 03 | quick-extract | Read source, extract public API surface | P3 auto-proceed |
+| 4 | 04 | compile | Assemble SKILL.md, context-snippet, metadata | P2 checkpoint (review output) |
+| 5 | 05 | validate | Validate against agentskills.io spec (community tier) | P3 auto-proceed |
+| 6 | 06 | write | Write files to output folder, display summary | Final step |
+
+---
+
+## Workflow Design
+
+### File Structure
+
+```
+quick-skill/
+├── workflow.md                         # Entry point
+├── data/
+│   ├── skill-template.md              # SKILL.md section template
+│   └── registry-resolution.md         # Package-to-repo resolution patterns
+└── steps-c/
+    ├── step-01-resolve-target.md
+    ├── step-02-ecosystem-check.md
+    ├── step-03-quick-extract.md
+    ├── step-04-compile.md
+    ├── step-05-validate.md
+    └── step-06-write.md
+```
+
+### Step Sequence Table
+
+| # | Name | Type | Menu | Frontmatter Refs |
+|---|------|------|------|-----------------|
+| 01 | resolve-target | Init (non-continuable) | User input → auto-proceed | nextStepFile, registryResolutionData |
+| 02 | ecosystem-check | Middle (Simple) | Conditional P/I/A if match, else P3 | nextStepFile |
+| 03 | quick-extract | Middle (Simple) | P3 auto-proceed | nextStepFile |
+| 04 | compile | Middle (Simple) | P2 (C only) checkpoint | nextStepFile, skillTemplateData |
+| 05 | validate | Middle (Simple) | P3 auto-proceed | nextStepFile |
+| 06 | write | Final | No next step | — |
+
+### Step Action Plans
+
+**Step 01 — resolve-target (Init):**
+- Accept user input: GitHub URL or package name
+- If GitHub URL: validate URL format, extract org/repo
+- If package name: resolution fallback chain (from registry-resolution.md data):
+  1. npm registry API → extract `repository.url`
+  2. PyPI API → extract `project_urls.Source`
+  3. crates.io API → extract `repository`
+  4. Web search fallback → find GitHub repo
+- Accept optional: language hint, scope hint
+- Set state: resolved_url, repo_name, language_hint, scope_hint
+- Auto-proceed to step-02
+
+**Step 02 — ecosystem-check (Conditional):**
+- Query agentskills.io ecosystem for repo_name skill
+- 5-second timeout, tool unavailability = silent skip
+- No match: auto-proceed to step-03 (no user interaction)
+- Match found: conditional menu P/I/A
+  - [P] Proceed — compile custom skill anyway
+  - [I] Install — install existing official skill (exit workflow)
+  - [A] Abort — cancel compilation
+
+**Step 03 — quick-extract (Auto-proceed):**
+- Read repo README.md for description, features, usage
+- Read manifest file (package.json / pyproject.toml / Cargo.toml)
+- Scan top-level exports (index.js/ts, __init__.py, lib.rs)
+- If scope hint: focus on specified directories
+- Extract: export names, function signatures, type definitions (surface-level)
+- No AST — grep/pattern-based extraction
+- Set state: extraction_inventory
+- Auto-proceed to step-04
+
+**Step 04 — compile (Checkpoint):**
+- Load skill-template.md from data/
+- Assemble SKILL.md from extraction_inventory
+- Generate context-snippet.md in two-line format (ADR-L, ~30 tokens)
+- Generate metadata.json with source_authority: community
+- Present compiled SKILL.md for review
+- [C] Continue to validation
+
+**Step 05 — validate (Auto-proceed):**
+- Check SKILL.md has required sections populated
+- Check context-snippet.md format compliance (two-line)
+- Check metadata.json has required fields
+- Community-tier validation (lighter than official)
+- Report any gaps/issues
+- Auto-proceed to step-06
+
+**Step 06 — write (Final):**
+- Create output directory: {skills_output_folder}/{name}/
+- Write SKILL.md, context-snippet.md, metadata.json
+- Display summary: files written, paths, token estimate
+- Recommend next: test-skill (advisory), export-skill
+
+### Data Flow
+
+```
+step-01 → resolved_url, repo_name, language_hint, scope_hint
+    ↓
+step-02 → ecosystem_status (match/no-match/skip)
+    ↓
+step-03 → extraction_inventory (exports, description, manifest_data)
+    ↓
+step-04 → skill_content (SKILL.md), context_snippet, metadata_json
+    ↓
+step-05 → validation_result (pass/fail, issues_list)
+    ↓
+step-06 → writes files, displays summary
+```
+
+### Error Handling
+
+| Error | Response |
+|-------|----------|
+| Unresolvable package name | Hard halt — cannot proceed without source |
+| GitHub repo inaccessible | Hard halt — need source to extract |
+| Ecosystem check tool unavailable | Silent skip — proceed as no-match |
+| Ecosystem check timeout (>5s) | Silent skip — proceed as no-match |
+| No exports found in source | Graceful — minimal SKILL.md from README |
+| Validation failures | Advisory — report issues, allow proceed |
+| File write failure | Hard halt — cannot complete without output |
+
+### Workflow Chaining
+
+- **Prerequisites:** none (brief-less entry point)
+- **Alternative to:** brief-skill → create-skill pipeline
+- **Recommended next:** test-skill (advisory), export-skill
+- **Output contract:** {skills_output_folder}/{name}/ with SKILL.md, context-snippet.md, metadata.json
+
+### Subprocess Optimization
+
+No subprocess optimization needed — linear pipeline, no parallelization opportunities.
+
+### Role and Persona
+
+Ferris — Architect mode. Prescriptive precision execution, speed-first, no creative facilitation.
+
+---
+
+## Foundation Build Complete
+
+**Created:**
+- Folder structure at: {bmb_creations_output_folder}/workflows/quick-skill/
+- workflow.md — entry point with SKF config loading, Ferris rapid compiler role
+- data/skill-template.md — SKILL.md section structure, context-snippet format (ADR-L), metadata.json format
+- data/registry-resolution.md — package-to-repo resolution fallback chain (npm/PyPI/crates.io/web search)
+- steps-c/ directory — ready for step file creation
+
+**Configuration:**
+- Workflow name: quick-skill
+- Continuable: no (single-session)
+- Document output: yes — multi-file (SKILL.md, context-snippet.md, metadata.json)
+- Mode: create-only (steps-c/ only)
+- Module config: {project-root}/_bmad/skf/config.yaml
+- Module variables: skills_output_folder, forge_data_folder
+
+**Next Steps:**
+- Step 8: Build step-01-resolve-target (Init)
+- Step 9: Build remaining steps 02-06 (repeatable)
+
+---
+
+## Step 01 Build Complete
+
+**Created:**
+- steps-c/step-01-resolve-target.md
+
+**Step Configuration:**
+- Type: Init (non-continuable, no input discovery)
+- Menu: Auto-proceed after successful resolution
+- Next Step: step-02-ecosystem-check
+- Data ref: registry-resolution.md for fallback chain
+- No step-01b (single-session workflow)
+
+**Supporting Files:**
+- data/registry-resolution.md (created in foundation)
+
+---
+
+## Steps 02-06 Build Complete
+
+**Created:**
+- steps-c/step-02-ecosystem-check.md (143 lines) — Conditional advisory gate, P/I/A on match, auto-proceed on no-match/skip
+- steps-c/step-03-quick-extract.md (177 lines) — Surface-level source reading, extraction inventory, auto-proceed
+- steps-c/step-04-compile.md (180 lines) — Assembles SKILL.md/snippet/metadata from inventory, P2 checkpoint for review
+- steps-c/step-05-validate.md (150 lines) — Community-tier advisory validation, auto-proceed
+- steps-c/step-06-write.md (160 lines) — Final step, writes files, displays summary, recommends next workflows
+
+**All step files within size limits except step-01 (165 vs 150 Init guideline — minor, 15 lines over)**
+
+**Complete file manifest:**
+- workflow.md (56 lines)
+- data/skill-template.md (66 lines)
+- data/registry-resolution.md (91 lines)
+- steps-c/step-01-resolve-target.md (165 lines)
+- steps-c/step-02-ecosystem-check.md (143 lines)
+- steps-c/step-03-quick-extract.md (177 lines)
+- steps-c/step-04-compile.md (180 lines)
+- steps-c/step-05-validate.md (150 lines)
+- steps-c/step-06-write.md (160 lines)
+- Total: 10 files, 1188 lines

package/src/workflows/quick-skill/workflow.md

@@ -0,0 +1,56 @@
+---
+name: quick-skill
+description: Brief-less fast skill with package-to-repo resolution
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/quick-skill'
+---
+
+# Quick Skill
+
+**Goal:** The fastest path to a skill — accept a GitHub URL or package name, resolve to source, extract public API surface, and produce a best-effort SKILL.md with context snippet and metadata. No brief needed.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a rapid skill compiler collaborating with a developer. This is a partnership, not a client-vendor relationship. You bring source analysis and skill document assembly expertise, while the user brings the target package or repository they want to create a skill for. Work together efficiently — speed is the priority.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory — never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **Append-Only Building**: Build output files progressively as directed by each step
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+- `skills_output_folder`, `forge_data_folder`
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `./steps-c/step-01-resolve-target.md` to begin the workflow.

package/src/workflows/setup-forge/data/tier-rules.md

@@ -0,0 +1,50 @@
+# Tier Calculation Rules
+
+## Tool Detection Commands
+
+| Tool | Verification Command | What Confirms Availability |
+|------|---------------------|---------------------------|
+| ast-grep | `ast-grep --version` | Returns version string without error |
+| gh | `gh --version` | Returns version string without error |
+| qmd | `qmd status` | Returns status indicating initialized and operational |
+
+**Important:** Use verification commands, not existence checks (`which`, `command -v`). A tool must be functional, not just present on PATH.
+
+## Tier Calculation
+
+| Tier | Required Tools | Rule |
+|------|---------------|------|
+| Quick | None | Default when no tools are available |
+| Forge | ast-grep | ast-grep available, regardless of gh/qmd |
+| Deep | ast-grep + gh + qmd | All three tools available and functional |
+
+**Override:** If `tier_override` is set in preferences.yaml, use that value instead of calculated tier.
+
+**Edge cases:**
+- gh available but no ast-grep → Quick (gh alone doesn't unlock Forge)
+- ast-grep + gh but no qmd → Forge (qmd required for Deep)
+- ast-grep + qmd but no gh → Forge (gh required for Deep)
+
+## Tier Capability Descriptions
+
+Use these for positive-framing in the report step. Describe what the tier GIVES, never what it lacks.
+
+### Quick Tier
+"Quick tier active. You have fast, template-driven skill generation with package-name resolution. Perfect for getting started quickly."
+
+### Forge Tier
+"Forge tier active. You have AST-backed structural code analysis with line-level citations, plus template-driven generation. Every skill instruction traces to verified source code."
+
+### Deep Tier
+"Deep tier active. Full capability unlocked — AST-backed code analysis, GitHub repository exploration, and QMD knowledge search with cross-repository synthesis. Maximum provenance and intelligence."
+
+## Re-run Tier Change Messages
+
+### Upgrade
+"Tier upgraded from {previous} to {current}. {newly available tool(s)} now detected — expanded capabilities unlocked."
+
+### Downgrade
+"Tier changed from {previous} to {current}. {tool} no longer detected. Run the tool's installation to restore capabilities."
+
+### Same
+"Tier unchanged: {current}. All previously detected tools confirmed."

package/src/workflows/setup-forge/steps-c/step-01-detect-and-tier.md

@@ -0,0 +1,140 @@
+---
+name: 'step-01-detect-and-tier'
+description: 'Detect available tools and determine forge capability tier'
+
+nextStepFile: './step-02-write-config.md'
+tierRulesData: '../data/tier-rules.md'
+---
+
+# Step 1: Detect Tools and Determine Tier
+
+## STEP GOAL:
+
+Verify availability of the three forge tools (ast-grep, gh, qmd), read any existing configuration for re-run comparison, check for tier override, and calculate the capability tier.
+
+## 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 environment resolution
+- ✅ Tool detection must be empirical — run actual commands, never assume
+- ✅ Record exact results (version strings, error messages)
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on tool detection and tier calculation
+- 🚫 FORBIDDEN to write any files — that is step-02's job
+- 🚫 FORBIDDEN to skip any tool check — all 3 must be verified
+- 💬 Tool command failures are NOT errors — they indicate unavailability
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Store all results in memory for step-02
+- 📖 Load tier-rules.md for calculation reference
+- 🚫 FORBIDDEN to proceed without checking all 3 tools
+
+## CONTEXT BOUNDARIES:
+
+- This is the first step — no prior context exists
+- Available: forge-tier.yaml and preferences.yaml may exist from prior runs
+- Focus: tool verification and tier calculation only
+- Dependencies: none — this step bootstraps everything
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Tier Rules
+
+Load and read {tierRulesData} for the tool detection commands and tier calculation logic.
+
+### 2. Check for Existing Configuration (Re-run Detection)
+
+**Read existing forge-tier.yaml** at `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml`:
+- If exists: store the current `tier` value as `{previous_tier}` and `tier_detected_at` as `{previous_detection_date}`
+- If not found: set `{previous_tier}` to null (first run)
+
+**Read existing preferences.yaml** at `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml`:
+- If exists: check for `tier_override` value
+- If not found: set `{tier_override}` to null
+
+### 3. Verify Tool: ast-grep
+
+Run: `ast-grep --version`
+
+- If succeeds: record `{ast_grep: true}` and store version string
+- If fails (command not found or error): record `{ast_grep: false}`
+
+### 4. Verify Tool: gh
+
+Run: `gh --version`
+
+- If succeeds: record `{gh_cli: true}` and store version string
+- If fails: record `{gh_cli: false}`
+
+### 5. Verify Tool: qmd
+
+Run: `qmd status`
+
+- If succeeds and indicates operational: record `{qmd: true}`
+- If fails or indicates not initialized: record `{qmd: false}`
+
+### 6. Calculate Tier
+
+**If `{tier_override}` is set and valid (Quick, Forge, or Deep):**
+- Use `{tier_override}` as `{calculated_tier}`
+- Note that override is active for the report step
+
+**If no override, apply tier rules from {tierRulesData}:**
+- `{ast_grep}` AND `{gh_cli}` AND `{qmd}` all true → **Deep**
+- `{ast_grep}` true (regardless of gh/qmd) → **Forge**
+- Otherwise → **Quick**
+
+**If `{tier_override}` is set but invalid:** ignore it, use detected tier, flag for warning in report.
+
+### 7. Auto-Proceed
+
+"**Proceeding to write configuration...**"
+
+#### Menu Handling Logic:
+
+- After tier calculation is complete, 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 detection and calculation
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all 3 tools have been verified and the tier has been calculated will you load and read fully `{nextStepFile}` to execute the configuration write step.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All 3 tools checked via verification commands (not existence checks)
+- Existing forge-tier.yaml read for re-run comparison (if present)
+- Existing preferences.yaml read for tier_override (if present)
+- Tier correctly calculated from tool results or override applied
+- All results stored in context for step-02
+- Auto-proceeded to step-02
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping any tool verification
+- Using `which` or `command -v` instead of verification commands
+- Assuming tool availability without running the command
+- Writing files in this step (that is step-02)
+- Not checking for existing configuration on re-runs
+
+**Master Rule:** Every tool MUST be verified empirically. No assumptions, no shortcuts.