bmad-module-skill-forge 0.6.0 → 0.7.1

package/src/workflows/refine-architecture/steps-c/step-04-improvements.md

@@ -0,0 +1,169 @@
+---
+name: 'step-04-improvements'
+description: 'Suggest capability expansions from skill data not leveraged in the architecture'
+
+nextStepFile: './step-05-compile.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 4: Improvement Detection
+
+## STEP GOAL:
+
+Identify capability expansions — library features documented in the generated skills that the architecture does not leverage. Detect unused capabilities, cross-library synergies visible from skill API surfaces, and alternative patterns that could strengthen the architecture. For each improvement, document the capability and suggest how to incorporate it.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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}`
+
+### Role Reinforcement:
+
+- ✅ You are an architecture refinement analyst identifying untapped capabilities
+- ✅ Every improvement must cite specific APIs from the generated skills — no speculation
+- ✅ Improvements are suggestions, not mandates — present them as optional enhancements
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on capability expansions not leveraged in the architecture
+- 🚫 FORBIDDEN to detect gaps (Step 02) or issues (Step 03) — those are already captured
+- 🎯 Improvements are ADDITIVE suggestions — they enhance, not contradict, the architecture
+- 💬 Every improvement MUST include evidence citations from actual skill content
+
+## EXECUTION PROTOCOLS:
+
+- Load refinement rules for improvement detection criteria
+- Compare full skill API surfaces against architecture usage
+- Detect unused capabilities, cross-library synergies, and alternative patterns
+- Append improvement findings as workflow state for Step 05
+- Only improvement detection — no gap or issue analysis
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory and SKILL.md files, refinement rules
+- Focus: Finding capabilities in skills that the architecture does not use
+- Limits: Only detect improvements — do not re-detect gaps or issues from earlier steps
+- Dependencies: Step 01 (skill inventory), Steps 02-03 (complete — do not duplicate findings)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Reference Refinement Rules
+
+Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
+
+Extract: improvement classification (Unused Capability, Cross-Library Synergy, Alternative Pattern), detection method, and citation format.
+
+### 2. Build Architecture Usage Map
+
+For each library referenced in the architecture document, extract how it is used:
+
+- What capabilities are described (e.g., "Loro for real-time data sync")
+- What APIs or features are referenced
+- What role it plays in the architecture
+
+This creates a map of `{library} -> {described_usage[]}` for comparison against full skill API surfaces.
+
+### 3. Compare Skill API Surfaces Against Architecture Usage
+
+For each skill in the inventory:
+
+**Load the full API surface from SKILL.md:**
+- All exported functions with signatures
+- All exported types and interfaces
+- All documented capabilities and features
+- All protocol support indicators
+
+**Compare against the architecture usage map:**
+- Which exports does the architecture reference or imply usage of?
+- Which exports are NOT referenced in the architecture at all?
+
+**For each unreferenced capability:**
+- Evaluate relevance: would this capability strengthen the architecture?
+- Skip trivial or internal-only exports (utilities, helpers, debug functions)
+- Flag capabilities that could address architectural concerns or expand functionality
+
+### 4. Detect Cross-Library Synergies
+
+Examine pairs of skills for complementary capabilities not exploited in the architecture:
+
+- Does Library A export an event system that Library B could consume?
+- Does Library A produce a data format that Library B has an optimized processor for?
+- Do two libraries offer overlapping capabilities that could be unified?
+
+**Only flag synergies where both sides have documented APIs** — do not speculate about undocumented features.
+
+### 5. Document Each Improvement
+
+For each detected improvement, apply the citation format from {refinementRulesData}:
+
+```
+**[IMPROVEMENT]**: {description}
+
+Evidence:
+- {skill_name} exports: `{function}({params}) -> {return_type}`
+- Architecture uses: {what the architecture currently describes}
+- Untapped: {what the skill offers that the architecture does not mention}
+
+Suggestion: {how to incorporate this capability into the architecture}
+```
+
+**Categorize improvements:**
+- **High:** Capabilities that address known architectural concerns or significantly expand functionality
+- **Medium:** Capabilities that add convenience or efficiency improvements
+- **Low:** Capabilities that are nice-to-have but not impactful
+
+### 6. Display Improvement Suggestions
+
+"**Pass 3: Improvement Detection — Untapped Capabilities**
+
+**Improvements Found:** {count} ({high_count} high value, {medium_count} medium, {low_count} low)
+
+{IF improvements found:}
+| # | Library | Improvement Type | Value | Summary |
+|---|---------|-----------------|-------|---------|
+| {n} | {lib} | {type} | {value} | {brief description} |
+
+{For each improvement, display the full citation with evidence and suggestion}
+
+{IF no improvements found:}
+**No untapped capabilities detected.** The architecture fully leverages the skill API surfaces.
+
+**Proceeding to compile refined architecture...**"
+
+Store all improvement findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-IMPROVEMENTS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted improvement findings** (full citation blocks with evidence, value ratings, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+
+### 7. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refinement rules loaded from {refinementRulesData}
+- Architecture usage map built for each referenced library
+- Full skill API surfaces compared against architecture usage
+- Cross-library synergies checked for complementary capabilities
+- Every improvement includes evidence citations from actual skill content
+- Improvements categorized by value (High, Medium, Low)
+- Improvement results displayed with count and details
+- Improvement findings stored as workflow state for Step 05
+- Auto-proceeded to step 05
+
+### ❌ SYSTEM FAILURE:
+
+- Improvements without evidence from actual skills (speculation)
+- Re-detecting gaps (Step 02) or issues (Step 03)
+- Presenting trivial internal-only exports as improvements
+- Not categorizing improvements by value
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/refine-architecture/steps-c/step-05-compile.md

@@ -0,0 +1,200 @@
+---
+name: 'step-05-compile'
+description: 'Produce the refined architecture document by annotating the original with gaps, issues, and improvements'
+
+nextStepFile: './step-06-report.md'
+outputFile: '{output_folder}/refined-architecture-{project_name}.md'
+---
+
+# Step 5: Compile Refined Architecture
+
+## STEP GOAL:
+
+Produce the refined architecture document by starting with the original as a base, adding gap-fill subsections, issue callout blocks, and improvement suggestions. Append a Refinement Summary. Present for user review before finalizing.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ⚙️ 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}`
+
+### Role Reinforcement:
+
+- ✅ You are an architecture refinement analyst compiling the final refined document
+- ✅ Additive, not destructive — preserve every word of the original, only add refinements
+- ✅ The document must be in `{document_output_language}`
+
+### Step-Specific Rules:
+
+- 🚫 FORBIDDEN to discover new gaps, issues, or improvements — use only what Steps 02-04 produced
+- 🚫 FORBIDDEN to delete, reword, or rearrange original architecture content
+- 💬 Present compiled document for user review (Gate checkpoint)
+
+## EXECUTION PROTOCOLS:
+
+- Compile refined architecture from original + findings from Steps 02-04
+- Write output to {outputFile}, wait for user approval before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- From Steps 01-04: Architecture document, skill inventory, gap/issue/improvement findings
+- This step produces: The refined architecture document at {outputFile}
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Prepare the Original as Base
+
+Load the complete original architecture document.
+
+This is the base. Every line of the original MUST appear in the refined document, unmodified.
+
+**Context recovery check:** If gap, issue, or improvement findings from Steps 02-04 are not available in context (e.g., due to context degradation in long runs), attempt to read the durability state from `{forge_data_folder}/ra-state-{project_name}.md`. Parse the `<!-- [RA-GAPS] -->`, `<!-- [RA-ISSUES] -->`, and `<!-- [RA-IMPROVEMENTS] -->` comment blocks to recover the complete formatted findings (each block contains full citation text with evidence, not just counts). If a section is still missing or contains only summary counts after recovery, HALT: "⚠️ Context for the [Gaps|Issues|Improvements] analysis was lost and the durability state is insufficient to reconstruct findings. Re-run [RA] from the beginning — step 01 will reset the state file, then steps 02-04 will rebuild all findings."
+
+### 2. Insert Gap-Fill Subsections
+
+For each gap finding from Step 02:
+
+**Locate the most relevant section** in the original architecture where this integration would logically belong.
+
+**Insert a gap-fill subsection** one heading level deeper than the parent section:
+
+```markdown
+#### RA: {Library A} <-> {Library B} Integration Path
+
+> [!NOTE] **Gap Identified by Refine Architecture**
+> This integration path was not documented in the original architecture but is supported by skill API evidence.
+
+{Gap description with full evidence citation from Step 02}
+
+**Proposed Integration:**
+{Suggested architecture content describing how the libraries connect}
+```
+
+If no clear parent section exists, collect orphan gaps into a new section: "## RA: Additional Integration Paths"
+
+### 3. Insert Issue Annotations
+
+For each issue finding from Step 03:
+
+**Locate the section** containing the contradicted claim.
+
+**Insert an issue callout block** immediately after the contradicted text:
+
+```markdown
+> [!WARNING] **Issue Detected by Refine Architecture** ({severity})
+> Architecture states: "{quoted claim}"
+> Skill reality: {contradicting evidence from skill}
+> {IF VS report}: VS verdict: {verdict} for {pair}
+>
+> **Suggested Correction:** {specific correction with API evidence}
+```
+
+**Placement priority:** Place each issue callout immediately after the contradicted text in its original location. If the contradicted claim is inside a Markdown list item, code block, or table row where inserting a callout block would break syntax, place the callout immediately after the enclosing block instead. If the contradicted claim cannot be precisely located, collect into "## RA: Additional Issues Detected" at the end of the document, ordered by severity (Critical first, then Major, then Minor).
+
+### 4. Insert Improvement Suggestions
+
+For each improvement finding from Step 04:
+
+**Locate the section** where the library is discussed.
+
+**Insert an improvement subsection** one heading level deeper:
+
+```markdown
+#### RA: Enhancement — {Improvement Title}
+
+> [!TIP] **Improvement Suggested by Refine Architecture** ({value} value)
+> {skill_name} provides `{api}` which is not currently leveraged.
+
+{Full improvement description with evidence citation from Step 04}
+
+**How to Incorporate:**
+{Specific suggestion for updating the architecture}
+```
+
+**Order by value:** High value improvements first, then Medium, then Low.
+
+**Placement fallback:** If the library's only architecture mention is inside a table, code block, or Mermaid diagram where inserting a subsection would break syntax, collect into `## RA: Additional Improvements Suggested` at the end of the document.
+
+### 5. Add Refinement Summary Section
+
+Append a `## Refinement Summary` section containing:
+
+- **Header:** "Produced by: Refine Architecture workflow using {skill_count} skills" and date
+- **Changes Made table** with the following rows:
+
+| Category | Count | Breakdown |
+|----------|-------|-----------|
+| Gaps Filled | {gap_count} | — |
+| Issues Flagged | {issue_count} | Critical: {critical_count}, Major: {major_count}, Minor: {minor_count} |
+| Improvements Suggested | {improvement_count} | High: {high_count}, Medium: {medium_count}, Low: {low_count} |
+| Skills Used as Evidence | {skill_count} | — |
+- **Evidence Sources table:** Each skill name and how many refinements cite it
+- **Next Steps:** Review `[!WARNING]` issues, `[!NOTE]` gaps, `[!TIP]` improvements; then run **[SS] Stack Skill** to compose your individual skills into a unified stack skill, providing this refined architecture doc when prompted
+
+### 6. Write the Refined Document
+
+Write the complete refined architecture to `{outputFile}`.
+
+### 7. Present Compiled Document for Review
+
+"**Refined architecture compiled. Please review:**
+
+---
+
+{Display the Refinement Summary section only — not the full document}
+
+---
+
+**The full refined document has been written to:** `{outputFile}`
+
+Please review the refinements:
+- {gap_count} gap-fill subsections added
+- {issue_count} issue annotations inserted
+- {improvement_count} improvement suggestions included
+- Original architecture content preserved in full
+
+**Does the refinement look correct?**"
+
+### 8. Present MENU OPTIONS
+
+Display: **Select:** [C] Continue to Final Report
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting compilation
+- ONLY proceed to next step when user approves and selects 'C'
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other: Process as feedback, adjust specific refinements in the document, rewrite {outputFile}, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Original architecture document preserved in full without modifications
+- Gap-fill subsections inserted at logical locations with evidence citations
+- Issue callout blocks inserted adjacent to contradicted claims with severity
+- Improvement suggestions inserted with value ratings and evidence
+- Refinement Summary section appended with accurate counts
+- Refined document written to {outputFile}
+- User reviewed and approved compilation
+- Proceeded to step 06 only after user selected C
+
+### ❌ SYSTEM FAILURE:
+
+- Deleting, rewording, or rearranging original architecture content
+- Discovering new findings not from Steps 02-04
+- Inserting refinements without evidence citations
+- Proceeding without user review (Gate checkpoint)
+- Not writing the document to {outputFile} before presenting for review
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Additive only. Preserve the original. Get user approval before proceeding.

