Skip to main content

ADK Implementation Patterns Catalog

Purpose: Comprehensive catalog of implementation patterns (good and bad) identified across all ADK implementations
Analysis Date: 2025-12-18
Status: COMPLETE
Version: 1.0.0
Part of: E6:S06:T01 – Comprehensive ADK implementation analysis across all projects

Data Sources:

  • 10 project analysis reports (9 client implementations + ai-dev-kit source)
  • Meta-analysis: Good/Bad Practice Catalog
  • Meta-analysis: Pattern/Anti-Pattern Identification
  • Pattern frequency tables

Executive Summary​

This catalog documents implementation patterns identified across all 10 analyzed projects (9 client implementations + ai-dev-kit source). Patterns are organized by framework dimension (Kanban, docs/documentation, workflows, cursorrules) and include frequency data, impact assessment, and examples.

Key Patterns:

  • Perfect Patterns (100%): 2 (KB directory naming, E/S/T hierarchy)
  • Strong Patterns (60-90%): 3 (task naming 60%, story checklists 90%, document frontmatter 90%)
  • Critical Anti-Patterns: 3 (Epic mashup 30%, Epic 9 mismatch, missing cursorrules in source)

1. Kanban Framework Patterns​

1.1 Good Patterns ✅​

Pattern 1.1: Full-Context Task Naming (E\{epic\}:S\{story\}:T\{task\})​

Frequency: 60% (6/10 projects)
Impact: HIGH - Excellent traceability
Status: ✅ CANONICAL PATTERN

Description:

  • Tasks use full context format: E\{epic\}:S\{story\}:T\{task\} (e.g., E6:S06:T01)
  • Provides complete context without navigation
  • Enables easy cross-referencing

Examples:

  • been-there: E1:S01:T01 format consistently
  • dev-toolkit: E6:S06:T01 format
  • agentic-ide-rules: E1:S01:T01 format
  • ai-dev-kit: Full-context naming throughout

Why It's a Pattern:

  • Strong convergence (60%)
  • Excellent traceability
  • Supports automated tooling
  • Makes task identification unambiguous

Reference Implementation: ai-dev-kit source uses full-context task naming consistently

Pattern 1.2: Perfect E/S/T Hierarchy​

Frequency: 100% (10/10 projects)
Impact: HIGH - Perfect convergence
Status: ✅ CANONICAL PATTERN

Description:

  • All projects use Epic → Story → Task hierarchy
  • Consistent nesting: epics/Epic-\{N\}/Story-{NNN}/Task-{YYY}.md
  • Clear parent-child relationships

Why It's a Pattern:

  • Perfect convergence (100% adoption)
  • Provides clear organizational structure
  • Enables hierarchical navigation
  • Supports automated tooling

Reference Implementation: All projects demonstrate perfect E/S/T hierarchy

Pattern 1.3: Story Checklist Pattern​

Frequency: 90% (9/10 projects)
Impact: HIGH - Excellent progress tracking
Status: ✅ STRONG PATTERN

Description:

  • Story checklists in Epic documents
  • Version markers: ✅ COMPLETE (v0.N.NNN.T+B)
  • Status tracking: TODO, IN PROGRESS, COMPLETE

Why It's a Pattern:

  • Strong convergence (90%)
  • Provides quick overview of story progress
  • Enables version tracking
  • Makes epic-level progress visible

Reference Implementation: ai-dev-kit source uses story checklists consistently

1.2 Bad Patterns ❌​

Anti-Pattern 1.1: Epic Mashup​

Frequency: 30% (3/10 projects)
Impact: CRITICAL - Causes framework drift
Status: ❌ CRITICAL ANTI-PATTERN

Description:

  • Projects copying ai-dev-kit's actual Kanban structure instead of using canonical templates
  • Results in inappropriate epics (e.g., "Book Related Work" in non-book projects)
  • Epic numbering conflicts with canonical structure

Affected Projects:

  • been-there
  • dev-toolkit
  • agentic-ide-rules

