Skip to main content

Meta-Analysis: Workflows

Purpose: Synthesize workflow structure analysis into comprehensive meta-analysis for "ultimate" canonical workflow structure
Analysis Date: 2025-12-17
Status: COMPLETE
Version: 1.0.0
Part of: E6:S06:T06 – Cross-project meta-analysis and canonical framework design

Executive Summary​

This document provides comprehensive meta-analysis of workflow structures across all 10 analyzed projects (9 client implementations + ai-dev-kit source), synthesizing:

  • Workflow structure analysis
  • Pattern frequency tables
  • Convergence/divergence maps
  • Canonical vs legacy matrices

Key Findings:

  • Moderate convergence on RW trigger adoption (50%, ai-dev-kit has workflow YAML but no cursorrules)
  • Low adoption of config-driven approach (30%, ai-dev-kit has example only)
  • CRITICAL gap: Branch safety check adoption is low (40%)
  • Moderate convergence on 11-step/12-step RW (50%)

Data Sources:

  • workflow-structure-analysis.md - Granular workflow analysis
  • meta-analysis-pattern-frequency-tables.md - Pattern frequency data
  • meta-analysis-convergence-divergence-maps.md - Convergence/divergence analysis
  • meta-analysis-canonical-vs-legacy-matrices.md - Canonical vs legacy comparison
  • 10 project analysis reports (9 client implementations + ai-dev-kit source)

1. Synthesis: Workflow File Patterns​

1.1 File Naming Convergence​

YAML Workflow Files:

  • Format: \{name\}-workflow.yaml (canonical)
  • Frequency: 30% (3/10 projects)
  • Alternative: \{name\}.yaml - 20% (2/10 projects)
  • Status: ⚠️ Moderate convergence

Script-Based Workflows:

  • Format: .py/.sh scripts
  • Frequency: 20% (2/10 projects)
  • Status: ⚠️ Legacy pattern

Embedded Workflows:

  • Format: RW trigger in .cursorrules
  • Frequency: 50% (5/10 projects, ai-dev-kit has workflow YAML but no cursorrules)
  • Status: ⚠️ Moderate convergence

Key Insight: YAML workflow files are canonical (30%), but embedded RW trigger is more common (50%). Note: ai-dev-kit (source) has workflow YAML but no .cursorrules file.

1.2 File Location Convergence​

Framework Package Location:

  • Path: packages/frameworks/workflow mgt/workflows/
  • Frequency: 30% (3/10 projects)
  • Status: ⚠️ ADK pattern

Project Root Location:

  • Path: workflows/
  • Frequency: 20% (2/10 projects)
  • Status: ⚠️ Project-specific pattern

Key Insight: File location patterns diverge, requiring flexible support.

2. Synthesis: Release Workflow Patterns​

2.1 Step Count Convergence​

12-Step RW (Canonical):

  • Frequency: 20% (2/10 projects)
  • Projects: ai-dev-kit, agentic-ide-rules
  • Status: ⚠️ Low adoption

11-Step RW:

  • Frequency: 30% (3/10 projects)
  • Projects: been-there, dev-toolkit, confidentia
  • Status: ⚠️ Moderate adoption (before Step 6 added)

10-Step RW:

  • Frequency: 10% (1/10 projects)
  • Projects: starborn_legacy
  • Status: ⚠️ Custom pattern

13-Step RW:

  • Frequency: 10% (1/10 projects)
  • Projects: agentic-ide-rules (extended with PDCA)
  • Status: ⚠️ Extended pattern

No RW Trigger:

  • Frequency: 40% (4/10 projects)
  • Projects: fynd.deals, free-party-promoter, vwmp, qa-kb
  • Status: ❌ CRITICAL GAP

Key Insight: RW step count varies significantly (10-step to 13-step), but 11-step/12-step combined is 56% (moderate convergence).

2.2 Branch Safety Check Convergence​

Branch Safety Check Present:

  • Frequency: 40% (4/10 projects)
  • Status: ❌ CRITICAL GAP - Low adoption
  • Impact: CRITICAL - Prevents cross-epic contamination

Branch Safety Check Missing:

  • Frequency: 50% (5/10 projects)
  • Status: ❌ CRITICAL GAP

Key Insight: Branch safety check adoption is low (44%), requiring immediate promotion.

2.3 Configuration Convergence​

Config-Driven (rw-config.yaml):

  • Frequency: 30% (3/10 projects)
  • Projects: been-there, dev-toolkit, agentic-ide-rules
  • Status: ⚠️ Low adoption

