Skip to main content

Ultimate Canonical Kanban Structure

Purpose: Definitive specification for the canonical Kanban E/S/T (Epic/Story/Task) structure
Status: COMPLETE
Version: 2.0.0
Part of: E6:S06:T06 – Cross-project meta-analysis and canonical framework design
Supersedes: v1.0.0

Based on: Comprehensive meta-analysis of 10 projects (9 client implementations + ai-dev-kit source) and user feedback

Executive Summary​

This document defines the ultimate canonical Kanban structure for ADK framework implementations. This is the definitive specification that all projects should adopt.

The Ultimate Canonical Kanban Structure consists of:

  1. Pre-Design Phase (E1): Project foundation, workflow management, versioning
  2. Design Phase (E2-E8): Kanban, FR/BR/UXR, Architecture, Data, Testing, Implementation, Documentation
  3. Ancillary Epics (E9+): CI/CD, Security, and project-specific epics

Key Structure:

  • E1: Project Foundation (Pre-Design) - includes workflow and versioning
  • E2: Kanban Framework (separate epic)
  • E3: FR/BR/UXR Management (consolidated)
  • E4: Architecture Design (comprehensive design specification)
  • E5: Data Management and Database
  • E6: Testing and Quality Assurance (TDD approach)
  • E7: Implementation (includes codebase maintenance and refactoring)
  • E8: Documentation
  • E9: Process Automation and CI/CD
  • E10: Security (enhanced with project security)

Complete Canonical Epic/Story/Task Inventory​

Pre-Design Phase​

Epic 1: Project Foundation and Setup​

Purpose: Pre-design phase foundation work.
Scope: Project setup, workflow management, versioning.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: Project Foundation and Setup

    • T01: Define project structure and directory layout
    • T02: Set up version control and repository configuration
    • T03: Configure development environment and tooling
    • T04: Create initial project documentation (README, CONTRIBUTING, LICENSE)
    • T05: Set up build system and dependency management
    • T06: Configure code quality tools (linters, formatters)
    • T07: Establish coding standards and conventions

  • Story 002: Workflow Management Framework

    • T01: Document existing workflow patterns
    • T02: Define standard workflow templates
    • T03: Create workflow execution guidelines
    • T04: Document workflow integration points
    • T05: Identify automatable workflows
    • T06: Implement workflow automation scripts
    • T07: Create workflow execution tools
    • T08: Document automation usage

  • Story 003: Versioning Framework

    • T01: Define versioning schema (e.g., RC.EPIC.STORY.TASK+BUILD)
    • T02: Document versioning policy
    • T03: Create version file structure
    • T04: Set up version tracking tools
    • T05: Integrate versioning with release workflow
    • T06: Create version bump automation
    • T07: Set up changelog generation
    • T08: Document version management process

Design Phase​

Epic 2: Kanban Framework​

Purpose: Kanban system implementation and governance.
Scope: Kanban policies, templates, intake processes, and Kanban-related tooling.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: Kanban Board Setup

    • T01: Create Kanban board structure
    • T02: Define epic/story/task hierarchy
    • T03: Set up Kanban policies and governance
    • T04: Configure Kanban tooling

  • Story 002: FR/BR Intake Process

    • T01: Design FR/BR intake workflow
    • T02: Create FR/BR templates
    • T03: Implement intake automation
    • T04: Document intake process

Epic 3: FR/BR/UXR Management​

