Skip to main content

Modularity Principles and Boundaries

Task: E1:S02:T02 – Document modularity principles and boundaries
Date: 2025-12-02
Status: ✅ COMPLETE

Executive Summary​

This document establishes the modularity principles and boundaries for the ai-dev-kit repository's framework packages. It defines what "modular" means for this dev-kit, establishes clear boundaries between packages, documents copy vs reference patterns, and defines dependency rules.

Key Principles:

  • Standalone First: Each package must be usable independently
  • Copy, Don't Reference: Packages are copied into projects, not referenced
  • Soft Dependencies: Dependencies between packages are optional, not required
  • Clear Boundaries: Each package has a well-defined scope and responsibility

1. What "Modular" Means for ai-dev-kit​

1.1 Core Definition​

Modularity in the context of ai-dev-kit means:

  1. Standalone Capability: Each framework package can be used independently without requiring other packages from the dev-kit
  2. Self-Contained: Each package includes all necessary documentation, policies, templates, and tools to function independently
  3. Flexible Consumption: Users can choose to use one, two, or all three packages based on their needs
  4. Clear Boundaries: Each package has a well-defined scope and responsibility with minimal overlap

1.2 Modularity Goals​

The dev-kit's modularity design aims to:

  • Maximize User Flexibility: Allow users to adopt only what they need
  • Minimize Adoption Friction: Make it easy to start with a single package
  • Enable Incremental Adoption: Allow users to add more packages over time
  • Maintain Package Independence: Ensure packages don't break when used alone

1.3 Independence Metrics​

A package is considered "modular" if it:

  • ✅ Can be copied and used without other dev-kit packages
  • ✅ Has no hard runtime dependencies on other dev-kit packages
  • ✅ Includes all necessary documentation and examples
  • ✅ Has clear customization boundaries
  • ✅ Documents optional integration points

Independence Score: Based on analysis (T001), all three packages score 9-10/10 for independence.

2. Package Boundaries​

2.1 Workflow Management Package​

Scope:

  • Release Workflow (RW) trigger and execution
  • Agent-driven workflow execution methodology
  • Workflow validation scripts
  • Cursor rules integration

Boundaries:

  • Includes: Versioning policy documents (for RW to work)
  • Excludes: Kanban-specific features (handled by Kanban package)
  • Optional Integration: Can integrate with Kanban for automatic updates

Responsibility:

  • Owns workflow execution patterns
  • Owns RW trigger mechanism
  • Owns validation scripts for workflows

What It Doesn't Own:

  • Kanban board structure (Kanban package)
  • Versioning strategy details (Numbering & Versioning package)
  • FR/BR intake flow (Kanban package)

2.2 Numbering & Versioning Package​

Scope:

  • Versioning policy and strategy
  • Version schema definition (RC.EPIC.STORY.TASK+BUILD)
  • Implementation guides
  • Templates (Epic, Story)

Boundaries:

  • Includes: Complete versioning documentation
  • Excludes: Workflow execution (Workflow Management package)
  • Excludes: Kanban governance (Kanban package, though includes versioning aspects)

Responsibility:

  • Owns versioning schema definition
  • Owns versioning strategy and policies
  • Owns versioning implementation guides

What It Doesn't Own:

  • Workflow execution (Workflow Management package)
  • Kanban board structure (Kanban package)
  • FR/BR intake (Kanban package)

2.3 Kanban Package​

Scope:

  • Kanban governance policy
  • Epic/Story/Task templates
  • FR/BR intake flow
  • Integration with versioning and workflows

Boundaries:

  • Includes: Complete Kanban system documentation
  • Includes: Integration guides (for optional integration with other packages)
  • Excludes: Workflow execution details (Workflow Management package)
  • Excludes: Versioning schema definition (Numbering & Versioning package)

Responsibility:

  • Owns Kanban governance and structure
  • Owns FR/BR → Task → Story → Epic flow
  • Owns Kanban templates
  • Owns integration documentation

What It Doesn't Own:

  • Workflow execution (Workflow Management package)
  • Versioning schema (Numbering & Versioning package)

