Techcle Wiki

Tasks

11 min read

Implementation Plan: Repository Structure

Overview

This implementation plan establishes the target repository architecture consisting of workspace-root (workspace-level tooling), workspace-shared (lightweight repo utilities), and k8s-lab (platform foundation). The plan focuses on achieving the target state architecture while preserving existing functionality and integrating AI Gateway and BMAD methodology support.

Tasks

  • 1. Establish workspace-shared repository with shared components

    • 1.1 Create workspace-shared repository structure

      • Set up repository with lightweight structure for repo-level utilities
      • Create basic Taskfile.yaml with docs:taskfile and CI tasks
      • Set up scripts directory for lightweight utilities
      • Set up templates directory for repo-level templates
      • Requirements: 3.1, 3.5

    • 1.2 Add shared components to workspace-shared

      • Move traefik-ingress Helm chart to workspace-shared/helm/
      • Move kustomize components to workspace-shared/kustomize/components/
      • Add steering documentation to workspace-shared/.kiro/steering/
      • Set up proper directory structure for shared components
      • Requirements: 10.6

    • [ ]* 1.3 Write property test for workspace-shared content restrictions

      • Property 1: Lightweight utilities only
      • Validates: Requirements 3.1, 3.3

  • 2. Configure workspace-root as comprehensive workspace tooling

    • 2.1 Establish workspace-root structure

      • Ensure workspace-root contains workspace management functionality
      • Set up AI Gateway configuration structure (ai-gateway.yaml)
      • Create BMAD methodology structure (_bmad/ directory)
      • Configure workspace discovery integration (workspaces.yaml)
      • Requirements: 2.1, 2.2, 7.1, 8.1

    • 2.2 Integrate AI Gateway and BMAD methodology

      • Set up _bmad/ directory structure with methodology templates
      • Create AI Gateway configuration with global settings
      • Configure cross-workspace learning structure in _bmad/_memory/
      • Set up workspace discovery patterns for .ai/ directories
      • Requirements: 7.2, 7.4, 8.2, 8.4

    • [ ]* 2.3 Write property test for workspace-root functionality

      • Property 2: Workspace-level tool accessibility
      • Validates: Requirements 2.1, 2.4

  • 3. Establish k8s-lab as platform foundation

    • 3.1 Configure k8s-lab foundation structure

      • Ensure ArgoCD bootstrap configuration is in place
      • Set up supporting applications (cert-manager, external-secrets, etc.)
      • Configure central secret store namespace and policies
      • Set up environment overlays for different deployment contexts
      • Requirements: 11.1, 12.1, 13.1, 14.1

    • 3.2 Implement foundation self-management

      • Configure ArgoCD self-management applications
      • Set up automated sync policies with proper ignoreDifferences
      • Ensure foundation can manage and update itself
      • Configure proper resource ordering and dependencies
      • Requirements: 12.2, 12.3, 12.5

    • 3.3 Organize foundation task structure

      • Create clear, non-overlapping task structure (bootstrap, apply, init)
      • Eliminate redundant tasks and provide clear descriptions
      • Organize tasks into logical groups (bootstrap, management, troubleshooting)
      • Ensure each deployment scenario has exactly one appropriate task
      • Requirements: 17.1, 17.2, 17.3, 17.6, 17.7

    • [ ]* 3.4 Write property test for foundation infrastructure

      • Property 3: Foundation includes only infrastructure components
      • Validates: Requirements 11.1, 11.4, 11.5

  • 4. Update repository integration patterns

    • 4.1 Configure workspace-shared submodule integration

      • Update consuming repositories to use workspace-shared at libs/workspace-shared
      • Configure helmGlobals.chartHome to point to libs/workspace-shared/helm
      • Set up proper submodule references and version pinning
      • Test integration patterns across multiple repositories
      • Requirements: 5.1, 10.1, 10.2

    • 4.2 Create automated workspace-shared management tasks

      • Create tasks for submodule setup, update, and version pinning
      • Add tasks for development workflow (commit, push, test, release)
      • Create tasks for checking component status and available updates
      • Set up validation tasks for submodule integrity
      • Requirements: 11.1, 11.2, 11.3, 11.4, 11.5, 11.6

    • [ ]* 4.3 Write property test for integration patterns

      • Property 4: Repository integration correctness
      • Validates: Requirements 5.1, 5.2, 5.3

  • 5. Validate cross-repository functionality

    • 5.1 Test workspace-root functionality

      • Validate workspace management across multiple repositories
      • Test AI Gateway configuration loading and workspace discovery
      • Verify BMAD methodology access and artifact generation
      • Test cross-workspace learning and template sharing
      • Requirements: 6.1, 6.3, 7.3, 8.3

    • 5.2 Test workspace-shared component distribution

      • Validate shared components work consistently across workspaces
      • Test component version pinning and update procedures
      • Verify semantic versioning and compatibility handling
      • Test development workflow for shared component changes
      • Requirements: 10.3, 10.4, 11.2, 11.5

    • 5.3 Test k8s-lab foundation deployment

      • Validate foundation bootstrap process on clean cluster
      • Test ArgoCD self-management and automated sync
      • Verify supporting applications deploy and integrate correctly
      • Test environment overlays and secret distribution
      • Requirements: 12.1, 13.2, 14.2, 16.1, 16.2

    • [ ]* 5.4 Write property test for cross-repository consistency

      • Property 5: Cross-repository functionality consistency
      • Validates: Requirements 6.1, 6.3, 6.4

  • 6. Create comprehensive documentation

    • 6.1 Document repository architecture and usage patterns

      • Create workspace-root README explaining workspace-level operations
      • Create workspace-shared README explaining repo-level utilities
      • Document k8s-lab foundation bootstrap and management procedures
      • Create integration guides for AI Gateway and BMAD methodology
      • Requirements: 12.1, 12.2, 12.3, 12.4, 12.5

    • 6.2 Create migration and setup guides

      • Document submodule setup and management procedures
      • Create guides for updating existing repositories
      • Document component versioning and update procedures
      • Provide troubleshooting guides for common issues
      • Requirements: 5.5, 10.5, 11.6

  • 7. Final validation and testing

    • 7.1 End-to-end architecture testing

      • Test complete workspace setup using workspace-root
      • Test repository development using workspace-shared submodule
      • Test platform foundation deployment and business capability integration
      • Validate all components work together as designed
      • Requirements: 1.4, 1.5, 15.1, 15.5

    • [ ]* 7.2 Write comprehensive validation tests

      • Property 6: End-to-end architecture validation
      • Validates: Requirements 1.4, 1.5, 6.5

  • 8. Final checkpoint - Complete architecture validation

    • Ensure all tests pass, ask the user if questions arise
    • Verify all requirements are met
    • Confirm target architecture is fully functional
    • Validate AI Gateway and BMAD integration works correctly
    • Validates: Requirements 2.1, 2.5

  • 5. Integrate AI Gateway configuration structure

    • Create ai-gateway.yaml with global AI Gateway configuration
    • Set up _bmad/ directory structure for centralized BMAD methodology
    • Create BMAD configuration files (methodology.yaml, templates.yaml, roles.yaml)
    • Set up cross-workspace learning structure in _bmad/_memory/
    • Requirements: 7.1, 7.2, 8.1, 8.2

  • [ ]* 5.1 Write property test for AI Gateway configuration centralization

    • Property 5: AI Gateway configuration accessibility
    • Validates: Requirements 7.1, 7.2

  • [ ]* 5.2 Write property test for BMAD methodology structure

    • Property 6: BMAD methodology consistency
    • Validates: Requirements 8.1, 8.2

  • 6. Update workspace discovery integration

    • Migrate workspaces.yaml from k8s-lab to workspace-root
    • Update workspace definitions to include AI Gateway and BMAD flags
    • Implement support for .ai/ directory pattern discovery
    • Ensure integration with existing workspace management
    • Requirements: 9.1, 9.3, 7.3

  • [ ]* 6.1 Write property test for workspace discovery integration

    • Property 7: Workspace discovery compatibility
    • Validates: Requirements 9.1, 9.3

  • 7. Checkpoint - Validate repository structures

    • Ensure workspace-root contains all heavy tooling
    • Ensure workspace-shared contains only lightweight utilities
    • Verify AI Gateway and BMAD integration
    • Test workspace discovery functionality

  • 8. Update repository references across ecosystem

    • Update k8s-lab to reference workspace-root for workspace operations
    • Update ai-dev to use workspace-shared submodule instead of dev-common
    • Update any other repositories using dev-common submodule
    • Update Taskfile includes to reference appropriate repositories
    • Requirements: 5.1, 5.2, 5.3

  • [ ]* 8.1 Write property test for reference update correctness

    • Property 8: Repository reference accuracy
    • Validates: Requirements 5.1, 5.2

  • 9. Update CI/CD configurations

    • Update GitLab CI configurations to use workspace-shared submodule
    • Ensure CI has local access to required tasks
    • Test CI functionality with new repository structure
    • Update any hardcoded paths or references
    • Requirements: 5.4, 3.4

  • [ ]* 9.1 Write property test for CI compatibility

    • Property 9: CI configuration compatibility
    • Validates: Requirements 5.4, 3.4

  • 10. Clean up original k8s-lab workspace tooling

    • Remove migrated workspace tooling from k8s-lab code-server
    • Update k8s-lab to reference workspace-root tooling
    • Remove duplicate workspaces.yaml from k8s-lab
    • Update k8s-lab documentation to reference new structure
    • Requirements: 2.4, 6.5

  • 11. Create comprehensive documentation

    • Create workspace-root README explaining workspace-level operations
    • Create workspace-shared README explaining repo-level utilities
    • Document AI Gateway integration and BMAD methodology usage
    • Create migration guide for updating existing repositories
    • Document architectural reasoning and AI Gateway ecosystem role
    • Requirements: 10.1, 10.2, 10.3, 10.4, 10.5

  • 12. Implement backward compatibility measures

    • Ensure existing workspace configurations continue to work
    • Provide compatibility shims where necessary
    • Test all existing development workflows
    • Document any breaking changes and migration paths
    • Requirements: 6.3, 6.5

  • [ ]* 12.1 Write property test for backward compatibility

    • Property 10: Backward compatibility preservation
    • Validates: Requirements 6.3, 6.5

  • 13. Validate cross-workspace BMAD functionality

    • Test BMAD methodology access from multiple workspaces
    • Verify cross-workspace learning storage in _bmad/_memory/
    • Test workspace-specific BMAD artifacts with central methodology
    • Ensure BMAD phase structure support across all workspaces
    • Requirements: 8.3, 8.4, 8.5

  • [ ]* 13.1 Write property test for cross-workspace BMAD consistency

    • Property 11: Cross-workspace BMAD functionality
    • Validates: Requirements 8.3, 8.4

  • 14. Test environment compatibility

    • Test workspace-root functionality in local development environment
    • Test workspace-root functionality in code-server environment
    • Verify workspace-shared submodule works in both environments
    • Test AI Gateway integration in both environments
    • Requirements: 9.5

  • [ ]* 14.1 Write property test for environment compatibility

    • Property 12: Environment compatibility
    • Validates: Requirements 9.5

  • 15. Final integration testing

    • Test complete workspace setup using workspace-root
    • Test repository development using workspace-shared submodule
    • Verify AI Gateway configuration loading and workspace discovery
    • Test BMAD methodology access and artifact generation
    • Validate all migration scenarios and rollback procedures
    • Requirements: 1.4, 1.5, 2.2, 7.4, 7.5

  • [ ]* 15.1 Write property test for repository separation consistency

    • Property 13: Repository separation enforcement
    • Validates: Requirements 1.4, 1.5

  • 16. Final checkpoint - Complete system validation

    • Ensure all tests pass, ask the user if questions arise
    • Verify all requirements are met
    • Confirm all existing functionality is preserved
    • Validate new AI Gateway and BMAD integration works correctly

  • 17. Implement single large workspace support

    • 17.1 Extend workspace configuration schema

      • Add internalFolder property to workspace definition schema
      • Update workspace configuration validation to support internal folder option
      • Ensure backward compatibility with existing workspace configurations
      • Document the internal folder configuration option
      • Requirements: 18.5, 18.7

    • 17.2 Update workspace setup logic

      • Modify workspace manager to detect internalFolder property
      • Implement logic to create internal folder structure during workspace setup
      • Update project cloning to place repositories under internal folder when specified
      • Ensure VS Code workspace file references correct paths for internal folder pattern
      • Requirements: 18.1, 18.6

    • 17.3 Validate single large workspace functionality

      • Test workspace creation with internalFolder: repos configuration
      • Verify all projects are cloned into repos/ subdirectory
      • Test that workspace discovery works with internal folder pattern
      • Ensure AI Gateway and BMAD integration work correctly with internal folder structure
      • Requirements: 18.2, 18.3, 18.4

    • [ ]* 17.4 Write property test for internal folder structure

      • Property 11: Internal folder structure consistency
      • Validates: Requirements 18.1, 18.3, 18.5

  • 18. Create example ai-agent workspace configuration

    • Add ai-agent workspace definition to workspaces.yaml
    • Configure with internalFolder: repos and all projects
    • Include all necessary extensions for cross-project development
    • Document the ai-agent workspace use case and benefits
    • Requirements: 18.2

  • 19. Implement unified project structure in .ai/projects/

    • 19.1 Create .ai/projects/ directory structure

      • Create .ai/projects/ directory in workspace-root
      • Add .ai/projects/ to .gitignore
      • Create project metadata schema (metadata.json format)
      • Document the unified project structure
      • Requirements: 20.1, 20.11

    • 19.2 Create migration scripts for existing projects

      • Create script to migrate Kiro specs from .kiro/specs/ to .ai/projects/
      • Create script to migrate Codev specs from codev/specs/ to .ai/projects/
      • Implement symlink creation for Kiro integration
      • Implement pointer file generation for Codev integration
      • Requirements: 20.9

    • 19.3 Implement helper scripts for project management

      • Create create-project.sh script for new projects
      • Create list-projects.sh script to show all projects
      • Create migrate-project.sh script for moving projects between tools
      • Create sync-metadata.sh script to update metadata.json files
      • Requirements: 20.7, 20.8

    • 19.4 Migrate existing Kiro projects

      • Run migration script for all projects in .kiro/specs/
      • Create symlinks from .kiro/specs/{project} to .ai/projects/{project}/
      • Generate metadata.json for each migrated project
      • Verify Kiro can still access all projects via symlinks
      • Requirements: 20.2, 20.5, 20.9

    • 19.5 Migrate existing Codev projects

      • Run migration script for all projects in codev/specs/
      • Create pointer files in codev/specs/, codev/plans/, codev/reviews/
      • Generate metadata.json for each migrated project
      • Verify Codev can access projects via pointer files
      • Requirements: 20.3, 20.6, 20.9

    • 19.6 Test multi-tool project support

      • Create a test project that uses both Kiro and Codev
      • Verify both tools can read and write to the same project
      • Test that metadata.json tracks both tools correctly
      • Verify no conflicts when both tools modify the same project
      • Requirements: 20.4, 20.10

    • 19.7 Update documentation for unified project structure

      • Document the .ai/projects/ structure and rationale
      • Create guide for creating new projects
      • Document migration process for existing projects
      • Add troubleshooting guide for symlink and pointer file issues
      • Requirements: 20.8

    • [ ]* 19.8 Write property test for unified project structure

      • Property 12: Unified project accessibility
      • Validates: Requirements 20.1, 20.5, 20.6, 20.8

  • 20. Create Taskfile tasks for unified project management

    • 20.1 Create task for creating new projects

      • Add projects:create task with PROJECT and FORMAT parameters
      • Support FORMAT=kiro or FORMAT=codev
      • Generate metadata.json with appropriate format
      • Create symlink (Kiro) or pointer files (Codev)
      • Create .ai/projects/ directory if it doesn’t exist
      • Requirements: 20.2, 20.3, 20.4, 20.7

    • 20.2 Create task for listing all projects

      • Add projects:list task to show all projects in .ai/projects/
      • Display project name, format, status, and artifacts
      • Support filtering by format (kiro/codev)
      • Show which projects have symlinks/pointers set up
      • Requirements: 20.8

    • 20.3 Create task for validating project structure

      • Add projects:validate task to check all projects
      • Verify metadata.json matches actual artifacts
      • Check symlinks/pointers are correctly set up
      • Report any inconsistencies or missing files
      • Requirements: 20.7, 20.8

    • 20.4 Create task for syncing project metadata

      • Add projects:sync task to update all metadata.json files
      • Scan actual artifacts and update metadata accordingly
      • Regenerate pointer files if needed
      • Verify symlinks are valid
      • Requirements: 20.7

    • 20.5 Document Taskfile tasks for project management

      • Add task descriptions to .kiro/steering/taskfile.md
      • Create examples for common workflows
      • Document task parameters and usage patterns
      • Requirements: 20.8

Notes

  • Tasks marked with * are optional and can be skipped for faster MVP
  • Each task references specific requirements for traceability
  • Checkpoints ensure incremental validation
  • Property tests validate universal correctness properties
  • Unit tests validate specific examples and edge cases
  • The migration preserves all existing functionality while adding new AI Gateway capabilities
  • The single large workspace feature is additive and maintains backward compatibility

Graph View