Purpose: Feature Request, Bug Report, and User Experience Research management.
Scope: FR/BR intake, processing, UXR, prioritization.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: FR Intake and Processing

    • T01: Design FR intake workflow
    • T02: Create FR processing automation
    • T03: Integrate FR intake with Kanban
    • T04: Document FR intake process
    • T05: Design FR prioritization framework
    • T06: Create FR planning templates
    • T07: Integrate prioritization with Kanban board
    • T08: Document prioritization process
    • T09: Document FR implementation patterns
    • T10: Create implementation templates
    • T11: Define testing requirements for FRs
    • T12: Document FR completion criteria

  • Story 002: BR Intake and Processing

    • T01: Design BR intake and triage workflow
    • T02: Create BR triage automation
    • T03: Integrate BR intake with Kanban
    • T04: Document BR intake and triage process
    • T05: Design BR prioritization framework
    • T06: Create BR assignment templates
    • T07: Integrate prioritization with Kanban board
    • T08: Document prioritization and assignment process
    • T09: Document bug fix patterns
    • T10: Create bug fix templates
    • T11: Define testing requirements for bug fixes
    • T12: Document bug fix completion criteria

  • Story 003: User Experience Research (UXR)

    • T01: Define research objectives and questions
    • T02: Recruit research participants
    • T03: Conduct user interviews
    • T04: Conduct user surveys/questionnaires
    • T05: Analyze research data and synthesize findings
    • T06: Create user personas
    • T07: Document research findings and insights
    • T08: Design usability test scenarios
    • T09: Recruit test participants
    • T10: Conduct usability testing sessions
    • T11: Analyze usability test results
    • T12: Identify usability issues and pain points
    • T13: Create usability test reports
    • T14: Document usability recommendations
    • T15: Design user feedback collection methods
    • T16: Set up feedback collection channels
    • T17: Implement feedback collection tools
    • T18: Create feedback analysis workflow
    • T19: Analyze feedback patterns and trends
    • T20: Convert feedback into actionable insights
    • T21: Document feedback analysis process
    • T22: Create user journey maps
    • T23: Identify touchpoints and interactions
    • T24: Identify pain points and opportunities
    • T25: Design improved user flows
    • T26: Create experience prototypes
    • T27: Validate experience designs with users
    • T28: Document user journey insights
    • T29: Synthesize research findings across studies
    • T30: Create UX insights reports
    • T31: Develop UX recommendations and action items
    • T32: Prioritize UX improvements
    • T33: Communicate insights to product and engineering teams
    • T34: Track implementation of UX recommendations
    • T35: Document UX insights and learnings

Epic 4: Architecture Design​

