Techcle Wiki

Requirements

16 min read

Requirements Document

Introduction

This specification defines the target architecture for a multi-repository platform that cleanly separates workspace-level operations, repository-level utilities, and platform foundation infrastructure. The architecture consists of workspace-root (workspace management and AI Gateway), workspace-shared (lightweight repo utilities), and k8s-lab (platform foundation), creating a cohesive ecosystem that supports both traditional development and AI-enabled workflows.

Glossary

  • Workspace_Root: Repository containing workspace-level tooling, AI Gateway configuration, BMAD methodology, and cross-workspace operations
  • Workspace_Shared: Lightweight repository containing repo-level shared utilities accessible via git submodule
  • Platform_Foundation: The k8s-lab repository providing base infrastructure (ArgoCD, supporting applications) for all platform capabilities
  • Foundation_Seed: Base infrastructure components in k8s-lab that provide GitOps foundation for business capabilities
  • Business_Capabilities: Application-specific components (Backstage, Image Factory, EDA) that build on the platform foundation
  • AI_Gateway: Mobile AI development system enabling AI-assisted workflows with centralized configuration
  • BMAD_Methodology: Business Method and Design methodology with centralized templates and cross-workspace learning
  • ArgoCD_Bootstrap: Self-managing GitOps engine that provides the foundation for all platform deployments
  • Supporting_Applications: Infrastructure services (cert-manager, external-secrets, Kargo, Headlamp) that support platform operations
  • Central_Secret_Store: Automated secret distribution system that eliminates manual secret management
  • Task_Organization: Clear, non-overlapping task structure that eliminates confusion between deployment scenarios
  • Workspace_Discovery: System for automatically identifying and configuring AI-enabled development environments
  • Environment_Overlays: Configuration system supporting different deployment environments with appropriate capability sets

Requirements

Requirement 1: Separate Workspace-Level and Repo-Level Concerns

User Story: As a developer, I want workspace-level tooling separated from repo-level utilities, so that I can use each at the appropriate level without duplication or confusion.

Acceptance Criteria

  1. WHEN workspace-level operations are needed, THE System SHALL provide tooling from workspace-root without requiring submodule inclusion
  2. WHEN repo-level utilities are needed, THE System SHALL provide lightweight tooling from workspace-shared via submodule
  3. WHEN a repository needs shared utilities, THE System SHALL not require inclusion of heavy workspace tooling
  4. WHEN workspace management is performed, THE System SHALL not duplicate tooling across multiple repository submodules
  5. THE System SHALL maintain clear separation between workspace-level and repo-level operations

Requirement 2: Workspace-Root Repository Structure

User Story: As a developer, I want workspace-root to provide comprehensive workspace-level tooling, so that I can manage multi-repository development environments effectively.

Acceptance Criteria

  1. WHEN workspace-root is accessed, THE System SHALL provide workspace management functionality for multi-repository operations
  2. WHEN workspace tooling is needed, THE System SHALL provide workspace management, BMAD methodology, AI Gateway configuration, and development environment setup
  3. WHEN workspace-root is referenced, THE System SHALL operate at the workspace level managing multiple repositories
  4. WHEN workspace configurations are processed, THE System SHALL handle them consistently across all supported environments
  5. THE System SHALL provide all workspace-level operations without requiring submodule inclusion

Requirement 3: Workspace-shared Repository

User Story: As a developer, I want a lightweight workspace-shared repository for repo-level utilities, so that I can include shared tasks in individual repositories without heavy dependencies.

Acceptance Criteria

  1. WHEN workspace-shared is created, THE System SHALL contain only lightweight repo-level utilities
  2. WHEN repositories include workspace-shared as submodule, THE System SHALL provide access to docs:taskfile and other CI tasks
  3. WHEN workspace-shared is updated, THE System SHALL not include heavy tooling like workspace management or bmad
  4. WHEN GitLab CI runs, THE System SHALL have local access to required tasks from workspace-shared submodule
  5. THE System SHALL keep workspace-shared minimal and focused on per-repository needs

Requirement 4: Extract and Migrate Repo-Level Tasks

User Story: As a developer, I want repo-level tasks extracted from the current dev-common into workspace-shared, so that repositories can access shared utilities without workspace-level dependencies.