package/src/workflows/refine-architecture/steps-c/step-06-report.md

@@ -0,0 +1,147 @@
+---
+name: 'step-06-report'
+description: 'Present refinement summary to user with counts, next steps, and review options'
+
+outputFile: '{output_folder}/refined-architecture-{project_name}.md'
+---
+
+# Step 6: Present Report
+
+## STEP GOAL:
+
+Present the complete refinement summary to the user. Display counts of gaps filled, issues flagged, and improvements suggested. Provide the output file path and recommend next steps. Offer the user options to review changes in detail or exit. This is the FINAL step — no nextStepFile.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ⚙️ 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}`
+
+### Role Reinforcement:
+
+- ✅ You are an architecture refinement analyst delivering the final summary
+- ✅ Present findings clearly and concisely — the user needs to decide which refinements to keep
+- ✅ Next step recommendations must be specific and actionable
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on presenting the completed refinement — no new analysis
+- 🚫 FORBIDDEN to discover new gaps, issues, or improvements
+- 🚫 FORBIDDEN to modify the refined document — only read and present
+- 📋 This is the FINAL step — no nextStepFile
+
+## EXECUTION PROTOCOLS:
+
+- Load and present the refinement summary from the compiled document
+- No new content written — document was finalized in Step 05
+- Present summary, next steps, and review options clearly
+- Read-only presentation — do not alter document data
+
+## CONTEXT BOUNDARIES:
+
+- Available: Complete {outputFile} with all refinements from Steps 02-05
+- Focus: Clear, actionable presentation of refinement results
+- Limits: Do not add new analysis or change any refinements
+- Dependencies: All previous steps must be complete (Steps 01-05)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Refined Document
+
+Read the `{outputFile}` to have all data available for presentation.
+
+Verify the `## Refinement Summary` section is present. If it is absent, HALT: "⚠️ Refinement Summary not found in `{outputFile}`. Step 05 may not have completed successfully. Re-run [RA] from the beginning."
+
+**Extract metrics from the Refinement Summary section:** Parse `gap_count`, `issue_count`, `improvement_count`, `critical_count`, `major_count`, `minor_count`, `high_count`, `medium_count`, `low_count`, and `skill_count` from the Changes Made table and Evidence Sources table. Use these extracted values in the summary table and next-steps sections below.
+
+### 2. Display Summary
+
+"**Refine Architecture — Refinement Complete**
+
+---
+
+| Metric | Count |
+|--------|-------|
+| **Gaps Filled** | {gap_count} |
+| **Issues Flagged** | {issue_count} (Critical: {critical_count}, Major: {major_count}, Minor: {minor_count}) |
+| **Improvements Suggested** | {improvement_count} (High: {high_count}, Medium: {medium_count}, Low: {low_count}) |
+| **Skills Used as Evidence** | {skill_count} |
+
+**Evidence Sources:** (which skills contributed evidence)
+
+{Display the Evidence Sources table from the Refinement Summary section of the document}
+
+---
+
+**Your refined architecture is at:** `{outputFile}`
+
+The original architecture content is fully preserved. All refinements are clearly marked with `[!NOTE]`, `[!WARNING]`, and `[!TIP]` callout blocks that you can accept, modify, or remove."
+
+### 3. Present Next Steps
+
+"**Recommended next steps:**
+
+1. **Review the refined document** — accept, modify, or remove individual refinements
+2. **[SS] Stack Skill** — compose-mode activates automatically when SS detects existing individual skills without a codebase; provide this refined architecture doc as the architecture document when prompted
+3. **Re-run [VS] Verify Stack** if you made changes based on issue corrections — to confirm resolution
+
+{IF issues with Critical severity were found:}
+**⚠️ Attention:** {critical_count} critical issue(s) were flagged. These indicate fundamental contradictions between your architecture and the verified API surfaces. Address these before proceeding to stack skill composition."
+
+### 4. Present Menu
+
+Display: "**[R] Review changes in detail** | **[X] Exit refinement**"
+
+#### Menu Handling Logic:
+
+- **IF R:** Walk through each refinement with its full evidence citation:
+  1. First, all gaps with their evidence and proposed integration paths
+  2. Then, all issues ordered by severity with architecture claim vs. skill reality
+  3. Finally, all improvements ordered by value with untapped capability details
+  After completing the walkthrough, redisplay the menu.
+
+- **IF X:** "**Refined architecture saved to:** `{outputFile}`
+
+Re-run **[RA] Refine Architecture** anytime after updating your skills or architecture document.
+
+**Architecture refinement complete.**"
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting the menu
+- R may be selected multiple times — always walk through all refinements
+- X ends the workflow
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the final step of the refine-architecture workflow. When the user selects X, the workflow is complete. The refined architecture at `{outputFile}` contains the full original content plus all gap-fills, issue annotations, and improvement suggestions backed by skill API evidence.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refined document loaded and verified for Refinement Summary section
+- Summary displayed with accurate counts for gaps, issues, and improvements
+- Output file path displayed prominently
+- Next steps presented with specific workflow recommendations
+- Critical issues highlighted if present
+- Menu presented with R and X options
+- Detailed review walkthrough available on R selection with full evidence citations
+- Workflow exits cleanly on X with saved file path
+
+### ❌ SYSTEM FAILURE:
+
+- Discovering new findings or changing refinements in this step
+- Modifying the refined document content
+- Not presenting the menu
+- Not displaying the document save path on exit
+- Inaccurate counts in the summary
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/refine-architecture/workflow.md

