bmad-module-skill-forge 0.2.0

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

@@ -0,0 +1,318 @@
+---
+conversionFrom: 'src/workflows/audit-skill/audit-skill.spec.md'
+originalFormat: 'BMAD Workflow Specification (Placeholder)'
+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-remaining-steps', 'step-10-confirmation']
+created: 2026-02-27
+status: VALIDATED
+confirmationDate: 2026-02-27
+confirmationType: conversion
+coverageStatus: complete
+validationStatus: COMPLETE
+validationDate: 2026-02-27
+validationReport: './validation-report.md'
+approvedDate: 2026-02-27
+---
+
+# Workflow Creation Plan
+
+## Conversion Source
+
+**Original Path:** src/workflows/audit-skill/audit-skill.spec.md
+**Original Format:** BMAD Workflow Specification (Placeholder)
+**Detected Structure:** 6-step create-only pipeline defined at spec level, no implementation files exist yet
+
+---
+
+## Original Workflow Analysis
+
+### Goal (from source)
+
+Drift detection between skill and current source. Compares an existing skill against its source code to detect drift. Forge tier: structural comparison via AST diff. Deep tier: full audit including semantic changes and temporal context via QMD. Produces a drift report with severity levels. ADR-A: core workflow, CI is optional export.
+
+### Original Steps (Complete List)
+
+**Step 1:** load-skill - Load existing skill and provenance map
+**Step 2:** re-index - Re-scan source with current tools
+**Step 3:** structural-diff - Compare AST extractions (Forge+)
+**Step 4:** semantic-diff - Compare QMD knowledge context (Deep only)
+**Step 5:** severity-classify - Classify drift items by severity
+**Step 6:** report - Generate drift report
+
+### Output / Deliverable
+
+Drift report with severity levels (added/removed/changed exports, breaking changes). Document-producing workflow.
+
+### Input Requirements
+
+**Required:**
+- Existing skill path
+- Source code (current version)
+
+**Optional:**
+- None specified
+
+### Key Instructions to LLM
+
+- Primary agent: Ferris (Audit mode)
+- Tiered operation: Forge tier (structural only) vs Deep tier (full semantic + QMD)
+- The spec references AST diff for structural comparison and QMD for semantic context
+- CI integration is noted as optional export (ADR-A decision)
+
+---
+
+## Conversion Notes (Memory-Enriched)
+
+**What works well in original (preserve):**
+- Clean 6-step pipeline with logical progression: load → scan → diff → classify → report
+- Tiered Forge/Deep separation aligns with established SKF tier architecture
+- Correct lifecycle positioning (Phase 2, after create-skill and test-skill)
+- Clear input/output specification
+- Document-producing output aligns with drift report use case
+
+**What needs improvement (fix during build):**
+- **Missing Quick tier path** — All SKF workflows support Quick/Forge/Deep with graceful degradation; Quick tier needs text-diff fallback
+- **No provenance map format specification** — Step 01 loads it, but must reference known `provenance-map.json` from create-skill's `forge-data/{name}/` output
+- **No confidence tier labels (T1/T2/T3)** — Every SKF workflow uses these for traceability; drift findings need confidence scoring
+- **Step 04 conditional skip** — semantic-diff is Deep-only but spec has no skip logic or degradation behavior for Forge/Quick tiers
+- No error handling or edge cases documented (missing skill, incompatible versions, no provenance map)
+- No data files, templates, or supporting materials defined
+
+**Missing features to add:**
+- **Batch mode** (`--batch`, `--continue` flags) — Consistent with test-skill, create-skill, and all lifecycle workflows
+- **Dual-mode support** — Individual skill vs stack skill auditing (stack skills have integration patterns needing cross-reference drift detection)
+- **Remediation suggestions** — Like test-skill's gap report, drift items should include actionable fix recommendations
+- **Update-skill chaining** — Drift report should optionally trigger update-skill workflow for detected issues
+
+**Compliance gaps identified:**
+- No step files exist (placeholder spec only)
+- No workflow.md entry point
+- No frontmatter on any files
+- No data/ folder with supporting reference materials (severity classification rules, drift pattern definitions)
+- No templates/ for drift report output format
+- Mode is marked create-only — confirmed appropriate for audit (re-audit is a fresh run, not an edit)
+
+**Cross-workflow integration points (from memory):**
+- **Input from create-skill:** `forge-data/{name}/provenance-map.json`, `evidence-report.md`, `extraction-rules.yaml`
+- **Input from setup-forge:** `forger-sidecar/forge-tier.yaml` for tier detection
+- **Output feeds update-skill:** Drift report triggers remediation workflow
+- **Sibling pattern: test-skill** — Same Ferris Audit mode, zero-hallucination AST citations, tier-aware depth scaling
+- **SKF config:** Loads from `_bmad/skf/config.yaml` (project_name, output_folder, skills_output_folder, forge_data_folder, sidecar_path)
+
+---
+
+## Classification Decisions
+
+**Workflow Name:** audit-skill
+**Target Path:** {project-root}/_bmad/skf/workflows/audit-skill/
+
+**4 Key Decisions:**
+1. **Document Output:** true (drift report with severity levels)
+2. **Module Affiliation:** SKF module
+3. **Session Type:** single-session
+4. **Lifecycle Support:** create-only
+
+**Structure Implications:**
+- Needs `steps-c/` folder only (no steps-e/ or steps-v/)
+- Standard `step-01-init.md` (no continuation logic)
+- Document template for progressive drift report building with `stepsCompleted` tracking
+- SKF module variables available (forge_data_folder, skills_output_folder, sidecar_path)
+- Config loaded from `_bmad/skf/config.yaml`
+- Ferris Audit mode as primary agent with zero-hallucination AST citations
+
+---
+
+## Requirements
+
+**Flow Structure:**
+- Pattern: Linear with conditional skip (Step 04 skipped at Quick/Forge tier)
+- Phases: Load & Baseline (01-02) → Analysis (03-04) → Assessment & Output (05-06)
+- Estimated steps: 6 (matching spec)
+- Step 01: init (load skill + provenance map + detect tier)
+- Step 02: re-index (re-scan source with current tools)
+- Step 03: structural-diff (AST comparison — Forge+ tiers)
+- Step 04: semantic-diff (QMD comparison — Deep tier only, SKIP for Quick/Forge)
+- Step 05: severity-classify (grade all drift items)
+- Step 06: report (generate final drift report)
+
+**User Interaction:**
+- Style: Mostly autonomous with 1 confirmation gate
+- Decision points: Gate 1 after Step 01 — confirm skill loaded, show baseline summary, offer degraded mode if provenance map missing
+- Checkpoint frequency: Minimal — audit is deterministic analysis
+
+**Inputs Required:**
+- Required: Existing skill path (skills/{name}/ with SKILL.md, metadata.json)
+- Required: Source code path (or auto-detect from provenance-map.json source_root)
+- Prerequisites: setup-forge completed (forger-sidecar/forge-tier.yaml), skill created by create-skill (provenance-map.json in forge-data/{name}/)
+- Optional: --batch flag for multiple skills, --continue for batch checkpoint resume, severity threshold filter
+
+**Output Specifications:**
+- Type: Document-producing drift report
+- Format: Structured (required sections)
+- Sections: Audit Summary, Structural Drift (Forge+), Semantic Drift (Deep only), Severity Classification (CRITICAL/HIGH/MEDIUM/LOW), Remediation Suggestions, Provenance
+- Frequency: Single per skill (batch loops at workflow level)
+- Output file: {forge_data_folder}/{skill_name}/drift-report-{timestamp}.md
+- Pattern: Direct-to-Final (steps progressively build the report)
+
+**Success Criteria:**
+- All structural drift items detected with correct severity classification
+- Every finding backed by AST file:line citations (zero hallucination)
+- Confidence tier labels (T1/T2/T3) on all findings
+- Graceful degradation: Quick (text diff) → Forge (AST diff) → Deep (AST + QMD)
+- Actionable remediation suggestions per drift item
+- Overall drift score: CLEAN / MINOR / SIGNIFICANT / CRITICAL
+
+**Instruction Style:**
+- Overall: Prescriptive
+- Notes: Deterministic analysis, not creative facilitation. Matches established SKF pattern (test-skill, create-skill). Every step has exact instructions for what to load, compare, and output.
+
+---
+
+## Tools Configuration
+
+**Core BMAD Tools:**
+- **Party Mode:** Excluded (menu option only) — Audit is deterministic analysis, not creative exploration
+- **Advanced Elicitation:** Excluded (menu option only) — No phases benefit from deep elicitation
+- **Brainstorming:** Excluded — Audit produces findings, not ideas
+
+**LLM Features:**
+- **File I/O:** Required — All phases read skill artifacts, source code, provenance maps; report step writes drift-report.md
+- **Sub-Processes:** Included — Batch mode parallel auditing of multiple skills (Step 01 batch loop)
+- **Sub-Agents:** Excluded — Single-agent workflow (Ferris Audit mode)
+- **Web-Browsing:** Excluded — All analysis is local
+
+**Memory:**
+- Type: Single-session (no complex memory)
+- Tracking: stepsCompleted in drift report frontmatter
+- Sidecar: Reads forger-sidecar/forge-tier.yaml (pre-existing from setup-forge)
+
+**External Integrations (SKF-specific, pre-detected by setup-forge):**
+- **ast_bridge** (ast-grep): Required at Forge/Deep tier — Steps 02-03 structural extraction and comparison
+- **gh_bridge** (gh CLI): Required at all tiers — Steps 01-02 source file reading
+- **qmd_bridge** (QMD): Required at Deep tier only — Step 04 semantic knowledge context
+- **skills_ref**: Included — Step 01 skill format validation and ecosystem cross-reference
+
+**Installation Requirements:**
+- None — all tools pre-detected by setup-forge workflow
+- User preference: N/A (no installation needed)
+
+---
+
+## Workflow Design
+
+### Step Sequence
+
+| Step | Name | Type | Menu | Subprocess | Size Est. |
+|------|------|------|------|------------|-----------|
+| 01 | init | Init with Input Discovery | C only (user gate) | — | ~180 lines |
+| 02 | re-index | Middle (Simple) | Auto-proceed | Pattern 2 (per-file AST) | ~150 lines |
+| 03 | structural-diff | Middle (Simple) | Auto-proceed | Pattern 4 (parallel diff) | ~200 lines |
+| 04 | semantic-diff | Middle (Simple) + Conditional Skip | Auto-proceed | Pattern 3 (QMD ops) | ~150 lines |
+| 05 | severity-classify | Middle (Simple) | Auto-proceed | Pattern 3 (rules lookup) | ~180 lines |
+| 06 | report | Final Step | No next step | — | ~200 lines |
+
+### Step Details
+
+**Step 01: init**
+- Type: Init with Input Discovery
+- Goal: Load existing skill, provenance map, and detect forge tier
+- Input Discovery: skill path → SKILL.md + metadata.json, provenance-map.json from forge-data, forge-tier.yaml from sidecar
+- Creates: drift report from template with frontmatter + Audit Summary skeleton
+- User Gate: Present baseline summary (skill name, export count, provenance age, tier, source path). Offer degraded mode if provenance map missing.
+- Menu: [C] Continue after confirmation
+- Batch: If --batch, loop over skill list; if --continue, check sidecar checkpoint
+
+**Step 02: re-index**
+- Type: Middle (Simple), Auto-proceed
+- Goal: Re-scan source code with current tier tools
+- Quick: text pattern extraction via gh_bridge
+- Forge: AST extraction via ast_bridge (T1 confidence)
+- Deep: AST + QMD temporal context (T2 confidence)
+- Subprocess: Pattern 2 — per source file, launch subprocess for extraction, return structured findings
+- Output: Internal state (current extraction snapshot), no report append yet
+
+**Step 03: structural-diff**
+- Type: Middle (Simple), Auto-proceed
+- Goal: Compare provenance map extractions against current scan
+- Diff categories: added exports, removed exports, changed signatures
+- Quick: text-based name comparison (T1-low)
+- Forge/Deep: full AST structural comparison with line-level citations (T1)
+- Subprocess: Pattern 4 — parallel comparison of export categories
+- Output: Appends ## Structural Drift section to drift report
+
+**Step 04: semantic-diff**
+- Type: Middle (Simple) with Conditional Skip, Auto-proceed
+- Goal: Compare QMD knowledge context (Deep tier only)
+- If Deep → execute semantic comparison via qmd_bridge
+- If Quick/Forge → skip with note in report
+- Subprocess: Pattern 3 — QMD collection query for semantic changes
+- Output: Appends ## Semantic Drift section (or skip notice) to report
+
+**Step 05: severity-classify**
+- Type: Middle (Simple), Auto-proceed
+- Goal: Grade every drift finding by severity
+- Loads: data/severity-rules.md for classification criteria
+- CRITICAL: removed/renamed exports, changed signatures (breaking)
+- HIGH: new public API not in skill
+- MEDIUM: implementation changes behind stable API
+- LOW: style/convention changes
+- Subprocess: Pattern 3 — load rules, classify findings, return assignments
+- Output: Appends ## Severity Classification section with categorized findings table
+
+**Step 06: report**
+- Type: Final Step (no nextStepFile)
+- Goal: Finalize drift report with summary, remediation, provenance
+- Calculate overall drift score: CLEAN / MINOR / SIGNIFICANT / CRITICAL
+- Generate remediation suggestions per drift item
+- Add update-skill chaining recommendation if CRITICAL/HIGH found
+- Add provenance section (comparison metadata, tools used, timestamp)
+- Update frontmatter: mark complete, set nextWorkflow if applicable
+
+### Data Flow
+
+```
+Step 01 → Loads skill baseline + creates report skeleton
+Step 02 → Produces current extraction snapshot (internal)
+Step 03 → Appends ## Structural Drift (compares baseline vs current)
+Step 04 → Appends ## Semantic Drift (Deep) or skip notice (Quick/Forge)
+Step 05 → Appends ## Severity Classification (grades all findings)
+Step 06 → Completes ## Audit Summary, ## Remediation, ## Provenance
+```
+
+### File Structure
+
+```
+audit-skill/
+├── workflow.md                          # Entry point (Ferris Audit mode)
+├── data/
+│   ├── severity-rules.md                # CRITICAL/HIGH/MEDIUM/LOW classification rules
+│   └── drift-report-template.md         # Structured report template with frontmatter
+└── steps-c/
+    ├── step-01-init.md                  # Init with input discovery + user gate
+    ├── step-02-re-index.md              # Re-scan source (auto-proceed)
+    ├── step-03-structural-diff.md       # AST comparison (auto-proceed)
+    ├── step-04-semantic-diff.md         # QMD comparison/skip (auto-proceed)
+    ├── step-05-severity-classify.md     # Grade findings (auto-proceed)
+    └── step-06-report.md               # Final report generation
+```
+
+### Role and Persona
+
+- Role: Skill auditor operating in Ferris Audit mode
+- Communication: Structured evidence-based reporting with file:line citations
+- Style: Prescriptive — every step has exact instructions
+- Principle: Zero hallucination — every finding must trace to actual code
+
+### Workflow Chaining
+
+- Required from setup-forge: {sidecar_path}/forge-tier.yaml
+- Required from create-skill: {forge_data_folder}/{skill_name}/provenance-map.json
+- Output feeds: update-skill (if CRITICAL/HIGH drift found)
+- Frontmatter contract: workflowType: 'audit-skill', nextWorkflow: 'update-skill'
+
+### Error Handling
+
+- Missing skill: Error with path guidance
+- Missing provenance map: Offer degraded mode (text-diff, T1-low confidence)
+- Missing forge-tier.yaml: Error — run setup-forge first
+- No drift found: Report CLEAN status
+- Step 04 at non-Deep tier: Graceful skip with documented reason

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

