bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-analyze-source/references/init.md

@@ -2,7 +2,7 @@
 nextStepFile: 'scan-project.md'
 continueFile: 'continue.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-templateFile: 'templates/analysis-report-template.md'
+templateFile: '{analysisReportTemplatePath}'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -21,15 +21,19 @@ To initialize the analyze-source workflow by loading configuration, detecting co
 
 ## MANDATORY SEQUENCE
 
+When `{headless_mode}` is true, every HARD HALT in this step emits the error envelope on **stderr** before exiting — shape and enum in `references/headless-contract.md` — using the exit code and `halt_reason` named at that HALT.
+
 ### 1. Check for Existing Report (Continuation Detection)
 
 Look for {outputFile}.
 
 **IF the file exists AND has `stepsCompleted` with entries:**
 - The report filename is keyed to `{project_name}` (the forge workspace), not the analyzed target — so a report from a *different* target can collide here. Before resuming, establish the requested target and compare it to the existing report:
-  - Determine the requested target now: if `--project-path <path>` was passed at invocation, set `project_paths[]` from it (comma-split if multiple); otherwise collect the path(s) using the section-3 "Collect Project Path" prompt and store as `project_paths[]`. (Section 3 must NOT re-prompt when `project_paths[]` is already populated here.)
+  - Determine the requested target now: if `--project-path <path>` was passed at invocation, set `project_paths[]` from it (comma-split if multiple); otherwise collect the path(s) using the section-3 "Collect Project Path" prompt and store as `project_paths[]`. (Section 3 does not re-prompt when `project_paths[]` is already populated here.)
   - Read the existing report's frontmatter `project_paths`.
-  - **IF the existing report's `project_paths` matches the requested target:** "**Found an existing analysis report. Resuming previous session...**" — Load, read entirely, then execute {continueFile}. **STOP HERE** — do not continue this sequence.
+  - **IF the existing report's `project_paths` matches the requested target:**
+    - **IF this invocation carries the `[auto]` flag (e.g. `AN[auto]`):** do not route to {continueFile} — auto mode is a single idempotent pass, not a resumable interactive session. Skip continuation and proceed to section 2; the `[auto]` check in §2b re-enters step-auto-scope.md, which re-runs cleanly and overwrites the prior auto report. (This keeps a re-invoked or interrupted auto run on the auto path instead of dropping it into the interactive chain.)
+    - **ELSE:** "**Found an existing analysis report. Resuming previous session...**" — Load, read entirely, then execute {continueFile}. **STOP HERE** — do not continue this sequence. ({continueFile} is mode-aware: a report written by a prior auto run resumes through the auto path, not the interactive chain.)
   - **ELSE (different target — stale collision):** the existing report belongs to another analysis. Archive it by renaming to `{forge_data_folder}/analyze-source-report-{project_name}-<UTC-timestamp>.md`, announce "**Existing report belongs to a different target — archived as <name>; starting a fresh analysis.**", then continue to section 2 (skip re-collecting the path in section 3 — it is already set).
 
 **IF the file does not exist OR stepsCompleted is empty:**
@@ -73,20 +77,16 @@ Look for {outputFile}.
 4. "**Auto mode activated — bypassing interactive analysis.**"
 5. **Route to auto-scope:** Load, read fully, then execute `references/step-auto-scope.md`. **STOP HERE** — do not continue to §3 or any subsequent section.
 
-**IF `{auto_mode}` is NOT true:**
+**IF `{auto_mode}` is not true:**
 Continue to §3 as normal — the entire interactive flow below is unchanged.
 
 ### 3. Collect Project Path
 
