bmad-module-skill-forge 0.8.3 → 0.8.4

package/README.md

@@ -74,7 +74,9 @@ You'll be prompted for project name, output folders, and IDE configuration. See
 
 1. **Set up your environment:** `@Ferris SF` — detects your tools and sets your capability tier
 2. **Generate your first skill:** `@Ferris QS <package-name>` — creates a verified skill in under a minute
-3. **Full quality path:** `@Ferris BS` then `@Ferris CS` — brief first, then compile for maximum accuracy
+3. **Full quality path:** `@Ferris BS` → clear session → `@Ferris CS` — brief first, then compile for maximum accuracy
+
+> **Tip:** Start a fresh conversation before each workflow. SKF workflows load significant context — clearing between them prevents interference.
 
 See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 12 available workflows.
 
@@ -84,6 +86,7 @@ See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/
 - **You maintain a library** and want to ship official, verified instruction files so AI agents use your API correctly
 - **You manage a codebase with many dependencies** and want a consolidated "stack skill" that teaches your agent how all the pieces fit together
 - **You use a SaaS API or closed-source tool** with no public code — SKF can generate skills from documentation alone
+- **You need different skills for different use cases** from the same target — compile multiple skills with different scopes from one repo or doc set (e.g., a core API skill and a migration guide skill)
 
 ## Learn More
 

package/docs/concepts.md

@@ -111,8 +111,38 @@ Skills can include executable scripts and static assets alongside the main SKILL
 
 ---
 
