@brunosps00/dev-workflow 0.0.3

package/scaffold/en/commands/run-task.md

@@ -0,0 +1,174 @@
+<system_instructions>
+You are an AI assistant responsible for implementing software development tasks. Your job is to identify the next available task, perform the necessary setup, implement, and validate before committing.
+
+<critical>You must not rush to finish the task. Always check the necessary files, verify the tests, and go through a reasoning process to ensure both understanding and correct execution.</critical>
+<critical>THE TASK CANNOT BE CONSIDERED COMPLETE UNTIL ALL TESTS ARE PASSING</critical>
+
+## Complementary Skills
+
+When available in the project at `./.agents/skills/`, use these skills as specialized support without replacing this command:
+
+- `vercel-react-best-practices`: use when the task touches React/Next.js, especially for rendering, data fetching, hydration, bundle, cache, and performance
+- `webapp-testing`: use when the task requires functional frontend validation in a real browser
+- `agent-browser`: use when UI validation requires persistent session, operational navigation inspection, or complementary visual evidence
+
+## File Locations
+
+- PRD: `./spec/prd-[feature-name]/prd.md`
+- Tech Spec: `./spec/prd-[feature-name]/techspec.md`
+- Tasks: `./spec/prd-[feature-name]/tasks.md`
+- Project Rules: `ai/rules/`
+
+## Steps to Execute
+
+### 0. Verify Branch
+- Confirm you are on the branch `feat/prd-[feature-name]`
+- If not: `git checkout feat/prd-[feature-name]`
+
+### 1. Pre-Task Setup
+- Read the task definition (`[num]_task.md`)
+- Review the PRD context
+- Verify tech spec requirements (including testing strategy)
+- Understand dependencies from previous tasks
+
+### 2. Task Analysis
+Analyze considering:
+- Main objectives of the task
+- How the task fits into the project context
+- Alignment with project rules and patterns (`ai/rules/`)
+- Possible solutions or approaches
+- If React/Next.js is in scope, explicitly incorporate relevant heuristics from `vercel-react-best-practices`
+
+### 3. Task Summary
+
+```
+Task ID: [ID or number]
+Task Name: [Name or brief description]
+PRD Context: [Key points from the PRD]
+Tech Spec Requirements: [Key technical requirements]
+Dependencies: [List of dependencies]
+Main Objectives: [Primary objectives]
+Risks/Challenges: [Identified risks or challenges]
+```
+
+### 4. Approach Plan
+
+```
+1. [First step]
+2. [Second step]
+3. [Additional steps as needed]
+```
+
+## Implementation
+
+After providing the summary and approach, **begin implementation immediately**:
+- Execute necessary commands
+- Make code changes
+- **Implement unit tests** (mandatory for backend)
+- Follow established project patterns
+- Ensure all requirements are met
+- **Run tests**: use the project's test command
+- If there is interactive frontend, also validate real behavior with `webapp-testing` or `agent-browser` when doing so reduces the risk of invisible regression in unit tests
+
+**YOU MUST** start the implementation right after the process above.
+
+<critical>Use the Context7 MCP to look up documentation for the language, frameworks, and libraries involved in the implementation</critical>
+
+## Important Notes
+
+- Always verify against the PRD, tech spec, and task file
+- Implement proper solutions **without using hacks or workarounds**
+- Follow all established project patterns
+
+## Post-Implementation Validation - Level 1 (Required)
+
+<critical>This validation is MANDATORY before the commit. If it fails, fix and re-validate.</critical>
+
+After implementing, execute the lightweight validation (Level 1):
+
+### Acceptance Criteria Checklist
+For each acceptance criterion defined in the task:
+- Verify it was implemented with evidence in the code
+- If any criterion was not met: **FIX before proceeding**
+
+### Test Execution
+```bash
+# Run tests for the impacted project
+pnpm test   # or npm test
+```
+- [ ] All tests pass (existing + new)
+- [ ] New tests were created for new code
+- If any test fails: **FIX before proceeding**
+
+### Basic Standards Verification
+- [ ] Explicit types (no `any`)
+- [ ] Code compiles without errors
+- [ ] Lint passes
+- [ ] Multi-tenancy respected (if applicable)
+- [ ] Project patterns followed (`ai/rules/`)
+
+### Functional UI Verification (for tasks with frontend)
+<critical>Placeholder/stub pages are NOT acceptable deliverables for user interaction FRs.</critical>
+- [ ] Each page/route created renders functional content (NOT a generic placeholder)
+- [ ] If the task covers a listing FR: the page shows a table/list with real API data
+- [ ] If the task covers a creation FR: the page has a functional form/dialog
+- [ ] If the task covers a configuration FR: the page displays and allows editing the parameters
+- [ ] No page shows a generic message like "initial foundation", "protected base", or "placeholder"
+- If any verification fails: **the task is NOT complete -- implement the real UI before committing**
+
+### Created Artifacts Documentation (MANDATORY)
+
+<critical>
+When finishing each task, RECORD in the project's tasks.md a "Created Artifacts" section with:
+
+1. **New API routes**: method + path (e.g., `GET /module/resource`)
+2. **New frontend pages**:
+   - URL (e.g., `/module/page`)
+   - How it is accessed: via menu (sidebar item) OR via link on another page (specify which)
+3. **Reusable components created**: name + location
+
+A page that is NOT accessible via the menu NOR via another page is USELESS -- ensure
+every new page has at least one access path for the user.
+</critical>
+
+Format in tasks.md (add after marking the task as completed):
+
+```markdown
+### Artifacts from Task X.0
+
+| Artifact | Type | Access |
+|----------|------|--------|
+| `GET /module/resource` | API | -- |
+| `/module/page` | Page | Menu: Module > Item |
+| `/module/page/sub` | Page | Link "Action" on page `/module/page` |
+| `ComponentScreen` | Component | Used by pages X, Y, Z |
+```
+
+### Validation Result
+- **If ALL OK**: Proceed to the commit
+- **If FAILURE**: Fix the issues and re-execute the validation
+- **DO NOT generate a report file** - only output in the terminal
+
+## Automatic Commit (Required)
+
+At the end of the task (after Level 1 validation passes), **always** commit (no push):
+
+```bash
+git status
+git add .
+git commit -m "feat([module]): [concise description]
+
+- [item 1 implemented]
+- [item 2 implemented]
+- Add unit tests"
+```
+
+**Note**: The push will only be done at PR creation when all tasks are completed.
+
+<critical>After completing the task, mark it as complete in tasks.md</critical>
+
+## Next Steps
+
+- If there are more tasks: `run-task [next-task]`
+- If last task: create PR (e.g., targeting `main`)
+</system_instructions>

