bmad-module-skill-forge 0.2.0

package/src/workflows/create-stack-skill/workflow-plan-create-stack-skill.md

@@ -0,0 +1,481 @@
+---
+conversionFrom: 'src/workflows/create-stack-skill/create-stack-skill.spec.md'
+originalFormat: 'spec-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-next-step', 'step-10-confirmation']
+created: 2026-02-27
+status: VALIDATED
+approvedDate: 2026-02-27
+confirmationDate: 2026-02-27
+confirmationType: conversion
+coverageStatus: complete
+validationStatus: COMPLETE
+validationDate: 2026-02-27
+validationReport: validation-report.md
+---
+
+# Workflow Creation Plan
+
+## Conversion Source
+
+**Original Path:** src/workflows/create-stack-skill/create-stack-skill.spec.md
+**Original Format:** Specification placeholder (spec.md) — not a running workflow, a design blueprint
+**Detected Structure:** Single specification document defining a 9-step create-only workflow for generating consolidated stack skills with integration patterns
+
+---
+
+## Original Workflow Analysis
+
+### Goal (from source)
+
+Consolidated project stack skill with integration patterns. Analyzes a project's dependency manifests, detects significant libraries, discovers co-import integration points, and produces a consolidated stack skill. The stack SKILL.md focuses on integration patterns — how libraries connect in THIS specific codebase. References/ contain per-library subsets and integration pair documentation. Absorbs analyze-stack internally.
+
+### Original Steps (Complete List)
+
+**Step 01:** detect-manifests - Find and parse dependency files (package.json, requirements.txt, Cargo.toml, etc.)
+**Step 02:** rank-dependencies - Rank libraries by import frequency, present ranked list for user confirmation
+**Step 03:** scope-confirmation - User confirms which dependencies to include in the stack skill
+**Step 04:** parallel-extract - Extract per-library documentation in parallel (uses max_parallel_generation)
+**Step 05:** detect-integrations - Find co-import patterns and integration points between libraries
+**Step 06:** compile-stack - Assemble the main stack SKILL.md with integration layer
+**Step 07:** generate-references - Write per-library reference files and integration pair documentation
+**Step 08:** validate - Validate output against specification
+**Step 09:** report - Display stack summary with integration graph
+
+### Output / Deliverable
+
+Multi-file document-producing workflow:
+- `{skills_output_folder}/{project}-stack/SKILL.md` — Main skill: integration patterns + conventions
+- `{skills_output_folder}/{project}-stack/context-snippet.md` — Compressed stack index for context loading
+- `{skills_output_folder}/{project}-stack/metadata.json` — Metadata with `skill_type: "stack"`
+- `{skills_output_folder}/{project}-stack/references/{library}.md` — Per-library reference subsets
+- `{skills_output_folder}/{project}-stack/references/integrations/{pair}.md` — Cross-library integration patterns
+
+### Input Requirements
+
+**Required:**
+- Project root with dependency manifests
+
+**Optional:**
+- Explicit dependency list (skip auto-detection)
+- Scope overrides per library
+
+### Key Instructions to LLM
+
+- Uses `manifest_reader` for dependency detection
+- ADR-D: compositional architecture — modular, composable design
+- ADR-E: smart scope with developer confirmation — auto-detect then confirm with user
+- Primary agent: Ferris (Architect mode)
+- Step 04 uses `max_parallel_generation` for parallel extraction
+- Create-only mode (steps-c/ only)
+
+---
+
+## Conversion Notes
+
+**What works well in original:**
+- Clear 9-step pipeline with logical progression (detect → rank → confirm → extract → analyze → compile → write → validate → report)
+- Smart scope approach: auto-detect then user confirms
+- Multi-file output structure with clear separation (main skill, context snippet, metadata, references)
+- Integration-focused architecture — not just listing libraries but mapping how they connect
+- Parallel extraction capability for performance
+
+**What needs improvement:**
+- Spec is a placeholder — no actual step file implementations exist
+- No collaborative conversation patterns defined
+- No menu handling or user interaction points specified beyond step 03
+- No data files, templates, or schemas defined
+- No error handling or fallback patterns
+
+**Compliance gaps identified:**
+- No workflow.md entry point file
+- No step files with proper frontmatter (name, description, nextStepFile)
+- No MANDATORY EXECUTION RULES sections
+- No EXECUTION PROTOCOLS sections
+- No menu handling logic defined
+- No state tracking (stepsCompleted) integration
+- No data/ folder with schemas or templates
+- Missing web_bundle consideration for step file sizes
+
+---
+
+## Memory-Informed Discovery Notes
+
+### Preserve (from established SKF patterns)
+
+- 9-step pipeline with integration-centric design (mapping library connections, not just listing)
+- Multi-file output structure matching SKF conventions (SKILL.md, context-snippet.md, metadata.json, references/)
+- User confirmation gate at step 03 aligns with ADR-E smart scope pattern
+- Parallel extraction at step 04 architecturally sound for multi-library processing
+- Logical progression: detect → rank → confirm → extract → analyze → compile → write → validate → report
+
+### Address (gaps identified from memory)
+
+- `manifest_reader` does not exist — needs self-contained dependency detection with fallback chain (npm/PyPI/crates.io/Cargo registry APIs → file parsing → web search)
+- No forge-tier awareness — must implement Quick/Forge/Deep tier behavior matching create-skill, quick-skill, test-skill, export-skill patterns
+- No tool bridge specifications — needs gh_bridge (all tiers), ast_bridge (Forge/Deep), qmd_bridge (Deep only)
+- No error handling matrix — needs hard halt / graceful degradation / silent skip / advisory categories
+- "Absorbs analyze-stack internally" undefined — must define concrete analyze-stack functionality within steps 01-05
+- SKF module config.yaml does not exist yet — setup-forge prerequisite must create it
+
+### Add (enhancements from ecosystem patterns)
+
+- Forge-tier dependent extraction: Quick = source reading + basic import counting; Forge = ast_bridge for structural co-import detection; Deep = qmd_bridge for temporal integration evolution
+- Confidence tier labeling (T1 AST-verified, T1-low source reading, T2 QMD-enriched) matching create-skill pattern
+- Workflow chaining: prerequisite = setup-forge; downstream = test-skill, export-skill
+- Positive capability framing in reporting ("Stack forged: {name} — {lib_count} libraries, {integration_count} integration patterns")
+- Error handling matrix following established 7-scenario pattern from create-skill design
+
+### Audience
+
+- Ferris in Architect mode — consistent with spec and all SKF creation workflows
+- Target: developers wanting consolidated view of how their project's dependencies integrate
+- Phase 1b (Entry Points) build priority
+
+---
+
+## Classification Decisions
+
+**Workflow Name:** create-stack-skill
+**Target Path:** src/workflows/create-stack-skill/ (spec) / _bmad-output/bmb-creations/workflows/create-stack-skill/ (build output)
+
+**4 Key Decisions:**
+1. **Document Output:** false — compile-then-write action pattern (collects data steps 01-05, compiles step 06, writes step 07), consistent with create-skill classification
+2. **Module Affiliation:** skf — SKF module, consistent with all Skill Forge workflows
+3. **Session Type:** single-session — consistent with all SKF workflows; subprocess calls (max_parallel_generation) handle heavy lifting outside main context
+4. **Lifecycle Support:** create-only — stack skills regenerated fresh when dependencies change, no incremental editing
+
+**Structure Implications:**
+- `steps-c/` only — no edit or validate folders
+- Standard init step (no step-01b continuation)
+- No stepsCompleted tracking in output (non-document, action-based)
+- SKF module variables: `skills_output_folder`, `forge_data_folder`, `forge-tier`
+- Subprocess support needed for `max_parallel_generation` at step 04
+- Installed path: `{project-root}/_bmad/skf/workflows/create-stack-skill`
+
+---
+
+## Requirements
+
+**Flow Structure:**
+- Pattern: linear pipeline
+- Phases: detect → rank → confirm → extract → analyze → compile → write → validate → report
+- Estimated steps: 9 (matching spec)
+- No looping or branching — straight through with confirmation gates
+
+**User Interaction:**
+- Style: mostly autonomous with strategic gates
+- Decision points:
+  - Gate 1 (Step 03): Scope confirmation — user confirms library list after ranking
+  - Gate 2 (Step 06): Compile checkpoint — review assembled SKILL.md integration layer before writing
+- Checkpoint frequency: 2 gates in 9-step pipeline (steps 03, 06)
+
+**Inputs Required:**
+- Required: Project root with dependency manifests (package.json, requirements.txt, Cargo.toml, go.mod, etc.)
+- Required: setup-forge completed — forge-tier.yaml with tier and available tools
+- Optional: Explicit dependency list (skip auto-detection)
+- Optional: Scope overrides per library (include/exclude specific exports)
+
+**Output Specifications:**
+- Type: action (multi-file generation)
+- Deliverable files in `{skills_output_folder}/{project}-stack/`:
+  - SKILL.md — Integration patterns + conventions (main skill)
+  - context-snippet.md — Compressed stack index (~30 tokens per lib, ADR-L)
+  - metadata.json — skill_type: "stack", library list, integration pair count
+  - references/{library}.md — Per-library API surface and key patterns
+  - references/integrations/{pair}.md — Cross-library integration patterns
+- Workspace artifacts in `{forge_data_folder}/{project}-stack/`:
+  - provenance-map.json — Source tracking per library extraction
+  - evidence-report.md — Extraction evidence and confidence breakdown
+- Frequency: single run per project (re-run when dependencies change)
+
+**Success Criteria:**
+- All confirmed libraries have reference files generated
+- Integration pairs documented for detected co-import patterns
+- SKILL.md has meaningful integration layer (not concatenated library docs)
+- All content has confidence tier labels (T1/T1-low/T2)
+- context-snippet.md within target token budget
+- metadata.json valid against agentskills.io spec
+- Positive capability framing: "Stack forged: {name} — {lib_count} libraries, {integration_count} integration patterns"
+
+**Instruction Style:**
+- Overall: prescriptive
+- Notes: Mechanical compilation pipeline with Ferris Architect mode. Steps 01-02, 04-09 are autonomous processing. Only step 03 has collaborative scope confirmation. Matches create-skill and quick-skill prescriptive patterns.
+
+---
+
+## Tools Configuration
+
+**Core BMAD Tools:**
+- **Party Mode:** excluded — prescriptive mechanical pipeline, no creative facilitation needed
+- **Advanced Elicitation:** excluded — same reasoning, consistent with all SKF workflows
+- **Brainstorming:** excluded — same reasoning
+
+**LLM Features:**
+- **Web-Browsing:** included — fetching library documentation during extraction (Phase 3), checking registry APIs during manifest resolution (Phase 1)
+- **File I/O:** included — essential for reading manifests (Phase 1) and writing all output files (Phase 6)
+- **Sub-Agents:** excluded — not needed for linear pipeline
+- **Sub-Processes:** included — essential for Phase 3 parallel extraction via max_parallel_generation
+
+**Memory:**
+- Type: single-session
+- Tracking: sidecar-file (forge-tier.yaml from setup-forge, read-only)
+
+**External Integrations (pre-detected by setup-forge):**
+- `gh_bridge` (all tiers) — GitHub API for repository access and source reading
+- `ast_bridge` (Forge/Deep tiers) — ast-grep for structural import/export analysis and co-import detection
+- `qmd_bridge` (Deep tier only) — QMD for temporal integration evolution patterns
+- `skills_ref` — agentskills.io spec for validation (Step 08)
+
+**Installation Requirements:**
+- None new — all tools pre-detected by setup-forge prerequisite workflow
+- User preference: no additional installation needed
+
+---
+
+## Workflow Design
+
+### File Structure
+
+```
+create-stack-skill/
+├── workflow.md                          (entry point, Ferris Architect mode)
+├── data/
+│   ├── manifest-patterns.md             (detection patterns per language ecosystem)
+│   ├── integration-patterns.md          (co-import detection rules and known pairs)
+│   └── stack-skill-template.md          (SKILL.md section structure)
+└── steps-c/
+    ├── step-01-init.md                  (Init Non-Continuable with discovery)
+    ├── step-02-detect-manifests.md      (Middle Simple, auto-proceed)
+    ├── step-03-rank-and-confirm.md      (Middle Simple, P2 Gate 1)
+    ├── step-04-parallel-extract.md      (Middle Simple, auto-proceed, subprocess)
+    ├── step-05-detect-integrations.md   (Middle Simple, auto-proceed)
+    ├── step-06-compile-stack.md         (Middle Simple, P2 Gate 2)
+    ├── step-07-generate-output.md       (Middle Simple, auto-proceed)
+    ├── step-08-validate.md              (Middle Simple, auto-proceed)
+    └── step-09-report.md               (Final)
+```
+
+### Step Sequence Table
+
+| Step | Name | Type | Menu | Key Refs |
+|------|------|------|------|----------|
+| 01 | init | Init Non-Continuable (discovery) | P3 auto-proceed | skfConfig, forgeTierFile |
+| 02 | detect-manifests | Middle Simple | P3 auto-proceed | manifestPatterns |
+| 03 | rank-and-confirm | Middle Simple | P2 C-only (Gate 1) | — |
+| 04 | parallel-extract | Middle Simple | P3 auto-proceed | — |
+| 05 | detect-integrations | Middle Simple | P3 auto-proceed | integrationPatterns |
+| 06 | compile-stack | Middle Simple | P2 C-only (Gate 2) | stackSkillTemplate |
+| 07 | generate-output | Middle Simple | P3 auto-proceed | — |
+| 08 | validate | Middle Simple | P3 auto-proceed | — |
+| 09 | report | Final | No nextStepFile | — |
+
+### Step Action Plans
+
+**Step 01 (init):**
+- Load SKF module config from `_bmad/skf/config.yaml`
+- Load forge-tier.yaml from sidecar: determine Quick/Forge/Deep tier and available tools
+- Validate prerequisites: forge-tier.yaml exists, project root accessible
+- Accept optional explicit dependency list (skip auto-detection if provided)
+- Accept optional scope overrides per library
+- Display init summary: project name, tier, available tools
+- Auto-proceed to step 02
+
+**Step 02 (detect-manifests):**
+- Scan project root for dependency manifest files using manifest-patterns.md:
+  - JavaScript: package.json, package-lock.json
+  - Python: requirements.txt, setup.py, pyproject.toml, Pipfile
+  - Rust: Cargo.toml
+  - Go: go.mod
+  - Java: pom.xml, build.gradle
+  - Ruby: Gemfile
+  - (extensible via data file)
+- Parse each manifest to extract dependency names and version constraints
+- If explicit dependency list provided in step 01, skip detection and use that list
+- Report: found X manifests, Y total dependencies
+- Auto-proceed to step 03
+
+**Step 03 (rank-and-confirm) — Gate 1:**
+- Count import/require statements per dependency across codebase (Pattern 1 subprocess grep)
+- Rank dependencies by import frequency (descending)
+- Filter out trivially-used dependencies (< threshold imports)
+- Present ranked table: library name, import count, manifest source
+- User confirms which dependencies to include/exclude
+- Gate 1: P2 C-only to confirm scope and proceed
+
+**Step 04 (parallel-extract):**
+- For each confirmed dependency, launch subprocess extraction (Pattern 4 parallel, max_parallel_generation):
+  - Quick tier: Read source files importing the library, extract usage patterns via source reading
+  - Forge tier: ast_bridge for structural export analysis, function signatures, type definitions
+  - Deep tier: qmd_bridge for temporal usage evolution, deprecated patterns, API migration history
+- Each subprocess returns: library name, key exports, usage patterns, confidence tier label
+- Aggregate results, report extraction summary (X libraries extracted, confidence distribution)
+- Auto-proceed to step 05
+
+**Step 05 (detect-integrations):**
+- For each pair of confirmed libraries, detect co-import patterns:
+  - Files that import both libraries (Pattern 1 subprocess grep)
+  - Shared type definitions between libraries
+  - Middleware/pipeline chains involving multiple libraries
+  - Configuration bridges (one library configuring another)
+  - Event handler patterns crossing library boundaries
+- Use integration-patterns.md for known integration pattern templates
+- Build integration graph: nodes = libraries, edges = integration points with descriptions
+- Auto-proceed to step 06
+
+**Step 06 (compile-stack) — Gate 2:**
+- Load stack-skill-template.md for SKILL.md section structure
+- Compile SKILL.md:
+  - Header: project name, library count, integration summary
+  - Integration layer: cross-cutting patterns, middleware chains, shared types, config bridges
+  - Per-library sections: key exports, usage conventions, gotchas, confidence annotations
+  - Confidence tier labels throughout (T1 AST-verified, T1-low source reading, T2 QMD-enriched)
+- Present compiled SKILL.md preview to user for review
+- Gate 2: P2 C-only to confirm compilation and proceed to writing
+
+**Step 07 (generate-output):**
+- Write all deliverable files to `{skills_output_folder}/{project}-stack/`:
+  - SKILL.md (from compilation)
+  - context-snippet.md (~30 tokens per library, ADR-L two-line format)
+  - metadata.json (skill_type: "stack", library list, integration pair count, version)
+  - references/{library}.md for each confirmed library
+  - references/integrations/{pair}.md for each detected integration pair
+- Write workspace artifacts to `{forge_data_folder}/{project}-stack/`:
+  - provenance-map.json (source tracking per library extraction)
+  - evidence-report.md (extraction evidence and confidence breakdown)
+- Auto-proceed to step 08
+
+**Step 08 (validate):**
+- Validate output against agentskills.io spec via skills_ref
+- Check: SKILL.md structure, metadata.json required fields, reference file completeness
+- Verify all confidence tier labels present
+- Report validation results (pass/fail with specific findings)
+- Advisory: show warnings but continue to report
+- Auto-proceed to step 09
+
+**Step 09 (report) — Final:**
+- Display: "Stack forged: {name} — {lib_count} libraries, {integration_count} integration patterns"
+- Show confidence distribution table (T1/T1-low/T2 counts with descriptions)
+- List all output files with purposes
+- Conditional warnings display (only if warnings exist)
+- Recommend next workflows: [TS] Test Skill, [ES] Export Skill
+- Workflow complete
+
+### Data Flow
+
+```
+step-01: tier, tools, optional_dep_list
+  → step-02: manifests[], raw_dependencies[]
+  → step-03: confirmed_dependencies[] (user-approved scope)
+  → step-04: per_library_extractions[] (exports, patterns, confidence)
+  → step-05: integration_graph {pairs[], shared_types[], chains[]}
+  → step-06: skill_content (compiled SKILL.md)
+  → step-07: written_files[] (all output artifacts)
+  → step-08: validation_result {pass/fail, findings[]}
+  → step-09: summary (console report)
+```
+
+### Error Handling Matrix
+
+| Scenario | Response |
+|----------|----------|
+| Missing forge-tier.yaml | Hard halt: "Run setup-forge first" |
+| No manifests found | Hard halt: "No dependency manifests detected in project" |
+| Inaccessible source code | Hard halt: "Cannot access source repository" |
+| Library extraction failure (single) | Graceful degradation: skip library, note in report |
+| No integrations detected | Graceful: "No co-import patterns found, stack contains library summaries only" |
+| Validation failures | Advisory: show warnings, continue to report |
+| Individual file write failure | Hard halt per file |
+
+### Workflow Chaining
+
+- **Prerequisites:** setup-forge (required — provides forge-tier.yaml)
+- **Optional inputs:** skill-brief.yaml files for individual libraries (from brief-skill)
+- **Downstream:** [TS] test-skill (recommended), [ES] export-skill (recommended)
+- No prerequisites from brief-skill or create-skill (this is an independent entry point)
+
+### Subprocess Optimization
+
+| Step | Pattern | Operation | Returns |
+|------|---------|-----------|---------|
+| 03 | Pattern 1 (Grep) | Count imports per library across codebase | `{library: import_count}` pairs |
+| 04 | Pattern 4 (Parallel) | Per-library extraction (max_parallel_generation) | Structured extraction per library |
+| 05 | Pattern 1 (Grep) | Co-import file detection per library pair | File lists with co-imports |
+
+Fallback for all: if subprocess unavailable, perform operations in main context thread.
+
+### Role and Persona
+
+- Ferris Architect mode — prescriptive precision execution
+- Speed-first, zero hallucination: all content traces to actual code with file:line citations
+- No creative facilitation, no A/P menus
+- Positive capability framing in reporting
+
+---
+
+## Foundation Build Complete
+
+**Created:**
+- Folder structure at: `_bmad-output/bmb-creations/workflows/create-stack-skill/`
+- `workflow.md` — Entry point with Ferris Architect mode, SKF config loading, zero-hallucination rules
+- `data/manifest-patterns.md` — Detection patterns for 8 language ecosystems with import counting rules
+- `data/integration-patterns.md` — 6 integration pattern types with detection signals and output format
+- `data/stack-skill-template.md` — SKILL.md structure, context-snippet format, metadata.json schema, reference file structures
+
+**Configuration:**
+- Workflow name: create-stack-skill
+- Continuable: no (single-session)
+- Document output: no (action-based, multi-file generation)
+- Mode: create-only (steps-c/ only)
+- No output template needed (non-document)
+
+**Next Steps:**
+- Step 8: Build step-01-init.md
+- Step 9: Build remaining steps 02-09 (iterative)
+
+---
+
+## Step 01 Build Complete
+
+**Created:**
+- steps-c/step-01-init.md
+
+**Step Configuration:**
+- Type: Init Non-Continuable (with input discovery for forge-tier.yaml)
+- Input Discovery: yes (forge-tier.yaml from sidecar, optional explicit dependency list)
+- Menu: P3 auto-proceed (no A/P, no user interaction)
+- Next Step: step-02-detect-manifests
+
+**No supporting files needed** — data files already created in foundation (manifest-patterns.md, integration-patterns.md, stack-skill-template.md)
+
+---
+
+## Steps 02-09 Build Complete
+
+**All workflow steps built in sequence:**
+
+| Step | File | Type | Menu |
+|------|------|------|------|
+| 02 | step-02-detect-manifests.md | Middle Simple | P3 auto-proceed |
+| 03 | step-03-rank-and-confirm.md | Middle Simple | P2 C-only (Gate 1) |
+| 04 | step-04-parallel-extract.md | Middle Simple | P3 auto-proceed |
+| 05 | step-05-detect-integrations.md | Middle Simple | P3 auto-proceed |
+| 06 | step-06-compile-stack.md | Middle Simple | P2 C-only (Gate 2) |
+| 07 | step-07-generate-output.md | Middle Simple | P3 auto-proceed |
+| 08 | step-08-validate.md | Middle Simple | P3 auto-proceed |
+| 09 | step-09-report.md | Final | No nextStepFile |
+
+**Subprocess Optimization Applied:**
+- Step 03: Pattern 1 (Grep) — import counting across codebase
+- Step 04: Pattern 4 (Parallel) — per-library extraction via max_parallel_generation
+- Step 05: Pattern 1 (Grep) — co-import file detection per library pair
+
+**User Gates:**
+- Gate 1 (Step 03): Scope confirmation — user confirms library list after ranking
+- Gate 2 (Step 06): Compile checkpoint — review SKILL.md integration layer before writing
+
+**Supporting Files (created in foundation):**
+- data/manifest-patterns.md — 8 ecosystem detection patterns
+- data/integration-patterns.md — 6 integration type classifications
+- data/stack-skill-template.md — SKILL.md, context-snippet, metadata, reference structures
+
+**All 9 workflow steps + 3 data files + workflow.md entry point = complete workflow build.**