+## Session Context
+
+Each SKF workflow should run in a clean conversation session. Workflows load step files, knowledge fragments, and extraction data into the LLM's context as they execute. If you run a second workflow in the same session, leftover context from the first workflow can interfere with the second — causing stale references, mode confusion, or degraded output quality.
+
+**Best practice:** Clear your session context (start a new conversation) before invoking a new workflow. For example, after `@Ferris CS` completes a skill, start a fresh session before running `@Ferris TS` to test it.
+
+This applies to sequential workflows in the same session. Sidecar state (forge tier, preferences) persists across sessions automatically — you don't lose any configuration by clearing context.
+
+---
+
+## Full Control Over Scope
+
+You can compile multiple skills from the same target (repo or docs) with different scopes, intents, and audiences. Each brief defines what to extract and why, producing a distinct skill from the same source.
+
+**Example:** From a single library like [cognee](https://github.com/topoteretes/cognee), you could compile:
+
+- `cognee-core` — public API surface for general usage
+- `cognee-graph-types` — type system and data model for schema work
+- `cognee-migration` — upgrade patterns and breaking changes for version transitions
+
+Each skill serves a different use case. You decide the scope — SKF compiles exactly what you specify.
+
+---
+
 ## Best Practices
 
 SKF integrates skill authoring best practices from the Claude platform and community guidelines. Generated skills use third-person descriptions for reliable agent discovery, consistent terminology throughout, and appropriate degrees of freedom (prescriptive for fragile operations like database migrations, flexible for creative tasks like code reviews). These practices are enforced during compilation and verified during testing.
 
 **Example:** A skill description reads "Processes payments via REST API with token-based auth. NOT for: billing dashboards" — third-person voice, specific keywords, and negative triggers help agents select the right skill.
+
+**Operational best practices:**
+
+- **One workflow per session** — clear context between workflows to prevent stale state from affecting results
+- **Multiple skills per target** — compile different skills from the same repo or docs for different use cases and audiences
+- **Progressive capability** — start with Quick mode, upgrade tiers as you install more tools

package/docs/examples.md

@@ -84,7 +84,9 @@ Alex's team adopts BMAD for 10 microservices (TypeScript, Go, Rust).
 
 ```
 @Ferris SF          # Setup — Deep mode detected
+# — clear session —
 @Ferris AN          # Analyze — 10 services mapped
+# — clear session —
 @Ferris CS --batch  # Create — batch generation
 ```
 
@@ -96,8 +98,11 @@ Sarah prepares v3.0.0 with breaking changes.
 
 ```
 @Ferris AS    # Audit — finds 3 renames, 1 removal, 1 addition
+# — clear session —
 @Ferris US    # Update — preserves [MANUAL] sections, adds annotations
+# — clear session —
 @Ferris TS    # Test — verify completeness
+# — clear session —
 @Ferris EX    # Export — package for npm release
 ```
 
@@ -197,6 +202,14 @@ Stack skills focus on integration patterns. Individual skills focus on API surfa
 
 After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates CLAUDE.md automatically. Skill generation becomes routine — like running tests.
 
+### One Workflow Per Session
+
+Clear your conversation context (start a new chat) before invoking a new workflow. Each SKF workflow loads step files, knowledge fragments, and extraction data into context. Starting fresh ensures the next workflow operates without interference from prior steps. Sidecar state (forge tier, preferences) persists automatically across sessions — you don't lose configuration.
+
+### Full Control Over Scope
+
+You can compile multiple skills from the same target (repo or docs) with different scopes and intents. Each brief defines what to extract and why, producing a distinct skill from the same source. For example, from a single library you could compile `cognee-core` for the public API, `cognee-graph-types` for the type system, and `cognee-migration` for upgrade patterns — each serving a different use case.
+
 ### Best Practices Built In
 
 Generated skills automatically follow authoring best practices: third-person descriptions for reliable agent discovery, consistent terminology, degrees-of-freedom matching (prescriptive for fragile operations, flexible for creative tasks), and table-of-contents headers in large reference files. Discovery testing recommendations are included in test reports.

package/docs/getting-started.md

@@ -103,14 +103,19 @@ This detects your tools, sets your capability tier, and initializes the forge en
 
 Ferris reads the repository, extracts the public API, and generates a skill in under a minute.
 
-**Full quality path:**
+**Full quality path (one workflow per session):**
 ```
 @Ferris BS    # Brief — scope and design the skill
+# — clear session —
 @Ferris CS    # Create — compile from the brief
+# — clear session —
 @Ferris TS    # Test — verify completeness
+# — clear session —
 @Ferris EX    # Export — package for distribution
 ```
 
+> Start a fresh conversation before each workflow. SKF workflows load significant context — clearing between them prevents interference. See [Session Context](../concepts/#session-context).
+
 ### 3. Stack Skill (for full projects)
 
 ```

package/docs/workflows.md

@@ -224,6 +224,8 @@ flowchart TD
     TS --> EX[Export Skill]
 ```
 
+> **One workflow per session.** Each arrow in the diagrams above represents a new conversation session. Clear your context between workflows for best results — this prevents leftover step files and extraction data from interfering with the next workflow. See [Session Context](../concepts/#session-context).
+
 ---
 
 ## Workflow Categories

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/agents/forger.agent.yaml

@@ -41,6 +41,7 @@ agent:
       - "Agent-level knowledge informs judgment across workflows — consult knowledge/ when a step directs, not from memory"
 
   critical_actions:
+    - "GUARD: Verify {sidecar_path} resolves to an actual directory path (not a literal '{sidecar_path}' string). If it does not resolve — HARD HALT: '**Cannot initialize.** `sidecar_path` is not defined in your installed config.yaml. Add `sidecar_path: _bmad/_memory/forger-sidecar` to your project config.yaml and retry. This is a known installer issue with `prompt: false` config variables.'"
     - "Load COMPLETE file {sidecar_path}/preferences.yaml"
     - "Load COMPLETE file {sidecar_path}/forge-tier.yaml"
     - "ONLY write STATE files to {project-root}/_bmad/_memory/forger-sidecar/ — reading from knowledge/ and workflow files is expected"

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

@@ -67,8 +67,8 @@ Attempt to load `{forgeTierFile}`:
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
 **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`
+- "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Please run the **setup-forge** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- HALT — do not proceed.
 
 ### 2. Welcome and Explain
 
@@ -197,7 +197,7 @@ ONLY WHEN C is selected and target repository is confirmed will you load and rea
 
 ### ✅ SUCCESS:
 
-- Forge tier discovered (or defaulted to Quick with warning), override applied if set in preferences.yaml
+- Forge tier discovered (HALT if missing), override applied if set in preferences.yaml
 - Target repository confirmed (GitHub URL or local path)
 - User intent captured with enough context for scoping
 - Skill name derived and confirmed
@@ -209,6 +209,7 @@ ONLY WHEN C is selected and target repository is confirmed will you load and rea
 
 - Analyzing source code in this step (too early)
 - Proceeding without a confirmed target repository
+- Not halting when forge tier is missing
 - Not attempting to discover forge tier
 - Generating a skill name without user confirmation
 - Skipping the intent gathering conversation

package/src/workflows/test-skill/steps-c/step-01-init.md

@@ -116,11 +116,9 @@ Read `{sidecarFile}` to determine available analysis depth.
 - Read tool availability flags (ast_grep, gh_cli, qmd)
 
 **If forge-tier.yaml missing:**
-"**Warning:** Forge tier not detected. Defaulting to **Quick** tier (structural checks only).
+"**Cannot proceed.** forge-tier.yaml not found at `{sidecarFile}`. Please run the **setup-forge** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
 
-Run **setup-forge** to enable deeper analysis with AST-backed verification."
-
-Default to Quick tier and continue.
+HALT — do not proceed.
 
 ### 4b. Apply Tier Override (if set)
 
@@ -194,7 +192,7 @@ ONLY WHEN all required files are validated, forge tier is loaded, output documen
 ### ✅ SUCCESS:
 
 - Skill path validated (SKILL.md exists)
-- Forge tier state loaded (or gracefully defaulted to Quick), override applied if set in preferences.yaml
+- Forge tier state loaded (HALT if missing), override applied if set in preferences.yaml
 - Skill metadata extracted
 - Output document created from template with initial frontmatter
 - Initialization status reported clearly

package/tools/cli/lib/installer.js

@@ -238,6 +238,7 @@ class Installer {
       document_output_language: 'en',
       skills_output_folder: config.skills_output_folder || 'skills',
       forge_data_folder: config.forge_data_folder || 'forge-data',
+      sidecar_path: '_bmad/_memory/forger-sidecar',
       skf_folder: config.skfFolder,
       ides: config.ides || [],
     };