workspace-architect 1.3.0

package/assets/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/assets/instructions/springboot.instructions.md

@@ -0,0 +1,68 @@
+---
+description: 'Guidelines for building Spring Boot base applications'
+applyTo: '**/*.java, **/*.kt'
+---
+
+# Spring Boot Development
+
+## General Instructions
+
+- Make only high confidence suggestions when reviewing code changes.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle edge cases and write clear exception handling.
+- For libraries or external dependencies, mention their usage and purpose in comments.
+
+## Spring Boot Instructions
+
+### Dependency Injection
+
+- Use constructor injection for all required dependencies.
+- Declare dependency fields as `private final`.
+
+### Configuration
+
+- Use YAML files (`application.yml`) for externalized configuration.
+- Environment Profiles: Use Spring profiles for different environments (dev, test, prod)
+- Configuration Properties: Use @ConfigurationProperties for type-safe configuration binding
+- Secrets Management: Externalize secrets using environment variables or secret management systems
+
+### Code Organization
+
+- Package Structure: Organize by feature/domain rather than by layer
+- Separation of Concerns: Keep controllers thin, services focused, and repositories simple
+- Utility Classes: Make utility classes final with private constructors
+
+### Service Layer
+
+- Place business logic in `@Service`-annotated classes.
+- Services should be stateless and testable.
+- Inject repositories via the constructor.
+- Service method signatures should use domain IDs or DTOs, not expose repository entities directly unless necessary.
+
+### Logging
+
+- Use SLF4J for all logging (`private static final Logger logger = LoggerFactory.getLogger(MyClass.class);`).
+- Do not use concrete implementations (Logback, Log4j2) or `System.out.println()` directly.
+- Use parameterized logging: `logger.info("User {} logged in", userId);`.
+
+### Security & Input Handling
+
+- Use parameterized queries | Always use Spring Data JPA or `NamedParameterJdbcTemplate` to prevent SQL injection.
+- Validate request bodies and parameters using JSR-380 (`@NotNull`, `@Size`, etc.) annotations and `BindingResult`
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean package`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.
+
+## Useful Commands
+
+| Gradle Command            | Maven Command                     | Description                                   |
+|:--------------------------|:----------------------------------|:----------------------------------------------|
+| `./gradlew bootRun`       |`./mvnw spring-boot:run`           | Run the application.                          |
+| `./gradlew build`         |`./mvnw package`                   | Build the application.                        |
+| `./gradlew test`          |`./mvnw test`                      | Run tests.                                    |
+| `./gradlew bootJar`       |`./mvnw spring-boot:repackage`     | Package the application as a JAR.             |
+| `./gradlew bootBuildImage`|`./mvnw spring-boot:build-image`   | Package the application as a container image. |

package/assets/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

package/assets/instructions/svelte.instructions.md

@@ -0,0 +1,161 @@
+---
+description: 'Svelte 5 and SvelteKit development standards and best practices for component-based user interfaces and full-stack applications'
+applyTo: '**/*.svelte, **/*.ts, **/*.js, **/*.css, **/*.scss, **/*.json'
+---
+
+# Svelte 5 and SvelteKit Development Instructions
+
+Instructions for building high-quality Svelte 5 and SvelteKit applications with modern runes-based reactivity, TypeScript, and performance optimization.
+
+## Project Context
+- Svelte 5.x with runes system ($state, $derived, $effect, $props, $bindable)
+- SvelteKit for full-stack applications with file-based routing
+- TypeScript for type safety and better developer experience
+- Component-scoped styling with CSS custom properties
+- Progressive enhancement and performance-first approach
+- Modern build tooling (Vite) with optimizations
+
+## Development Standards
+
+### Architecture
+- Use Svelte 5 runes system for all reactivity instead of legacy stores
+- Organize components by feature or domain for scalability
+- Separate presentation components from logic-heavy components
+- Extract reusable logic into composable functions
+- Implement proper component composition with slots and snippets
+- Use SvelteKit's file-based routing with proper load functions
+
+### TypeScript Integration
+- Enable strict mode in `tsconfig.json` for maximum type safety
+- Define interfaces for component props using `$props()` syntax
+- Type event handlers, refs, and SvelteKit's generated types
+- Use generic types for reusable components
+- Leverage `$types.ts` files generated by SvelteKit
+- Implement proper type checking with `svelte-check`
+
+### Component Design
+- Follow single responsibility principle for components
+- Use `<script lang="ts">` with runes syntax as default
+- Keep components small and focused on one concern
+- Implement proper prop validation with TypeScript
+- Use slots and snippets for flexible composition
+- Design components to be testable and reusable
+
+### Svelte 5 Runes System
+- Use `$state()` for reactive local state management
+- Implement `$derived()` for computed values and expensive calculations
+- Use `$effect()` for side effects with proper cleanup
+- Define component props with `$props()` and destructuring
+- Use `$bindable()` for two-way data binding between components
+- Migrate from legacy stores to runes for better performance
+
+### State Management
+- Use `$state()` for local component state
+- Implement context API with `setContext`/`getContext` for shared state
+- Use SvelteKit stores for global application state when needed
+- Keep state normalized for complex data structures
+- Use derived state for computed values
+- Implement proper state persistence for client-side data
+
+### SvelteKit Patterns
+- Use `+page.svelte` for page components with proper SEO
+- Implement `+layout.svelte` for shared layouts and navigation
+- Use `+page.server.ts` for server-side data loading and API calls
+- Implement form actions in `+page.server.ts` for data mutations
+- Use `+server.ts` for API endpoints and server-side logic
+- Handle routing with SvelteKit's file-based system
+
+### Styling
+- Use component-scoped styles with `<style>` blocks
+- Implement CSS custom properties for theming and design systems
+- Use `class:` directive for conditional styling
+- Follow BEM or utility-first CSS conventions
+- Implement responsive design with mobile-first approach
+- Use `:global()` sparingly for truly global styles
+
+### Performance Optimization
+- Use keyed `{#each}` blocks for efficient list rendering
+- Implement lazy loading with dynamic imports and `svelte:component`
+- Use `$derived()` for expensive computations to avoid unnecessary recalculations
+- Leverage SvelteKit's automatic code splitting and preloading
+- Optimize bundle size with tree shaking and proper imports
+- Profile with Svelte DevTools to identify performance bottlenecks
+
+### Data Fetching
+- Use SvelteKit's load functions for server-side and universal data fetching
+- Implement proper loading, error, and success states
+- Handle streaming data with promises in server load functions
+- Use `invalidate()` and `invalidateAll()` for cache management
+- Implement optimistic updates for better user experience
+- Handle offline scenarios and network errors gracefully
+
+### Error Handling
+- Implement `+error.svelte` pages for route-level error boundaries
+- Use try/catch blocks in load functions and form actions
+- Provide meaningful error messages and fallback UI
+- Log errors appropriately for debugging and monitoring
+- Handle validation errors in forms with proper user feedback
+- Use SvelteKit's error and redirect helpers
+
+### Forms and Validation
+- Use SvelteKit's form actions for server-side form handling
+- Implement progressive enhancement with `use:enhance`
+- Use `bind:value` for controlled form inputs
+- Validate data both client-side and server-side
+- Handle file uploads and complex form scenarios
+- Implement proper accessibility with labels and ARIA attributes
+
+### Testing
+- Write unit tests for components using Vitest and Testing Library
+- Test component behavior, not implementation details
+- Use Playwright for end-to-end testing of user workflows
+- Mock SvelteKit's load functions and stores appropriately
+- Test form actions and API endpoints thoroughly
+- Implement accessibility testing with axe-core
+
+### Security
+- Sanitize user inputs to prevent XSS attacks
+- Use `@html` directive carefully and validate HTML content
+- Implement proper CSRF protection with SvelteKit
+- Validate and sanitize data in load functions and form actions
+- Use HTTPS for all external API calls and production deployments
+- Store sensitive data securely with proper session management
+
+### Accessibility
+- Use semantic HTML elements and proper heading hierarchy
+- Implement keyboard navigation for all interactive elements
+- Provide proper ARIA labels and descriptions
+- Ensure color contrast meets WCAG guidelines
+- Test with screen readers and accessibility tools
+- Implement focus management for dynamic content
+
+## Implementation Process
+1. Initialize SvelteKit project with TypeScript and desired adapters
+2. Set up project structure with proper folder organization
+3. Define TypeScript interfaces and component props
+4. Implement core components with Svelte 5 runes
+5. Add routing, layouts, and navigation with SvelteKit
+6. Implement data loading and form handling
+7. Add styling system with custom properties and responsive design
+8. Implement error handling and loading states
+9. Add comprehensive testing coverage
+10. Optimize performance and bundle size
+11. Ensure accessibility compliance
+12. Deploy with appropriate SvelteKit adapter
+
+## Additional Guidelines
+- Follow Svelte's naming conventions (PascalCase for components, camelCase for functions)
+- Use ESLint with eslint-plugin-svelte and Prettier for code consistency
+- Keep dependencies up to date and audit for security vulnerabilities
+- Document complex components and logic with JSDoc
+- Use Svelte DevTools for debugging and performance analysis
+- Implement proper SEO with SvelteKit's meta tags and structured data
+- Use environment variables for configuration across different deployment stages
+
+## Common Patterns
+- Renderless components with slots for flexible UI composition
+- Custom directives for cross-cutting concerns and DOM manipulation
+- Snippet-based composition for reusable template logic
+- Context providers for application-wide state management
+- Progressive enhancement for forms and interactive features
+- Server-side rendering with client-side hydration for optimal performance