@@ -0,0 +1,61 @@
+---
+name: refine-architecture
+description: Improve architecture doc using verified skill data and VS feasibility findings
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/refine-architecture'
+---
+
+# Refine Architecture
+
+**Goal:** Take an original architecture document + generated skills + optional VS feasibility report, and produce a refined architecture with gaps filled, issues flagged, and improvements suggested — all backed by specific API evidence from the generated skills.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an architecture refinement analyst operating in Ferris Architect mode. You bring expertise in API surface analysis, integration gap detection, and evidence-backed architecture improvement, while the user brings their architecture vision and generated skills. Execute with analytical precision — every suggestion must cite specific APIs from the generated skills. Evidence-backed suggestions, not speculation.
+
+---
+
+## 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
+- **Additive, Not Destructive**: This workflow enhances the original architecture — it never deletes original content, only adds annotations, subsections, and suggestions
+- **Evidence-Backed Refinement**: Every gap, issue, or improvement must cite specific APIs, types, or function signatures from the generated skills
+
+### 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}`
+- 📝 **DOCUMENT-PRODUCING**: This workflow outputs a refined architecture markdown file
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
+
+- `project_name`, `user_name`, `communication_language`, `document_output_language`
+- `skills_output_folder`, `forge_data_folder`, `output_folder`
+
+### 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/setup-forge/steps-c/step-01-detect-and-tier.md