Root Cause:

  • Epic 9 mismatch in ai-dev-kit source ("Book Related Work" vs canonical "User Management and Authentication")
  • Unclear installation instructions
  • No installer validation

Prevention:

  • Fix Epic 9 mismatch in ai-dev-kit source
  • Add installer validation
  • Clearly distinguish templates from actual Kanban

Anti-Pattern 1.2: Epic 9 Mismatch in Source​

Frequency: 1 project (ai-dev-kit source)
Impact: CRITICAL - Root cause of Epic mashup
Status: ❌ CRITICAL ANTI-PATTERN

Description:

  • ai-dev-kit's Epic 9 "Book Related Work" conflicts with canonical Epic 9 "User Management and Authentication"
  • Projects copying ai-dev-kit's actual Kanban get wrong Epic 9
  • Causes Epic mashup in 30% of client projects

Required Action:

  • Rename ai-dev-kit's Epic 9 to Epic 24+ (project-specific range)
  • Update all Epic 9 references
  • Document as project-specific, not canonical

2. docs/documentation Framework Patterns​

2.1 Good Patterns ✅​

Pattern 2.1: Perfect KB Directory Naming (docs/)​

Frequency: 100% (10/10 projects)
Impact: HIGH - Perfect convergence
Status: ✅ CANONICAL PATTERN

Description:

  • All projects use docs/ as root directory for knowledge base
  • Perfect convergence across all analyzed projects
  • Universal pattern, no exceptions

Why It's a Pattern:

  • Perfect convergence (100% adoption)
  • Universal pattern
  • Clear and concise
  • Easy to identify knowledge base

Reference Implementation: All projects use docs/ directory naming

Pattern 2.2: Document Frontmatter​

Frequency: 90% (9/10 projects)
Impact: HIGH - Excellent metadata management
Status: ✅ STRONG PATTERN

Description:

  • YAML frontmatter with lifecycle metadata
  • Required fields: lifecycle, created_at
  • Optional fields: ttl_days, expires_at, housekeeping_policy

Why It's a Pattern:

  • Strong convergence (90%)
  • Enables document lifecycle management
  • Supports automated housekeeping
  • Provides document metadata

Reference Implementation: ai-dev-kit source uses frontmatter consistently

2.2 Bad Patterns ❌​

Anti-Pattern 2.1: Missing Lifecycle Metadata​

Frequency: 40% (4/10 projects)
Impact: MEDIUM - Poor document management
Status: ❌ MODERATE ANTI-PATTERN

Description:

  • Documents missing lifecycle metadata
  • Cannot track document expiration
  • No automated housekeeping

Prevention:

  • Make lifecycle metadata required
  • Provide templates
  • Demonstrate benefits

3. Workflow Framework Patterns​

3.1 Good Patterns ✅​

Pattern 3.1: Config-Driven Approach​

Frequency: 30% (3/10 projects)
Impact: HIGH - Best practice
Status: ✅ RECOMMENDED PATTERN

Description:

  • Using rw-config.yaml for workflow configuration
  • Config-driven instead of hardcoded paths
  • Enables customization without code changes

Why It's a Pattern:

  • Best practice (even if only 30% adoption)
  • Enables customization
  • Reduces hardcoded paths
  • Supports multiple project structures

Reference Implementation: ai-dev-kit source has rw-config.yaml example

Promotion Needed: Increase adoption from 30% to 100%

3.2 Bad Patterns ❌​

Anti-Pattern 3.1: Hardcoded Paths​

Frequency: 50% (5/10 projects)
Impact: MEDIUM - Poor customization
Status: ❌ MODERATE ANTI-PATTERN

Description:

  • Hardcoded paths in .cursorrules instead of using rw-config.yaml
  • Cannot customize without editing .cursorrules
  • Breaks when project structure changes

Prevention:

  • Promote config-driven approach
  • Better documentation
  • Simpler examples

Anti-Pattern 3.2: Missing Validation​

Frequency: 20% (2/10 projects)
Impact: HIGH - Risk of invalid releases
Status: ❌ MODERATE ANTI-PATTERN

