@totaland/create-starter-kit 1.0.0 → 2.0.1

package/templates/backend/.github/instructions/self-explanatory-code-commenting.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments.'
+applyTo: '**'
+---
+
+# Self-explanatory Code Commenting Instructions
+
+## Core Principle
+**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**
+We do not need comments most of the time.
+
+## Commenting Guidelines
+
+### ❌ AVOID These Comment Types
+
+**Obvious Comments**
+```javascript
+// Bad: States the obvious
+let counter = 0;  // Initialize counter to zero
+counter++;  // Increment counter by one
+```
+
+**Redundant Comments**
+```javascript
+// Bad: Comment repeats the code
+function getUserName() {
+    return user.name;  // Return the user's name
+}
+```
+
+**Outdated Comments**
+```javascript
+// Bad: Comment doesn't match the code
+// Calculate tax at 5% rate
+const tax = price * 0.08;  // Actually 8%
+```
+
+### ✅ WRITE These Comment Types
+
+**Complex Business Logic**
+```javascript
+// Good: Explains WHY this specific calculation
+// Apply progressive tax brackets: 10% up to 10k, 20% above
+const tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);
+```
+
+**Non-obvious Algorithms**
+```javascript
+// Good: Explains the algorithm choice
+// Using Floyd-Warshall for all-pairs shortest paths
+// because we need distances between all nodes
+for (let k = 0; k < vertices; k++) {
+    for (let i = 0; i < vertices; i++) {
+        for (let j = 0; j < vertices; j++) {
+            // ... implementation
+        }
+    }
+}
+```
+
+**Regex Patterns**
+```javascript
+// Good: Explains what the regex matches
+// Match email format: username@domain.extension
+const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+```
+
+**API Constraints or Gotchas**
+```javascript
+// Good: Explains external constraint
+// GitHub API rate limit: 5000 requests/hour for authenticated users
+await rateLimiter.wait();
+const response = await fetch(githubApiUrl);
+```
+
+## Decision Framework
+
+Before writing a comment, ask:
+1. **Is the code self-explanatory?** → No comment needed
+2. **Would a better variable/function name eliminate the need?** → Refactor instead
+3. **Does this explain WHY, not WHAT?** → Good comment
+4. **Will this help future maintainers?** → Good comment
+
+## Special Cases for Comments
+
+### Public APIs
+```javascript
+/**
+ * Calculate compound interest using the standard formula.
+ * 
+ * @param {number} principal - Initial amount invested
+ * @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
+ * @param {number} time - Time period in years
+ * @param {number} compoundFrequency - How many times per year interest compounds (default: 1)
+ * @returns {number} Final amount after compound interest
+ */
+function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
+    // ... implementation
+}
+```
+
+### Configuration and Constants
+```javascript
+// Good: Explains the source or reasoning
+const MAX_RETRIES = 3;  // Based on network reliability studies
+const API_TIMEOUT = 5000;  // AWS Lambda timeout is 15s, leaving buffer
+```
+
+### Annotations
+```javascript
+// TODO: Replace with proper user authentication after security review
+// FIXME: Memory leak in production - investigate connection pooling
+// HACK: Workaround for bug in library v2.1.0 - remove after upgrade
+// NOTE: This implementation assumes UTC timezone for all calculations
+// WARNING: This function modifies the original array instead of creating a copy
+// PERF: Consider caching this result if called frequently in hot path
+// SECURITY: Validate input to prevent SQL injection before using in query
+// BUG: Edge case failure when array is empty - needs investigation
+// REFACTOR: Extract this logic into separate utility function for reusability
+// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0
+```
+
+## Anti-Patterns to Avoid
+
+### Dead Code Comments
+```javascript
+// Bad: Don't comment out code
+// const oldFunction = () => { ... };
+const newFunction = () => { ... };
+```
+
+### Changelog Comments
+```javascript
+// Bad: Don't maintain history in comments
+// Modified by John on 2023-01-15
+// Fixed bug reported by Sarah on 2023-02-03
+function processData() {
+    // ... implementation
+}
+```
+
+### Divider Comments
+```javascript
+// Bad: Don't use decorative comments
+//=====================================
+// UTILITY FUNCTIONS
+//=====================================
+```
+
+## Quality Checklist
+
+Before committing, ensure your comments:
+- [ ] Explain WHY, not WHAT
+- [ ] Are grammatically correct and clear
+- [ ] Will remain accurate as code evolves
+- [ ] Add genuine value to code understanding
+- [ ] Are placed appropriately (above the code they describe)
+- [ ] Use proper spelling and professional language
+
+## Summary
+
+Remember: **The best comment is the one you don't need to write because the code is self-documenting.**

