initial doc-index workflow

src/modules/bmm/README.md

@@ -45,6 +45,7 @@ The heart of BMM - structured workflows for the four development phases:
    - `review-story` - Quality validation
    - `correct-course` - Issue resolution
    - `retrospective` - Continuous improvement
+   - `doc-index` - Build/update categorized documentation index (post-doc generation)
 
 ### 👥 `/teams`
 
@@ -76,6 +77,9 @@ bmad dev develop
 
 # Review implementation
 bmad sr review-story
+
+# Build or update documentation index (after docs exist)
+bmad sm doc-index
 ```
 
 ## Key Concepts

src/modules/bmm/agents/sm.agent.yaml

@@ -41,3 +41,11 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml"
       data: "{project-root}/bmad/_cfg/agent-party.xml"
       description: Facilitate team retrospective after epic/sprint
+
+    - trigger: doc-index
+      workflow: "{project-root}/bmad/bmm/workflows/documentation/doc-index/workflow.yaml"
+      description: Build or update categorized documentation index for quick reference
+
+    - trigger: update-doc-index
+      workflow: "{project-root}/bmad/bmm/workflows/documentation/doc-index/workflow.yaml"
+      description: Update documentation index (incremental)

src/modules/bmm/workflows/4-implementation/create-story/instructions.md

@@ -1,6 +1,6 @@
 # Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
 
-```xml
+````xml
 <critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
@@ -16,6 +16,7 @@
   </step>
 
   <step n="2" goal="Discover and load source documents">
+    <action>If doc index exists at {{doc_index_file}}: READ it and parse the Machine Index JSON block (```json doc-index ... ```). Use it to resolve authoritative documents for this epic in priority: PRD (requirements), Architecture (HLA / architecture docs), Design (if relevant), Testing (strategy/standards). Fallback to direct file discovery below if any are missing.</action>
     <action>If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time.</action>
     <action>Build a prioritized document set for this epic:
       1) tech_spec_file (epic-scoped)
@@ -78,4 +79,4 @@
   </step>
 
 </workflow>
-```
+````

src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -21,6 +21,7 @@ variables:
   epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
   prd_file: "{output_folder}/prd.md" # Fallback for requirements
   hla_file: "{output_folder}/high-level-architecture.md" # Optional architecture context
+  doc_index_file: "{project-root}/docs/doc-index.md" # Optional documentation index to accelerate discovery
   tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
   tech_spec_search_dir: "{project-root}/docs"
   tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"

src/modules/bmm/workflows/4-implementation/story-context/instructions.md

@@ -1,6 +1,6 @@
 <!-- BMAD BMM Story Context Assembly Instructions (v6) -->
 
-```xml
+````xml
 <critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>This workflow assembles a Story Context XML for a single user story by extracting ACs, tasks, relevant docs/code, interfaces, constraints, and testing guidance to support implementation.</critical>
@@ -22,7 +22,8 @@
   </step>
 
   <step n="2" goal="Collect relevant documentation">
-    <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks<</action>
+    <action>If doc index exists at {{doc_index_file}}: READ it and parse the Machine Index JSON (```json doc-index ... ```). Use it to quickly pull relevant Requirements (PRD), Architecture (HLA, patterns), Testing & QA (strategy/standards), API (OpenAPI/REST), Data (schema/models) for this story based on title/AC keywords. Fallback to scanning if any are missing.</action>
+    <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks</action>
     <action>Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
     <template-output file="{default_output_file}">
       Add artifacts.docs entries with {path, title, section, snippet} (NO invention)
@@ -73,4 +74,4 @@
   </step>
 
 </workflow>