Hardcoded Paths:

  • Frequency: 20% (2/10 projects)
  • Projects: fynd.deals, confidentia (some)
  • Status: ⚠️ Legacy pattern

No Configuration:

  • Frequency: 40% (4/10 projects)
  • Projects: starborn_legacy, free-party-promoter, vwmp, qa-kb
  • Status: ⚠️ No workflow adoption

Key Insight: Config-driven approach adoption is low (33%), requiring promotion.

3. Synthesis: Workflow Execution Patterns​

3.1 Execution Pattern Convergence​

Agent-Driven (ANALYZE → DETERMINE → EXECUTE → VALIDATE → PROCEED):

  • Frequency: 50% (5/10 projects)
  • Status: ⚠️ Moderate convergence
  • Rationale: ADK canonical pattern, intelligent execution

Script-Based:

  • Frequency: 20% (2/10 projects)
  • Status: ⚠️ Legacy pattern

Manual:

  • Frequency: 20% (2/10 projects)
  • Status: ⚠️ No workflow adoption

Key Insight: Agent-driven execution is canonical (56%), but script-based and manual patterns exist.

3.2 Progress Tracking Convergence​

Cursor TODOs:

  • Frequency: 50% (5/10 projects)
  • Status: ⚠️ Moderate convergence
  • Rationale: ADK canonical pattern, user visibility

Manual Tracking:

  • Frequency: 40% (4/10 projects)
  • Status: ⚠️ No TODO tracking

Key Insight: Cursor TODO tracking adoption is moderate (56%), requiring promotion.

3.3 Validation Convergence​

Validation Present:

  • Frequency: 50% (5/10 projects)
  • Status: ⚠️ Moderate convergence
  • Validators: Branch context, changelog format

Validation Missing:

  • Frequency: 40% (4/10 projects)
  • Status: ⚠️ No validation

Key Insight: Validation adoption is moderate (56%), requiring promotion.

4. Critical Issues Identified​

4.1 Branch Safety Check Adoption (CRITICAL)​

Frequency: 44% adoption (4/9 projects)
Impact: CRITICAL - Prevents cross-epic contamination
Root Cause: Branch safety check not enforced, benefits not documented

Promotion Strategy:

  1. Enforce branch safety check in RW (mandatory, blocking)
  2. Document benefits and risks
  3. Provide examples of contamination prevention
  4. Make branch safety check part of installation

4.2 Config-Driven Approach Adoption (HIGH)​

Frequency: 33% adoption (3/9 projects)
Impact: HIGH - Hardcoded paths reduce flexibility
Root Cause: Config benefits not documented, migration path unclear

Promotion Strategy:

  1. Document config benefits (flexibility, maintainability)
  2. Provide migration guide from hardcoded paths
  3. Make config part of installation
  4. Show examples of config-driven customization

4.3 RW Trigger Adoption (HIGH)​

Frequency: 56% adoption (5/9 projects), 44% missing
Impact: HIGH - No standardized release workflow
Root Cause: RW trigger not part of installation, benefits not documented

Promotion Strategy:

  1. Document RW trigger benefits
  2. Provide examples and templates
  3. Make RW trigger part of installation
  4. Show standardized release process

5. Recommendations for "Ultimate" Canonical Workflow Structure​

5.1 Workflow File Structure​

Recommended: YAML Workflow Files

  • Format: {workflow-name}-workflow.yaml
  • Location: workflows/ directory (project root) or packages/frameworks/workflow mgt/workflows/ (framework)
  • Legacy Support: Support \{name\}.yaml format, script-based workflows (.py/.sh)

Rationale:

  • YAML workflow files are canonical (33%)
  • Embedded RW trigger is more common (56%), but YAML files provide better structure
  • Support legacy script-based workflows during migration

5.2 Release Workflow Structure​

Recommended: 12-Step RW (Canonical)

Required Steps:

  1. 🚨 MANDATORY BLOCKING: Branch Safety Check - CRITICAL: Prevents cross-epic contamination
  2. Bump Version - Update version file
  3. Create Detailed Changelog - Generate detailed changelog
  4. Update Main Changelog - Add summary entry
  5. Update README - Update version badge (optional)
  6. Update BR/FR Docs - Document fix attempts (optional)
  7. Auto-update Kanban Docs - Update Epic/Story docs with version markers
  8. Stage Files - Stage all modified files
  9. Run Validators - Execute branch context and changelog format validators
  10. Commit Changes - Create git commit with versioned message
  11. Create Git Tag - Create annotated tag
  12. Push to Remote - Push branch and tags