-**Headless flag consumption:** If `project_paths[]` is already populated (e.g. collected by the section-1 stale-collision guard) OR `--project-path <path>` was passed at invocation, set/keep `project_paths[]` (comma-split the flag value if multiple paths were supplied), skip the prompt below, and proceed to validation. Otherwise prompt as today.
+**Headless flag consumption:** If `project_paths[]` is already populated (e.g. collected by the section-1 stale-collision guard) OR `--project-path <path>` was passed at invocation, set/keep `project_paths[]` (comma-split the flag value if multiple paths were supplied), skip the prompt below, and proceed to validation. If `{headless_mode}` is true and no path is available from either source, HARD HALT with exit code 2 (`input-missing`): "**No project path — headless mode requires `--project-path`.**" (interactive prompting is unavailable headless). Otherwise prompt as today.
 
 **Per-path ref overrides (`--target-refs`):** If `--target-refs <mapping>` was passed at invocation, parse it as a comma-separated list of `path:ref` pairs (e.g., `owner/repo:v1.0.0,owner/repo2:main`). Build a `constituent_refs` map from the pairs. Each key must match an entry in `project_paths[]` (validated after path collection). When `--target-refs` is absent but multiple `project_paths` exist, set `constituent_refs` to `{}` (empty — all paths use default ref resolution). When only a single path exists, omit `constituent_refs` entirely (use `target_ref` if set on the brief). `constituent_refs` and `target_ref` are mutually exclusive — if both are supplied, HALT with: "`--target-refs` and `--target-ref` are mutually exclusive. Use `--target-refs` for multi-path analysis, or `--target-ref` for single-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(s) to analyze:**
+"**Please provide the project root path(s) to analyze** — I'll identify discrete skillable units and produce a skill-brief.yaml for each.
 
 This can be:
 - A single root directory of a repo or multi-service project
@@ -149,7 +149,7 @@ These units will be flagged as 'already skilled' during analysis. If source chan
 
 ### 6. Create Analysis Report
 