-```
+````

src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml

@@ -25,6 +25,7 @@ variables:
   tech_spec_search_dir: "{project-root}/docs"
   tech_spec_glob_template: "tech-spec-epic-{{epic_id}}*.md"
   non_interactive: true
+  doc_index_file: "{project-root}/docs/doc-index.md" # Optional documentation index to accelerate discovery
 
 # Output configuration
 default_output_file: "{output_folder}/story-context-{{epic_id}}.{{story_id}}.xml"

src/modules/bmm/workflows/documentation/doc-index/README.md

@@ -0,0 +1,20 @@
+# doc-index Workflow
+
+Builds or updates a categorized, tagged documentation index after agents have generated project documentation. The index helps downstream workflows (e.g., create-story, story-context) quickly locate authoritative docs.
+
+- Output: `docs/doc-index.md`
+- Categories: Architecture, Requirements, Design, Testing & QA, API, Data, Security, Development, Operations, Decisions, Planning, Knowledge, Other
+- Includes a machine-readable `json doc-index` code block at the top.
+
+## Run
+
+```bash
+bmad sm doc-index
+# or the alias
+bmad sm update-doc-index
+```
+
+## Notes
+
+- Safe to rerun anytime; defaults to incremental, but rebuilds full file content for consistency.
+- Workflows `create-story` and `story-context` will preferentially consult this index when present.

src/modules/bmm/workflows/documentation/doc-index/checklist.md

@@ -0,0 +1,20 @@
+<checklist id="bmad/bmm/workflows/documentation/doc-index/checklist">
+  <section title="Discovery">
+    <item>Scans only intended directories (docs and configured output)</item>
+    <item>Respects include/exclude globs and ignores hidden/system folders</item>
+    <item>Skips non-markdown files unless explicitly included</item>
+  </section>
+  <section title="Classification">
+    <item>Each entry has exactly one primary category (archetype)</item>
+    <item>Category assignment follows category_patterns heuristics</item>
+    <item>Tags are concise (1-2 words) and relevant</item>
+    <item>No invented facts in descriptions; derived from content</item>
+  </section>
+  <section title="Output">
+    <item>Index includes Machine Index JSON block (valid JSON)</item>
+    <item>Markdown sections exist for all main archetypes</item>
+    <item>All links are relative and clickable from project root</item>
+    <item>Entries sorted alphabetically within categories</item>
+    <item>Updated timestamp present and accurate</item>
+  </section>
+</checklist>

src/modules/bmm/workflows/documentation/doc-index/instructions.md

@@ -0,0 +1,53 @@
+<!-- BMAD BMM Documentation Index (doc-index) Workflow Instructions -->
+
+````xml
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow scans generated documentation AFTER agents/workflows have produced them, then builds/updates a categorized, tagged Markdown index at {output_file}.</critical>
+<critical>Default: non-interactive, incremental true. Always prefer regeneration over prompts. If discovery fails, HALT with clear message.</critical>
+
+<workflow>
+
+  <step n="1" goal="Resolve inputs and discover candidates">
+    <action>Resolve variables: scan_dirs, include_globs, exclude_globs, output_file, category_patterns, max_desc_words, incremental.</action>
+    <action>For each directory in {{scan_dirs}}: recursively GLOB include_globs then filter out exclude_globs and hidden files. Limit to markdown files (.md, .mdx).</action>
+    <action>Normalize paths to be relative to project root and use forward slashes.</action>
+    <check>HALT if no candidate files found: "No documentation files found under configured scan_dirs"</check>
+  </step>
+
+  <step n="2" goal="Extract metadata and categorize">
+    <action>For each candidate file:
+      - READ the file
+      - Extract title: first level-1 heading (# ...) or first non-empty line
+      - Extract a brief description: summarize opening paragraph or first section to {{max_desc_words}} words (do NOT invent domain facts)
+      - Compute last_updated from file mtime
+      - Infer categories from filename/content using {{category_patterns}} (lowercase filename + headings). Assign the BEST single archetype; if strong signals for several, pick primary and add others as tags
+      - Compute tags: derive from keywords (e.g., api, security, ci, ux, db, testing, nfr, performance, accessibility, mobile, backend, frontend, devops, adr)
+    </action>
+    <action>Build a data record for each file: { path, title, description, category, tags[], last_updated }</action>
+    <action>Keep a deduplicated set by normalized relative path.</action>
+  </step>
+
+  <step n="3" goal="Merge with existing index (if incremental)">
+    <action>If {{incremental}} and {output_file} exists: READ file and locate the Machine Index JSON code block fenced as ```json doc-index ... ```</action>
+    <action>If present, PARSE JSON into priorIndex. Merge: update entries for changed files, add new files, remove entries for missing files under current scan scope. Preserve prior tags if not conflicting. If absent or parse fails, treat as full rebuild.</action>
+  </step>
+
+  <step n="4" goal="Render Markdown index using template">
+    <action>Initialize {output_file} from template if creating new. If updating, rebuild complete content to avoid drift.</action>
+    <action>Write a Machine Index JSON code block at the top using fence label "json doc-index" with schema: { version, generated_at, project_root: "{project-root}", files: [ { path, title, description, category, tags, last_updated } ] }</action>
+    <action>Under each archetype section in the template (Architecture, Requirements, Design, Testing & QA, API, Data, Security, Development, Operations, Decisions, Planning, Knowledge, Other):
+      - Sort entries alphabetically by title
+      - Emit bullets: "- [Title](./relative/path) — short description [tags: tag1, tag2]"
+      - If a category has no entries, leave section with a note "(none indexed)"</action>
+    <action>Place a Tag Glossary at the bottom: List unique tags alphabetically with brief meaning derived from first occurrence context (one short phrase each).</action>
+  </step>
+
+  <step n="5" goal="Validate and save">
+    <invoke-task optional="true">Optionally run helper task at bmad/core/tasks/index-docs.xml for baseline grouping; then prefer doc-index results for final output.</invoke-task>
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <action>Save to {output_file}. Report total indexed files and categories coverage.</action>
+  </step>
+
+</workflow>
+````

src/modules/bmm/workflows/documentation/doc-index/template.md

@@ -0,0 +1,72 @@
+# Project Documentation Index
+
+> Updated: {{generated_at}}
+
+```json doc-index
+{
+  "version": "1.0",
+  "generated_at": "{{generated_at}}",
+  "project_root": "{project-root}",
+  "files": [
+    /* Filled by workflow: array of { path, title, description, category, tags, last_updated } */
+  ]
+}
+```
+
+## Architecture
+
+<!-- architecture entries injected here -->
+
+## Requirements
+
+<!-- requirements entries injected here -->
+
+## Design
+
+<!-- design entries injected here -->
+
+## Testing & QA
+
+<!-- testing entries injected here -->
+
+## API
+
+<!-- api entries injected here -->
+
+## Data
+
+<!-- data entries injected here -->
+
+## Security
+
+<!-- security entries injected here -->
+
+## Development
+
+<!-- development entries injected here -->
+
+## Operations
+
+<!-- operations entries injected here -->
+
+## Decisions
+
+<!-- decisions entries injected here -->
+
+## Planning
+
+<!-- planning entries injected here -->
+
+## Knowledge
+
+<!-- knowledge entries injected here -->
+
+## Other
+
+<!-- uncategorized entries injected here -->
+
+---
+
+## Tag Glossary
+
+<!-- Tag list injected here: - tag: short meaning -->

src/modules/bmm/workflows/documentation/doc-index/workflow.yaml

@@ -0,0 +1,147 @@
+# Documentation Index Workflow
+name: doc-index
+description: "Scan generated documentation and build/update a categorized, tagged Markdown index for quick referencing by workflows"
+author: "BMad"
+
+# Config and environment
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/bmad/bmm/workflows/documentation/doc-index"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Variables and inputs
+variables:
+  scan_dirs: |
+    - "{project-root}/docs"
+    - "{output_folder}"
+  include_globs: |
+    - "**/*.md"
+    - "**/*.mdx"
+  exclude_globs: |
+    - "**/node_modules/**"
+    - "**/.git/**"
+    - "**/dist/**"
+    - "**/build/**"
+    - "**/.cache/**"
+    - "**/.vite/**"
+    - "**/bmad/**"
+    - "**/ide-info/**"
+  output_file: "{project-root}/docs/doc-index.md"
+  incremental: true
+  non_interactive: true
+  max_desc_words: 14
+  # Main archetypes and patterns used for categorization. Patterns are matched
+  # against lowercase filename and content signals.
+  category_patterns:
+    architecture:
+      - "solution-architecture"
+      - "infrastructure-architecture"
+      - "architecture"
+      - "tech-stack"
+      - "backend-architecture"
+      - "frontend-architecture"
+      - "data-models"
+      - "database-schema"
+      - "rest-api-spec"
+      - "external-apis"
+      - "system-context"
+    requirements:
+      - "prd"
+      - "product-requirements"
+      - "requirements"
+      - "brd"
+      - "specification"
+    design:
+      - "brain-storm"
+      - "brainstorm"
+      - "product-brief"
+      - "ux"
+      - "ui"
+      - "wireframe"
+      - "prototype"
+    testing:
+      - "testing-strategy"
+      - "test-strategy"
+      - "qa"
+      - "quality"
+      - "nfr"
+      - "non-functional"
+      - "coverage"
+    api:
+      - "openapi"
+      - "swagger"
+      - "api"
+      - "rest"
+      - "graphql"
+    data:
+      - "database"
+      - "schema"
+      - "er-"
+      - "data-model"
+    security:
+      - "security"
+      - "threat"
+      - "owasp"
+      - "secret"
+      - "auth"
+      - "authorization"
+      - "authentication"
+    development:
+      - "coding-standards"
+      - "contributing"
+      - "developer-guide"
+      - "setup"
+      - "local-dev"
+      - "styleguide"
+    operations:
+      - "devops"
+      - "infrastructure"
+      - "deployment"
+      - "ci"
+      - "cd"
+      - "observability"
+      - "monitoring"
+    decisions:
+      - "adr"
+      - "decision"
+      - "technical-decisions"
+    planning:
+      - "epics"
+      - "roadmap"
+      - "backlog"
+      - "stories"
+    knowledge:
+      - "kb"
+      - "knowledge-base"
+
+# Output
+default_output_file: "{output_file}"
+
+required_tools:
+  - list_files
+  - file_info
+  - read_file
+  - write_file
+  - glob
+  - search_repo
+  - parse_markdown
+
+tags:
+  - docs
+  - indexing
+  - bmad-v6
+  - utilities
+
+execution_hints:
+  interactive: false
+  autonomous: true
+  iterative: true
+
+web_bundle: false