@@ -0,0 +1,63 @@
+---
+name: audit-skill
+description: "Drift detection. Forge tier: structural. Deep tier: full."
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/audit-skill'
+---
+
+# Audit Skill
+
+**Goal:** Detect drift between an existing skill and its current source code, producing a severity-graded drift report with AST-backed findings and actionable remediation suggestions.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a skill auditor operating in Ferris Audit mode. This is a deterministic analysis workflow — every finding must trace to actual code with file:line citations. You enforce the zero-hallucination principle: structural truth over semantic guessing. You bring AST analysis expertise and drift detection methodology, while the source code provides the ground truth.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### 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
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array
+- **Append-Only Building**: Build the drift report by appending sections as directed to the output file
+- **Tier-Aware Execution**: Adapt analysis depth based on detected forge tier (Quick/Forge/Deep) with graceful degradation
+
+### 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. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **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** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **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
+- ⚙️ **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}`
+
+---
+
+## 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`, `sidecar_path`
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `./steps-c/step-01-init.md` to begin the workflow.

package/src/workflows/brief-skill/data/skill-brief-schema.md

@@ -0,0 +1,82 @@
+# Skill Brief Schema
+
+## Required Fields
+
+| Field | Type | Description | Validation |
+|-------|------|-------------|------------|
+| name | string | Kebab-case skill name | Must match `[a-z0-9-]+` |
+| version | string | Semantic version | Must match `X.Y.Z` pattern, default "1.0.0" |
+| source_repo | string | GitHub URL or local path | Must be accessible |
+| language | string | Primary programming language | Must be detected or user-specified |
+| scope | object | Inclusion/exclusion boundaries | Must have type + at least one pattern |
+| description | string | What this skill covers | 1-3 sentences |
+| forge_tier | string | Compilation tier | One of: quick, forge, deep |
+| created | string | Creation date | ISO date format |
+| created_by | string | User who created the brief | From config user_name |
+
+## Scope Object Structure
+
+```yaml
+scope:
+  type: full-library | specific-modules | public-api
+  include:
+    - "src/**/*.ts"           # Glob patterns for included files/directories
+  exclude:
+    - "**/*.test.*"           # Glob patterns for excluded files
+    - "**/node_modules/**"
+  notes: "Optional notes about scope decisions"
+```
+
+## YAML Template
+
+```yaml
+---
+name: "{skill-name}"
+version: "1.0.0"
+source_repo: "{github-url-or-local-path}"
+language: "{detected-language}"
+description: "{brief-description}"
+forge_tier: "{quick|forge|deep}"
+created: "{date}"
+created_by: "{user_name}"
+scope:
+  type: "{full-library|specific-modules|public-api}"
+  include:
+    - "{pattern}"
+  exclude:
+    - "{pattern}"
+  notes: "{optional-scope-notes}"
+---
+```
+
+## Human-Readable Presentation Format
+
+When presenting the brief for confirmation (step 04), display as:
+
+```
+Skill Brief: {name}
+====================
+
+Target:      {source_repo}
+Language:    {language}
+Forge Tier:  {forge_tier}
+Description: {description}
+
+Scope: {scope.type}
+  Include: {scope.include patterns, one per line}
+  Exclude: {scope.exclude patterns, one per line}
+  Notes:   {scope.notes}
+
+Version:    {version}
+Created:    {created}
+Created by: {created_by}
+```
+
+## Validation Rules
+
+1. `name` must be unique within {forge_data_folder}
+2. `source_repo` must be accessible (gh api for GitHub, path exists for local)
+3. `language` must be a recognized programming language
+4. `scope.type` must be one of the three defined types
+5. `scope.include` must have at least one pattern
+6. `forge_tier` must match the tier from forge-tier.yaml (or default to quick)