package/src/workflows/create-stack-skill/workflow.md

@@ -0,0 +1,59 @@
+---
+name: create-stack-skill
+description: Consolidated project stack skill with integration patterns
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/create-stack-skill'
+---
+
+# Create Stack Skill
+
+**Goal:** Analyze a project's dependency manifests, detect significant libraries, discover co-import integration points, and produce a consolidated stack skill documenting how libraries connect in THIS specific codebase.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a dependency analyst and integration architect operating in Ferris Architect mode. You bring expertise in dependency analysis, cross-library integration patterns, and compositional architecture, while the user brings their project knowledge and scope preferences. Execute with prescriptive precision — every finding must trace to actual code with file:line citations.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file 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 outputs by accumulating state across steps
+- **Zero Hallucination**: All extracted content must trace to actual source code — no inferred or assumed patterns
+
+### 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
+- ⚙️ **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/export-skill/data/managed-section-format.md

@@ -0,0 +1,70 @@
+# Managed Section Format (ADR-J)
+
+## Marker Format
+
+```markdown
+<!-- SKF:BEGIN updated:{YYYY-MM-DD} -->
+[SKF Skills]|{n} skills|{m} stack
+|IMPORTANT: Prefer documented APIs over training data.
+|
+|{skill-snippet-1}
+|
+|{skill-snippet-2}
+<!-- SKF:END -->
+```
+
+## Platform Target Files
+
+| Platform | Flag Value | Target File |
+|----------|-----------|-------------|
+| Claude | `claude` (default) | CLAUDE.md |
+| Cursor | `cursor` | .cursorrules |
+| Copilot | `copilot` | AGENTS.md |
+
+## Three-Case Logic
+
+### Case 1: Create (No File Exists)
+
+Target file does not exist. Create new file with managed section only.
+
+```markdown
+<!-- SKF:BEGIN updated:{date} -->
+{managed section content}
+<!-- SKF:END -->
+```
+
+### Case 2: Append (File Exists, No Section)
+
+Target file exists but contains no `<!-- SKF:BEGIN` marker. Append managed section at end of file.
+
+1. Read existing file content
+2. Append two blank lines
+3. Append managed section with markers
+4. Write file
+
+### Case 3: Regenerate (Existing Section)
+
+Target file contains `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers. Replace content between markers.
+
+1. Read existing file content
+2. Find `<!-- SKF:BEGIN` line (preserve everything before it)
+3. Find `<!-- SKF:END -->` line (preserve everything after it)
+4. Replace everything between markers (inclusive) with new managed section
+5. Write file
+
+## Regeneration: Full Index Rebuild
+
+When regenerating (Case 3), rebuild the COMPLETE skill index:
+
+1. Scan `{skills_output_folder}/*/context-snippet.md` for all exported skills
+2. Count total skills and stack skills
+3. Assemble all snippets into managed section
+4. Sort alphabetically by skill name
+5. Update the header line with correct counts
+
+## Safety Rules
+
+- NEVER modify content outside the `<!-- SKF:BEGIN/END -->` markers
+- ALWAYS preserve existing file content above and below markers
+- ALWAYS verify file was written correctly after write
+- If write fails, report error — do not attempt partial writes

package/src/workflows/export-skill/data/snippet-format.md

@@ -0,0 +1,32 @@
+# Context Snippet Format (ADR-L)
+
+## Format Rules
+
+- One format always — two-line per skill
+- No adaptive format switching (consistent for agent parsing)
+- ~30 tokens per skill target
+- T1-now content only (AST-current, no annotations)
+
+## Single Skill Snippet Template
+
+```markdown
+{skill-name} → skills/{skill-name}/
+  exports: {export-1}, {export-2}, {export-3}, {export-4}, {export-5}
+```
+
+## Stack Skill Snippet Template
+
+```markdown
+{project}-stack → skills/{project}-stack/
+  stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
+  integrations: {pattern-1}, {pattern-2}, {pattern-3}
+```
+
+## Rules
+
+- **exports**: Top 5 most-used exports from metadata.json `exports` array
+- **stack**: Component versions from metadata.json `components` for stack skills
+- **integrations**: Co-import patterns from metadata.json `integrations` for stack skills
+- If fewer than 5 exports exist, list all available
+- If no exports data available, omit the exports line (name + path only)
+- Skill path is relative to project root