-Create {outputFile} from {templateFile}.
+Create {outputFile} from {templateFile}. If the write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
 
 **Populate frontmatter:**
 ```yaml
@@ -183,18 +183,5 @@ nextWorkflow: ''
 
 ### 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_paths, forge_tier, existing_skills) will you load and read fully {nextStepFile} to execute and begin the project scan.
+Initialization is complete and the report is created — immediately load, read the entire file, then execute {nextStepFile}. This step has no user choices.
 

package/src/skf-analyze-source/references/map-and-detect.md

@@ -1,7 +1,7 @@
 ---
 nextStepFile: 'recommend.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: 'references/unit-detection-heuristics.md'
+heuristicsFile: '{unitDetectionHeuristicsPath}'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -31,16 +31,16 @@ Load {heuristicsFile} for stack skill candidate detection rules.
 
 ### 2. Map Export Surfaces Per Unit (Subagent Fan-Out)
 
-DO NOT BE LAZY — For EACH qualifying unit, delegate deep analysis to a subagent so per-unit work runs in parallel and the parent's context stays clean.
+For each qualifying unit, delegate deep analysis to a subagent so per-unit work runs in parallel and the parent's context stays clean.
 
 **Subagent fan-out protocol:**
 
-1. **Build the qualifying-unit list.** Read the unit list produced upstream (Step §3 / §4 outputs already in workflow context — names, paths, scope types, languages, file counts). Do NOT re-scan the project here.
+1. **Build the qualifying-unit list.** Read the unit list produced upstream (Step §3 / §4 outputs already in workflow context — names, paths, scope types, languages, file counts). Do not re-scan the project here.
 
 2. **Delegate per-unit deep analysis to a subagent.** For each qualifying unit, launch a subagent task with these explicit constraints:
-   - The subagent reads ONLY that unit's directory tree
+   - The subagent reads only that unit's directory tree
    - The subagent analyzes exports / usage / CCC signals / scripts+assets for that one unit
-   - **The parent does NOT read the unit's source files before delegating** (avoid the implicit-read trap — the whole point of fan-out is to keep large source bodies out of the parent's context)
+   - **The parent does not read the unit's source files before delegating** (avoid the implicit-read trap — the whole point of fan-out is to keep large source bodies out of the parent's context)
 
 3. **Per-unit analysis the subagent performs (scaled by size-aware strategy):**
 
@@ -66,7 +66,7 @@ DO NOT BE LAZY — For EACH qualifying unit, delegate deep analysis to a subagen
    - Script/asset presence: check for `scripts/`, `bin/`, `assets/`, `templates/` directories and files matching detection signals in `{heuristicsFile}`
    - Analysis strategy used and coverage confidence
 
-4. **Subagent return contract.** Each subagent returns ONLY this JSON object — no prose, no commentary, no markdown fences:
+4. **Subagent return contract.** Each subagent returns only this JSON object — no prose, no commentary, no markdown fences:
 
    ```json
    {
@@ -129,12 +129,7 @@ Identify cross-unit integration patterns:
 
 ### 5. Flag Stack Skill Candidates
 
-Using rules from {heuristicsFile}, check for stack skill indicators:
-
-1. **Co-import frequency:** Two or more units 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
+Check each of the four stack-skill indicators defined in {heuristicsFile}'s Stack Skill Candidate Detection section — co-import frequency, integration adapter, shared state, orchestration layer — against the units.
 
 **For each candidate, document:**
 - Units involved
@@ -197,12 +192,5 @@ Display: "**Select:** [C] Continue to Recommendations | [D] Discover Additional
 - IF D: Accept a new repo path/URL from the user. Run a lightweight scan (directory structure + manifest detection from step 02) and classify (unit identification from step 03) for the new source only. Merge results into the existing report — append new units to the unit list, update `project_paths[]` in frontmatter. Then redisplay this step's export mapping for the new units before returning to the menu.
 - 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 both the Export Map and Integration Points sections have been appended to {outputFile} with complete findings, and frontmatter stepsCompleted and stack_skill_candidates have been updated, will you load and read fully {nextStepFile} to begin recommendations.
+**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: auto-proceed with [C] Continue past export/integration findings, log: "headless: auto-continue past integration analysis".
 

package/src/skf-analyze-source/references/recommend.md

@@ -1,7 +1,7 @@
 ---
 nextStepFile: 'generate-briefs.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-schemaFile: 'assets/skill-brief-schema.md'
+schemaFile: '{briefSchemaPath}'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -38,7 +38,7 @@ Load {schemaFile} for reference on what skill-brief.yaml requires (so recommenda
 
 ### 2. Build Recommendation Cards
 
-For EACH qualifying unit, prepare a recommendation card:
+For each qualifying unit, prepare a recommendation card:
 
 ```
 **Unit: {name}**
@@ -167,18 +167,8 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Disc
 - IF P: Invoke {partyModeSkill}, and when finished redisplay the menu
 - IF D: Accept a new repo path/URL from the user. Run a lightweight scan + classify (subset of steps 02-03) for the new source only. Merge new units into the existing report and update `project_paths[]` in frontmatter. Run export mapping for the new units (same logic as step 04 section 2). Generate recommendation cards for the new units and present them for confirmation. Then redisplay this menu.
 - IF C: Save recommendations to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, and counts/paths reflecting state at cancellation
+- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the error envelope on stderr with `halt_reason: "user-cancelled"` and counts/paths reflecting state at cancellation (shape in `references/headless-contract.md`)
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
 
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: accept all recommendations and auto-proceed, log: "headless: auto-accept all recommendations"
-- ONLY proceed to next step when user selects 'C'
-- After other menu items execution, return to this menu
-- User can chat or ask questions — always respond and then redisplay menu
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN all units have explicit user decisions (Y/N/M), the confirmed_units list is finalized in frontmatter, and the user has given final confirmation, will you load and read fully {nextStepFile} to begin brief generation.
+**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: accept all recommendations and auto-proceed, log: "headless: auto-accept all recommendations".
 

package/src/skf-analyze-source/references/scan-project.md

@@ -1,7 +1,7 @@
 ---
 nextStepFile: 'identify-units.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: 'references/unit-detection-heuristics.md'
+heuristicsFile: '{unitDetectionHeuristicsPath}'
 scanManifestsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
   - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
@@ -149,16 +149,8 @@ Display: "**Select:** [C] Continue to Unit Identification | [X] Cancel and exit"
 #### Menu Handling Logic:
 
 - IF C: Save scan results to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, and counts/paths reflecting state at cancellation
+- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the error envelope on stderr with `halt_reason: "user-cancelled"` and counts/paths reflecting state at cancellation (shape in `references/headless-contract.md`)
 - IF Any other: help user, then [Redisplay Menu Options](#7-present-menu-options)
 
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past scan results"
-- ONLY proceed to next step when user selects 'C'
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the Project Scan section has been appended to {outputFile} with complete boundary, manifest, and entry point catalogs, and frontmatter stepsCompleted has been updated, will you load and read fully {nextStepFile} to begin unit identification.
+**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past scan results".