Description:

  • Skipping branch safety checks
  • Missing changelog format validation
  • Risk of invalid releases

Prevention:

  • Enforce validation in workflows
  • Make validation mandatory
  • Document validation requirements

4. Cursorrules Framework Patterns​

4.1 Good Patterns ✅​

Pattern 4.1: Comprehensive RW Trigger Section​

Frequency: 20% (2/10 projects)
Impact: HIGH - Best practice
Status: ✅ RECOMMENDED PATTERN

Description:

  • Comprehensive 12-step RW trigger section in .cursorrules
  • All steps defined with detailed descriptions
  • Mandatory branch safety check (Step 1)
  • Progress tracking with Cursor TODOs

Why It's a Pattern:

  • Best practice (even if only 20% adoption)
  • Provides intelligent execution
  • User visibility
  • Config-driven approach

Reference Implementation: agentic-ide-rules demonstrates comprehensive 12-step RW trigger

Promotion Needed: Increase adoption from 20% to 100%

4.2 Bad Patterns ❌​

Anti-Pattern 4.1: Missing Cursorrules File​

Frequency: 1 project (ai-dev-kit source)
Impact: HIGH - Cannot demonstrate framework
Status: ❌ CRITICAL ANTI-PATTERN

Description:

  • ai-dev-kit source missing .cursorrules file
  • Cannot demonstrate own cursorrules framework
  • Source doesn't serve as reference implementation

Required Action:

  • Add .cursorrules file to ai-dev-kit source
  • Include comprehensive RW trigger section
  • Serve as reference implementation

5. Pattern Summary​

5.1 Perfect Patterns (100% Convergence)​

PatternFrameworkFrequencyStatus
KB directory naming (docs/)docs/documentation100%✅ Canonical
E/S/T hierarchyKanban100%✅ Canonical

5.2 Strong Patterns (60-90% Convergence)​

PatternFrameworkFrequencyStatus
Full-context task namingKanban60%✅ Strong
Story checklist patternKanban90%✅ Strong
Document frontmatterdocs/documentation90%✅ Strong
PatternFrameworkFrequencyStatus
Config-driven approachWorkflows30%✅ Recommended
Comprehensive RW triggerCursorrules20%✅ Recommended

5.4 Critical Anti-Patterns​

Anti-PatternFrameworkFrequencyImpact
Epic mashupKanban30%CRITICAL
Epic 9 mismatch in sourceKanban1 projectCRITICAL
Missing cursorrules in sourceCursorrules1 projectHIGH
Hardcoded pathsWorkflows50%MEDIUM
Missing validationWorkflows20%MEDIUM

6. Pattern Adoption Recommendations​

6.1 Promote to Canonical (100% Adoption)​

  • ✅ KB directory naming (docs/) - Already canonical
  • ✅ E/S/T hierarchy - Already canonical

6.2 Promote to Strong Pattern (60-90% → 100%)​

  • Full-context task naming (60% → 100%)
  • Story checklist pattern (90% → 100%)
  • Document frontmatter (90% → 100%)

6.3 Promote Recommended Patterns (20-30% → 100%)​

  • Config-driven approach (30% → 100%)
  • Comprehensive RW trigger (20% → 100%)

6.4 Eliminate Anti-Patterns​

  • Fix Epic 9 mismatch in source (CRITICAL)
  • Add cursorrules to source (HIGH)
  • Reduce hardcoded paths (50% → 0%)
  • Enforce validation (20% → 0%)
  • Good/Bad Practice Catalog: meta-analysis-good-bad-practices.md
  • Pattern/Anti-Pattern Identification: meta-analysis-patterns-anti-patterns.md
  • Pattern Frequency Tables: meta-analysis-pattern-frequency-tables.md
  • Convergence/Divergence Maps: meta-analysis-convergence-divergence-maps.md
  • Project Analysis Reports: projects/*-adk-analysis.md

Last Updated: 2025-12-18T00:00:00Z
Version: 1.0.0
Status: COMPLETE