3. Copy vs Reference Patterns​

3.1 Copy, Don't Reference​

Core Principle: Packages are copied into projects, not referenced as external dependencies.

Why Copy?

  1. Customization: Each project needs to customize paths, schemas, and examples
  2. Independence: Projects shouldn't depend on external repositories
  3. Version Control: Projects need to version their own copies
  4. Flexibility: Projects can adapt packages to their specific needs

What Gets Copied:

  • All package files (documentation, templates, scripts)
  • Directory structure (adapted to project structure)
  • Policy documents (customized for project)

What Doesn't Get Copied:

  • Dev-kit specific examples (replaced with project examples)
  • Dev-kit specific paths (updated to project paths)
  • Dev-kit version numbers (replaced with project versions)

3.2 Customization Boundaries​

What Can Be Customized:

  • ✅ File paths and directory structures
  • ✅ Version schema (if needed)
  • ✅ Branch naming conventions
  • ✅ Project-specific examples
  • ✅ Policy details (within reason)

What Should Be Preserved:

  • ⚠️ Core methodology (e.g., RW 11-step process)
  • ⚠️ Version schema structure (unless explicitly changing)
  • ⚠️ Integration patterns (if using multiple packages)
  • ⚠️ Validation logic (unless fixing bugs)

Customization Guidelines:

  • Document all customizations
  • Maintain compatibility with integration points
  • Update examples to reflect customizations
  • Test customizations thoroughly

3.3 Reference Patterns (When Appropriate)​

When to Reference:

  • Integration guides can reference other packages (optional)
  • Examples can reference other packages (optional)
  • Documentation can mention other packages (optional)

Reference Format:

  • Use relative paths when packages are in same repo
  • Use clear labels: [Optional: Requires Numbering & Versioning package]
  • Document what happens if referenced package is not used

Example:

## Optional Integration

This feature integrates with the **Numbering & Versioning** package
(see `../numbering & versioning/README.md`).

If you're not using the Numbering & Versioning package, you can:
- Use your own versioning policy
- Skip this integration step
- Use the feature independently

4. Dependency Rules​

4.1 Hard Dependencies (Not Allowed)​

Rule: No package can have a hard dependency on another dev-kit package.

What This Means:

  • Packages cannot require other packages to function
  • Packages cannot break if other packages are missing
  • Packages must work standalone

Exception: Standard tools (Git, Python, etc.) are allowed as dependencies.

4.2 Soft/Optional Dependencies​

Rule: Packages can have soft/optional dependencies on other packages.

What This Means:

  • Packages can integrate with other packages (optional)
  • Packages can recommend other packages (optional)
  • Packages can provide better functionality with other packages (optional)

Documentation Requirements:

  • Must clearly label dependencies as "optional"
  • Must document what happens if dependency is not used
  • Must provide alternatives if dependency is not available

Example:

## Dependencies

**Standalone:** ✅ Yes — this package can be used on its own

**Soft / optional companions:**
- `packages/frameworks/numbering & versioning/` — provides a portable policy set for the version schema that this package uses

If you prefer a different versioning strategy, you can:
- Keep this package and swap in your own versioning policy docs, or
- Use this package only for the workflow pattern and ignore the included policy documents

4.3 Integration Dependencies​

Rule: Integration between packages is optional and must be well-documented.

What This Means:

  • Packages can integrate with each other (optional)
  • Integration must be clearly documented
  • Integration must not break standalone usage

Integration Patterns:

  • Workflow Management ↔ Numbering & Versioning: RW uses version schema
  • Kanban ↔ Numbering & Versioning: Kanban uses version markers
  • Kanban ↔ Workflow Management: RW updates Kanban docs

Documentation Requirements:

  • Integration guides must exist (e.g., kanban/integration/)
  • Integration must be clearly marked as optional
  • Standalone usage must be documented

5. Package Independence Rules​

5.1 Self-Containment​

Rule: Each package must be self-contained.

What This Means:

  • Package includes all necessary documentation
  • Package includes all necessary examples
  • Package includes all necessary tools/scripts
  • Package doesn't require external dev-kit resources