Optional Steps: 13. PDCA Verification - Optional CHECK phase 14. Summary - Optional ACT phase

Legacy Support:

  • Support 10-step/11-step RW variants
  • Support 13-step RW with PDCA extension

Rationale:

  • 12-step RW is canonical (22% adoption, but ADK standard)
  • 11-step/12-step combined is 56% (moderate convergence)
  • Support legacy step counts during migration

5.3 Configuration Structure​

Recommended: Config-Driven Approach

Config File: rw-config.yaml

Required Config:

version_file: src/{project}/version.py
main_changelog: CHANGELOG.md
changelog_dir: docs/changelog-and-release-notes/changelog-archive
scripts_path: packages/frameworks/workflow mgt/scripts
readme_file: README.md

Optional Config:

use_kanban: true
kanban_root: docs/project-management/kanban
epic_doc_pattern: epics/Epic-{epic}/Epic-{epic}.md
story_doc_pattern: epics/Epic-{epic}/Story-{story}-*.md

Legacy Support:

  • Support hardcoded paths during migration
  • Support projects without config (fallback to defaults)

Rationale:

  • Config-driven approach is canonical (33% adoption, but ADK standard)
  • Provides flexibility and maintainability
  • Support hardcoded paths during migration

5.4 Execution Pattern​

Recommended: Agent-Driven Execution

Pattern: ANALYZE → DETERMINE → EXECUTE → VALIDATE → PROCEED

Progress Tracking:

  • Required: Cursor TODOs for all steps
  • Rationale: User visibility, agent organization, error recovery

Atomicity:

  • Required: Complete all steps or explicitly abort
  • Rationale: Prevents partial releases, maintains consistency

Legacy Support:

  • Support script-based execution
  • Support manual execution

Rationale:

  • Agent-driven execution is canonical (56% adoption)
  • Provides intelligent execution, user visibility
  • Support legacy execution patterns during migration

5.5 Validation Structure​

Recommended: Required Validation

Validators:

  • Branch Context: validate_branch_context.py --strict
  • Changelog Format: validate_changelog_format.py

Rationale:

  • Validation adoption is moderate (56%)
  • Prevents invalid releases, maintains quality
  • Support optional validation during migration

6. Summary: "Ultimate" Canonical Workflow Structure​

6.1 File Structure​

  • Format: {workflow-name}-workflow.yaml
  • Location: workflows/ directory (project root) or framework location
  • Legacy Support: \{name\}.yaml, script-based workflows

6.2 Release Workflow​

  • Step Count: 12 steps (canonical) + 2 optional steps
    • Reference Implementation: ai-dev-kit source has comprehensive 12-step workflow YAML definitions
  • Step 1: Branch Safety Check (mandatory, blocking) - CRITICAL
  • Steps 2-12: Standard RW steps
  • Legacy Support: 10-step/11-step/13-step variants
  • Note: ai-dev-kit source demonstrates workflow YAML structure but lacks .cursorrules file (should be added)

6.3 Configuration​

  • Config File: rw-config.yaml (config-driven approach)
  • Required Config: Version file, changelog paths, scripts path
  • Optional Config: Kanban integration, custom patterns
  • Legacy Support: Hardcoded paths during migration

6.4 Execution​

  • Pattern: Agent-driven (ANALYZE → DETERMINE → EXECUTE → VALIDATE → PROCEED)
  • Progress Tracking: Cursor TODOs (required)
  • Atomicity: Complete all steps or abort (required)
  • Legacy Support: Script-based, manual execution

6.5 Validation​

  • Required: Branch context validation, changelog format validation
  • Legacy Support: Optional validation during migration

7. Next Steps​

This workflow structure meta-analysis informs:

  • Ultimate Canonical Workflow Structure Design (final deliverable)
  • Framework Hardening Recommendations (in good/bad practice catalog)

See Also:

  • workflow-structure-analysis.md - Source granular analysis
  • meta-analysis-pattern-frequency-tables.md - Pattern frequency data
  • meta-analysis-convergence-divergence-maps.md - Convergence/divergence analysis
  • meta-analysis-canonical-vs-legacy-matrices.md - Canonical vs legacy comparison

Last Updated: 2025-12-17
Version: 1.0.0
Status: COMPLETE