bmad-module-skill-forge 0.2.0

package/src/knowledge/zero-hallucination.md

@@ -0,0 +1,101 @@
+# Zero Hallucination Principle
+
+## Principle
+
+Every instruction, signature, parameter, and behavioral claim in a generated skill must trace to a verifiable source location. Content that cannot be cited from source code, documentation, or verified external references is excluded — never guessed, inferred, or fabricated.
+
+## Rationale
+
+Agent skills direct other AI agents to use libraries and APIs. A hallucinated parameter name, an invented default value, or a fabricated usage pattern will cause the consuming agent to generate broken code. Unlike documentation aimed at humans who can cross-reference, skills are consumed by agents that treat every statement as ground truth.
+
+Without zero hallucination enforcement:
+- Agents follow fabricated instructions and produce broken code
+- Confidence in the entire skill degrades when any claim proves false
+- Users lose trust in the forge pipeline and revert to manual documentation
+
+With zero hallucination enforcement:
+- Every claim is backed by a source citation with file, line number, and confidence tier
+- Gaps in knowledge produce explicit "not extracted" markers rather than guesses
+- Skills become machine-verifiable evidence documents, not prose summaries
+
+## Pattern Examples
+
+### Example 1: Export Signature Extraction
+
+**Context:** Creating a skill for a TypeScript library with exported functions.
+
+**Implementation:** The extraction step reads source files and records each export with its exact signature, parameters, return type, and source location. If a parameter has no explicit type annotation, the skill records it as `unknown` with a T1-low citation rather than inferring the type from usage patterns.
+
+```
+## `parseConfig(input: string): Config`
+[AST:src/parser.ts:L42]
+
+## `validate(data: unknown): boolean`
+[SRC:src/validator.ts:L18] — parameter type not annotated in source
+```
+
+**Key Points:**
+- Exact signatures from source, not from README examples
+- Missing type information acknowledged, not filled in
+- Citation format includes file path and line number
+
+### Example 2: Handling Undocumented Behavior
+
+**Context:** Source code contains a function with side effects not described in JSDoc.
+
+**Implementation:** The skill documents only what can be structurally verified. Observable side effects (file writes, network calls) are noted only if they appear in the function body with verifiable call sites. Behavioral nuances described nowhere in source are omitted with a coverage gap note.
+
+```
+### Coverage Gaps
+- `initializeCache()` — internal caching behavior not fully traceable;
+  implementation references external service not available for inspection
+```
+
+**Key Points:**
+- Absence is documented as a gap, not filled with speculation
+- Coverage gaps inform the test-skill scoring (reduces coverage score, not coherence)
+- Gaps are actionable — they tell the user what to add via \[MANUAL\] sections
+
+### Example 3: Quick Tier Without AST
+
+**Context:** Operating at Quick tier where ast-grep is unavailable.
+
+**Implementation:** Extraction relies on source reading and pattern matching. All citations use `[SRC:file:Lnn]` format (T1-low confidence). The skill clearly states its extraction tier so consuming agents understand the confidence level.
+
+```yaml
+# metadata.json (excerpt)
+confidence_distribution:
+  t1: 0
+  t1_low: 47
+  t2: 0
+  t3: 3
+extraction_tier: quick
+```
+
+**Key Points:**
+- Quick tier skills are legitimate — lower confidence, not lower integrity
+- T1-low citations still reference real source locations
+- Metadata makes the confidence distribution transparent
+
+## Anti-Patterns
+
+- Inferring return types from variable names or function names — use `unknown` if not annotated
+- Copying usage examples from README without verifying they match current source signatures
+- Describing "typical usage patterns" from training data rather than from the actual codebase
+- Omitting the confidence tier from citations — every citation must declare its trust level
+
+## Checklist
+
+- [ ] Every API signature extracted from source, not from memory or documentation alone
+- [ ] Missing information produces gaps, not guesses
+- [ ] All citations include source file, line number, and confidence tier
+- [ ] metadata.json reflects actual confidence distribution
+- [ ] Quick tier skills clearly labeled as T1-low extraction
+
+## Related Fragments
+
+- [confidence-tiers.md](confidence-tiers.md) — defines the T1/T1-low/T2/T3 trust model
+- [provenance-tracking.md](provenance-tracking.md) — the mechanism for recording and verifying citations
+- [progressive-capability.md](progressive-capability.md) — how tier affects extraction without compromising integrity
+
+_Source: distilled from agent principles, create-skill extraction logic, and update-skill merge rules_