package/templates/backend/.github/instructions/spec-driven-workflow-v1.instructions.md

@@ -0,0 +1,323 @@
+---
+description: 'Specification-Driven Workflow v1 provides a structured approach to software development, ensuring that requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented and validated.'
+applyTo: '**'
+---
+# Spec Driven Workflow v1
+
+**Specification-Driven Workflow:**
+Bridge the gap between requirements and implementation.
+
+**Maintain these artifacts at all times:**
+
+- **`requirements.md`**: User stories and acceptance criteria in structured EARS notation.
+- **`design.md`**: Technical architecture, sequence diagrams, implementation considerations.
+- **`tasks.md`**: Detailed, trackable implementation plan.
+
+## Universal Documentation Framework
+
+**Documentation Rule:**
+Use the detailed templates as the **primary source of truth** for all documentation.
+
+**Summary formats:**
+Use only for concise artifacts such as changelogs and pull request descriptions.
+
+### Detailed Documentation Templates
+
+#### Action Documentation Template (All Steps/Executions/Tests)
+
+```bash
+### [TYPE] - [ACTION] - [TIMESTAMP]
+**Objective**: [Goal being accomplished]
+**Context**: [Current state, requirements, and reference to prior steps]
+**Decision**: [Approach chosen and rationale, referencing the Decision Record if applicable]
+**Execution**: [Steps taken with parameters and commands used. For code, include file paths.]
+**Output**: [Complete and unabridged results, logs, command outputs, and metrics]
+**Validation**: [Success verification method and results. If failed, include a remediation plan.]
+**Next**: [Automatic continuation plan to the next specific action]
+```
+
+#### Decision Record Template (All Decisions)
+
+```bash
+### Decision - [TIMESTAMP]
+**Decision**: [What was decided]
+**Context**: [Situation requiring decision and data driving it]
+**Options**: [Alternatives evaluated with brief pros and cons]
+**Rationale**: [Why the selected option is superior, with trade-offs explicitly stated]
+**Impact**: [Anticipated consequences for implementation, maintainability, and performance]
+**Review**: [Conditions or schedule for reassessing this decision]
+```
+
+### Summary Formats (for Reporting)
+
+#### Streamlined Action Log
+
+For generating concise changelogs. Each log entry is derived from a full Action Document.
+
+`[TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]`
+
+#### Compressed Decision Record
+
+For use in pull request summaries or executive summaries.
+
+`Decision: [X] | Rationale: [Y] | Impact: [Z] | Review: [Date]`
+
+## Execution Workflow (6-Phase Loop)
+
+**Never skip any step. Use consistent terminology. Reduce ambiguity.**
+
+### **Phase 1: ANALYZE**
+
+**Objective:**
+
+- Understand the problem.
+- Analyze the existing system.
+- Produce a clear, testable set of requirements.
+- Think about the possible solutions and their implications.
+
+**Checklist:**
+
+- [ ] Read all provided code, documentation, tests, and logs.
+      - Document file inventory, summaries, and initial analysis results.
+- [ ] Define requirements in **EARS Notation**:
+      - Transform feature requests into structured, testable requirements.
+      - Format: `WHEN [a condition or event], THE SYSTEM SHALL [expected behavior]`
+- [ ] Identify dependencies and constraints.
+      - Document a dependency graph with risks and mitigation strategies.
+- [ ] Map data flows and interactions.
+      - Document system interaction diagrams and data models.
+- [ ] Catalog edge cases and failures.
+      - Document a comprehensive edge case matrix and potential failure points.
+- [ ] Assess confidence.
+      - Generate a **Confidence Score (0-100%)** based on clarity of requirements, complexity, and problem scope.
+      - Document the score and its rationale.
+
+**Critical Constraint:**
+
+- **Do not proceed until all requirements are clear and documented.**
+
+### **Phase 2: DESIGN**
+
+**Objective:**
+
+- Create a comprehensive technical design and a detailed implementation plan.
+
+**Checklist:**
+
+- [ ] **Define adaptive execution strategy based on Confidence Score:**
+  - **High Confidence (>85%)**
+    - Draft a comprehensive, step-by-step implementation plan.
+    - Skip proof-of-concept steps.
+    - Proceed with full, automated implementation.
+    - Maintain standard comprehensive documentation.
+  - **Medium Confidence (66–85%)**
+    - Prioritize a **Proof-of-Concept (PoC)** or **Minimum Viable Product (MVP)**.
+    - Define clear success criteria for PoC/MVP.
+    - Build and validate PoC/MVP first, then expand plan incrementally.
+    - Document PoC/MVP goals, execution, and validation results.
+  - **Low Confidence (<66%)**
+    - Dedicate first phase to research and knowledge-building.
+    - Use semantic search and analyze similar implementations.
+    - Synthesize findings into a research document.
+    - Re-run ANALYZE phase after research.
+    - Escalate only if confidence remains low.
+
+- [ ] **Document technical design in `design.md`:**
+  - **Architecture:** High-level overview of components and interactions.
+  - **Data Flow:** Diagrams and descriptions.
+  - **Interfaces:** API contracts, schemas, public-facing function signatures.
+  - **Data Models:** Data structures and database schemas.
+
+- [ ] **Document error handling:**
+  - Create an error matrix with procedures and expected responses.
+
+- [ ] **Define unit testing strategy.**
+
+- [ ] **Create implementation plan in `tasks.md`:**
+  - For each task, include description, expected outcome, and dependencies.
+
+**Critical Constraint:**
+
+- **Do not proceed to implementation until design and plan are complete and validated.**
+
+### **Phase 3: IMPLEMENT**
+
+**Objective:**
+
+- Write production-quality code according to the design and plan.
+
+**Checklist:**
+
+- [ ] Code in small, testable increments.
+      - Document each increment with code changes, results, and test links.
+- [ ] Implement from dependencies upward.
+      - Document resolution order, justification, and verification.
+- [ ] Follow conventions.
+      - Document adherence and any deviations with a Decision Record.
+- [ ] Add meaningful comments.
+      - Focus on intent ("why"), not mechanics ("what").
+- [ ] Create files as planned.
+      - Document file creation log.
+- [ ] Update task status in real time.
+
+**Critical Constraint:**
+
+- **Do not merge or deploy code until all implementation steps are documented and tested.**
+
+### **Phase 4: VALIDATE**
+
+**Objective:**
+
+- Verify that implementation meets all requirements and quality standards.
+
+**Checklist:**
+
+- [ ] Execute automated tests.
+      - Document outputs, logs, and coverage reports.
+      - For failures, document root cause analysis and remediation.
+- [ ] Perform manual verification if necessary.
+      - Document procedures, checklists, and results.
+- [ ] Test edge cases and errors.
+      - Document results and evidence of correct error handling.
+- [ ] Verify performance.
+      - Document metrics and profile critical sections.
+- [ ] Log execution traces.
+      - Document path analysis and runtime behavior.
+
+**Critical Constraint:**
+
+- **Do not proceed until all validation steps are complete and all issues are resolved.**
+
+### **Phase 5: REFLECT**
+
+**Objective:**
+
+- Improve codebase, update documentation, and analyze performance.
+
+**Checklist:**
+
+- [ ] Refactor for maintainability.
+      - Document decisions, before/after comparisons, and impact.
+- [ ] Update all project documentation.
+      - Ensure all READMEs, diagrams, and comments are current.
+- [ ] Identify potential improvements.
+      - Document backlog with prioritization.
+- [ ] Validate success criteria.
+      - Document final verification matrix.
+- [ ] Perform meta-analysis.
+      - Reflect on efficiency, tool usage, and protocol adherence.
+- [ ] Auto-create technical debt issues.
+      - Document inventory and remediation plans.
+
+**Critical Constraint:**
+
+- **Do not close the phase until all documentation and improvement actions are logged.**
+
+### **Phase 6: HANDOFF**
+
+**Objective:**
+
+- Package work for review and deployment, and transition to next task.
+
+**Checklist:**
+
+- [ ] Generate executive summary.
+      - Use **Compressed Decision Record** format.
+- [ ] Prepare pull request (if applicable):
+    1. Executive summary.
+    2. Changelog from **Streamlined Action Log**.
+    3. Links to validation artifacts and Decision Records.
+    4. Links to final `requirements.md`, `design.md`, and `tasks.md`.
+- [ ] Finalize workspace.
+      - Archive intermediate files, logs, and temporary artifacts to `.agent_work/`.
+- [ ] Continue to next task.
+      - Document transition or completion.
+
+**Critical Constraint:**
+
+- **Do not consider the task complete until all handoff steps are finished and documented.**
+
+## Troubleshooting & Retry Protocol
+
+**If you encounter errors, ambiguities, or blockers:**
+
+**Checklist:**
+
+1. **Re-analyze**:
+   - Revisit the ANALYZE phase.
+   - Confirm all requirements and constraints are clear and complete.
+2. **Re-design**:
+   - Revisit the DESIGN phase.
+   - Update technical design, plans, or dependencies as needed.
+3. **Re-plan**:
+   - Adjust the implementation plan in `tasks.md` to address new findings.
+4. **Retry execution**:
+   - Re-execute failed steps with corrected parameters or logic.
+5. **Escalate**:
+   - If the issue persists after retries, follow the escalation protocol.
+
+**Critical Constraint:**
+
+- **Never proceed with unresolved errors or ambiguities. Always document troubleshooting steps and outcomes.**
+
+## Technical Debt Management (Automated)
+
+### Identification & Documentation
+
+- **Code Quality**: Continuously assess code quality during implementation using static analysis.
+- **Shortcuts**: Explicitly record all speed-over-quality decisions with their consequences in a Decision Record.
+- **Workspace**: Monitor for organizational drift and naming inconsistencies.
+- **Documentation**: Track incomplete, outdated, or missing documentation.
+
+### Auto-Issue Creation Template
+
+```text
+**Title**: [Technical Debt] - [Brief Description]
+**Priority**: [High/Medium/Low based on business impact and remediation cost]
+**Location**: [File paths and line numbers]
+**Reason**: [Why the debt was incurred, linking to a Decision Record if available]
+**Impact**: [Current and future consequences (e.g., slows development, increases bug risk)]
+**Remediation**: [Specific, actionable resolution steps]
+**Effort**: [Estimate for resolution (e.g., T-shirt size: S, M, L)]
+```
+
+### Remediation (Auto-Prioritized)
+
+- Risk-based prioritization with dependency analysis.
+- Effort estimation to aid in future planning.
+- Propose migration strategies for large refactoring efforts.
+
+## Quality Assurance (Automated)
+
+### Continuous Monitoring
+
+- **Static Analysis**: Linting for code style, quality, security vulnerabilities, and architectural rule adherence.
+- **Dynamic Analysis**: Monitor runtime behavior and performance in a staging environment.
+- **Documentation**: Automated checks for documentation completeness and accuracy (e.g., linking, format).
+
+### Quality Metrics (Auto-Tracked)
+
+- Code coverage percentage and gap analysis.
+- Cyclomatic complexity score per function/method.
+- Maintainability index assessment.
+- Technical debt ratio (e.g., estimated remediation time vs. development time).
+- Documentation coverage percentage (e.g., public methods with comments).
+
+## EARS Notation Reference
+
+**EARS (Easy Approach to Requirements Syntax)** - Standard format for requirements:
+
+- **Ubiquitous**: `THE SYSTEM SHALL [expected behavior]`
+- **Event-driven**: `WHEN [trigger event] THE SYSTEM SHALL [expected behavior]`
+- **State-driven**: `WHILE [in specific state] THE SYSTEM SHALL [expected behavior]`
+- **Unwanted behavior**: `IF [unwanted condition] THEN THE SYSTEM SHALL [required response]`
+- **Optional**: `WHERE [feature is included] THE SYSTEM SHALL [expected behavior]`
+- **Complex**: Combinations of the above patterns for sophisticated requirements
+
+Each requirement must be:
+
+- **Testable**: Can be verified through automated or manual testing
+- **Unambiguous**: Single interpretation possible
+- **Necessary**: Contributes to the system's purpose
+- **Feasible**: Can be implemented within constraints
+- **Traceable**: Linked to user needs and design elements