Purpose: System architecture design and refactoring.
Scope: Architecture design, patterns, refactoring, technical decisions.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: Comprehensive Architecture Design and Specification

    This story forms the backbone and abstract plan for the design phase. The output should enable any competent programmer/vibe-coder to implement a system that satisfies requirements using the deliverables from E4S01. All tasks follow SOLID software engineering principles.

    • T01: Requirements Engineering

      • Elicit and document functional requirements
      • Elicit and document non-functional requirements
      • Prioritize requirements (MoSCow: must-have, should-have, could-have)
      • Create requirements traceability matrix

    • T02: Use Case Modelling

      • Identify actors and stakeholders
      • Define use cases for all major system interactions
      • Create use case diagrams (UML)
      • Document use case specifications (preconditions, postconditions, main flow, alternate flows, exceptions)
      • Validate use cases with stakeholders

    • T03: Domain Analysis and Noun-Verb Analysis

      • Perform noun-verb analysis of requirements and ADRs
      • Identify domain entities (nouns) and operations (verbs)
      • Create domain model (entity-relationship model)
      • Identify domain boundaries and bounded contexts
      • Document domain vocabulary and glossary

    • T04: Top-Down High-Level System View

      • Create system context diagram
      • Define system boundaries and external interfaces
      • Identify major subsystems and components
      • Create high-level system architecture diagram
      • Document system-level responsibilities and interactions

    • T05: Data Flow Diagrams (DFDs)

      • Create Level 0 (Context) DFD
      • Create Level 1 DFD (major processes)
      • Create Level 2+ DFDs (detailed processes as needed)
      • Document data flows, data stores, and processes
      • Validate data flows with stakeholders

    • T06: UML Design Models

      • Create class diagrams (domain model, design model)
      • Create sequence diagrams for key interactions
      • Create state diagrams for stateful components
      • Create component diagrams (system structure)
      • Create deployment diagrams (if applicable)
      • Create activity diagrams for complex workflows

    • T07: Object and Interface Specifications

      • Define object responsibilities using SOLID principles:
        • Single Responsibility Principle (SRP)
        • Open/Closed Principle (OCP)
        • Liskov Substitution Principle (LSP)
        • Interface Segregation Principle (ISP)
        • Dependency Inversion Principle (DIP)
      • Specify contracts and interfaces for all components
      • Define preconditions, postconditions, and invariants
      • Document interface contracts (input/output specifications)
      • Create interface documentation (API contracts)

    • T08: Architecture Patterns and Design Decisions

      • Select and document architecture patterns (e.g., MVC, Repository, Factory, Strategy)
      • Create architecture decision records (ADRs)
      • Document design rationale and trade-offs
      • Define design constraints and assumptions
      • Document architectural principles and guidelines

    • T09: Integration Points and System Boundaries

      • Define integration points between subsystems
      • Specify external system interfaces
      • Document integration protocols and data formats
      • Define system boundaries and responsibilities
      • Create integration architecture diagrams

    • T10: Design Validation and Review

      • Review design against requirements (traceability)
      • Validate SOLID principles application
      • Conduct design review with stakeholders
      • Validate design completeness and consistency
      • Document design review findings and updates

    • T11: Design Documentation and Deliverables

      • Create comprehensive design specification document
      • Document design assumptions and constraints
      • Create design glossary and terminology
      • Generate design artifacts index
      • Ensure design is implementation-ready (any competent programmer can implement from this)

  • Story 002: Architecture Refactoring

    • T01: Identify architecture improvement opportunities
    • T02: Design refactoring approach
    • T03: Implement architecture refactoring
    • T04: Validate refactored architecture
    • T05: Update architecture documentation
    • T06: Document refactoring learnings

Note: Architecture refactoring stories are in E4. Implementation refactoring stories are in E7.

Epic 5: Data Management and Database​

Purpose: Data management, database design, and data operations.
Scope: Database schema, migrations, data access layer, data validation, data integrity.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: Database Schema Design

    • T01: Design database schema
    • T02: Create entity-relationship diagrams
    • T03: Implement database migrations
    • T04: Set up database indexes
    • T05: Define database constraints
    • T06: Create seed data scripts

  • Story 002: Data Access Layer

    • T01: Design data access architecture
    • T02: Implement repository pattern
    • T03: Create query builders/ORMs
    • T04: Implement data validation
    • T05: Add transaction management
    • T06: Create data access utilities

  • Story 003: Data Migration and Seeding

    • T01: Create migration framework
    • T02: Implement migration scripts
    • T03: Create seed data system
    • T04: Add migration rollback capability
    • T05: Document migration process

Epic 6: Testing and Quality Assurance​

Purpose: Testing infrastructure, test coverage, and quality assurance processes (TDD approach).
Scope: Unit tests, integration tests, E2E tests, test automation, quality metrics.
Status: Core Framework Epic (always installed)

Rationale: Once we have architecture (E4), we can design tests using TDD approach.

Canonical Stories:

  • Story 001: Testing Infrastructure Setup

    • T01: Choose and set up testing framework
    • T02: Configure test runners
    • T03: Set up test data management
    • T04: Create test utilities and helpers
    • T05: Configure test coverage reporting

  • Story 002: Test Design and Implementation (TDD approach)

    • T01: Design test scenarios based on architecture
    • T02: Write unit tests for core functionality
    • T03: Write integration tests
    • T04: Write end-to-end tests
    • T05: Add test fixtures and mocks
    • T06: Implement test data factories

  • Story 003: Test Automation and CI/CD Integration

    • T01: Set up automated test execution
    • T02: Integrate tests with CI/CD pipeline
    • T03: Add test reporting and notifications
    • T04: Set up test coverage thresholds
    • T05: Document testing process

Epic 7: Implementation​