Acceptance Criteria

  1. WHEN docs:taskfile task is migrated, THE System SHALL provide identical functionality in workspace-shared
  2. WHEN other repo-level utilities are identified, THE System SHALL migrate them to workspace-shared
  3. WHEN tasks are extracted, THE System SHALL maintain the same task interface and behavior
  4. WHEN repositories reference workspace-shared tasks, THE System SHALL provide the same functionality as current dev-common submodule usage
  5. THE System SHALL not migrate workspace-level tasks to workspace-shared

Requirement 5: Update Repository References and Usage Patterns

User Story: As a developer, I want existing repositories updated to use the new structure, so that I can benefit from the improved architecture without breaking existing workflows.

Acceptance Criteria

  1. WHEN repositories currently using dev-common submodule are updated, THE System SHALL reference workspace-shared instead
  2. WHEN workspace-level operations are needed, THE System SHALL reference workspace-root directly
  3. WHEN Taskfile includes are updated, THE System SHALL reference the appropriate repository for each task type
  4. WHEN GitLab CI configurations are updated, THE System SHALL continue to work with workspace-shared submodule
  5. THE System SHALL provide migration documentation for updating existing repositories

Requirement 6: Maintain Functional Compatibility

User Story: As a developer, I want all existing functionality preserved during the restructure, so that my current workflows continue to work without interruption.

Acceptance Criteria

  1. WHEN workspace management tasks are executed, THE System SHALL provide identical functionality from workspace-root
  2. WHEN repo-level tasks are executed, THE System SHALL provide identical functionality from workspace-shared
  3. WHEN workspace configurations are processed, THE System SHALL handle them with the same behavior as before
  4. WHEN development tools are installed, THE System SHALL provide the same installation and management capabilities
  5. THE System SHALL not break any existing workspace or repository functionality during migration

Requirement 7: Integrate with AI Gateway Workspace Structure

User Story: As a developer, I want the repository restructure to support the AI Gateway workspace architecture, so that workspace-root can serve as the foundation for AI-enabled development workflows.

Acceptance Criteria

  1. WHEN workspace-root is established, THE System SHALL support the global AI Gateway configuration pattern from ai-dev design
  2. WHEN workspace-root contains BMAD methodology, THE System SHALL provide centralized BMAD templates and configuration for all workspaces
  3. WHEN workspace discovery is implemented, THE System SHALL integrate with the existing workspaces.yaml structure
  4. WHEN AI-enabled workspaces are created, THE System SHALL support the .ai/ directory pattern for workspace-specific AI state
  5. THE System SHALL enable workspace-root to serve as the central location for cross-workspace BMAD artifacts and methodology

Requirement 8: Support BMAD Methodology Structure

User Story: As a developer, I want workspace-root to contain the centralized BMAD methodology structure, so that all AI-enabled workspaces can access consistent business method and design templates.

Acceptance Criteria

  1. WHEN BMAD methodology is centralized, THE System SHALL provide the _bmad/ directory structure in workspace-root
  2. WHEN BMAD configuration is accessed, THE System SHALL provide methodology definitions, templates, and role configurations
  3. WHEN cross-workspace learning occurs, THE System SHALL store patterns and lessons learned in the centralized _bmad/_memory/ location
  4. WHEN workspace-specific BMAD artifacts are created, THE System SHALL reference the centralized methodology while maintaining workspace isolation
  5. THE System SHALL support the BMAD phase structure (bmb, bmm, cis, core, planning-artifacts, implementation-artifacts)

Requirement 9: Enable Workspace Discovery Integration

User Story: As a developer, I want workspace-root to integrate with the existing workspace discovery system, so that AI Gateway can automatically discover and configure AI-enabled workspaces.

Acceptance Criteria

  1. WHEN workspace discovery is performed, THE System SHALL read workspace definitions from the existing workspaces.yaml structure
  2. WHEN AI Gateway configuration is loaded, THE System SHALL provide global AI settings from workspace-root
  3. WHEN workspace-specific AI state is needed, THE System SHALL support the .ai/ directory pattern in individual workspace repositories
  4. WHEN workspace scope is determined, THE System SHALL derive AI scope from existing workspace project definitions
  5. THE System SHALL support both local development and code-server environments through unified configuration

Requirement 10: Shared Component Distribution and Management