Exception: Standard tools (Git, Python, etc.) are allowed.

5.2 Documentation Completeness​

Rule: Each package must have complete documentation for standalone usage.

What This Means:

  • README explains what the package does
  • README explains how to use it standalone
  • README explains optional integrations
  • Examples show standalone usage

Documentation Checklist:

  • ✅ Package overview
  • ✅ Quick start guide
  • ✅ Standalone usage examples
  • ✅ Optional integration documentation
  • ✅ Customization guide
  • ✅ Troubleshooting

5.3 Version Schema Independence​

Rule: Each package can include its own versioning policy, but should document compatibility.

What This Means:

  • Workflow Management includes versioning policy (for RW to work)
  • Numbering & Versioning includes versioning policy (canonical)
  • Kanban references versioning (for integration)

Compatibility:

  • Packages should use compatible version schemas
  • Packages should document schema compatibility
  • Packages should provide migration guides if schemas differ

6. Consumption Patterns​

6.1 Standalone Consumption​

Pattern: Use a single package independently.

When to Use:

  • Starting with one framework
  • Only need one capability
  • Want to minimize adoption complexity

Example:

  • Use only Workflow Management for RW trigger
  • Use only Numbering & Versioning for versioning policy
  • Use only Kanban for Kanban board structure

Requirements:

  • Package must work without other packages
  • Package must document standalone usage
  • Package must provide standalone examples

6.2 Combined Consumption​

Pattern: Use multiple packages together.

When to Use:

  • Need multiple capabilities
  • Want integrated workflows
  • Want comprehensive framework coverage

Example:

  • Use Workflow Management + Numbering & Versioning for RW with versioning
  • Use Kanban + Numbering & Versioning for Kanban with version markers
  • Use All Three for complete integrated system

Requirements:

  • Packages must integrate cleanly
  • Integration must be well-documented
  • Integration must not break standalone usage

6.3 Incremental Adoption​

Pattern: Start with one package, add more over time.

When to Use:

  • Gradual adoption strategy
  • Learning curve management
  • Phased implementation

Example:

  1. Start with Numbering & Versioning (versioning policy)
  2. Add Workflow Management (RW trigger)
  3. Add Kanban (Kanban board)

Requirements:

  • Packages must support incremental adoption
  • Integration must work at each stage
  • Migration guides must exist

7. Customization Boundaries​

7.1 What Can Be Customized​

File Paths:

  • ✅ All file paths can be customized
  • ✅ Directory structures can be adapted
  • ✅ Documentation locations can be changed

Version Schema:

  • ✅ Version schema can be customized (if needed)
  • ⚠️ Must maintain compatibility if using multiple packages
  • ⚠️ Must update validation scripts if schema changes

Branch Naming:

  • ✅ Branch naming conventions can be customized
  • ⚠️ Must update validation scripts if conventions change
  • ⚠️ Must update documentation if conventions change

Project-Specific Content:

  • ✅ Examples can be project-specific
  • ✅ Policy details can be project-specific
  • ✅ Templates can be customized

7.2 What Should Be Preserved​

Core Methodology:

  • ⚠️ RW 11-step process (unless explicitly changing)
  • ⚠️ Version schema structure (unless explicitly changing)
  • ⚠️ Kanban hierarchy (Epic → Story → Task)
  • ⚠️ Integration patterns (if using multiple packages)

Validation Logic:

  • ⚠️ Validation scripts should be preserved (unless fixing bugs)
  • ⚠️ Validation rules should be preserved (unless explicitly changing)
  • ⚠️ Error handling should be preserved

Documentation Structure:

  • ⚠️ Documentation structure should be preserved (for consistency)
  • ⚠️ Policy document structure should be preserved
  • ⚠️ Template structure should be preserved

7.3 Customization Documentation​

Rule: All customizations must be documented.

What to Document:

  • What was customized
  • Why it was customized
  • How it differs from original
  • Impact on other packages (if using multiple)

Documentation Format:

  • Customization notes in README
  • Customization log in project docs
  • Migration notes if upgrading