Purpose: Feature implementation, codebase maintenance, and refactoring.
Scope: Feature implementation, code quality, maintenance, implementation refactoring.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: Feature Implementation

    • T01: Implement features based on architecture (E4) and tests (E6)
    • T02: Follow TDD approach (tests first, then implementation)
    • T03: Implement business logic
    • T04: Integrate with data layer (E5)
    • T05: Implement API endpoints (if applicable)
    • T06: Implement UI components (if applicable)
    • T07: Add error handling
    • T08: Add logging

  • Story 002: Codebase Maintenance

    • T01: Set up IDE issue tracking
    • T02: Create maintenance task workflow
    • T03: Define maintenance priorities
    • T04: Document maintenance process
    • T05: Address IDE-flagged issues (errors, warnings, info)
    • T06: Define code review standards
    • T07: Create code review checklist
    • T08: Set up code review automation
    • T09: Document code review process
    • T10: Set up code quality metrics
    • T11: Create quality monitoring dashboards
    • T12: Define quality thresholds
    • T13: Document quality improvement process

  • Story 003: Implementation Refactoring

    • T01: Identify implementation improvement opportunities
    • T02: Design refactoring approach
    • T03: Implement code refactoring
    • T04: Validate refactored code
    • T05: Update implementation documentation
    • T06: Document refactoring learnings

  • Story 004: Post-Implementation Review (PIR)

    • T01: Conduct post-implementation review
    • T02: Document implementation outcomes
    • T03: Identify lessons learned
    • T04: Document best practices
    • T05: Update implementation patterns
    • T06: Share learnings with team

Note:

  • Architecture refactoring is in E4 (Story 002)
  • Implementation refactoring is in E7 (Story 003)

Epic 8: Documentation​

Purpose: Project documentation, user guides, and developer documentation.
Scope: API documentation, user manuals, developer guides, architecture documentation.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: Developer Documentation

    • T01: Create architecture documentation
    • T02: Document code structure and patterns
    • T03: Create setup and installation guides
    • T04: Document development workflow
    • T05: Create contribution guidelines
    • T06: Add code examples and tutorials

  • Story 002: User Documentation

    • T01: Create user manual/guide
    • T02: Document features and functionality
    • T03: Create FAQ section
    • T04: Add troubleshooting guides
    • T05: Create video tutorials (optional)
    • T06: Add in-app help/tooltips

  • Story 003: API Documentation

    • T01: Generate API documentation (OpenAPI/Swagger)
    • T02: Document API endpoints
    • T03: Add API usage examples
    • T04: Create API integration guides
    • T05: Document API versioning

Ancillary Epics​

Epic 9: Process Automation and CI/CD​

Purpose: Establish automated, robust development workflows.
Scope: CI/CD pipelines, pre-commit hooks, automated rule enforcement, testing infrastructure, quality gates.
Status: Core Framework Epic (always installed)

Canonical Stories:

  • Story 001: CI/CD Pipeline Setup

    • T01: Configure build/test pipelines
    • T02: Add artifact publishing
    • T03: Add quality gate enforcement
    • T04: Document pipeline operations

  • Story 002: Automated Rule Enforcement (Pre-commit Hooks)

    • T01: Add formatters/linters to hooks
    • T02: Add changelog/version checks
    • T03: Add policy checks (commit msg, branch rules)
    • T04: Document hook usage

  • Story 003: Testing Infrastructure

    • T01: Define coverage thresholds
    • T02: Add test fixtures and factories
    • T03: Parallelize tests
    • T04: Add flaky-test detection

  • Story 004: Quality Gates and Branch Protection

    • T01: Define protected files and rules
    • T02: Require status checks and reviews
    • T03: Enforce changelog/version checks
    • T04: Monitor gate effectiveness

  • Story 005: Automated Dependency Management

    • T01: Add dependency scanning
    • T02: Automate upgrade PRs
    • T03: Add vulnerability monitoring
    • T04: Document upgrade playbooks