User Story: As a platform engineer, I want to reuse common infrastructure components across multiple workspaces via workspace-shared, so that all projects can benefit from standardized configurations without duplicating code.

Acceptance Criteria

  1. WHEN consuming common components from workspace-shared repository, THE System SHALL support git submodule references at libs/workspace-shared
  2. WHEN common components are updated in workspace-shared, THE System SHALL allow consuming workspaces to pin to specific versions for stability
  3. WHEN multiple workspaces use shared components, THE System SHALL maintain consistent behavior across all consuming workspaces
  4. WHEN component versions are released, THE System SHALL follow semantic versioning with git tags to communicate breaking changes and compatibility
  5. WHEN consuming workspaces import shared components, THE System SHALL provide clear documentation for submodule integration patterns and configuration options
  6. WHEN shared components include Helm charts, kustomize components, and steering documentation, THE System SHALL organize them in the established workspace-shared directory structure

Requirement 11: Automated Taskfile Management for Shared Components

User Story: As a platform engineer, I want automated tasks for managing workspace-shared components, so that I can easily set up, update, and maintain shared components across multiple workspaces.

Acceptance Criteria

  1. WHEN setting up a new workspace, THE System SHALL provide tasks to automatically add workspace-shared as a submodule at libs/workspace-shared
  2. WHEN workspace-shared components are updated, THE System SHALL provide tasks to update submodules in consuming workspaces
  3. WHEN pinning to specific component versions, THE System SHALL provide tasks to pin submodules to specific git tags
  4. WHEN checking component status, THE System SHALL provide tasks to show current versions and available updates
  5. WHEN developing workspace-shared components from consuming workspaces, THE System SHALL provide tasks for committing, pushing, testing, and releasing changes
  6. WHEN consuming workspaces need to validate their workspace-shared integration, THE System SHALL provide tasks to verify submodule integrity and component functionality

Requirement 12: Clear Documentation and Usage Patterns

User Story: As a developer, I want clear documentation on when to use workspace-root vs workspace-shared, so that I can choose the appropriate tooling for my needs.

Acceptance Criteria

  1. WHEN documentation is provided, THE System SHALL clearly explain workspace-root usage for workspace-level operations including AI Gateway and BMAD
  2. WHEN documentation is provided, THE System SHALL clearly explain workspace-shared usage for repo-level operations
  3. WHEN migration guides are created, THE System SHALL provide step-by-step instructions for updating existing repositories
  4. WHEN examples are provided, THE System SHALL show proper usage patterns for both repositories including AI Gateway integration
  5. THE System SHALL document the architectural reasoning behind the separation and its role in the AI Gateway ecosystem

Requirement 10: Clear Documentation and Usage Patterns

User Story: As a developer, I want clear documentation on when to use workspace-root vs workspace-shared, so that I can choose the appropriate tooling for my needs.

Acceptance Criteria

  1. WHEN documentation is provided, THE System SHALL clearly explain workspace-root usage for workspace-level operations including AI Gateway and BMAD
  2. WHEN documentation is provided, THE System SHALL clearly explain workspace-shared usage for repo-level operations
  3. WHEN migration guides are created, THE System SHALL provide step-by-step instructions for updating existing repositories
  4. WHEN examples are provided, THE System SHALL show proper usage patterns for both repositories including AI Gateway integration
  5. THE System SHALL document the architectural reasoning behind the separation and its role in the AI Gateway ecosystem

Requirement 11: Platform Foundation Infrastructure Separation

User Story: As a platform engineer, I want k8s-lab to provide foundational infrastructure components separate from business capabilities, so that I can reuse the foundation across multiple platform deployments and maintain clear separation of concerns.

Acceptance Criteria

  1. WHEN deploying the foundation seed in k8s-lab, THE Foundation_Seed SHALL install ArgoCD and all supporting applications without any business capabilities
  2. WHEN the foundation is deployed, THE Foundation_Seed SHALL provide a stable base that other repositories can assume exists
  3. WHEN business capabilities are deployed, THE Business_Capabilities SHALL assume ArgoCD and supporting applications are already available
  4. THE Foundation_Seed SHALL include ArgoCD, cert-manager, external-secrets, Kargo, Headlamp, and other supporting applications
  5. THE Foundation_Seed SHALL NOT include Backstage, Image Factory, or EDA Mesh components