package/src/workflows/brief-skill/steps-c/step-01-gather-intent.md

@@ -0,0 +1,184 @@
+---
+name: 'step-01-gather-intent'
+description: 'Initialize brief-skill workflow, discover forge tier, and gather user intent for skill creation'
+
+nextStepFile: './step-02-analyze-target.md'
+forgeTierFile: '{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml'
+---
+
+# Step 1: Gather Intent
+
+## STEP GOAL:
+
+To initialize the brief-skill workflow by discovering the forge tier configuration, then gathering the user's target repository, intent, and any upfront scope hints for skill creation.
+
+## 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}`
+- ⚙️ 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
+
+### Role Reinforcement:
+
+- ✅ You are a skill scoping architect in Ferris Architect mode (exploratory, collaborative)
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring source code analysis and skill design expertise, user brings their domain knowledge and use case
+- ✅ Maintain a warm, guiding tone — this is a discovery conversation
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on gathering intent — do not analyze the repo yet (that's step 02)
+- 🚫 FORBIDDEN to examine source code or list exports in this step
+- 💬 Approach: Open-ended discovery facilitation — "What interests you about this library?"
+- 📋 Collect: target repo, user intent, scope hints, skill name
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Accumulate gathered information conversationally for use in subsequent steps
+- 📖 This is the init step — sets up everything that follows
+- 🚫 FORBIDDEN to proceed without a confirmed target repository
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Module config (forge_data_folder, user_name), forge-tier.yaml (if available)
+- Focus: Understanding WHAT the user wants to skill and WHY
+- Limits: Do not analyze source code, detect language, or list exports — that's step 02
+- Dependencies: None — this is the first step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Discover Forge Tier
+
+Attempt to load `{forgeTierFile}`:
+
+**If found:**
+- Read the tier level (quick, forge, or deep)
+- Note available tools for scoping guidance later
+
+**If not found:**
+- Display: "**Note:** No forge tier configuration found. Defaulting to Quick tier. Run **setup-forge** first for full capabilities."
+- Default to: `forge_tier: quick`
+
+### 2. Welcome and Explain
+
+"**Welcome to Brief Skill — the skill scoping workflow.**
+
+I'll help you define exactly what to skill and produce a `skill-brief.yaml` that drives the create-skill compilation workflow.
+
+We'll work through this together:
+1. **Now:** Understand what you want to skill and why
+2. **Next:** Analyze the target repo structure
+3. **Then:** Define scope boundaries
+4. **Finally:** Confirm and write the brief
+
+**Your forge tier:** {detected tier} — this determines what compilation capabilities are available.
+
+Let's get started."
+
+### 3. Gather Target Repository
+
+"**What repository do you want to create a skill for?**
+
+Provide either:
+- A **GitHub URL** (e.g., `https://github.com/org/repo`)
+- A **local path** (e.g., `/path/to/project`)
+
+**Target:**"
+
+Wait for user response. Confirm the target.
+
+### 4. Gather User Intent
+
+"**What's your intent for this skill?**
+
+Help me understand:
+- **What** specifically do you want to skill from this repo?
+- **Why** — what's the use case? How will an AI agent use this skill?
+- **Any initial thoughts** on scope? (Full library? Specific modules? Public API only?)
+
+Take your time — the more context you share, the better the brief."
+
+Wait for user response. Ask follow-up questions if intent is unclear.
+
+### 5. Capture Scope Hints
+
+If the user mentioned scope preferences in their intent response, acknowledge them:
+
+"**I noted these scope hints from your response:**
+- {list any scope hints mentioned}
+
+We'll refine these after analyzing the repo structure in the next step."
+
+If no scope hints were mentioned, that's fine — skip this acknowledgment.
+
+### 6. Derive Skill Name
+
+Based on the target repo and intent, propose a skill name:
+
+"**Suggested skill name:** `{derived-name}` (kebab-case)
+
+This will be used for the output directory and file naming. Want to use this name or suggest something different?"
+
+Wait for confirmation or alternative.
+
+### 7. Summarize Gathered Intent
+
+"**Here's what I've captured:**
+
+- **Target:** {repo URL or path}
+- **Intent:** {user's intent summary}
+- **Scope hints:** {any hints, or "None — we'll define scope after analysis"}
+- **Skill name:** {confirmed name}
+- **Forge tier:** {tier}
+
+Ready to analyze the target repository?"
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select:** [C] Continue to Target Analysis"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other: Help user, then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and target repository is confirmed will you load and read fully `./step-02-analyze-target.md` to execute target analysis.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Forge tier discovered (or defaulted to Quick with warning)
+- Target repository confirmed (GitHub URL or local path)
+- User intent captured with enough context for scoping
+- Skill name derived and confirmed
+- Scope hints noted (if provided)
+- User ready to proceed to analysis
+
+### ❌ SYSTEM FAILURE:
+
+- Analyzing source code in this step (too early)
+- Proceeding without a confirmed target repository
+- Not attempting to discover forge tier
+- Generating a skill name without user confirmation
+- Skipping the intent gathering conversation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.