package/src/module-help.csv

@@ -0,0 +1,12 @@
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
+skf,anytime,Setup Forge,SF,,_bmad/skf/workflows/skillforge/setup-forge/workflow.md,skf_setup_forge,false,ferris,Create Mode,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Deep)",,forge-config.yaml,
+skf,anytime,Analyze Source,AN,,_bmad/skf/workflows/skillforge/analyze-source/workflow.md,skf_analyze_source,false,ferris,Create Mode,"Discover what to skill in a large repo — produces recommended skill briefs",forge_data_folder,skill-brief.yaml,
+skf,anytime,Brief Skill,BS,,_bmad/skf/workflows/skillforge/brief-skill/workflow.md,skf_brief_skill,false,ferris,Create Mode,"Design a skill scope through guided discovery",forge_data_folder,skill-brief.yaml,
+skf,anytime,Create Skill,CS,,_bmad/skf/workflows/skillforge/create-skill/workflow.md,skf_create_skill,false,ferris,Create Mode,"Compile a skill from a brief — supports --batch for multiple briefs",skills_output_folder,SKILL.md,
+skf,anytime,Quick Skill,QS,,_bmad/skf/workflows/skillforge/quick-skill/workflow.md,skf_quick_skill,false,ferris,Create Mode,"Fast skill from a package name or GitHub URL — no brief needed",skills_output_folder,SKILL.md,
+skf,anytime,Stack Skill,SS,,_bmad/skf/workflows/skillforge/create-stack-skill/workflow.md,skf_create_stack_skill,false,ferris,Create Mode,"Consolidated project stack skill with integration patterns",skills_output_folder,SKILL.md,
+skf,anytime,Update Skill,US,,_bmad/skf/workflows/skillforge/update-skill/workflow.md,skf_update_skill,false,ferris,Create Mode,"Smart regeneration preserving [MANUAL] sections after source changes",skills_output_folder,SKILL.md,
+skf,anytime,Audit Skill,AS,,_bmad/skf/workflows/skillforge/audit-skill/workflow.md,skf_audit_skill,false,ferris,Create Mode,"Drift detection between skill and current source code",,"drift report",
+skf,anytime,Test Skill,TS,,_bmad/skf/workflows/skillforge/test-skill/workflow.md,skf_test_skill,false,ferris,Create Mode,"Cognitive completeness verification — quality gate before export",,"completeness score",
+skf,anytime,Export Skill,EX,,_bmad/skf/workflows/skillforge/export-skill/workflow.md,skf_export_skill,false,ferris,Create Mode,"Package for distribution and inject context into CLAUDE.md/AGENTS.md",skills_output_folder,"agentskills.io package",
+skf,anytime,Knowledge Index,KI,,_bmad/skf/knowledge/skf-knowledge-index.csv,skf_knowledge_index,false,ferris,Reference,"Cross-cutting principles and patterns — JiT loaded by workflows via index lookup",,"knowledge fragments",

package/src/module.yaml

@@ -0,0 +1,22 @@
+code: skf
+name: "SKF: Skill Forge — Evidence-Based Agent Skills Compiler"
+header: "Automated skill compiler — AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse"
+subheader: "Zero hallucination tolerance. Every instruction traces to code."
+description: "Skill Forge transforms code repositories, documentation, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Uses ast-grep for structural truth, QMD for knowledge intelligence, and a progressive capability model (Quick/Forge/Deep). Standalone module — no other modules required. Recommended alongside BMM for full development workflow integration."
+default_selected: false
+
+skills_output_folder:
+  prompt: "Where should generated skills be saved?"
+  default: "skills"
+  result: "{project-root}/{value}"
+
+forge_data_folder:
+  prompt: "Where should forge workspace artifacts be stored?"
+  default: "forge-data"
+  result: "{project-root}/{value}"
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## document_output_language
+## output_folder

