bmad-module-skill-forge 0.2.0

package/src/workflows/brief-skill/steps-c/step-02-analyze-target.md

@@ -0,0 +1,203 @@
+---
+name: 'step-02-analyze-target'
+description: 'Analyze target repository structure, detect language, and list modules and exports'
+
+nextStepFile: './step-03-scope-definition.md'
+---
+
+# Step 2: Analyze Target
+
+## STEP GOAL:
+
+To analyze the target repository by resolving its location, reading its structure, detecting the primary language, and listing top-level modules and exports — providing the user with a factual foundation for scoping decisions.
+
+## 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 in Ferris Architect mode
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Report ONLY what is found — zero hallucination tolerance
+- ✅ You bring structural analysis expertise, user brings their domain understanding
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on analysis — do not define scope yet (that's step 03)
+- 🚫 FORBIDDEN to make scoping decisions or recommendations in this step
+- 🚫 FORBIDDEN to hallucinate or guess about repository contents
+- 💬 Approach: Prescriptive — exact analysis instructions, factual reporting
+- 📋 Report everything found; let the user interpret for scoping
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Analysis results are accumulated conversationally for use in step 03
+- 📖 This step is autonomous — minimal user interaction required
+- 🚫 FORBIDDEN to proceed if target is inaccessible — halt with actionable error
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Target repo (URL or path), user intent, skill name, forge tier — all from step 01
+- Focus: Structural analysis of the repository
+- Limits: Do not read file contents deeply — only structure, exports, and metadata
+- Dependencies: Confirmed target repository from step 01
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Resolve Target Location
+
+**For GitHub URLs:**
+- Use `gh api repos/{owner}/{repo}` to verify the repository exists
+- Use `gh api repos/{owner}/{repo}/git/trees/HEAD?recursive=1` to get the file tree
+- If inaccessible: **HALT** — "**Error:** Cannot access repository at {url}. Please verify the URL is correct and you have access. If private, ensure `gh auth` is configured."
+
+**For local paths:**
+- Verify the directory exists
+- List the directory tree
+- If path doesn't exist: **HALT** — "**Error:** Directory not found at {path}. Please verify the path is correct."
+
+Display: "**Resolving target...**"
+
+### 2. Read Repository Structure
+
+List the top-level directory structure:
+
+"**Repository Structure:**
+```
+{repo-name}/
+├── {top-level files}
+├── {top-level directories}/
+│   └── ...
+└── ...
+```
+**Total:** {file count} files, {directory count} directories"
+
+### 3. Detect Primary Language
+
+Examine file extensions and configuration files to detect the primary language:
+
+**Detection signals (check in order):**
+1. `package.json` → JavaScript/TypeScript
+2. `tsconfig.json` → TypeScript
+3. `Cargo.toml` → Rust
+4. `pyproject.toml` or `setup.py` or `setup.cfg` → Python
+5. `go.mod` → Go
+6. `pom.xml` or `build.gradle` → Java
+7. `*.csproj` or `*.sln` → C#
+8. `Gemfile` → Ruby
+9. File extension frequency analysis as fallback
+
+"**Detected language:** {language}
+**Confidence:** {high/medium/low}
+**Detection source:** {what config file or pattern confirmed it}"
+
+If confidence is low or ambiguous: flag for user override in step 03.
+
+### 4. List Top-Level Modules and Exports
+
+Based on detected language, identify public API surface:
+
+**For JavaScript/TypeScript:**
+- Check `package.json` for `main`, `exports`, `module` fields
+- Look for `index.ts`/`index.js` in `src/`
+- List directories under `src/` as potential modules
+
+**For Python:**
+- Check `__init__.py` files for public exports
+- List top-level packages under the source directory
+
+**For Rust:**
+- Check `lib.rs` for `pub mod` declarations
+- List modules from `src/` directory
+
+**For other languages:**
+- List top-level source directories as potential modules
+- Note any obvious entry points
+
+"**Top-Level Modules/Directories:**
+{numbered list of modules with brief description of each}
+
+**Detected Exports/Entry Points:**
+{numbered list of public-facing items found}"
+
+### 5. Report Analysis Summary
+
+Present the complete analysis:
+
+"**Analysis Complete**
+
+---
+
+**Target:** {repo URL or path}
+**Language:** {detected language} ({confidence})
+**Structure:** {file count} files across {directory count} directories
+
+**Key Modules ({count}):**
+{bulleted list of modules}
+
+**Public Exports/Entry Points ({count}):**
+{bulleted list of exports}
+
+**Notable Files:**
+- README: {found/not found}
+- Tests: {found/not found — location}
+- Docs: {found/not found — location}
+- Config: {list of config files found}
+
+---
+
+{If language confidence is low:}
+**Note:** Language detection confidence is low. You'll be able to override this in the next step.
+
+Moving to scope definition where you'll choose what to include and exclude."
+
+### 6. Auto-Proceed to Scope Definition
+
+Display: "**Proceeding to scope definition...**"
+
+#### Menu Handling Logic:
+
+- After analysis report is presented to user, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step — analysis is factual reporting with no user choices
+- Proceed directly to step 03 after presenting the analysis summary
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the analysis is complete and the summary has been presented to the user will you load and read fully `./step-03-scope-definition.md` to begin scope definition.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Target repository resolved and accessible
+- Repository structure listed clearly
+- Primary language detected with confidence level
+- Top-level modules and exports identified
+- Analysis summary presented factually
+- Auto-proceeded to scope definition
+
+### ❌ SYSTEM FAILURE:
+
+- Hallucinating or guessing about repository contents
+- Making scoping recommendations (too early — that's step 03)
+- Proceeding when target is inaccessible (must halt with error)
+- Not detecting or reporting the primary language
+- Skipping the analysis summary
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/brief-skill/steps-c/step-03-scope-definition.md

@@ -0,0 +1,225 @@
+---
+name: 'step-03-scope-definition'
+description: 'Collaboratively define skill scope boundaries using analysis findings and scope templates'
+
+nextStepFile: './step-04-confirm-brief.md'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step 3: Scope Definition
+
+## STEP GOAL:
+
+To collaboratively define the skill's inclusion and exclusion boundaries using the analysis findings from step 02, scope templates, and the user's intent from step 01.
+
+## 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 boundary architect in Ferris Architect mode (collaborative, exploratory)
+- ✅ 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 API surface design expertise, user brings their domain knowledge of what's valuable
+- ✅ Maintain warm, guiding tone — help the user make informed scoping decisions
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on defining scope boundaries — do not write the brief yet (that's step 05)
+- 🚫 FORBIDDEN to make scope decisions unilaterally — user drives all scope choices
+- 💬 Approach: Intent-based discovery — "Which parts are most relevant to your use case?"
+- 📋 Produce: scope type, include patterns, exclude patterns
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Accumulate scope decisions conversationally for use in subsequent steps
+- 📖 Reference analysis findings from step 02 throughout
+- 🚫 FORBIDDEN to proceed without user confirmation of scope boundaries
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Target repo, user intent, skill name, forge tier (step 01), repo structure, detected language, modules, exports (step 02)
+- Focus: Defining WHAT is in scope and what is NOT
+- Limits: Do not generate the brief — only define boundaries
+- Dependencies: Analysis findings from step 02
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Present Scope Context
+
+"**Let's define the scope for your skill.**
+
+Based on the analysis, here's what we're working with:
+
+- **Target:** {repo}
+- **Language:** {detected language}
+- **Modules found:** {count} — {list names}
+- **Your intent:** {user intent from step 01}
+{If scope hints from step 01:}
+- **Your initial scope hints:** {hints}"
+
+### 2. Offer Scope Templates
+
+"**How broadly should this skill cover the library?**
+
+**[F] Full Library** — Include everything. Best for smaller, focused libraries.
+- All public exports, all modules
+- Exclude only tests, build artifacts, and internal utilities
+
+**[M] Specific Modules** — Select which modules to include. Best for large libraries where only some parts are relevant.
+- You choose which modules/directories
+- Fine-grained control over what's in and out
+
+**[P] Public API Only** — Include only the public-facing API surface. Best for libraries with a clear public/private boundary.
+- Entry points and exported interfaces only
+- Internal implementation excluded
+
+Which scope type fits your needs?"
+
+Wait for user selection.
+
+### 3. Define Boundaries Based on Selection
+
+**If [F] Full Library:**
+
+"**Full Library scope selected.**
+
+Default inclusions:
+- All source files under {main source directory}
+- All public modules: {list from analysis}
+
+Default exclusions:
+- Test files (`**/*.test.*`, `**/*.spec.*`, `**/test/`, `**/tests/`)
+- Build artifacts (`**/dist/`, `**/build/`, `**/target/`)
+- Configuration files
+- Documentation source files
+
+Any additional exclusions you'd like to add? Or adjustments to these defaults?"
+
+**If [M] Specific Modules:**
+
+"**Specific Modules scope selected.**
+
+Here are the modules found in the analysis:
+
+{numbered list of modules from step 02 with brief descriptions}
+
+Which modules would you like to include? (Enter numbers, comma-separated):"
+
+Wait for selection. Then:
+
+"**Selected modules:**
+- {list selected modules}
+
+For these modules, should I include:
+- **A)** Everything in those modules (all files)
+- **B)** Only public exports from those modules
+
+Any files or patterns to explicitly exclude within these modules?"
+
+**If [P] Public API Only:**
+
+"**Public API scope selected.**
+
+From the analysis, these appear to be the public entry points:
+
+{numbered list of exports/entry points from step 02}
+
+Which of these would you like to include? (Enter numbers, or 'all'):"
+
+Wait for selection. Then:
+
+"**Selected exports:**
+- {list selected exports}
+
+Exclusions will include all internal implementation files, tests, and utilities.
+
+Any additional items you'd like to include or exclude?"
+
+### 4. Handle Language Override
+
+{If language detection confidence was low from step 02:}
+
+"**Language confirmation needed.**
+
+The analysis detected **{language}** with low confidence. Is this correct, or should we set a different primary language?"
+
+Wait for confirmation or override.
+
+### 5. Summarize Scope Decisions
+
+"**Scope Summary:**
+
+**Type:** {Full Library / Specific Modules / Public API}
+
+**Include:**
+{bulleted list of include patterns}
+
+**Exclude:**
+{bulleted list of exclude patterns}
+
+**Language:** {confirmed language}
+
+{If any scope notes:}
+**Notes:** {scope notes}
+
+Does this look right? You can adjust before we continue."
+
+Wait for confirmation. Make adjustments if requested.
+
+### 6. Present MENU OPTIONS
+
+Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Brief Confirmation
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- 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 C is selected and scope boundaries are confirmed will you load and read fully `./step-04-confirm-brief.md` to present the complete brief for confirmation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Scope type selected by user (Full Library, Specific Modules, or Public API)
+- Include patterns defined and confirmed
+- Exclude patterns defined and confirmed
+- Language confirmed (or overridden if detection was low confidence)
+- User confirmed the scope summary
+- Menu presented and user input handled correctly
+
+### ❌ SYSTEM FAILURE:
+
+- Making scope decisions without user input
+- Not presenting the scope templates for user selection
+- Skipping the scope summary confirmation
+- Not handling language override when detection confidence was low
+- Writing the brief in this step (too early — that's step 05)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/brief-skill/steps-c/step-04-confirm-brief.md

@@ -0,0 +1,185 @@
+---
+name: 'step-04-confirm-brief'
+description: 'Present complete skill brief for user review and confirmation before writing'
+
+nextStepFile: './step-05-write-brief.md'
+reviseStepFile: './step-03-scope-definition.md'
+briefSchemaFile: '../data/skill-brief-schema.md'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step 4: Confirm Brief
+
+## STEP GOAL:
+
+To present the complete skill brief in human-readable format, highlighting all fields that will be written to skill-brief.yaml, and obtain explicit user approval before writing.
+
+## 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 quality reviewer in Ferris Architect mode
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Present information precisely and clearly — this is a confirmation gate
+- ✅ Highlight anything with low confidence or defaults that the user should verify
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on presenting and confirming — do not write files yet (that's step 05)
+- 🚫 FORBIDDEN to proceed without explicit user approval
+- 💬 Approach: Prescriptive — exact presentation format showing all YAML fields
+- 📋 This is a P2 confirmation gate — the user MUST approve before continuing
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Load the schema to ensure all required fields are presented
+- 📖 This is a mandatory checkpoint — no auto-proceed
+- 🚫 FORBIDDEN to write skill-brief.yaml in this step
+
+## CONTEXT BOUNDARIES:
+
+- Available context: All gathered data from steps 01-03 (target, intent, name, tier, language, scope)
+- Focus: Presenting the complete brief for final review
+- Limits: Do not write files — only present for approval
+- Dependencies: Confirmed scope boundaries from step 03
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Schema
+
+Load `{briefSchemaFile}` to reference required fields and the human-readable presentation format.
+
+### 2. Assemble Complete Brief
+
+Compile all gathered data from steps 01-03 into the complete brief:
+
+- **name:** {skill name from step 01}
+- **version:** "1.0.0" (default)
+- **source_repo:** {target repo from step 01}
+- **language:** {detected/confirmed language from steps 02-03}
+- **description:** {derived from user intent in step 01}
+- **forge_tier:** {tier from step 01}
+- **created:** {current date}
+- **created_by:** {user_name from config}
+- **scope.type:** {scope type from step 03}
+- **scope.include:** {include patterns from step 03}
+- **scope.exclude:** {exclude patterns from step 03}
+- **scope.notes:** {any scope notes from step 03}
+
+### 3. Present Brief for Review
+
+Using the presentation format from the schema:
+
+"**Please review the complete skill brief before I write it.**
+
+---
+
+```
+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}
+```
+
+---"
+
+### 4. Highlight Items Needing Attention
+
+Flag any fields that may need review:
+
+{If language was overridden or low confidence:}
+"**Note:** Language was {auto-detected / manually overridden}."
+
+{If description was derived (not stated by user):}
+"**Note:** Description was derived from your stated intent. Adjust if needed."
+
+{If forge tier was defaulted:}
+"**Note:** Forge tier defaulted to Quick (no forge-tier.yaml found)."
+
+{If any scope patterns seem broad or narrow:}
+"**Note:** {specific observation about scope breadth}."
+
+"**This is your last chance to make changes before writing the file.**
+
+You can:
+- Adjust any field by telling me what to change
+- Revise scope boundaries by selecting [R]
+- Proceed to write by selecting [C]"
+
+### 5. Handle Inline Adjustments
+
+If the user requests changes to specific fields (name, description, version, etc.):
+- Make the adjustment
+- Re-present the updated brief
+- Return to the menu
+
+### 6. Present MENU OPTIONS
+
+Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Party Mode [C] Approve and Write
+
+#### Menu Handling Logic:
+
+- IF R: Load, read entire file, then execute {reviseStepFile} to re-enter scope definition
+- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond, apply any field adjustments, re-present brief if changed, then [Redisplay Menu Options](#6-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to write step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat, request field changes, or ask questions — always respond and then redisplay menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and the user has explicitly approved the brief will you load and read fully `./step-05-write-brief.md` to write the skill-brief.yaml file.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Schema loaded for field reference
+- Complete brief assembled from all gathered data
+- Brief presented in human-readable format
+- Low-confidence or defaulted fields highlighted
+- User explicitly approved the brief
+- Menu presented with revise option
+
+### ❌ SYSTEM FAILURE:
+
+- Writing skill-brief.yaml in this step (too early)
+- Proceeding without explicit user approval
+- Not presenting all required fields
+- Not highlighting defaulted or low-confidence values
+- Not offering the [R] Revise option
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.