Requirement 12: ArgoCD Bootstrap and Self-Management

User Story: As a platform operator, I want ArgoCD to bootstrap itself and then manage all subsequent deployments, so that I have a GitOps-native platform from the start.

Acceptance Criteria

  1. WHEN applying the foundation seed, THE ArgoCD_Bootstrap SHALL install ArgoCD using a single kubectl apply command
  2. WHEN ArgoCD is running, THE Self_Managing_Seed SHALL create ArgoCD applications that manage the seed directory itself
  3. WHEN changes are made to the seed configuration, THE Self_Managing_Seed SHALL automatically detect and apply those changes
  4. THE ArgoCD_Bootstrap SHALL include initial ArgoCD configuration, projects, and RBAC settings
  5. THE Self_Managing_Seed SHALL prevent infinite sync loops through proper ignoreDifferences configuration

Requirement 13: Environment Overlay Support

User Story: As a platform engineer, I want to support different deployment environments with varying capabilities, so that I can use the same foundation across development, staging, and production environments.

Acceptance Criteria

  1. WHEN deploying to different environments, THE Foundation_Seed SHALL support environment-specific overlays
  2. WHEN using local development overlays, THE Foundation_Seed SHALL include all supporting applications for full development capabilities
  3. WHEN using production overlays, THE Foundation_Seed SHALL include only essential supporting applications for production stability
  4. THE Foundation_Seed SHALL support branch targeting for isolated development workflows
  5. THE Foundation_Seed SHALL maintain consistent core functionality across all environment overlays

Requirement 14: Central Secret Management

User Story: As a security engineer, I want all secrets to be managed centrally and distributed automatically, so that I maintain security best practices and avoid manual secret management.

Acceptance Criteria

  1. WHEN the foundation is deployed, THE Foundation_Seed SHALL create a central secret store namespace
  2. WHEN secrets are needed by applications, THE Foundation_Seed SHALL automatically distribute secrets from the central store
  3. WHEN new namespaces are created, THE Foundation_Seed SHALL automatically provision required secrets based on namespace labels
  4. THE Foundation_Seed SHALL include External Secrets Operator for automated secret distribution
  5. THE Foundation_Seed SHALL never create secrets manually in individual namespaces

Requirement 15: Lightweight Business Capability Integration

User Story: As a business capability developer, I want to deploy my capabilities assuming the foundation exists, so that I can focus on business logic without managing infrastructure concerns.

Acceptance Criteria

  1. WHEN business capabilities are deployed, THE Business_Capabilities SHALL assume ArgoCD is already running and configured
  2. WHEN creating ArgoCD applications for business capabilities, THE Business_Capabilities SHALL use the existing ArgoCD instance
  3. WHEN business capabilities need supporting services, THE Business_Capabilities SHALL reference services provided by the foundation
  4. THE Business_Capabilities SHALL not duplicate any infrastructure components provided by the foundation
  5. THE Business_Capabilities SHALL be deployable as lightweight seeds that extend the foundation

Requirement 16: Foundation Testing and Validation

User Story: As a platform engineer, I want comprehensive testing of the foundation seed, so that I can ensure reliability and catch regressions early.

Acceptance Criteria

  1. WHEN the foundation seed is deployed, THE Foundation_Seed SHALL pass all validation tests
  2. WHEN ArgoCD applications are created, THE Foundation_Seed SHALL verify that all applications sync successfully
  3. WHEN supporting applications are deployed, THE Foundation_Seed SHALL validate that all services are healthy
  4. THE Foundation_Seed SHALL include automated tests for the bootstrap process
  5. THE Foundation_Seed SHALL include tests for self-management functionality

Requirement 17: Clear Task Organization and Workflow

User Story: As a platform operator, I want clearly organized and non-overlapping Taskfile commands with obvious purposes, so that I can efficiently manage the foundation without confusion about which task to use in different scenarios.