package/src/workflows/README.md

@@ -0,0 +1,148 @@
+# SKF Workflows
+
+Ten workflows covering the full skill compilation lifecycle — from source discovery through verified export.
+
+All workflows are triggered via Ferris (`@Ferris <code>`) and execute as step-by-step sequences with just-in-time step loading.
+
+## Workflow Index
+
+| Code | Workflow | Steps | Mode | Purpose |
+| --- | --- | --- | --- | --- |
+| SF | [setup-forge](setup-forge/workflow.md) | 4 | Architect | Initialize environment, detect tools, set capability tier |
+| AN | [analyze-source](analyze-source/workflow.md) | 7 | Architect | Discover skillable units in a repo, produce recommended briefs |
+| BS | [brief-skill](brief-skill/workflow.md) | 5 | Architect | Design a skill scope through guided discovery |
+| CS | [create-skill](create-skill/workflow.md) | 8 | Surgeon | Compile a skill from brief with provenance (supports --batch) |
+| QS | [quick-skill](quick-skill/workflow.md) | 6 | Surgeon | Fast skill from package name or GitHub URL — no brief needed |
+| SS | [create-stack-skill](create-stack-skill/workflow.md) | 9 | Surgeon | Consolidated project stack skill with integration patterns |
+| US | [update-skill](update-skill/workflow.md) | 7 | Surgeon | Regenerate after source changes, preserving \[MANUAL\] sections |
+| AS | [audit-skill](audit-skill/workflow.md) | 6 | Audit | Drift detection between skill and current source code |
+| TS | [test-skill](test-skill/workflow.md) | 6 | Audit | Cognitive completeness verification — quality gate before export |
+| EX | [export-skill](export-skill/workflow.md) | 6 | Delivery | Package for distribution, inject into CLAUDE.md/AGENTS.md |
+
+## Typical Flows
+
+**First-time setup:**
+
+```
+SF → AN → CS (batch) → TS → EX
+```
+
+**Single skill (full quality):**
+
+```
+SF → BS → CS → TS → EX
+```
+
+**Single skill (fast):**
+
+```
+SF → QS → EX
+```
+
+**Maintenance:**
+
+```
+AS → US → TS → EX
+```
+
+## Knowledge vs. Data
+
+The module uses two kinds of reference material, loaded just-in-time during workflow execution:
+
+| Aspect | Knowledge (`knowledge/`) | Data (`{workflow}/data/`) |
+| --- | --- | --- |
+| Scope | Cross-cutting, multi-workflow | Single workflow, single step |
+| Content | Principles, patterns, judgment rules | Schemas, templates, scoring formulas |
+| Index | `skf-knowledge-index.csv` | Referenced directly by step files |
+| Examples | zero-hallucination, confidence-tiers | skill-brief-schema.md, scoring-rules.md |
+
+**Knowledge files** live in `src/knowledge/` and capture principles Ferris applies across multiple workflows — zero hallucination, confidence tiers, provenance tracking, \[MANUAL\] preservation. Workflow steps reference these when they need cross-cutting judgment, not step-specific rules.
+
+**Data files** live in each workflow's `data/` directory and contain operational artifacts tightly coupled to specific steps — schemas, templates, scoring formulas, extraction patterns.
+
+Neither duplicates the other. Knowledge files reference (not repeat) data files where the detailed operational rules live.
+
+## Directory Structure
+
+Each workflow follows a consistent structure:
+
+```
+{workflow}/
+├── workflow.md              # Entry point — goals, mode routing, step sequence
+├── steps-c/                 # Create-mode steps (sequential execution)
+│   ├── step-01-*.md
+│   ├── step-02-*.md
+│   └── ...
+├── data/                    # Reference data — schemas, rules, patterns
+│   └── *.md
+├── templates/               # Output skeletons (only analyze-source, test-skill)
+│   └── *-template.md
+├── workflow-plan-*.md       # Design plan (build artifact)
+└── validation-report.md     # BMAD validation results (build artifact)
+```
+
+### Step Loading
+
+Steps execute sequentially via just-in-time loading. Only the current step is in context. Each step explicitly names the next step file. Data and template files are loaded on demand by the steps that need them.
+
+## Workflow Details
+
+### setup-forge (SF)
+
+**4 steps** | **Data:** tier-rules.md
+
+Detects available tools (ast-grep, gh, QMD), determines the capability tier (Quick/Forge/Deep), writes `forge-tier.yaml` to the sidecar, and optionally indexes the project. Run this first — all other workflows adapt behavior to the detected tier.
+
+### analyze-source (AN)
+
+**7 steps** | **Data:** skill-brief-schema.md, unit-detection-heuristics.md | **Templates:** analysis-report-template.md
+
+Brownfield onboarding entry point. Scans project structure, identifies skillable units using confidence-tiered heuristic signals, maps exports and integration points, presents recommendations for user confirmation, then generates `skill-brief.yaml` files ready for `create-skill --batch`.
+
+### brief-skill (BS)
+
+**5 steps** | **Data:** skill-brief-schema.md
+
+Interactive guided discovery. Gathers user intent (target repo, language, what to skill), analyzes the target to understand boundaries, walks through scope definition with the user, confirms the brief, then writes a validated `skill-brief.yaml`.
+
+### create-skill (CS)
+
+**8 steps** | **Data:** extraction-patterns.md, skill-sections.md
+
+The core compilation engine. Loads a brief, checks ecosystem context, extracts source with AST-backed provenance (T1 confidence when ast-grep available), enriches with usage patterns, compiles into agentskills.io-compliant sections, validates structural integrity, generates the `SKILL.md` artifact, and produces an evidence report. Supports `--batch` for processing multiple briefs.
+
+### quick-skill (QS)
+
+**6 steps** | **Data:** registry-resolution.md, skill-template.md
+
+Fastest path to a skill. Accepts a GitHub URL or package name, resolves to source via registry lookup, performs ecosystem check, extracts public API surface without requiring a brief, compiles best-effort `SKILL.md`, validates, and writes output.
+
+### create-stack-skill (SS)
+
+**9 steps** | **Data:** integration-patterns.md, manifest-patterns.md, stack-skill-template.md
+
+Analyzes dependency manifests (package.json, requirements.txt, Cargo.toml, etc.) to detect libraries, ranks by import frequency, discovers co-import integration patterns between libraries, compiles a consolidated stack skill documenting how libraries connect, validates, and generates output.
+
+### update-skill (US)
+
+**7 steps** | **Data:** manual-section-rules.md, merge-conflict-rules.md
+
+Surgical update engine. Loads the existing skill, detects what changed in source since last compilation, re-extracts only affected exports with fresh provenance, merges new extractions while preserving all `[MANUAL]` developer-authored content, validates the merged result, writes the updated skill, and produces a change report.
+
+### audit-skill (AS)
+
+**6 steps** | **Data:** drift-report-template.md, severity-rules.md
+
+Drift detection engine. Loads the skill under audit, re-indexes current source to build a fresh reference, performs structural diff (signature changes, missing exports), performs semantic diff (behavioral divergence), classifies each finding by severity using defined rules, and produces a graded drift report.
+
+### test-skill (TS)
+
+**6 steps** | **Data:** output-section-formats.md, scoring-rules.md | **Templates:** test-report-template.md
+
+Quality gate before export. Loads the skill, detects test mode (naive for Quick tier, contextual for Forge/Deep), runs coverage checks against source, runs coherence checks for internal consistency, scores using weighted rubric, and produces a completeness report with pass/fail gate decision.
+
+### export-skill (EX)
+
+**6 steps** | **Data:** managed-section-format.md, snippet-format.md
+
+Distribution packaging. Loads the completed skill, packages as agentskills.io-compliant bundle, generates context snippets optimized for token efficiency, updates managed sections in `CLAUDE.md` / `AGENTS.md` with platform-aware injection, produces a token budget report, and summarizes the export.

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