package/templates/backend/.github/instructions/sql-sp-generation.instructions.md

@@ -0,0 +1,74 @@
+---
+description: 'Guidelines for generating SQL statements and stored procedures'
+applyTo: '**/*.sql'
+---
+
+# SQL Development
+
+## Database schema generation
+- all table names should be in singular form
+- all column names should be in singular form
+- all tables should have a primary key column named `id`
+- all tables should have a column named `created_at` to store the creation timestamp
+- all tables should have a column named `updated_at` to store the last update timestamp
+
+## Database schema design
+- all tables should have a primary key constraint
+- all foreign key constraints should have a name
+- all foreign key constraints should be defined inline
+- all foreign key constraints should have `ON DELETE CASCADE` option
+- all foreign key constraints should have `ON UPDATE CASCADE` option
+- all foreign key constraints should reference the primary key of the parent table
+
+## SQL Coding Style
+- use uppercase for SQL keywords (SELECT, FROM, WHERE)
+- use consistent indentation for nested queries and conditions
+- include comments to explain complex logic
+- break long queries into multiple lines for readability
+- organize clauses consistently (SELECT, FROM, JOIN, WHERE, GROUP BY, HAVING, ORDER BY)
+
+## SQL Query Structure
+- use explicit column names in SELECT statements instead of SELECT *
+- qualify column names with table name or alias when using multiple tables
+- limit the use of subqueries when joins can be used instead
+- include LIMIT/TOP clauses to restrict result sets
+- use appropriate indexing for frequently queried columns
+- avoid using functions on indexed columns in WHERE clauses
+
+## Stored Procedure Naming Conventions
+- prefix stored procedure names with 'usp_'
+- use PascalCase for stored procedure names
+- use descriptive names that indicate purpose (e.g., usp_GetCustomerOrders)
+- include plural noun when returning multiple records (e.g., usp_GetProducts)
+- include singular noun when returning single record (e.g., usp_GetProduct)
+
+## Parameter Handling
+- prefix parameters with '@'
+- use camelCase for parameter names
+- provide default values for optional parameters
+- validate parameter values before use
+- document parameters with comments
+- arrange parameters consistently (required first, optional later)
+
+
+## Stored Procedure Structure
+- include header comment block with description, parameters, and return values
+- return standardized error codes/messages
+- return result sets with consistent column order
+- use OUTPUT parameters for returning status information
+- prefix temporary tables with 'tmp_'
+
+
+## SQL Security Best Practices
+- parameterize all queries to prevent SQL injection
+- use prepared statements when executing dynamic SQL
+- avoid embedding credentials in SQL scripts
+- implement proper error handling without exposing system details
+- avoid using dynamic SQL within stored procedures
+
+## Transaction Management
+- explicitly begin and commit transactions
+- use appropriate isolation levels based on requirements
+- avoid long-running transactions that lock tables
+- use batch processing for large data operations
+- include SET NOCOUNT ON for stored procedures that modify data