package/scaffold/en/templates/bugfix-template.md

@@ -0,0 +1,91 @@
+# Bugfix: [Bug Name]
+
+## Problem Summary
+
+| Field | Value |
+|-------|-------|
+| **Affected Project(s)** | [project1, project2, etc.] |
+| **Severity** | [critical / high / medium / low] |
+| **Environment** | [production / staging / development] |
+| **Reported on** | [date] |
+| **Reported by** | [name/channel] |
+
+## Bug Description
+
+[Describe the incorrect behavior observed. Be specific about what happens vs what should happen.]
+
+## Steps to Reproduce
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+4. [Observed result]
+
+**Test data:** [If applicable, include data needed to reproduce]
+
+## Expected Behavior
+
+[Describe the correct behavior that should occur]
+
+## Evidence
+
+### Logs/Stack Trace
+```
+[Paste relevant logs or stack traces]
+```
+
+### Screenshots/Videos
+[If applicable]
+
+### Related Commits
+- [hash] - [description]
+
+## Root Cause Analysis
+
+### Symptom
+[What the user observes]
+
+### Identified Cause
+[Technical explanation of the bug's cause]
+
+### Affected Files
+| File | Change Type | Description |
+|------|-------------|-------------|
+| [path] | [fix/test/config] | [what to change] |
+
+## Impact
+
+### Affected Users
+[How many users? Which personas?]
+
+### Impacted Features
+[List of features that depend on the buggy code]
+
+### Regression Risk
+[low / medium / high] - [justification]
+
+## Proposed Solution
+
+[Describe the fix approach at a high level]
+
+### Alternatives Considered
+| Alternative | Pros | Cons |
+|-------------|------|------|
+| [option 1] | | |
+| [option 2] | | |
+
+## Acceptance Criteria
+
+- [ ] Bug no longer reproduces following the described steps
+- [ ] Automated tests cover the scenario
+- [ ] No regression in related features
+- [ ] [Other specific criteria]
+
+## Out of Scope
+
+[What will NOT be fixed in this bugfix - future improvements, refactoring, etc.]
+
+## Open Questions
+
+- [ ] [Question 1]
+- [ ] [Question 2]

package/scaffold/en/templates/prd-template.md

@@ -0,0 +1,70 @@
+# Product Requirements Document (PRD) Template
+
+## Overview
+
+[Provide a high-level overview of your product/feature. Explain what problem it solves, who it's for, and why it's valuable.]
+
+## Goals
+
+[List specific, measurable goals for this feature:
+
+- What success looks like
+- Key metrics to track
+- Business objectives to achieve]
+
+## User Stories
+
+[Detail user narratives describing feature usage and benefits:
+
+- As a [user type], I want to [perform an action] so that [benefit]
+- Include primary and secondary user personas
+- Cover main flows and edge cases]
+
+## Core Features
+
+[List and describe your product's core features. For each feature, include:
+
+- What it does
+- Why it's important
+- How it works at a high level
+- Functional requirements (numbered for clarity)]
+
+## User Experience
+
+[Describe the user journey and experience:
+
+- User personas and their needs
+- Main user flows and interactions
+- UI/UX considerations and requirements
+- Accessibility requirements]
+
+## High-Level Technical Constraints
+
+[Capture only high-level constraints and considerations (avoid design solutions -- those belong in the Tech Spec):
+
+- Required external integrations or existing systems to interface with
+- Compliance, regulatory, or security mandates
+- Performance/scalability targets (e.g., expected TPS, upper latency bounds)
+- Data sensitivity/privacy considerations
+- Non-negotiable technology or protocol requirements
+
+Implementation details will be addressed in the Technical Specification.]
+
+## Out of Scope
+
+[Clearly state what this feature will NOT include to manage scope:
+
+- Explicitly excluded features
+- Future considerations that are out of scope
+- Boundaries and limitations
+
+(Note: Technical implementation risks will be detailed in the Tech Spec.)]
+
+## Open Questions
+
+[List any remaining questions or areas needing additional clarification:
+
+- Unclear requirements or edge cases
+- Questions about user needs or business goals
+- Dependencies on external business factors
+- Areas requiring design or user research]

package/scaffold/en/templates/task-template.md

@@ -0,0 +1,62 @@
+# Task X.0: [Main Task Title]
+
+<critical>Read the prd.md and techspec.md files in this folder. If you don't read these files your task will be invalidated.</critical>
+
+## Overview
+
+[Brief task description]
+
+**Functional Requirements covered**: FR[X.Y], FR[X.Z] (maximum 2 per task)
+
+<requirements>
+[List of mandatory requirements]
+</requirements>
+
+## Subtasks
+
+### Implementation
+- [ ] X.1 [Subtask description]
+- [ ] X.2 [Subtask description]
+
+### Unit Tests (Mandatory for Backend)
+- [ ] X.3 Create tests for [service/use-case]
+- [ ] X.4 Create tests for [controller/adapter]
+
+## Unit Tests
+
+### Test Cases
+
+| Method | Cases |
+|--------|-------|
+| `[method1]` | Happy path, edge case, error |
+| `[method2]` | Happy path, not found |
+
+### Required Mocks
+- `[repository/service]` - mocked via mock function
+
+## Implementation Details
+
+[Relevant sections from the tech spec - reference techspec.md instead of duplicating content]
+
+## Success Criteria
+
+- [Measurable outcomes]
+- [Quality requirements]
+- **Unit tests passing**
+- **Minimum 80% coverage** on services/use-cases
+
+## Relevant Files
+- [Files relevant to this task]
+- [File].spec.ts - Unit tests
+
+## Commit on Completion
+
+When completing this task, commit:
+```bash
+git add .
+git commit -m "feat([module]): [description]
+
+- [item 1]
+- [item 2]
+- Add unit tests"
+```

package/scaffold/en/templates/tasks-template.md

@@ -0,0 +1,34 @@
+# Implementation Tasks Summary for [Feature]
+
+## Branch
+
+```
+feat/prd-[feature-name]
+```
+
+## Impacted Projects
+
+- [ ] [Project 1]
+- [ ] [Project 2]
+
+## Tasks
+
+| Task | Description | FRs | Status |
+|------|-------------|-----|--------|
+| 1.0 | [Title] | FR1.1, FR1.2 | Pending |
+| 2.0 | [Title] | FR2.1 | Pending |
+| 3.0 | [Title] | FR3.1, FR3.2 | Pending |
+
+## Progress
+
+- [ ] 1.0 Main Task Title
+- [ ] 2.0 Main Task Title
+- [ ] 3.0 Main Task Title
+
+## Workflow
+
+Each task follows this flow:
+1. `/execute-task [N]_task.md` - Implements the task
+2. Unit tests included in the implementation
+3. Commit at the end of each task (no push)
+4. Next task or `/generate-pr [target-branch]` when all tasks are completed

package/scaffold/en/templates/techspec-template.md

@@ -0,0 +1,123 @@
+# Technical Specification Template
+
+## Executive Summary
+
+[Provide a brief technical overview of the solution approach. Summarize the key architectural decisions and implementation strategy in 1-2 paragraphs.]
+
+## System Architecture
+
+### Component Overview
+
+[Brief description of main components and their responsibilities:
+
+- Component names and primary functions
+- Key relationships between components
+- Data flow overview]
+
+## Implementation Design
+
+### Key Interfaces
+
+[Define main service interfaces (<=20 lines per example):
+
+```
+// Example interface definition
+type ServiceName interface {
+    MethodName(ctx context.Context, input Type) (output Type, error)
+}
+```
+
+]
+
+### Data Models
+
+[Define essential data structures:
+
+- Core domain entities (if applicable)
+- Request/response types
+- Database schemas (if applicable)]
+
+### API Endpoints
+
+[List API endpoints if applicable:
+
+- Method and path (e.g., `POST /api/v0/resource`)
+- Brief description
+- Request/response format references]
+
+## Integration Points
+
+[Include only if the feature requires external integrations:
+
+- External services or APIs
+- Authentication requirements
+- Error handling approach]
+
+## Testing Approach
+
+### Unit Tests
+
+[Describe unit testing strategy:
+
+- Key components to test
+- Mock requirements (external services only)
+- Critical test scenarios]
+
+### Integration Tests
+
+[If needed, describe integration tests:
+
+- Components to test together
+- Test data requirements]
+
+## Development Sequencing
+
+### Build Order
+
+[Define implementation sequence:
+
+1. First component/feature (why first)
+2. Second component/feature (dependencies)
+3. Subsequent components
+4. Integration and testing]
+
+### Technical Dependencies
+
+[List any blocking dependencies:
+
+- Required infrastructure
+- External service availability]
+
+## Monitoring and Observability
+
+[Define monitoring approach using existing infrastructure:
+
+- Metrics to expose
+- Key logs and log levels
+- Integration with existing dashboards]
+
+## Technical Considerations
+
+### Key Decisions
+
+[Document important technical decisions:
+
+- Chosen approach and justification
+- Trade-offs considered
+- Rejected alternatives and why]
+
+### Known Risks
+
+[Identify technical risks:
+
+- Potential challenges
+- Mitigation approaches
+- Areas needing research]
+
+### Standards Compliance
+
+[Review the rules in `ai/rules/` that apply to this techspec and list them below:]
+
+### Relevant Files
+
+[List relevant project files here]