@@ -0,0 +1,75 @@
+# Skill Brief Schema
+
+## Purpose
+
+Defines the output contract for skill-brief.yaml files generated by analyze-source. Each generated brief must conform to this schema to be consumable by brief-skill and create-skill downstream workflows.
+
+## Required Fields (9)
+
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
+| version | string | Semantic `X.Y.Z` | Defaults to `1.0.0` |
+| source_repo | string | GitHub URL or local path | Repository or project root |
+| language | string | Recognized language | Primary programming language |
+| scope | object | See Scope Object below | Boundary definition |
+| description | string | 1-3 sentences | What the skill covers |
+| forge_tier | string | `quick` / `forge` / `deep` | Inherited from forge-tier.yaml |
+| created | string | ISO date `YYYY-MM-DD` | Generation date |
+| created_by | string | user_name from config | Who generated the brief |
+
+## Scope Object
+
+```yaml
+scope:
+  type: full-library | specific-modules | public-api
+  include:
+    - 'src/**/*.ts'          # At least one required
+  exclude:
+    - 'src/**/*.test.ts'     # Optional
+  notes: 'Optional rationale for scope decision'
+```
+
+### Scope Types
+
+| Type | Use When |
+|------|----------|
+| full-library | Entire codebase of a unit |
+| specific-modules | Selected components or packages |
+| public-api | Only exported interfaces |
+
+## YAML Template
+
+```yaml
+name: '{unit-name}'
+version: '1.0.0'
+source_repo: '{project_path}'
+language: '{detected_language}'
+scope:
+  type: '{detected_scope_type}'
+  include:
+    - '{include_pattern}'
+  exclude:
+    - '{exclude_pattern}'
+  notes: '{scope_rationale}'
+description: '{1-3 sentence description}'
+forge_tier: '{forge_tier}'
+created: '{current_date}'
+created_by: '{user_name}'
+```
+
+## Validation Rules
+
+1. **Name uniqueness**: No duplicate names within forge_data_folder
+2. **Source accessibility**: source_repo path must exist or be reachable
+3. **Language recognized**: Must be a known programming language
+4. **Scope type valid**: Must match one of the three defined types
+5. **Include patterns**: At least one include glob pattern required
+6. **Forge tier match**: Must match value in forge-tier.yaml
+
+## Output Location
+
+Each skill-brief.yaml is written to:
+```
+{forge_data_folder}/{unit-name}/skill-brief.yaml
+```