Epic 10: Security​

Purpose: Security measures, vulnerability management, and security best practices.
Scope: Security audits, vulnerability scanning, security policies, encryption, secure coding, project security (Dependabot, etc.).
Status: Ancillary Epic (project-specific, canonical pattern)

Canonical Stories:

  • Story 001: Security Infrastructure

    • T01: Conduct security audit
    • T02: Implement encryption (data at rest/transit)
    • T03: Set up security headers
    • T04: Configure HTTPS/SSL
    • T05: Implement secure session management
    • T06: Add security middleware

  • Story 002: Vulnerability Management

    • T01: Set up vulnerability scanning
    • T02: Implement dependency security checks
    • T03: Set up Dependabot (or equivalent)
    • T04: Create security update process
    • T05: Document security incident response
    • T06: Add security testing

  • Story 003: Security Best Practices

    • T01: Create security policy document
    • T02: Implement secure coding guidelines
    • T03: Add security code review checklist
    • T04: Conduct security training
    • T05: Document security procedures

  • Story 004: Dependabot Management

    • T01: Review Dependabot pull requests
    • T02: Assess dependency update impact
    • T03: Test dependency updates in development environment
    • T04: Merge approved Dependabot updates
    • T05: Address breaking changes from dependency updates
    • T06: Update documentation for dependency changes
    • T07: Monitor and track Dependabot issue resolution
    • T08: Document Dependabot management process

Note: Enhanced to include project security (Dependabot, etc.) in addition to context-specific security.

Design Decisions (Based on User Feedback)​

All questions have been answered and decisions incorporated into the canonical structure:

  1. Epic 1 Scope: ✅ Confirmed - Includes both pre-design phase work and initial project setup
  2. Epic 2 (Kanban): ✅ Confirmed - Kanban is its own separate epic
  3. Epic 3 (FR/BR/UXR): ✅ Confirmed - Consolidated into single epic
  4. Epic 4 (Architecture): ✅ Confirmed - Includes both initial design and refactoring. Future refactoring work can create new E4 stories as needed
  5. Epic 7 (Implementation): ✅ Confirmed - Codebase maintenance stays in E7
  6. Epic 8 (Documentation): ✅ Confirmed
  7. Epic 9 (CI/CD): ✅ Confirmed
  8. Epic 10 (Security): ✅ Confirmed - Combined project security (Dependabot) and context-specific security
  9. Data Management Placement: ✅ Confirmed - E5 (before Testing). Rationale: Architecture (E4) defines system structure → Data Management (E5) implements persistence → Testing (E6) can be designed based on both architecture and data layer
  10. Old E18 (Documentation): ✅ Confirmed - Moved to E8
  11. Old E22 (Architecture Refactoring): ✅ Confirmed - Split between E4 (architecture refactoring) and E7 (implementation refactoring)
  12. Old E23 (CI/CD): ✅ Confirmed - Moved to E9
  13. Remaining Epics: ✅ Confirmed - Renumbered starting at E11 (User Management, API, Frontend, Deployment, Performance, Integration, Analytics, Mobile, Internationalization)

Epic Numbering Summary​

EpicNameStatusNotes
E1Project Foundation (Pre-Design)CoreIncludes workflow and versioning
E2Kanban FrameworkCoreSeparate epic
E3FR/BR/UXR ManagementCoreConsolidated from old E5/E6/E7
E4Architecture DesignCoreComprehensive design specification
E5Data Management and DatabaseCoreFrom old E10
E6Testing and Quality AssuranceCoreTDD approach, from old E13
E7ImplementationCoreIncludes old E8 + implementation refactoring + PIR
E8DocumentationCoreFrom old E18
E9Process Automation and CI/CDCoreFrom old E23
E10SecurityAncillaryEnhanced from old E15
E11+Project-Specific EpicsAncillaryUser Management, API, Frontend, etc.

Directory Structure Specification​

Canonical Path Structure​