8. Integration Patterns​

8.1 Workflow Management ↔ Numbering & Versioning​

Integration Type: Soft/Optional

How It Works:

  • Workflow Management uses version schema from Numbering & Versioning
  • RW reads version from version.py (uses schema)
  • RW validates version format (uses schema)

Standalone Usage:

  • Workflow Management includes its own versioning policy
  • Can use Workflow Management without Numbering & Versioning
  • Can swap in custom versioning policy

Integration Benefits:

  • Consistent versioning across projects
  • Shared versioning policy
  • Easier maintenance

8.2 Kanban ↔ Numbering & Versioning​

Integration Type: Integration (Optional)

How It Works:

  • Kanban uses version markers (e.g., ✅ COMPLETE (v0.1.2.1+1))
  • Kanban references version schema
  • Kanban validates version format

Standalone Usage:

  • Kanban can work without versioning
  • Can use custom versioning
  • Can skip version markers

Integration Benefits:

  • Forensic traceability
  • Version-based ordering
  • Automatic version updates via RW

8.3 Kanban ↔ Workflow Management​

Integration Type: Integration (Optional)

How It Works:

  • RW (Workflow Management) updates Kanban docs
  • RW adds version markers to Kanban
  • RW validates Kanban structure

Standalone Usage:

  • Kanban can work without RW
  • Can use custom workflow
  • Can manually update Kanban

Integration Benefits:

  • Automatic Kanban updates
  • Consistent version markers
  • Reduced manual work

8.4 All Three Packages​

Integration Type: Full Integration (Optional)

How It Works:

  • Workflow Management uses Numbering & Versioning schema
  • Workflow Management updates Kanban docs
  • Kanban uses Numbering & Versioning version markers
  • All three work together seamlessly

Standalone Usage:

  • Each package can be used independently
  • Can mix and match packages
  • Can use custom integrations

Integration Benefits:

  • Complete integrated system
  • End-to-end traceability
  • Automated workflows
  • Consistent versioning

9. Best Practices​

9.1 Package Design​

  1. Design for Standalone First:** Ensure packages work independently before adding integrations
  2. Document Dependencies Clearly: Label all dependencies as optional or required
  3. Provide Integration Guides: Document how packages integrate (optional)
  4. Maintain Boundaries: Keep package scopes clear and well-defined

9.2 Consumption​

  1. Start Small: Begin with one package, add more as needed
  2. Read Documentation: Understand package boundaries before customizing
  3. Document Customizations: Keep track of what you change
  4. Test Integrations: Verify integrations work before relying on them

9.3 Maintenance​

  1. Preserve Core Methodology: Don't break core functionality when customizing
  2. Update Documentation: Keep customization notes current
  3. Test After Updates: Verify packages still work after updates
  4. Share Improvements: Contribute improvements back to dev-kit (if appropriate)

10. Summary​

10.1 Core Principles​

  1. Standalone First: Each package must work independently
  2. Copy, Don't Reference: Packages are copied, not referenced
  3. Soft Dependencies: Dependencies are optional, not required
  4. Clear Boundaries: Each package has well-defined scope

10.2 Package Boundaries​

  • Workflow Management: Owns workflow execution, RW trigger, validation
  • Numbering & Versioning: Owns versioning schema, policy, strategy
  • Kanban: Owns Kanban governance, templates, FR/BR intake

10.3 Dependency Rules​

  • No Hard Dependencies: Packages cannot require other packages
  • Soft Dependencies Allowed: Optional integrations are encouraged
  • Integration Documentation Required: All integrations must be documented

10.4 Consumption Patterns​

  • Standalone: Use one package independently
  • Combined: Use multiple packages together
  • Incremental: Start with one, add more over time

11. Next Steps​

This document establishes the foundation for:

  • Task 3: Create package dependency matrix (visual representation)
  • Task 4: Document consumption patterns for each framework (detailed examples)
  • Task 5: Update package READMEs with modularity information (implementation)

Document completed: 2025-12-02
Task: E1:S02:T002
Next: E1:S02:T03 – Create package dependency matrix