package/src/workflows/analyze-source/data/unit-detection-heuristics.md

@@ -0,0 +1,88 @@
+# Unit Detection Heuristics
+
+## Purpose
+
+Rules for identifying discrete skillable units within a project. A "skillable unit" is a self-contained component with clear boundaries that can be documented as an independent skill.
+
+## Detection Signals
+
+### Strong Signals (High Confidence)
+
+| Signal | Description | Example |
+|--------|-------------|---------|
+| Independent package.json / Cargo.toml / go.mod | Unit has its own dependency manifest | `packages/auth/package.json` |
+| Separate entry point | Unit has a main/index file | `services/api/src/index.ts` |
+| Docker/service definition | Unit runs as an independent service | `docker-compose.yml` service entry |
+| Distinct export surface | Unit exports a public API consumed by others | `src/lib/index.ts` with re-exports |
+| Workspace member | Listed in root workspace configuration | `pnpm-workspace.yaml` packages |
+
+### Moderate Signals (Medium Confidence)
+
+| Signal | Description | Example |
+|--------|-------------|---------|
+| Directory depth boundary | Top-level directory with self-contained structure | `src/modules/payments/` |
+| Naming convention | Follows organizational naming pattern | `@org/package-name` |
+| Separate test suite | Has its own test directory or config | `packages/auth/__tests__/` |
+| README.md presence | Has documentation at directory level | `libs/utils/README.md` |
+| CI/CD pipeline reference | Referenced in build/deploy configuration | `.github/workflows/deploy-auth.yml` |
+
+### Weak Signals (Low Confidence — Require Corroboration)
+
+| Signal | Description | Example |
+|--------|-------------|---------|
+| Large directory | Many files in a subtree | 50+ files under one directory |
+| Comment boundaries | Code comments marking sections | `// --- Auth Module ---` |
+| Import clustering | Files that import primarily from each other | Tight import graph cluster |
+
+## Boundary Classification
+
+### Service Boundary
+- Independent deployable unit
+- Own process, port, or container
+- Clear network interface (REST, gRPC, message queue)
+- Scope type: `full-library`
+
+### Package Boundary
+- Workspace member or independently versioned package
+- Own dependency manifest
+- Exports consumed by other packages
+- Scope type: `full-library` or `specific-modules`
+
+### Module Boundary
+- Logical grouping within a single package
+- Shared namespace or directory structure
+- Internal cohesion, external coupling through defined interface
+- Scope type: `specific-modules` or `public-api`
+
+### Library Boundary
+- Third-party dependency with significant project-specific usage patterns
+- Custom wrappers, configurations, or integration code
+- Scope type: `public-api`
+
+## Disqualification Rules
+
+Do NOT recommend as a skillable unit if:
+
+1. **Too small**: Fewer than 3 source files or 100 lines of code
+2. **Generated code**: Auto-generated files (protobuf, GraphQL codegen, etc.)
+3. **Pure configuration**: Only config files with no logic
+4. **Test-only**: Test utilities with no production code
+5. **Vendor/dependency**: Third-party code copied into project
+6. **Already skilled**: Existing skill found in forge_data_folder (recommend update-skill instead)
+
+## Stack Skill Candidate Detection
+
+Flag units as stack skill candidates when:
+
+1. **Co-import frequency**: Two or more units are imported together in 3+ files
+2. **Integration adapter**: A unit exists primarily to bridge two other units
+3. **Shared state**: Multiple units read/write to the same data store
+4. **Orchestration layer**: A unit coordinates calls across multiple other units
+
+## Tier-Aware Scanning Depth
+
+| Forge Tier | Scanning Approach |
+|------------|-------------------|
+| Quick | File structure analysis: directory trees, manifest files, entry points, naming conventions |
+| Forge | AST analysis: export surfaces, import graphs, dependency trees, type hierarchies |
+| Deep | AST + QMD: temporal evolution, refactoring patterns, semantic relationships, architectural drift |

