1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
# Workflow to detect and fix documentation drift in the MkDocs Material documentation
# This workflow analyzes the codebase and updates docs/*.md files
# to reflect the latest supported features and syntax.
name: prodigy-mkdocs-drift-detection
mode: mapreduce
# Environment variables for parameterization
env:
# Project configuration
PROJECT_NAME: "Prodigy"
PROJECT_CONFIG: ".prodigy/mkdocs-config.json"
FEATURES_PATH: ".prodigy/mkdocs-analysis/features.json"
# MkDocs-specific settings
DOCS_DIR: "docs"
MKDOCS_CONFIG: "mkdocs.yml"
ANALYSIS_DIR: ".prodigy/mkdocs-analysis"
CHAPTERS_FILE: "workflows/data/mkdocs-chapters.json"
# Workflow settings
MAX_PARALLEL: "3"
# Setup phase: Analyze codebase for feature coverage
setup:
- shell: "mkdir -p $ANALYSIS_DIR"
# Step 1: Analyze codebase for workflow features, command types, and configuration
# Reuses existing feature analysis or creates MkDocs-specific version
- claude: "/prodigy-analyze-features-for-mkdocs --project $PROJECT_NAME --config $PROJECT_CONFIG"
# Step 2: Detect documentation gaps for missing features
# Ensures all major features have documentation pages
# This analyzes features.json against existing docs and creates stub pages for missing features
- claude: "/prodigy-detect-mkdocs-gaps --project $PROJECT_NAME --config $PROJECT_CONFIG --features $FEATURES_PATH --chapters $CHAPTERS_FILE --docs-dir $DOCS_DIR"
commit_required: true
# Step 3: Analyze page sizes and structural complexity
# Identifies oversized pages that should be split into subpages
# Generates structure-report.json with recommendations
- claude: "/prodigy-analyze-mkdocs-structure --project $PROJECT_NAME --docs-dir $DOCS_DIR --pages $CHAPTERS_FILE --output $ANALYSIS_DIR/structure-report.json"
# Step 4: Automatically split all oversized pages into subpages
# This runs BEFORE map phase so agents process optimally-sized pages
# Reads structure-report.json and orchestrates splitting of high-priority pages
- claude: "/prodigy-split-oversized-mkdocs-pages --project $PROJECT_NAME --pages $CHAPTERS_FILE --docs-dir $DOCS_DIR --structure-report $ANALYSIS_DIR/structure-report.json"
commit_required: false
# Step 5: Auto-discover ALL documentation pages (including newly created subpages)
# This ensures we process all pages, not just the curated list in chapters.json
- shell: |
find $DOCS_DIR -name "*.md" -type f -not -path "*/.prodigy/*" | sort | jq -R -s '
split("\n") |
map(select(length > 0)) |
map({
id: (split("/")[-1] | split(".md")[0]),
title: (split("/")[-1] | split(".md")[0] | gsub("-|_"; " ")),
file: .,
type: "auto-discovered",
topics: [],
validation: "Auto-discovered page - check for drift and enhance with visual features"
})
' > $ANALYSIS_DIR/flattened-items.json
commit_required: false
# Map phase: Analyze and fix each documentation page for drift
map:
input: "${ANALYSIS_DIR}/flattened-items.json"
json_path: "$[*]"
agent_template:
# Step 1: Analyze the page for drift (subsection-aware command)
- claude: "/prodigy-analyze-mkdocs-drift --project $PROJECT_NAME --json '${item}' --features $FEATURES_PATH"
commit_required: true
# Step 2: Fix the drift in this page (subsection-aware command)
- claude: "/prodigy-fix-mkdocs-drift --project $PROJECT_NAME --json '${item}'"
commit_required: true
validate:
claude: "/prodigy-validate-mkdocs-page --project $PROJECT_NAME --json '${item}' --output .prodigy/validation-result.json"
result_file: ".prodigy/validation-result.json"
threshold: 100 # Documentation must meet 100% quality standards
on_incomplete:
claude: "/prodigy-complete-mkdocs-fix --project $PROJECT_NAME --json '${item}' --gaps ${validation.gaps}"
max_attempts: 3
fail_workflow: false # Continue even if we can't reach 100%
commit_required: true # Require commit to verify improvements were made
# Step 3: Enhance page with visual features (diagrams, admonitions, annotations)
# This runs per-page so Claude has full context about what the page discusses
- claude: "/prodigy-enhance-mkdocs-page --project $PROJECT_NAME --json '${item}' --auto-fix true"
commit_required: true
max_parallel: ${MAX_PARALLEL}
# Reduce phase: Validate and handle any issues
reduce:
# Rebuild the docs to ensure all pages compile together
- shell: "mkdocs build --strict"
on_failure:
# Only needed if there are build errors (broken links, etc)
claude: "/prodigy-fix-mkdocs-build-errors --project $PROJECT_NAME"
commit_required: true
# Structural validation - detect cross-cutting organizational issues
- claude: "/prodigy-validate-mkdocs-structure --project $PROJECT_NAME --docs-dir $DOCS_DIR --output $ANALYSIS_DIR/structure-validation.json --auto-fix true"
commit_required: true
# Feature consistency check - verify all pages have good feature usage
# Note: Page-level enhancements happen in map phase where agents have context
# This just checks consistency and reports any pages that slipped through
- claude: "/prodigy-validate-feature-consistency --project $PROJECT_NAME --docs-dir $DOCS_DIR --output $ANALYSIS_DIR/feature-consistency.json"
# Mermaid diagram validation - ensure all diagrams have valid syntax
- shell: "mermaid-sonar $DOCS_DIR --strict"
on_failure:
# Fix any invalid Mermaid diagrams found
# Pass validation output to Claude for context
claude: "/prodigy-fix-mermaid-diagrams '${shell.stderr}'"
commit_required: true
# Clean up temporary analysis files (keep structure-report.json and validation reports for review)
- shell: "rm -rf ${ANALYSIS_DIR}/features.json ${ANALYSIS_DIR}/flattened-items.json ${ANALYSIS_DIR}/drift-*.json ${ANALYSIS_DIR}/gap-report.json"
- shell: "git add -A && git commit -m 'chore: remove temporary mkdocs analysis files for ${PROJECT_NAME}' || true"
# Error handling
error_policy:
on_item_failure: dlq
continue_on_failure: true
max_failures: 2
error_collection: aggregate