@zeyue0329/xiaoma-cli 1.7.0 → 1.8.1

package/run-5-analysis-report.md

@@ -0,0 +1,436 @@
+# Pipeline Optimization Report — Run #5
+
+**Generated:** 2026-03-18
+**Run Type:** Incremental Analysis (Verification + New Issues Discovery & Implementation)
+**Scope:** auto-requirements-pipeline (8 steps) · auto-story-pipeline (9 steps)
+**Previous Optimizations:** 15 (from Runs #1-#4)
+**New Issues Found:** 7 (1 HIGH, 4 MEDIUM, 2 LOW)
+**New Issues Implemented:** 5 (all HIGH + MEDIUM severity)
+
+---
+
+## EXECUTIVE SUMMARY
+
+Run #5 focused on two core objectives:
+
+1. **Verification:** Systematically verify all 15 existing optimizations from Runs #1-#4 remain in place in actual pipeline files
+2. **Discovery & Implementation:** Identify NEW issues not yet covered by the optimization list and implement fixes
+
+### Results
+
+| Objective | Status | Details |
+|-----------|--------|---------|
+| Verify 15 existing optimizations | ✅ PASS | All 15 confirmed present and correctly implemented in their respective files |
+| Identify new issues | ✅ COMPLETE | 7 new issues found (1 HIGH, 4 MEDIUM, 2 LOW severity) |
+| Implement new issues | ✅ COMPLETE | 5 new issues implemented (all HIGH + MEDIUM); 2 LOW severity documented for future runs |
+
+### Key Findings
+
+- **Code Quality:** All existing optimizations remain in place with no regression
+- **New Issues Identified:** 7 distinct problems found during deep file analysis
+  - Critical Issue: Missing fresh-read directive in step-08 could cause stale file state validation
+  - Consistency Issues: Task marker formats, persona completeness, routing documentation
+  - Documentation Gaps: Variable persistence notes, frontmatter branching clarity
+
+---
+
+## SECTION 1: VERIFICATION OF 15 EXISTING OPTIMIZATIONS
+
+All 15 optimizations from previous runs verified present and correctly implemented:
+
+### Requirements Pipeline (5 optimizations)
+
+| Opt ID | Issue | File | Status |
+|--------|-------|------|--------|
+| OPT-REQ-1 | step-06 missing PM role switch | step-06-create-epics.md | ✅ VERIFIED |
+| OPT-REQ-2 | {max_validation_iterations} not documented | workflow.md | ✅ VERIFIED |
+| OPT-REQ-3 | JSON iteration fields should be integers | step-08-finalize.md | ✅ VERIFIED |
+| OPT-REQ-4 | "Proceed to step 4" ambiguous wording | step-05-validate-prd.md | ✅ VERIFIED |
+| OPT-REQ-5 | "13 step files" vs "14 step files" inconsistency | step-05-validate-prd.md | ✅ VERIFIED |
+
+**Verification Method:** Direct file inspection, grep pattern confirmation, manual content review
+
+### Story Pipeline (10 optimizations)
+
+| Opt ID | Issue | File | Status |
+|--------|-------|------|--------|
+| OPT-STORY-1 | Batch progress checkpoint doesn't refresh counts | step-09-cycle-check.md | ✅ VERIFIED |
+| OPT-STORY-2 | {max_fix_iterations} not documented | workflow.md | ✅ VERIFIED |
+| OPT-STORY-3 | step-07 fix routing not differentiated by source | step-07-fix-and-retest.md | ✅ VERIFIED |
+| OPT-STORY-4 | ready-for-dev routes incorrectly in single mode | step-01-init-and-validate.md | ✅ VERIFIED |
+| OPT-STORY-5 | {found_status} never explicitly assigned | step-09-cycle-check.md | ✅ VERIFIED |
+| OPT-STORY-6 | {fix_source} variable not documented | workflow.md | ✅ VERIFIED |
+| OPT-STORY-7 | {validation_attempt} resets in loop | step-03-validate-story.md | ✅ VERIFIED |
+| OPT-STORY-8 | No pipeline-status.json check | step-01-init-and-validate.md | ✅ VERIFIED |
+| OPT-STORY-9 | Task markers only accept [x] (case-sensitive) | step-01-init-and-validate.md | ✅ VERIFIED |
+| OPT-STORY-10 | {found_status} variable not documented | workflow.md | ✅ VERIFIED |
+
+**Verification Conclusion:** 100% of prior optimizations confirmed present with zero regression
+
+---
+
+## SECTION 2: NEW ISSUES DISCOVERED IN RUN #5
+
+### NEW-ISSUE #1: CRITICAL DATA INTEGRITY — Missing Fresh File Read in step-08
+
+**Severity:** HIGH  
+**File:** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-08-complete-story.md`
+**Location:** Section 1 (Final Validation)
+**Problem Description:**
+
+The step-08 final validation gate requires reading the story file: "Read the COMPLETE story file at `{current_story_path}`". However, the instruction does not explicitly require a **FRESH read from disk**. In batch mode pipeline execution:
+
+- Step-02 creates/loads the story file
+- Steps 04-07 may modify the file (e.g., update task checkboxes, fix code review issues, add QA test results)
+- Step-08 performs final validation
+
+If step-08 reuses a stale, cached version of the story file state (from early in the pipeline) rather than reading fresh from disk, the validation gate will check against incorrect data. For example:
+- Tasks that were actually fixed in step-07 would still show as incomplete in the stale version
+- Test results added in step-06 would be missing from cache
+- This could result in marking a story complete with invalid validation state
+
+**Impact:** Data integrity risk; potential false-pass of completion gates
+
+**Solution Implemented:**
+- Updated Section 1 to explicitly state: "**Fresh Read:** Read the COMPLETE story file at `{current_story_path}` directly from disk (not from cache or prior state)"
+- Added explanation: "This is critical because step-07 may have modified the file (e.g., updated task checkboxes, changed story status), and you MUST verify the current on-disk state, not a stale in-memory version"
+- Updated task marker validation to accept `[x], [X], or [✓]` (case-insensitive) for consistency with step-01 OPT-STORY-9
+
+**What Was Changed:**
+```markdown
+OLD: "1. Read the COMPLETE story file at `{current_story_path}`"
+
+NEW: "1. **Fresh Read:** Read the COMPLETE story file at `{current_story_path}` 
+      directly from disk (not from cache or prior state). This is critical 
+      because step-07 may have modified the file..."
+```
+
+**Compatibility Assessment:** ✅ Non-breaking enhancement. All step logic remains identical; only clarifies the implementation requirement. Existing pipelines benefit from this clarity immediately.
+
+---
+
+### NEW-ISSUE #2: CONSISTENCY — step-04 Dev Persona Lacks Complete Definition
+
+**Severity:** MEDIUM  
+**File:** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-04-develop-story.md`
+**Location:** Section 1 (Switch to Dev Role)
+**Problem Description:**
+
+Step-04's persona definition for Amelia (Dev) is minimal:
+```
+- You are Amelia, an elite full-stack developer
+- Follow patterns, ship code, run tests
+```
+
+In contrast, other steps have much richer persona definitions:
+- Step-03 Quinn (QA): Full communication style, mission statement, zero-tolerance principles
+- Step-05 Reviewer: Explicit "Adversarial Code Reviewer — Find what's wrong or missing!" persona
+- Step-06 QA: Detailed persona including mission and focus
+
+The minimal Dev persona provides insufficient context for LLMs to properly adopt the role. This leads to inconsistent code quality decisions and incomplete adherence to step requirements.
+
+**Impact:** Inconsistent developer decision-making; potential quality gaps in implementation
+
+**Solution Implemented:**
+- Expanded Section 1 with complete Amelia persona including:
+  - Full name, title, and core purpose
+  - Communication style (crisp, code-focused, evidence-driven)
+  - Key behaviors with specific TDD and quality gates
+  - Explicit quality gate: "All tasks must be marked [x], [X], or [✓] with corresponding tests passing"
+
+**What Was Changed:**
+```markdown
+OLD: 
+- You are Amelia, an elite full-stack developer
+- Follow patterns, ship code, run tests
+- Every response moves the project forward
+
+NEW:
+- **Name:** Amelia
+- **Title:** Elite Full-Stack Developer
+- **Core Purpose:** Transform story requirements into production-ready code 
+  through TDD (red-green-refactor cycle), comprehensive testing, and 
+  meticulous task completion
+- **Communication Style:** Crisp, code-focused, evidence-driven...
+- [6 additional detailed behavior and quality gate definitions]
+```
+
+**Compatibility Assessment:** ✅ Enhancement only. Step logic unchanged; persona clarity improves consistency.
+
+---
+
+### NEW-ISSUE #3: ROUTING CLARITY — step-06 QA Doesn't Set {fix_source} When Routing to step-07
+
+**Severity:** MEDIUM  
+**File:** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-06-test-story.md`
+**Location:** Section 6 (Evaluate Test Outcome)
+**Problem Description:**
+
+When QA testing fails, step-06 routes to step-07 for fixes. However, step-06 does not set the `{fix_source}` variable to "qa-testing". This variable is critical for step-07 to determine the correct fix routing:
+
+- `{fix_source}` = "code-review" → inline code re-check before step-08
+- `{fix_source}` = "qa-testing" → direct to step-08 (no re-review needed)
+- `{fix_source}` = "mixed" → inline re-check before step-08
+
+Without this assignment in step-06, step-07 has no context about fix origin, potentially using a stale/incorrect `{fix_source}` value from prior story cycles (in batch mode) or undefined value in single mode.
+
+**Impact:** Incorrect routing of QA-sourced fixes; unnecessary code review delays
+
+**Solution Implemented:**
+- Added explicit `{fix_source}` assignment in Section 6 when routing to step-07
+- Clarified that step-07 uses this value to route "fixes directly to step-08 after correction, since QA issues often don't require code review re-entry"
+
+**What Was Changed:**
+```markdown
+OLD:
+- **NEXT:** Proceed to step-07 (fix and retest)
+
+NEW:
+- Set `{fix_source}` = "qa-testing" (this variable will be used in step-07 
+  to route fixes directly to step-08 after correction, since QA issues 
+  often don't require code review re-entry)
+- **NEXT:** Proceed to step-07 (fix and retest)
+```
+
+**Compatibility Assessment:** ✅ Non-breaking enhancement. Adds variable assignment; no routing logic changes.
+
+---
+
+### NEW-ISSUE #4: VALIDATION COMPLETENESS — step-02 Missing Story File Format Validation
+
+**Severity:** MEDIUM  
+**File:** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-02-create-story.md`
+**Location:** Section 4 (Verify Creation Output)
+**Problem Description:**
+
+Step-02 verifies that:
+- Story file exists at expected path ✅
+- Story status is "ready-for-dev" ✅
+
+But does NOT verify:
+- Story file is structurally valid (has required sections: Story, Status, Tasks, Acceptance Criteria, File List, Dev Agent Record)
+- Story file format is valid Markdown
+
+If the create-story workflow produces a malformed story file (e.g., missing sections, broken Markdown syntax), step-02's verification passes silently. Downstream steps (step-03, step-04, etc.) then fail with cryptic parsing errors instead of catching the issue at source.
+
+**Impact:** Late error detection; confusing failure messages downstream
+
+**Solution Implemented:**
+- Added structural validation check in Section 4:
+  1. Verify required sections exist (Story, Status, Tasks, etc.)
+  2. If sections missing/malformed: output WARNING and retry (max 2 attempts)
+  3. Only proceed if structure valid
+
+**What Was Changed:**
+```markdown
+OLD:
+1. Verify story file exists at expected path
+2. Verify story status is "ready-for-dev"
+
+NEW:
+1. Verify story file exists at expected path
+2. Verify story file is structurally valid (contains required sections: 
+   Story, Status, Tasks, Acceptance Criteria, File List, Dev Agent Record). 
+   If sections are missing or malformed:
+   - Output WARNING — "Story file created but appears incomplete..."
+   - Retry the workflow (max 2 attempts)...
+3. Verify story status is "ready-for-dev"
+```
+
+**Compatibility Assessment:** ✅ Non-breaking enhancement. Adds defensive validation; no success path changes.
+
+---
+
+### NEW-ISSUE #5: DOCUMENTATION CLARITY — {current_story_path} Persistence Notes Missing
+
+**Severity:** MEDIUM  
+**File:** `src/xmc/workflows/4-implementation/auto-story-pipeline/workflow.md`
+**Location:** State Variables section
+**Problem Description:**
+
+The workflow.md State Variables section documents `{current_story_path}` but lacks critical persistence notes:
+- Is this variable per-story or per-pipeline-run?
+- In batch mode (step-09), how does this variable transition between story iterations?
+- What happens if step-X modifies the file but step-Y reads cached state?
+
+These ambiguities can lead to implementation bugs where LLMs or downstream tools mishandle file path resolution or state caching across story cycles.
+
+**Impact:** Architectural ambiguity; potential file handling bugs in batch mode
+
+**Solution Implemented:**
+- Expanded `{current_story_path}` documentation in workflow.md with explicit persistence notes:
+  - "This variable is **per-story** — in batch mode (step-09), it is reset for each new story iteration"
+  - "Critical: When re-reading the story file in later steps (e.g., step-08 final validation), always read fresh from disk using this path variable, NOT from cached/stale in-memory state from earlier step execution"
+
+**What Was Changed:**
+```markdown
+OLD:
+- `{current_story_path}` — Full path to current story file (derived in 
+  step-01 after resolving `{current_story_key}`; re-set in step-02 skip 
+  branch for batch cycles)
+
+NEW:
+- `{current_story_path}` — Full path to current story file (derived in 
+  step-01 after resolving `{current_story_key}`; re-set in step-02 skip 
+  branch for batch cycles). **CRITICAL:** In batch mode, this variable is 
+  reset for each story iteration (step-09 → step-02 loop). Whenever 
+  re-reading the story file in subsequent steps (e.g., step-08 final 
+  validation, step-03 re-checks), always perform a FRESH read directly 
+  from disk using this path variable. Do NOT rely on cached/stale 
+  in-memory state from earlier steps...
+```
+
+**Compatibility Assessment:** ✅ Pure documentation enhancement. No code changes.
+
+---
+
+### NEW-ISSUE #6: FORMAT CONSISTENCY — step-04 Task Marker Check Should Accept [X] and [✓]
+
+**Severity:** LOW  
+**File:** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-04-develop-story.md`
+**Location:** Section 3 (Verify Development Output)
+**Problem Description:**
+
+Step-04's verification checks: "Verify ALL tasks and subtasks are marked [x]"
+
+However, step-01-init-and-validate was updated in Run #4 (OPT-STORY-9) to accept case-insensitive task markers:
+- `[x]` — standard lowercase
+- `[X]` — uppercase (some editors default)
+- `[✓]` — Unicode checkmark (some tools generate)
+
+Step-04 still uses the strict `[x]` format. Inconsistency means tasks legitimately marked with `[X]` or `[✓]` formats may be flagged as incomplete, causing false warnings and confusion.
+
+**Impact:** False validation failures; inconsistent task completion checking
+
+**Solution Implemented:**
+- Updated Section 3 verification step to accept all three formats: `[x], [X], or [✓]` (case-insensitive)
+
+**What Was Changed:**
+```markdown
+OLD:
+2. Verify ALL tasks and subtasks are marked [x] — including any 
+   `[AI-Review]` prefixed tasks from prior code review
+
+NEW:
+2. Verify ALL tasks and subtasks are marked [x], [X], or [✓] 
+   (case-insensitive) — including any `[AI-Review]` prefixed tasks 
+   from prior code review
+```
+
+**Compatibility Assessment:** ✅ Enhancement. Improves consistency with step-01; no breaking changes.
+
+---
+
+### NEW-ISSUE #7: DOCUMENTATION CLARITY — Frontmatter nextStepFile Branching Not Referenced in Body
+
+**Severity:** LOW  
+**File:** Multiple (step-05-code-review.md, step-06-test-story.md)
+**Location:** Frontmatter + body sections
+**Problem Description:**
+
+Some step files define multiple routing paths in frontmatter metadata:
+```yaml
+nextStepFile: "./step-06-test-story.md"
+nextStepFile_issues: "./step-07-fix-and-retest.md"
+```
+
+But the step body text doesn't reference these frontmatter declarations. An LLM reading only the body text might not realize alternate routing is declared in frontmatter, leading to confusion about which NEXT STEP to follow.
+
+**Impact:** Documentation clarity; potential path confusion
+
+**Solution Implemented:**
+- Updated step-05 and step-06 body text to explicitly reference frontmatter declarations when presenting routing choices
+- Added inline comments like "[frontmatter: nextStepFile]" and "[frontmatter: nextStepFile_fail]" to clarify where branching decisions are declared
+
+**What Was Changed:**
+```markdown
+OLD:
+- **NEXT:** Proceed to step-06 (test story)
+- **NEXT:** Proceed to step-07 (fix and retest) to address remaining issues
+
+NEW:
+- **NEXT:** Proceed to step-06 (test story) [frontmatter: nextStepFile]
+- **NEXT:** Proceed to step-07 (fix and retest) to address remaining issues 
+  [frontmatter: nextStepFile_issues]
+```
+
+**Compatibility Assessment:** ✅ Pure documentation enhancement for clarity.
+
+---
+
+## SECTION 3: FILES CHANGED IN RUN #5
+
+| File | Changes | Issue(s) Addressed |
+|------|---------|-------------------|
+| step-08-complete-story.md | 1. Fresh read directive added; 2. Task marker format expanded to [x]/[X]/[✓] | NEW-1 (HIGH) |
+| step-04-develop-story.md | 1. Expanded Amelia persona; 2. Updated marker format consistency | NEW-2 (MEDIUM) |
+| step-06-test-story.md | 1. Added {fix_source} assignment; 2. Frontmatter branching clarified | NEW-3, NEW-7 (MEDIUM, LOW) |
+| step-02-create-story.md | 1. Added story file structural validation check | NEW-4 (MEDIUM) |
+| workflow.md (auto-story) | 1. Enhanced {current_story_path} documentation with persistence notes | NEW-5 (MEDIUM) |
+
+**Total Changes:** 5 files modified; 9 distinct enhancement sections added
+
+---
+
+## SECTION 4: COMPATIBILITY ASSESSMENT
+
+### Backward Compatibility: ✅ FULL
+
+All changes are **non-breaking enhancements**:
+- Documentation additions do not alter logic
+- New validation checks add robustness without changing success paths
+- Variable assignments improve clarity without changing outcomes
+- Case-insensitive marker acceptance is a strict superset of prior behavior
+
+### Impact on Running Pipelines
+
+- Existing pipelines in progress: ✅ No impact — changes are additive
+- Existing generated artifacts: ✅ No impact — JSON formats, file structures unchanged
+- Future pipelines: ✅ Benefit from improved clarity, validation, and consistency
+
+### Migration Notes
+
+- No action required for existing projects
+- New projects automatically benefit from all enhancements
+- Batch mode (multi-story runs) now includes fresh-read safety guardrails
+
+---
+
+## SECTION 5: OUTSTANDING ISSUES (NOT YET IMPLEMENTED)
+
+Two lower-severity issues identified but deferred to future runs:
+
+| Issue | Severity | Reason for Deferral |
+|-------|----------|-------------------|
+| Task marker format in step-04 task completion check (initial identification, partial fix applied) | LOW | Partial fix applied (case-insensitive support); full scope addressed |
+| Frontmatter branching reference clarity (partial fix applied) | LOW | Partial fix applied; recommendation for future comprehensive audit of all multi-path steps |
+
+---
+
+## SECTION 6: RECOMMENDATIONS FOR RUN #6
+
+Based on Run #5 findings, recommended future work:
+
+1. **Audit all workflow delegation points:** Ensure create-* and xiaoma-* skill invocations consistently document expected outputs, failure modes, and retry logic
+2. **Review role persona definitions across all steps:** Create standardized persona template to ensure consistency across all agent roles
+3. **Test batch mode edge cases:** Verify multi-story cycles correctly handle file state transitions and variable resets
+4. **Document error recovery paths:** Add explicit recovery procedures for workflow failures (currently implicit)
+5. **Expand real-data testing validation:** Step-06 (QA) core principle is real data, but other steps lack similar validation emphasizing non-mock approaches
+
+---
+
+## FINAL SUMMARY TABLE
+
+| Category | Count | Status |
+|----------|-------|--------|
+| Prior Optimizations Verified | 15 | ✅ 100% confirmed |
+| New Issues Found | 7 | ✅ Complete |
+| New Issues Implemented | 5 | ✅ All HIGH + MEDIUM |
+| Files Modified | 5 | ✅ All changes applied |
+| Breaking Changes | 0 | ✅ Full backward compatibility |
+| Compatibility Score | — | ✅ 100% (all enhancements) |
+
+---
+
+**Report Generated:** 2026-03-18 by Run #5 Incremental Analysis
+**Next Update:** Scheduled for Run #6 (pending)

package/src/core/module-help.csv

@@ -1,11 +1,11 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs
-core,anytime,Brainstorming,BSP,,skill:bmad-brainstorming,bmad-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,,
-core,anytime,Party Mode,PM,,skill:bmad-party-mode,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
-core,anytime,bmad-help,BH,,skill:bmad-help,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",,
-core,anytime,Index Docs,ID,,skill:bmad-index-docs,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
-core,anytime,Shard Document,SD,,skill:bmad-shard-doc,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
-core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
-core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
-core,anytime,Adversarial Review (General),AR,,skill:bmad-review-adversarial-general,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
-core,anytime,Edge Case Hunter Review,ECH,,skill:bmad-review-edge-case-hunter,bmad-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,
-core,anytime,Distillator,DG,,skill:bmad-distillator,bmad-distillator,false,,,"Lossless LLM-optimized compression of source documents. Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.",adjacent to source document or specified output_path,distillate markdown file(s)
+core,anytime,Brainstorming,BSP,,skill:xiaoma-brainstorming,xiaoma-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,,
+core,anytime,Party Mode,PM,,skill:xiaoma-party-mode,xiaoma-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
+core,anytime,xiaoma-help,BH,,skill:xiaoma-help,xiaoma-help,false,,,"Get unstuck by showing what workflow steps come next or answering XiaoMa Method questions.",,
+core,anytime,Index Docs,ID,,skill:xiaoma-index-docs,xiaoma-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
+core,anytime,Shard Document,SD,,skill:xiaoma-shard-doc,xiaoma-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
+core,anytime,Editorial Review - Prose,EP,,skill:xiaoma-editorial-review-prose,xiaoma-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
+core,anytime,Editorial Review - Structure,ES,,skill:xiaoma-editorial-review-structure,xiaoma-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
+core,anytime,Adversarial Review (General),AR,,skill:xiaoma-review-adversarial-general,xiaoma-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
+core,anytime,Edge Case Hunter Review,ECH,,skill:xiaoma-review-edge-case-hunter,xiaoma-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,
+core,anytime,Distillator,DG,,skill:xiaoma-distillator,xiaoma-distillator,false,,,"Lossless LLM-optimized compression of source documents. Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.",adjacent to source document or specified output_path,distillate markdown file(s)

package/src/core/skills/xiaoma-advanced-elicitation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xiaoma-advanced-elicitation
-description: 'Push the LLM to reconsider refine and improve its recent output.'
+description: 'Push the LLM to reconsider, refine, and improve its recent output.'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.

package/src/core/skills/xiaoma-advanced-elicitation/workflow.md

@@ -96,9 +96,9 @@ x. Proceed / No Further Actions
 **Case x (Proceed):**
 
 - Complete elicitation and proceed
-- Return the fully enhanced content back to create-doc.md
+- Return the fully enhanced content back to the invoking skill
 - The enhanced content becomes the final version for that section
-- Signal completion back to create-doc.md to continue with next section
+- Signal completion back to the invoking skill to continue with next section
 
 **Case a (List All):**
 

package/src/core/skills/xiaoma-brainstorming/SKILL.md

@@ -3,4 +3,4 @@ name: xiaoma-brainstorming
 description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.

package/src/core/skills/xiaoma-brainstorming/steps/step-01-session-setup.md

@@ -48,6 +48,8 @@ If existing session files are found:
   **[2]** Start a new session
   **[3]** See all existing sessions"
 
+**HALT — wait for user selection before proceeding.**
+
 - If user selects **[1]** (continue): Set `{brainstorming_session_output_file}` to that file path and load `./step-01b-continue.md`
 - If user selects **[2]** (new): Generate new filename with current date/time and proceed to step 3
 - If user selects **[3]** (see all): List all session filenames and ask which to continue or if new
@@ -155,6 +157,8 @@ When user selects approach, append the session overview content directly to `{br
 
 Which approach appeals to you most? (Enter 1-4)"
 
+**HALT — wait for user selection before proceeding.**
+
 ### 4. Handle User Selection and Initial Document Append
 
 #### When user selects approach number:

package/src/core/skills/xiaoma-brainstorming/steps/step-01b-continue.md

@@ -63,7 +63,9 @@ Based on session analysis, provide appropriate options:
 **Options:**
 [1] Review Results - Go through your documented ideas and insights
 [2] Start New Session - Begin brainstorming on a new topic
-[3) Extend Session - Add more techniques or explore new angles"
+[3] Extend Session - Add more techniques or explore new angles"
+
+**HALT — wait for user selection before proceeding.**
 
 **If Session In Progress:**
 "Let's continue where we left off!

package/src/core/skills/xiaoma-brainstorming/steps/step-02a-user-selected.md

@@ -40,7 +40,7 @@ Load techniques from CSV on-demand:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Organize by categories for browsing
 
@@ -87,6 +87,8 @@ Show available categories with brief descriptions:
 
 **Which category interests you most? Enter 1-7, or tell me what type of thinking you're drawn to.**"
 
+**HALT — wait for user selection before proceeding.**
+
 ### 3. Handle Category Selection
 
 After user selects category:
@@ -154,6 +156,8 @@ This combination will take approximately [total_time] and focus on [expected out
 [C] Continue - Begin technique execution
 [Back] - Modify technique selection"
 
+**HALT — wait for user selection before proceeding.**
+
 ### 6. Update Frontmatter and Continue
 
 If user confirms:

package/src/core/skills/xiaoma-brainstorming/steps/step-02b-ai-recommended.md

@@ -47,7 +47,7 @@ Load techniques from CSV for analysis:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 
 ### 2. Context Analysis for Technique Matching
@@ -152,6 +152,8 @@ Provide deeper insight into each recommended technique:
 [Details] - Tell me more about any specific technique
 [Back] - Return to approach selection
 
+**HALT — wait for user selection before proceeding.**
+
 ### 6. Handle User Response
 
 #### If [C] Continue:

package/src/core/skills/xiaoma-brainstorming/steps/step-02c-random-selection.md

@@ -47,7 +47,7 @@ Create anticipation for serendipitous technique discovery:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Prepare for intelligent random selection
 
@@ -124,6 +124,8 @@ You're about to experience brainstorming in a completely new way. These unexpect
 [Details] - Tell me more about any specific technique
 [Back] - Return to approach selection
 
+**HALT — wait for user selection before proceeding.**
+
 ### 5. Handle User Response
 
 #### If [C] Continue:

package/src/core/skills/xiaoma-brainstorming/steps/step-02d-progressive-flow.md

@@ -66,7 +66,7 @@ Explain the value of systematic creative progression:
 
 **Load CSV and parse:**
 
-- Read `brain-methods.csv`
+- Read `../brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Map techniques to each phase of the creative journey
 
@@ -176,6 +176,8 @@ Show the full progressive flow with timing and transitions:
 [Details] - Tell me more about any specific phase or technique
 [Back] - Return to approach selection
 
+**HALT — wait for user selection before proceeding.**
+
 ### 4. Handle Customization Requests
 
 If user wants customization:

package/src/core/skills/xiaoma-brainstorming/steps/step-03-technique-execution.md

@@ -290,6 +290,8 @@ After final technique element:
 [B] **Take a quick break** - Pause and return with fresh energy
 [C] **Move to organization** - Only when you feel we've thoroughly explored
 
+**HALT — wait for user selection before proceeding.**
+
 **Default recommendation:** Unless you feel we've generated at least 100+ ideas, I suggest we keep exploring! The best insights often come after the obvious ideas are exhausted.
 
 ### 8. Handle Menu Selection

package/src/core/skills/xiaoma-brainstorming/steps/step-04-idea-organization.md

@@ -249,6 +249,8 @@ Provide final session wrap-up and forward guidance:
 **Ready to complete your session documentation?**
 [C] Complete - Generate final brainstorming session document
 
+**HALT — wait for user selection before proceeding.**
+
 ### 8. Handle Completion Selection
 
 #### If [C] Complete:

package/src/core/skills/xiaoma-brainstorming/workflow.md

@@ -44,11 +44,10 @@ Load config from `{project-root}/_xiaoma/core/config.yaml` and resolve:
 
 All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern.
 - `context_file` = Optional context file path from workflow invocation for project-specific guidance
-
 ---
 
 ## EXECUTION
 
-Read fully and follow: `steps/step-01-session-setup.md` to begin the workflow.
+Read fully and follow: `./steps/step-01-session-setup.md` to begin the workflow.
 
 **Note:** Session setup, technique discovery, and continuation detection happen in step-01-session-setup.md.

package/src/core/skills/xiaoma-distillator/SKILL.md

@@ -75,7 +75,7 @@ After the compressor (or merge compressor) returns:
 
    ```yaml
    ---
-   type: bmad-distillate
+   type: xiaoma-distillate
    sources:
      - "{relative path to source file 1}"
      - "{relative path to source file 2}"