@totaland/create-starter-kit 1.0.0 → 2.0.1

package/templates/backend/.github/prompts/architecture-blueprint-generator.prompt.md

@@ -0,0 +1,321 @@
+---
+description: 'Comprehensive project architecture blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks and architectural patterns, generates visual diagrams, documents implementation patterns, and provides extensible blueprints for maintaining architectural consistency and guiding new development.'
+---
+
+# Comprehensive Project Architecture Blueprint Generator
+
+## Configuration Variables
+${PROJECT_TYPE="Auto-detect|.NET|Java|React|Angular|Python|Node.js|Flutter|Other"} <!-- Primary technology -->
+${ARCHITECTURE_PATTERN="Auto-detect|Clean Architecture|Microservices|Layered|MVVM|MVC|Hexagonal|Event-Driven|Serverless|Monolithic|Other"} <!-- Primary architectural pattern -->
+${DIAGRAM_TYPE="C4|UML|Flow|Component|None"} <!-- Architecture diagram type -->
+${DETAIL_LEVEL="High-level|Detailed|Comprehensive|Implementation-Ready"} <!-- Level of detail to include -->
+${INCLUDES_CODE_EXAMPLES=true|false} <!-- Include sample code to illustrate patterns -->
+${INCLUDES_IMPLEMENTATION_PATTERNS=true|false} <!-- Include detailed implementation patterns -->
+${INCLUDES_DECISION_RECORDS=true|false} <!-- Include architectural decision records -->
+${FOCUS_ON_EXTENSIBILITY=true|false} <!-- Emphasize extension points and patterns -->
+
+## Generated Prompt
+
+"Create a comprehensive 'Project_Architecture_Blueprint.md' document that thoroughly analyzes the architectural patterns in the codebase to serve as a definitive reference for maintaining architectural consistency. Use the following approach:
+
+### 1. Architecture Detection and Analysis
+- ${PROJECT_TYPE == "Auto-detect" ? "Analyze the project structure to identify all technology stacks and frameworks in use by examining:
+  - Project and configuration files
+  - Package dependencies and import statements
+  - Framework-specific patterns and conventions
+  - Build and deployment configurations" : "Focus on ${PROJECT_TYPE} specific patterns and practices"}
+  
+- ${ARCHITECTURE_PATTERN == "Auto-detect" ? "Determine the architectural pattern(s) by analyzing:
+  - Folder organization and namespacing
+  - Dependency flow and component boundaries
+  - Interface segregation and abstraction patterns
+  - Communication mechanisms between components" : "Document how the ${ARCHITECTURE_PATTERN} architecture is implemented"}
+
+### 2. Architectural Overview
+- Provide a clear, concise explanation of the overall architectural approach
+- Document the guiding principles evident in the architectural choices
+- Identify architectural boundaries and how they're enforced
+- Note any hybrid architectural patterns or adaptations of standard patterns
+
+### 3. Architecture Visualization
+${DIAGRAM_TYPE != "None" ? `Create ${DIAGRAM_TYPE} diagrams at multiple levels of abstraction:
+- High-level architectural overview showing major subsystems
+- Component interaction diagrams showing relationships and dependencies
+- Data flow diagrams showing how information moves through the system
+- Ensure diagrams accurately reflect the actual implementation, not theoretical patterns` : "Describe the component relationships based on actual code dependencies, providing clear textual explanations of:
+- Subsystem organization and boundaries
+- Dependency directions and component interactions
+- Data flow and process sequences"}
+
+### 4. Core Architectural Components
+For each architectural component discovered in the codebase:
+
+- **Purpose and Responsibility**:
+  - Primary function within the architecture
+  - Business domains or technical concerns addressed
+  - Boundaries and scope limitations
+
+- **Internal Structure**:
+  - Organization of classes/modules within the component
+  - Key abstractions and their implementations
+  - Design patterns utilized
+
+- **Interaction Patterns**:
+  - How the component communicates with others
+  - Interfaces exposed and consumed
+  - Dependency injection patterns
+  - Event publishing/subscription mechanisms
+
+- **Evolution Patterns**:
+  - How the component can be extended
+  - Variation points and plugin mechanisms
+  - Configuration and customization approaches
+
+### 5. Architectural Layers and Dependencies
+- Map the layer structure as implemented in the codebase
+- Document the dependency rules between layers
+- Identify abstraction mechanisms that enable layer separation
+- Note any circular dependencies or layer violations
+- Document dependency injection patterns used to maintain separation
+
+### 6. Data Architecture
+- Document domain model structure and organization
+- Map entity relationships and aggregation patterns
+- Identify data access patterns (repositories, data mappers, etc.)
+- Document data transformation and mapping approaches
+- Note caching strategies and implementations
+- Document data validation patterns
+
+### 7. Cross-Cutting Concerns Implementation
+Document implementation patterns for cross-cutting concerns:
+
+- **Authentication & Authorization**:
+  - Security model implementation
+  - Permission enforcement patterns
+  - Identity management approach
+  - Security boundary patterns
+
+- **Error Handling & Resilience**:
+  - Exception handling patterns
+  - Retry and circuit breaker implementations
+  - Fallback and graceful degradation strategies
+  - Error reporting and monitoring approaches
+
+- **Logging & Monitoring**:
+  - Instrumentation patterns
+  - Observability implementation
+  - Diagnostic information flow
+  - Performance monitoring approach
+
+- **Validation**:
+  - Input validation strategies
+  - Business rule validation implementation
+  - Validation responsibility distribution
+  - Error reporting patterns
+
+- **Configuration Management**:
+  - Configuration source patterns
+  - Environment-specific configuration strategies
+  - Secret management approach
+  - Feature flag implementation
+
+### 8. Service Communication Patterns
+- Document service boundary definitions
+- Identify communication protocols and formats
+- Map synchronous vs. asynchronous communication patterns
+- Document API versioning strategies
+- Identify service discovery mechanisms
+- Note resilience patterns in service communication
+
+### 9. Technology-Specific Architectural Patterns
+${PROJECT_TYPE == "Auto-detect" ? "For each detected technology stack, document specific architectural patterns:" : `Document ${PROJECT_TYPE}-specific architectural patterns:`}
+
+${(PROJECT_TYPE == ".NET" || PROJECT_TYPE == "Auto-detect") ? 
+"#### .NET Architectural Patterns (if detected)
+- Host and application model implementation
+- Middleware pipeline organization
+- Framework service integration patterns
+- ORM and data access approaches
+- API implementation patterns (controllers, minimal APIs, etc.)
+- Dependency injection container configuration" : ""}
+
+${(PROJECT_TYPE == "Java" || PROJECT_TYPE == "Auto-detect") ? 
+"#### Java Architectural Patterns (if detected)
+- Application container and bootstrap process
+- Dependency injection framework usage (Spring, CDI, etc.)
+- AOP implementation patterns
+- Transaction boundary management
+- ORM configuration and usage patterns
+- Service implementation patterns" : ""}
+
+${(PROJECT_TYPE == "React" || PROJECT_TYPE == "Auto-detect") ? 
+"#### React Architectural Patterns (if detected)
+- Component composition and reuse strategies
+- State management architecture
+- Side effect handling patterns
+- Routing and navigation approach
+- Data fetching and caching patterns
+- Rendering optimization strategies" : ""}
+
+${(PROJECT_TYPE == "Angular" || PROJECT_TYPE == "Auto-detect") ? 
+"#### Angular Architectural Patterns (if detected)
+- Module organization strategy
+- Component hierarchy design
+- Service and dependency injection patterns
+- State management approach
+- Reactive programming patterns
+- Route guard implementation" : ""}
+
+${(PROJECT_TYPE == "Python" || PROJECT_TYPE == "Auto-detect") ? 
+"#### Python Architectural Patterns (if detected)
+- Module organization approach
+- Dependency management strategy
+- OOP vs. functional implementation patterns
+- Framework integration patterns
+- Asynchronous programming approach" : ""}
+
+### 10. Implementation Patterns
+${INCLUDES_IMPLEMENTATION_PATTERNS ? 
+"Document concrete implementation patterns for key architectural components:
+
+- **Interface Design Patterns**:
+  - Interface segregation approaches
+  - Abstraction level decisions
+  - Generic vs. specific interface patterns
+  - Default implementation patterns
+
+- **Service Implementation Patterns**:
+  - Service lifetime management
+  - Service composition patterns
+  - Operation implementation templates
+  - Error handling within services
+
+- **Repository Implementation Patterns**:
+  - Query pattern implementations
+  - Transaction management
+  - Concurrency handling
+  - Bulk operation patterns
+
+- **Controller/API Implementation Patterns**:
+  - Request handling patterns
+  - Response formatting approaches
+  - Parameter validation
+  - API versioning implementation
+
+- **Domain Model Implementation**:
+  - Entity implementation patterns
+  - Value object patterns
+  - Domain event implementation
+  - Business rule enforcement" : "Mention that detailed implementation patterns vary across the codebase."}
+
+### 11. Testing Architecture
+- Document testing strategies aligned with the architecture
+- Identify test boundary patterns (unit, integration, system)
+- Map test doubles and mocking approaches
+- Document test data strategies
+- Note testing tools and frameworks integration
+
+### 12. Deployment Architecture
+- Document deployment topology derived from configuration
+- Identify environment-specific architectural adaptations
+- Map runtime dependency resolution patterns
+- Document configuration management across environments
+- Identify containerization and orchestration approaches
+- Note cloud service integration patterns
+
+### 13. Extension and Evolution Patterns
+${FOCUS_ON_EXTENSIBILITY ? 
+"Provide detailed guidance for extending the architecture:
+
+- **Feature Addition Patterns**:
+  - How to add new features while preserving architectural integrity
+  - Where to place new components by type
+  - Dependency introduction guidelines
+  - Configuration extension patterns
+
+- **Modification Patterns**:
+  - How to safely modify existing components
+  - Strategies for maintaining backward compatibility
+  - Deprecation patterns
+  - Migration approaches
+
+- **Integration Patterns**:
+  - How to integrate new external systems
+  - Adapter implementation patterns
+  - Anti-corruption layer patterns
+  - Service facade implementation" : "Document key extension points in the architecture."}
+
+${INCLUDES_CODE_EXAMPLES ? 
+"### 14. Architectural Pattern Examples
+Extract representative code examples that illustrate key architectural patterns:
+
+- **Layer Separation Examples**:
+  - Interface definition and implementation separation
+  - Cross-layer communication patterns
+  - Dependency injection examples
+
+- **Component Communication Examples**:
+  - Service invocation patterns
+  - Event publication and handling
+  - Message passing implementation
+
+- **Extension Point Examples**:
+  - Plugin registration and discovery
+  - Extension interface implementations
+  - Configuration-driven extension patterns
+
+Include enough context with each example to show the pattern clearly, but keep examples concise and focused on architectural concepts." : ""}
+
+${INCLUDES_DECISION_RECORDS ? 
+"### 15. Architectural Decision Records
+Document key architectural decisions evident in the codebase:
+
+- **Architectural Style Decisions**:
+  - Why the current architectural pattern was chosen
+  - Alternatives considered (based on code evolution)
+  - Constraints that influenced the decision
+
+- **Technology Selection Decisions**:
+  - Key technology choices and their architectural impact
+  - Framework selection rationales
+  - Custom vs. off-the-shelf component decisions
+
+- **Implementation Approach Decisions**:
+  - Specific implementation patterns chosen
+  - Standard pattern adaptations
+  - Performance vs. maintainability tradeoffs
+
+For each decision, note:
+- Context that made the decision necessary
+- Factors considered in making the decision
+- Resulting consequences (positive and negative)
+- Future flexibility or limitations introduced" : ""}
+
+### ${INCLUDES_DECISION_RECORDS ? "16" : INCLUDES_CODE_EXAMPLES ? "15" : "14"}. Architecture Governance
+- Document how architectural consistency is maintained
+- Identify automated checks for architectural compliance
+- Note architectural review processes evident in the codebase
+- Document architectural documentation practices
+
+### ${INCLUDES_DECISION_RECORDS ? "17" : INCLUDES_CODE_EXAMPLES ? "16" : "15"}. Blueprint for New Development
+Create a clear architectural guide for implementing new features:
+
+- **Development Workflow**:
+  - Starting points for different feature types
+  - Component creation sequence
+  - Integration steps with existing architecture
+  - Testing approach by architectural layer
+
+- **Implementation Templates**:
+  - Base class/interface templates for key architectural components
+  - Standard file organization for new components
+  - Dependency declaration patterns
+  - Documentation requirements
+
+- **Common Pitfalls**:
+  - Architecture violations to avoid
+  - Common architectural mistakes
+  - Performance considerations
+  - Testing blind spots
+
+Include information about when this blueprint was generated and recommendations for keeping it updated as the architecture evolves."

package/templates/backend/.github/prompts/breakdown-epic-arch.prompt.md

@@ -0,0 +1,65 @@
+---
+description: 'Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document.'
+---
+
+# Epic Architecture Specification Prompt
+
+## Goal
+
+Act as a Senior Software Architect. Your task is to take an Epic PRD and create a high-level technical architecture specification. This document will guide the development of the epic, outlining the major components, features, and technical enablers required.
+
+## Context Considerations
+
+- The Epic PRD from the Product Manager.
+- **Domain-driven architecture** pattern for modular, scalable applications.
+- **Self-hosted and SaaS deployment** requirements.
+- **Docker containerization** for all services.
+- **TypeScript/Next.js** stack with App Router.
+- **Turborepo monorepo** patterns.
+- **tRPC** for type-safe APIs.
+- **Stack Auth** for authentication.
+
+**Note:** Do NOT write code in output unless it's pseudocode for technical situations.
+
+## Output Format
+
+The output should be a complete Epic Architecture Specification in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/arch.md`.
+
+### Specification Structure
+
+#### 1. Epic Architecture Overview
+
+- A brief summary of the technical approach for the epic.
+
+#### 2. System Architecture Diagram
+
+Create a comprehensive Mermaid diagram that illustrates the complete system architecture for this epic. The diagram should include:
+
+- **User Layer**: Show how different user types (web browsers, mobile apps, admin interfaces) interact with the system
+- **Application Layer**: Depict load balancers, application instances, and authentication services (Stack Auth)
+- **Service Layer**: Include tRPC APIs, background services, workflow engines (n8n), and any epic-specific services
+- **Data Layer**: Show databases (PostgreSQL), vector databases (Qdrant), caching layers (Redis), and external API integrations
+- **Infrastructure Layer**: Represent Docker containerization and deployment architecture
+
+Use clear subgraphs to organize these layers, apply consistent color coding for different component types, and show the data flow between components. Include both synchronous request paths and asynchronous processing flows where relevant to the epic.
+
+#### 3. High-Level Features & Technical Enablers
+
+- A list of the high-level features to be built.
+- A list of technical enablers (e.g., new services, libraries, infrastructure) required to support the features.
+
+#### 4. Technology Stack
+
+- A list of the key technologies, frameworks, and libraries to be used.
+
+#### 5. Technical Value
+
+- Estimate the technical value (e.g., High, Medium, Low) with a brief justification.
+
+#### 6. T-Shirt Size Estimate
+
+- Provide a high-level t-shirt size estimate for the epic (e.g., S, M, L, XL).
+
+## Context Template
+
+- **Epic PRD:** [The content of the Epic PRD markdown file]

package/templates/backend/.github/prompts/breakdown-epic-pm.prompt.md

@@ -0,0 +1,57 @@
+---
+description: 'Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification.'
+---
+
+# Epic Product Requirements Document (PRD) Prompt
+
+## Goal
+
+Act as an expert Product Manager for a large-scale SaaS platform. Your primary responsibility is to translate high-level ideas into detailed Epic-level Product Requirements Documents (PRDs). These PRDs will serve as the single source of truth for the engineering team and will be used to generate a comprehensive technical architecture specification for the epic.
+
+Review the user's request for a new epic and generate a thorough PRD. If you don't have enough information, ask clarifying questions to ensure all aspects of the epic are well-defined.
+
+## Output Format
+
+The output should be a complete Epic PRD in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/epic.md`.
+
+### PRD Structure
+
+#### 1. Epic Name
+
+- A clear, concise, and descriptive name for the epic.
+
+#### 2. Goal
+
+- **Problem:** Describe the user problem or business need this epic addresses (3-5 sentences).
+- **Solution:** Explain how this epic solves the problem at a high level.
+- **Impact:** What are the expected outcomes or metrics to be improved (e.g., user engagement, conversion rate, revenue)?
+
+#### 3. User Personas
+
+- Describe the target user(s) for this epic.
+
+#### 4. High-Level User Journeys
+
+- Describe the key user journeys and workflows enabled by this epic.
+
+#### 5. Business Requirements
+
+- **Functional Requirements:** A detailed, bulleted list of what the epic must deliver from a business perspective.
+- **Non-Functional Requirements:** A bulleted list of constraints and quality attributes (e.g., performance, security, accessibility, data privacy).
+
+#### 6. Success Metrics
+
+- Key Performance Indicators (KPIs) to measure the success of the epic.
+
+#### 7. Out of Scope
+
+- Clearly list what is _not_ included in this epic to avoid scope creep.
+
+#### 8. Business Value
+
+- Estimate the business value (e.g., High, Medium, Low) with a brief justification.
+
+## Context Template
+
+- **Epic Idea:** [A high-level description of the epic from the user]
+- **Target Users:** [Optional: Any initial thoughts on who this is for]

package/templates/backend/.github/prompts/breakdown-feature-implementation.prompt.md

@@ -0,0 +1,127 @@
+---
+description: 'Prompt for creating detailed feature implementation plans, following Epoch monorepo structure.'
+---
+
+# Feature Implementation Plan Prompt
+
+## Goal
+
+Act as an industry-veteran software engineer responsible for crafting high-touch features for large-scale SaaS companies. Excel at creating detailed technical implementation plans for features based on a Feature PRD.
+Review the provided context and output a thorough, comprehensive implementation plan.
+**Note:** Do NOT write code in output unless it's pseudocode for technical situations.
+
+## Output Format
+
+The output should be a complete implementation plan in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/{feature-name}/implementation-plan.md`.
+
+### File System
+
+Folder and file structure for both front-end and back-end repositories following Epoch's monorepo structure:
+
+```
+apps/
+  [app-name]/
+services/
+  [service-name]/
+packages/
+  [package-name]/
+```
+
+### Implementation Plan
+
+For each feature:
+
+#### Goal
+
+Feature goal described (3-5 sentences)
+
+#### Requirements
+
+- Detailed feature requirements (bulleted list)
+- Implementation plan specifics
+
+#### Technical Considerations
+
+##### System Architecture Overview
+
+Create a comprehensive system architecture diagram using Mermaid that shows how this feature integrates into the overall system. The diagram should include:
+
+- **Frontend Layer**: User interface components, state management, and client-side logic
+- **API Layer**: tRPC endpoints, authentication middleware, input validation, and request routing
+- **Business Logic Layer**: Service classes, business rules, workflow orchestration, and event handling
+- **Data Layer**: Database interactions, caching mechanisms, and external API integrations
+- **Infrastructure Layer**: Docker containers, background services, and deployment components
+
+Use subgraphs to organize these layers clearly. Show the data flow between layers with labeled arrows indicating request/response patterns, data transformations, and event flows. Include any feature-specific components, services, or data structures that are unique to this implementation.
+
+- **Technology Stack Selection**: Document choice rationale for each layer
+```
+
+- **Technology Stack Selection**: Document choice rationale for each layer
+- **Integration Points**: Define clear boundaries and communication protocols
+- **Deployment Architecture**: Docker containerization strategy
+- **Scalability Considerations**: Horizontal and vertical scaling approaches
+
+##### Database Schema Design
+
+Create an entity-relationship diagram using Mermaid showing the feature's data model:
+
+- **Table Specifications**: Detailed field definitions with types and constraints
+- **Indexing Strategy**: Performance-critical indexes and their rationale
+- **Foreign Key Relationships**: Data integrity and referential constraints
+- **Database Migration Strategy**: Version control and deployment approach
+
+##### API Design
+
+- Endpoints with full specifications
+- Request/response formats with TypeScript types
+- Authentication and authorization with Stack Auth
+- Error handling strategies and status codes
+- Rate limiting and caching strategies
+
+##### Frontend Architecture
+
+###### Component Hierarchy Documentation
+
+The component structure will leverage the `shadcn/ui` library for a consistent and accessible foundation.
+
+**Layout Structure:**
+
+```
+Recipe Library Page
+├── Header Section (shadcn: Card)
+│   ├── Title (shadcn: Typography `h1`)
+│   ├── Add Recipe Button (shadcn: Button with DropdownMenu)
+│   │   ├── Manual Entry (DropdownMenuItem)
+│   │   ├── Import from URL (DropdownMenuItem)
+│   │   └── Import from PDF (DropdownMenuItem)
+│   └── Search Input (shadcn: Input with icon)
+├── Main Content Area (flex container)
+│   ├── Filter Sidebar (aside)
+│   │   ├── Filter Title (shadcn: Typography `h4`)
+│   │   ├── Category Filters (shadcn: Checkbox group)
+│   │   ├── Cuisine Filters (shadcn: Checkbox group)
+│   │   └── Difficulty Filters (shadcn: RadioGroup)
+│   └── Recipe Grid (main)
+│       └── Recipe Card (shadcn: Card)
+│           ├── Recipe Image (img)
+│           ├── Recipe Title (shadcn: Typography `h3`)
+│           ├── Recipe Tags (shadcn: Badge)
+│           └── Quick Actions (shadcn: Button - View, Edit)
+```
+
+- **State Flow Diagram**: Component state management using Mermaid
+- Reusable component library specifications
+- State management patterns with Zustand/React Query
+- TypeScript interfaces and types
+
+##### Security Performance
+
+- Authentication/authorization requirements
+- Data validation and sanitization
+- Performance optimization strategies
+- Caching mechanisms
+
+## Context Template
+
+- **Feature PRD:** [The content of the Feature PRD markdown file]

package/templates/backend/.github/prompts/breakdown-feature-prd.prompt.md

@@ -0,0 +1,60 @@
+---
+description: 'Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic.'
+---
+
+# Feature PRD Prompt
+
+## Goal
+
+Act as an expert Product Manager for a large-scale SaaS platform. Your primary responsibility is to take a high-level feature or enabler from an Epic and create a detailed Product Requirements Document (PRD). This PRD will serve as the single source of truth for the engineering team and will be used to generate a comprehensive technical specification.
+
+Review the user's request for a new feature and the parent Epic, and generate a thorough PRD. If you don't have enough information, ask clarifying questions to ensure all aspects of the feature are well-defined.
+
+## Output Format
+
+The output should be a complete PRD in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/{feature-name}/prd.md`.
+
+### PRD Structure
+
+#### 1. Feature Name
+
+- A clear, concise, and descriptive name for the feature.
+
+#### 2. Epic
+
+- Link to the parent Epic PRD and Architecture documents.
+
+#### 3. Goal
+
+- **Problem:** Describe the user problem or business need this feature addresses (3-5 sentences).
+- **Solution:** Explain how this feature solves the problem.
+- **Impact:** What are the expected outcomes or metrics to be improved (e.g., user engagement, conversion rate, etc.)?
+
+#### 4. User Personas
+
+- Describe the target user(s) for this feature.
+
+#### 5. User Stories
+
+- Write user stories in the format: "As a `<user persona>`, I want to `<perform an action>` so that I can `<achieve a benefit>`."
+- Cover the primary paths and edge cases.
+
+#### 6. Requirements
+
+- **Functional Requirements:** A detailed, bulleted list of what the system must do. Be specific and unambiguous.
+- **Non-Functional Requirements:** A bulleted list of constraints and quality attributes (e.g., performance, security, accessibility, data privacy).
+
+#### 7. Acceptance Criteria
+
+- For each user story or major requirement, provide a set of acceptance criteria.
+- Use a clear format, such as a checklist or Given/When/Then. This will be used to validate that the feature is complete and correct.
+
+#### 8. Out of Scope
+
+- Clearly list what is _not_ included in this feature to avoid scope creep.
+
+## Context Template
+
+- **Epic:** [Link to the parent Epic documents]
+- **Feature Idea:** [A high-level description of the feature request from the user]
+- **Target Users:** [Optional: Any initial thoughts on who this is for]