Acceptance Criteria

  1. WHEN managing the foundation, THE Foundation_Seed SHALL provide distinct tasks for each deployment scenario without functional overlap
  2. WHEN bootstrapping a clean cluster, THE Foundation_Seed SHALL provide a single clear bootstrap task that handles the complete initial setup
  3. WHEN applying routine updates, THE Foundation_Seed SHALL provide a separate apply task that assumes the foundation already exists
  4. WHEN initializing secrets and prerequisites, THE Foundation_Seed SHALL provide a dedicated initialization task that can be run independently
  5. THE Foundation_Seed SHALL eliminate redundant tasks that perform similar functions with different names
  6. WHEN viewing available tasks, THE Foundation_Seed SHALL provide clear descriptions that explain when each task should be used
  7. THE Foundation_Seed SHALL organize tasks into logical groups (bootstrap, management, troubleshooting) for better discoverability

Requirement 18: Single Large Workspace for AI Agents

User Story: As an AI agent, I want a single large workspace option that includes all projects in a unified structure, so that the AI can have as much context as possible to help it understand work & can work across multiple repositories.

Acceptance Criteria

  1. WHEN a workspace is configured with an internal folder setting, THE System SHALL instantiate all configured projects as subdirectories under that internal folder
  2. WHEN an AI agent workspace is created, THE System SHALL support a “repos” subfolder containing all project repositories
  3. WHEN projects are cloned into an internal folder workspace, THE System SHALL maintain the same project structure and functionality as individual workspaces
  4. WHEN workspace discovery occurs, THE System SHALL support both traditional multi-workspace and single large workspace patterns
  5. THE System SHALL allow workspaces to specify an internalFolder property that determines where projects are instantiated
  6. WHEN an internal folder is specified, THE System SHALL create the folder structure automatically during workspace setup
  7. THE System SHALL maintain backward compatibility with existing workspace configurations that don’t use internal folders

Requirement 19: Modular ArgoCD Application Organization

User Story: As a platform engineer, I want the k8s-lab foundation seed organized into logical ArgoCD application groupings (core-infrastructure, platform-services, remote-development, observability), so that I can manage, deploy, and troubleshoot related components together while keeping the main seed focused and maintainable.

Acceptance Criteria

  1. WHEN organizing components in k8s-lab, THE System SHALL group them into logical directories: core-infrastructure/, platform-services/, remote-development/, and observability/
  2. WHEN deploying the foundation seed, THE System SHALL deploy core-infrastructure and platform-services components as part of the main seed
  3. WHEN deploying modular components, THE System SHALL create separate ArgoCD applications for remote-development and observability component groups
  4. WHEN a component group is deployed as an ArgoCD application, THE System SHALL reference the component group directory path in the application source
  5. THE System SHALL maintain independent sync policies and health checks for each modular ArgoCD application
  6. WHEN troubleshooting components, THE System SHALL provide isolated status and logs per component group
  7. THE System SHALL support enabling/disabling entire component groups based on environment needs (e.g., disable remote-development in production)

Requirement 20: Unified Project Structure for Multi-Tool Development

User Story: As a developer using multiple AI coding tools (Kiro and Codev), I want a single unified projects folder where all project artifacts live, so that I can work on projects with any tool without duplicating specifications or managing multiple tool-specific folders.

Acceptance Criteria

  1. WHEN creating a new project, THE System SHALL store all project artifacts in a unified .ai/projects/{project-name}/ directory
  2. WHEN a project uses Kiro format, THE System SHALL store requirements.md, design.md, and tasks.md in the project directory
  3. WHEN a project uses Codev format, THE System SHALL store spec.md, plan.md, and review.md in the project directory
  4. WHEN a project is created, THE System SHALL use exactly one format (Kiro or Codev), not both simultaneously
  5. WHEN Kiro needs to access a project, THE System SHALL provide a symlink from .kiro/specs/{project-name} to .ai/projects/{project-name}/
  6. WHEN Codev needs to access a project, THE System SHALL provide pointer files in codev/specs/, codev/plans/, and codev/reviews/ that reference the unified project location
  7. WHEN a project is created, THE System SHALL generate a metadata.json file tracking which tool format the project uses and which artifacts are present
  8. WHEN listing projects, THE System SHALL show all projects regardless of which tool format they use
  9. WHEN migrating existing projects, THE System SHALL preserve all existing artifacts and maintain the original tool format
  10. THE System SHALL support converting a project from one format to another through explicit migration
  11. THE System SHALL ensure .ai/projects/ is included in .gitignore to keep AI-specific project state local to each developer

Graph View