package/src/workflows/analyze-source/steps-c/step-01-init.md

@@ -0,0 +1,191 @@
+---
+name: 'step-01-init'
+description: 'Initialize analysis workflow — load config, detect continuation, accept project path, check existing skills, create report'
+
+nextStepFile: './step-02-scan-project.md'
+continueFile: './step-01b-continue.md'
+outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+templateFile: '../templates/analysis-report-template.md'
+---
+
+# Step 1: Initialize Analysis
+
+## STEP GOAL:
+
+To initialize the analyze-source workflow by loading configuration, detecting continuation state, accepting the target project path, checking for existing skills, and creating the analysis report document.
+
+## 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 source code analyst and decomposition architect (Ferris Architect mode)
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Prescriptive precision — zero-hallucination, only report what is found
+- ✅ File:line citation tracing for all claims
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on initialization — do NOT begin scanning or analysis
+- 🚫 FORBIDDEN to analyze source code in this step
+- 💬 Collect project path and scope hints from user
+- 📋 Verify prerequisites before proceeding
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Create output document from template when initialization complete
+- 📖 Update output frontmatter with initialization data
+- 🚫 FORBIDDEN to proceed without valid project path and forge-tier.yaml
+
+## CONTEXT BOUNDARIES:
+
+- Available: SKF module config (loaded by workflow.md), forge_data_folder, skills_output_folder, forge_tier
+- Focus: Setup and validation only — no analysis
+- Limits: Do not read source files beyond checking prerequisites
+- Dependencies: setup-forge must have been run (forge-tier.yaml must exist)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Check for Existing Report (Continuation Detection)
+
+Look for {outputFile}.
+
+**IF the file exists AND has `stepsCompleted` with entries:**
+- "**Found an existing analysis report. Resuming previous session...**"
+- Load, read entirely, then execute {continueFile}
+- **STOP HERE** — do not continue this sequence
+
+**IF the file does not exist OR stepsCompleted is empty:**
+- Continue to section 2
+
+### 2. Verify Prerequisites
+
+**Check forge-tier.yaml:**
+- Look for `{forge_data_folder}/forge-tier.yaml`
+- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{forge_data_folder}/forge-tier.yaml`. Please run the setup-forge workflow first to configure your forge tier (Quick/Forge/Deep)."
+- **IF found:** Read and note the forge tier value
+
+"**Forge tier detected:** {tier} — analysis depth will be calibrated accordingly."
+
+### 3. Collect Project Path
+
+"**Welcome to Analyze Source — the SKF decomposition engine.**
+
+I'll analyze your project to identify discrete skillable units and produce skill-brief.yaml files for each recommended unit.
+
+**Please provide the project root path to analyze:**
+
+This should be the root directory of the repo or multi-service project you want to decompose."
+
+Wait for user input.
+
+**Validate the path:**
+- Check that the path exists and contains source files
+- **IF invalid:** "That path doesn't appear to be a valid project directory. Please provide the correct path."
+
+### 4. Collect Optional Scope Hints
+
+"**Optional: Do you have scope hints to narrow the analysis?**
+
+For example:
+- Specific packages to focus on (e.g., `packages/auth`, `services/api`)
+- Directories to exclude (e.g., `vendor/`, `node_modules/`, `dist/`)
+
+Enter scope hints, or press Enter to analyze the entire project."
+
+Wait for user input. Document any hints provided.
+
+### 5. Check for Existing Skills
+
+Scan `{forge_data_folder}/` for existing `skill-brief.yaml` files.
+
+**IF existing skills found:**
+"**Existing skills detected:**
+{list each existing skill name and path}
+
+These units will be flagged as 'already skilled' during analysis. If source changes are detected, I'll recommend running update-skill instead of generating new briefs."
+
+**IF no existing skills found:**
+"**No existing skills found.** All identified units will be treated as new."
+
+### 6. Create Analysis Report
+
+Create {outputFile} from {templateFile}.
+
+**Populate frontmatter:**
+```yaml
+stepsCompleted: ['step-01-init']
+lastStep: 'step-01-init'
+lastContinued: ''
+date: '{current_date}'
+user_name: '{user_name}'
+project_name: '{project_name}'
+project_path: '{provided_project_path}'
+forge_tier: '{detected_tier}'
+existing_skills: [{list of existing skill names}]
+confirmed_units: []
+stack_skill_candidates: []
+nextWorkflow: ''
+```
+
+"**Initialization complete.**
+
+**Project:** {project_path}
+**Forge Tier:** {forge_tier}
+**Existing Skills:** {count}
+**Scope Hints:** {hints or 'None — full project analysis'}
+
+**Proceeding to project scan...**"
+
+### 7. Proceed to Next Step
+
+Display: "**Proceeding to project scan...**"
+
+#### Menu Handling Logic:
+
+- After initialization is complete and report is created, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed initialization step with no user choices at this point
+- Proceed directly to next step after setup
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the output report has been created with populated frontmatter (project_path, forge_tier, existing_skills) will you load and read fully {nextStepFile} to execute and begin the project scan.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Continuation detection performed correctly
+- forge-tier.yaml verified present and tier noted
+- Valid project path collected from user
+- Optional scope hints collected
+- Existing skills scanned and documented
+- Analysis report created from template with populated frontmatter
+- Auto-proceeded to step 02
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping forge-tier.yaml check
+- Accepting an invalid project path
+- Not checking for existing skills
+- Not creating the output report before proceeding
+- Beginning source analysis in this step
+- Hardcoded paths instead of using frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.