docs/project-management/kanban/epics/
├── Epic-1/
│   ├── Epic-1.md
│   ├── Story-001-project-foundation-and-setup/
│   │   └── Story-001-project-foundation-and-setup.md
│   ├── Story-002-workflow-management-framework/
│   │   └── Story-002-workflow-management-framework.md
│   └── Story-003-versioning-framework/
│       └── Story-003-versioning-framework.md
├── Epic-2/
│   ├── Epic-2.md
│   ├── Story-001-kanban-board-setup/
│   │   └── Story-001-kanban-board-setup.md
│   └── Story-002-fr-br-intake-process/
│       └── Story-002-fr-br-intake-process.md
└── ...

Naming Conventions​

Epic Naming​

CANONICAL: Epic-\{N\} (hyphen, e.g., Epic-1, Epic-9)

Epic Numbering:

  • Core Epics: 1-9 (always installed)
  • Ancillary Epics: 10+ (selected based on project needs)
  • Project-Specific: 11+ (not canonical)

Story Naming​

CANONICAL: Story-{NNN}-\{description\} (3-digit padding, kebab-case)

Examples:

  • Story-001-project-foundation-and-setup.md
  • Story-002-workflow-management-framework.md

Task Naming​

CANONICAL: E\{epic\}:S\{story\}:T\{task\} (full context, required, e.g., E6:S06:T01)

Padding: 2-digit (T01, T02, T10)

Validation Rules​

Epic Validation​

Required:

  • Epic naming: Epic-\{N\} format
  • Epic numbering: 1-10 (canonical) or 11+ (project-specific)
  • Epic directory: docs/project-management/kanban/epics/Epic-\{N\}/
  • Epic document: Epic-\{N\}.md exists
  • Story checklist present in Epic document

Story Validation​

Required:

  • Story naming: Story-{NNN}-\{description\} format (3-digit padding)
  • Story directory: Story-{NNN}-\{description\}/ exists
  • Story document: Story-{NNN}-\{description\}.md exists
  • Task checklist present in Story document

Task Validation​

Required:

  • Task naming: E\{epic\}:S\{story\}:T\{task\} format (full context, 2-digit padding)
  • Task structure includes required fields (Status, Input, Deliverable, Acceptance Criteria)

Critical Requirements​

Epic 9 Mismatch Fix​

CRITICAL: ai-dev-kit source Epic 9 "Book Related Work" must be renamed to Epic 24+ (project-specific range)

Current (WRONG):

  • Epic 9: "Book Related Work" (project-specific)

Canonical (CORRECT):

  • Epic 9: "Process Automation and CI/CD" (canonical)

Action Required:

  • Rename ai-dev-kit's Epic 9 to Epic 24+
  • Update all Epic 9 references
  • Ensure canonical Epic 9 template matches "Process Automation and CI/CD"

Installer Validation​

CRITICAL: Installer must validate canonical epics installation and prevent Epic mashup

Validation Rules:

  • Check for Epic 9 "Book Related Work" (should be Epic 24+)
  • Validate that canonical epics match templates
  • Warn if ai-dev-kit's actual Kanban structure detected

Clear Separation​

CRITICAL: Clear separation between canonical templates and ai-dev-kit's actual Kanban

Requirements:

  • Canonical templates in packages/frameworks/kanban/templates/
  • ai-dev-kit's actual Kanban in docs/project-management/kanban/epics/
  • Clear documentation of distinction

Implementation​

Installation​

CANONICAL METHOD: Use installer (install_kanban_framework.py)

Installation Steps:

  1. Run installer: python packages/frameworks/kanban/scripts/install_kanban_framework.py
  2. Select canonical epics to install
  3. Installer validates and installs canonical structure
  4. Installer prevents Epic mashup

DO NOT: Manually copy ai-dev-kit's actual Kanban structure (causes Epic mashup)

Last Updated: 2025-12-18
Version: 2.0.0
Status: COMPLETE