From 3a0e34a12cd9267fbea4513acbfed6b6d68a0680 Mon Sep 17 00:00:00 2001 From: pbean Date: Wed, 8 Oct 2025 00:08:04 -0700 Subject: [PATCH] initial doc-index workflow --- src/modules/bmm/README.md | 4 + src/modules/bmm/agents/sm.agent.yaml | 8 + .../create-story/instructions.md | 5 +- .../create-story/workflow.yaml | 1 + .../story-context/instructions.md | 7 +- .../story-context/workflow.yaml | 1 + .../documentation/doc-index/README.md | 20 +++ .../documentation/doc-index/checklist.md | 20 +++ .../documentation/doc-index/instructions.md | 53 +++++++ .../documentation/doc-index/template.md | 72 +++++++++ .../documentation/doc-index/workflow.yaml | 147 ++++++++++++++++++ 11 files changed, 333 insertions(+), 5 deletions(-) create mode 100644 src/modules/bmm/workflows/documentation/doc-index/README.md create mode 100644 src/modules/bmm/workflows/documentation/doc-index/checklist.md create mode 100644 src/modules/bmm/workflows/documentation/doc-index/instructions.md create mode 100644 src/modules/bmm/workflows/documentation/doc-index/template.md create mode 100644 src/modules/bmm/workflows/documentation/doc-index/workflow.yaml diff --git a/src/modules/bmm/README.md b/src/modules/bmm/README.md index 4e2a9ec8..1301348c 100644 --- a/src/modules/bmm/README.md +++ b/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 diff --git a/src/modules/bmm/agents/sm.agent.yaml b/src/modules/bmm/agents/sm.agent.yaml index 724d51cc..43a4e517 100644 --- a/src/modules/bmm/agents/sm.agent.yaml +++ b/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) diff --git a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md index 85bd8b5f..e77197a6 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md +++ b/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 The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml 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. @@ -16,6 +16,7 @@ + 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. 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. Build a prioritized document set for this epic: 1) tech_spec_file (epic-scoped) @@ -78,4 +79,4 @@ -``` +```` diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml index eaa76f41..3adc600c 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ b/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" diff --git a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md index 6d4715fd..400914a0 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md @@ -1,6 +1,6 @@ -```xml +````xml The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml 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. @@ -22,7 +22,8 @@ - Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks< + 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. + Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs. Add artifacts.docs entries with {path, title, section, snippet} (NO invention) @@ -73,4 +74,4 @@ -``` +```` diff --git a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml index 2664fca7..f41149bb 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml +++ b/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" diff --git a/src/modules/bmm/workflows/documentation/doc-index/README.md b/src/modules/bmm/workflows/documentation/doc-index/README.md new file mode 100644 index 00000000..a63cedc9 --- /dev/null +++ b/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. diff --git a/src/modules/bmm/workflows/documentation/doc-index/checklist.md b/src/modules/bmm/workflows/documentation/doc-index/checklist.md new file mode 100644 index 00000000..76bb01a0 --- /dev/null +++ b/src/modules/bmm/workflows/documentation/doc-index/checklist.md @@ -0,0 +1,20 @@ + +
+ Scans only intended directories (docs and configured output) + Respects include/exclude globs and ignores hidden/system folders + Skips non-markdown files unless explicitly included +
+
+ Each entry has exactly one primary category (archetype) + Category assignment follows category_patterns heuristics + Tags are concise (1-2 words) and relevant + No invented facts in descriptions; derived from content +
+
+ Index includes Machine Index JSON block (valid JSON) + Markdown sections exist for all main archetypes + All links are relative and clickable from project root + Entries sorted alphabetically within categories + Updated timestamp present and accurate +
+ diff --git a/src/modules/bmm/workflows/documentation/doc-index/instructions.md b/src/modules/bmm/workflows/documentation/doc-index/instructions.md new file mode 100644 index 00000000..7ba13e6b --- /dev/null +++ b/src/modules/bmm/workflows/documentation/doc-index/instructions.md @@ -0,0 +1,53 @@ + + +````xml +The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +This workflow scans generated documentation AFTER agents/workflows have produced them, then builds/updates a categorized, tagged Markdown index at {output_file}. +Default: non-interactive, incremental true. Always prefer regeneration over prompts. If discovery fails, HALT with clear message. + + + + + Resolve variables: scan_dirs, include_globs, exclude_globs, output_file, category_patterns, max_desc_words, incremental. + For each directory in {{scan_dirs}}: recursively GLOB include_globs then filter out exclude_globs and hidden files. Limit to markdown files (.md, .mdx). + Normalize paths to be relative to project root and use forward slashes. + HALT if no candidate files found: "No documentation files found under configured scan_dirs" + + + + 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) + + Build a data record for each file: { path, title, description, category, tags[], last_updated } + Keep a deduplicated set by normalized relative path. + + + + If {{incremental}} and {output_file} exists: READ file and locate the Machine Index JSON code block fenced as ```json doc-index ... ``` + 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. + + + + Initialize {output_file} from template if creating new. If updating, rebuild complete content to avoid drift. + 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 } ] } + 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)" + Place a Tag Glossary at the bottom: List unique tags alphabetically with brief meaning derived from first occurrence context (one short phrase each). + + + + Optionally run helper task at bmad/core/tasks/index-docs.xml for baseline grouping; then prefer doc-index results for final output. + Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml + Save to {output_file}. Report total indexed files and categories coverage. + + + +```` diff --git a/src/modules/bmm/workflows/documentation/doc-index/template.md b/src/modules/bmm/workflows/documentation/doc-index/template.md new file mode 100644 index 00000000..51ad8e58 --- /dev/null +++ b/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 + + + +## Requirements + + + +## Design + + + +## Testing & QA + + + +## API + + + +## Data + + + +## Security + + + +## Development + + + +## Operations + + + +## Decisions + + + +## Planning + + + +## Knowledge + + + +## Other + + + +--- + +## Tag Glossary + + diff --git a/src/modules/bmm/workflows/documentation/doc-index/workflow.yaml b/src/modules/bmm/workflows/documentation/doc-index/workflow.yaml new file mode 100644 index 00000000..21c3010c --- /dev/null +++ b/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