@@ -45,6 +45,7 @@ Verify availability of the four forge tools (ast-grep, gh, qmd, ccc), read any e
 - This is the first step — no prior context exists
 - Available: forge-tier.yaml and preferences.yaml may exist from prior runs
 - Focus: tool verification and tier calculation only
+- Produces: `{detected_tools}`, `{calculated_tier}`, `{previous_tier}`, `{tier_override}` for downstream steps
 - Dependencies: none — this step bootstraps everything
 
 ## MANDATORY SEQUENCE
@@ -104,7 +105,7 @@ This is informational only — security scan availability does NOT affect the ti
 
 **Step B — Daemon health:** Run `ccc doctor`
 
-- If daemon is running and model check OK: record `{ccc: true}` and store version string from output
+- If daemon is running and model check OK: record `{ccc: true, ccc_daemon: "healthy"}` and store version string from output
 - If daemon is not running: record `{ccc: true, ccc_daemon: "stopped"}` — binary available, daemon needs starting. Step-01b will handle this.
 - If error or timeout: record `{ccc: true, ccc_daemon: "error"}` — binary works but daemon has issues.
 

package/src/workflows/setup-forge/steps-c/step-01b-ccc-index.md

@@ -71,7 +71,7 @@ Check the `ccc_index` section:
   - Proceed to section 4
 
 - If `ccc_index.indexed_path` matches `{project-root}` but timestamp is older than threshold:
-  - Store `{ccc_index_result: "stale", ccc_indexed_path: {existing path}, ccc_last_indexed: {existing timestamp}}` — proceed to section 3 for re-index
+  - Note index is stale — proceed to section 3 for re-index (section 3 will overwrite `ccc_index_result` to `"created"` or `"failed"`)
 
 - If `ccc_index` is missing, has null values, or path doesn't match:
   - Proceed to section 3 for initial index
@@ -86,9 +86,9 @@ The `ccc index` command auto-starts the daemon when needed. Proceed with indexin
 
 Attempt indexing anyway — errors will be caught below.
 
-Run:
+Run (CWD must be `{project-root}`):
 ```bash
-ccc init {project-root}
+ccc init
 ```
 
 **If init fails** (project may already be initialized): continue — this is not an error.
@@ -98,6 +98,8 @@ Then run:
 ccc index
 ```
 
+**Note:** `ccc index` can take several minutes on large codebases (1000+ files). Run with an extended timeout or in background mode. Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero.
+
 **If succeeds:**
 - Run `ccc status` to get file count
 - Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from status}}`