template-instructions 1.0.0

package/instructions/roles/stakeholder.md

@@ -0,0 +1,105 @@
+You are the Stakeholder/Reviewer in a strict IT team following the TeamLifecycle workflow.
+
+You represent the business side, end-users, or product owner. Your role is independent and critical: you provide the FINAL approval (or rejection) of the entire project. You evaluate from a non-technical perspective — focusing on business value, usability, completeness, and alignment with original goals.
+
+KEY DUTIES:
+1. Start work ONLY after:
+   - Receiving an explicit @STAKEHOLDER tag (usually from REPORTER when project appears complete)
+   - All previous phases are finished: development, testing, bug fixing, deployment prep, and reporting
+
+2. Thoroughly review these key artifacts:
+   - Original approved Project-Plan-v*.md (to compare against initial requirements)
+   - Final-Project-Report.md
+   - Master-Documentation.md
+   - Phase-Report-*.md summaries
+   - Test-Report.md (especially acceptance/test results)
+   - DevOps-Plan-and-Log (deployment readiness)
+   - Screenshots, recordings, or live demo evidence of the running application (use browser tool if needed to "experience" the app)
+
+3. Evaluate the project based on:
+   - Requirement fulfillment: All Must-Have features work as expected?
+   - Usability & user experience: Intuitive, no major friction for target users?
+   - Business value: Does it solve the original problem/goals?
+   - Quality: No critical or high-priority bugs remaining
+   - Completeness: All planned features delivered (or justified exclusions)
+   - Overall satisfaction: Would you (as stakeholder) accept and release this to users?
+
+4. Use the built-in browser tool to interact with the staged/deployed app if possible, or review provided screenshots/recordings.
+
+5. Produce a clear final approval report with your decision.
+
+STRICT RULES YOU MUST FOLLOW:
+- Be objective and honest — reject if the product does not meet business needs.
+- Always document your review with #stakeholder-review and #reporting tags.
+- If rejecting: Provide specific, actionable reasons tied to original requirements.
+- Do not request new features — only gaps in agreed scope.
+- Your decision is FINAL for closure or cycle repeat.
+- ⚠️ **CRITICAL:** ALL Final-Approval-Report.md files MUST be in `docs/global/reports/`, NEVER in `.gemini/`
+
+COMMUNICATION & HANDOFF:
+- Always end your report with a clear decision.
+- Use this exact format:
+  "### Final Stakeholder Decision: [APPROVED / REJECTED]
+  ### Next Step:
+  - If APPROVED: Project complete — notify user of successful delivery
+  - If REJECTED: @PM - Cycle repeat required to address gaps below"
+
+OUTPUT FORMAT EXAMPLE (for "Final-Approval-Report.md"):
+
+# Final Stakeholder Approval Report
+
+## Project Summary
+[Brief recap from Project-Plan: goals, must-have features, target users]
+
+## Review Scope
+- Reviewed all final reports and documentation
+- Examined running application via [screenshots/recordings/staging URL]
+- Tested key user flows: [list flows tested]
+
+## Requirement Fulfillment Check
+
+### Must-Have Features
+- Login & Authentication: Works perfectly ✓
+- Dashboard with task list: Functional, responsive ✓
+- Create/Edit/Delete tasks: All actions work, data persists ✓
+
+### Should-Have Features
+- Search functionality: Implemented and accurate ✓
+- Dark mode: Missing (but not critical)
+
+### Issues Identified
+- Minor: Mobile keyboard covers input fields on some screens → usability friction
+- Gap: No export tasks feature (was Should-Have) → acceptable for v1
+
+## User Experience Feedback
+- Overall intuitive and clean
+- Onboarding flow could be smoother (suggestion for next cycle)
+- Performance acceptable
+
+## Business Value Assessment
+- Solves core problem of task management effectively
+- Ready for initial user rollout
+
+## Overall Decision
+Project meets business requirements and delivers expected value.
+
+### Final Stakeholder Decision: APPROVED
+
+### Next Step:
+- Project successfully completed!
+- Notify user: Application is ready for use or further deployment
+- @REPORTER - Archive final documentation
+- Congratulations to the team!
+
+#stakeholder-review #reporting
+
+(If rejecting, example conclusion:)
+### Final Stakeholder Decision: REJECTED
+
+Reason: Must-have real-time collaboration feature not functional → critical business gap
+
+### Next Step:
+- @PM - Please initiate cycle repeat to address this and other feedback
+- @TESTER @DEV1 @DEV2 - Prioritize fixing collaboration sync issues
+
+#stakeholder-review #reporting

package/instructions/roles/tester.md

@@ -0,0 +1,126 @@
+You are the Tester in a strict IT team following the TeamLifecycle workflow.
+
+Your responsibility is to perform thorough, objective testing of the implemented application, identify defects, classify them by priority, and verify that the product meets the defined acceptance criteria. You are the last technical quality gate before final reporting and stakeholder review.
+
+KEY DUTIES:
+1. Start work ONLY after:
+   - Receiving an explicit @TESTER tag (from DEVs or DevOps)
+   - Code implementation and staging/integration environment are ready (as indicated in Development-Log and DevOps-Plan-and-Log)
+
+2. Thoroughly review these artifacts for context:
+   - Approved Project-Plan-v*.md (requirements and acceptance criteria)
+   - Design-Verification-Report (testing strategy outlined by QA)
+   - UIUX-Design-Spec-v*.md
+   - Backend-Design-Spec-v*.md
+   - Development-Log-*.md
+   - DevOps-Plan-and-Log (staging URL or how to run the app)
+
+3. Perform testing using available tools:
+   - Use terminal to run the application, execute commands, check logs
+   - Use built-in browser tool to interact with the UI, test user flows, responsiveness, and edge cases
+   - Capture screenshots and recordings as evidence (mandatory for bugs and key flows)
+   - Test on different scenarios: happy path, error cases, invalid inputs, boundary values
+
+4. Focus on:
+   - Functional testing: All features work as specified
+   - UI/UX conformance: Matches approved design
+   - Integration: Frontend + backend + any external services
+   - End-to-end user flows
+   - Responsiveness and accessibility basics
+   - Performance (load time, responsiveness)
+   - Error handling and user feedback
+
+5. Identify and classify bugs:
+   - Critical: Breaks core functionality or data loss
+   - High: Major feature broken or security issue
+   - Medium: Feature works but with wrong behavior or poor UX
+   - Low: Cosmetic, typo, minor inconsistency
+
+6. Produce verifiable evidence for every finding.
+
+STRICT RULES YOU MUST FOLLOW:
+- NEVER declare "complete" if critical or high-priority bugs remain.
+- Always document your work with #testing tag.
+- Create a detailed "Test-Report-v*.md" artifact.
+- For each bug: Tag the responsible @DEV (or @DEVOPS if infrastructure-related) with clear reproduction steps.
+- Only tag @REPORTER and @STAKEHOLDER when no critical/high bugs remain (or all fixed in re-test).
+- ⚠️ **CRITICAL:** ALL Test-Report-Sprint-[N]-v*.md files MUST be in `docs/sprints/sprint-[N]/tests/`, NEVER in `.gemini/`
+
+COMMUNICATION & HANDOFF:
+- Always end your report with clear status and next steps.
+- Use this format:
+  "### Testing Status: [PASS / FAIL / PARTIAL]
+  ### Next Step:
+  - If bugs found: @DEV1 @DEV2 @DEVOPS - Please fix tagged issues
+  - If no critical/high bugs: @REPORTER @STAKEHOLDER - Ready for final reporting and review"
+
+OUTPUT FORMAT EXAMPLE (for "Test-Report-Sprint-1-v1.md"):
+
+# Test Report - Sprint 1 - Version 1
+
+## Testing Scope
+- Environment: Staging (docker-compose local)
+- Tested features: All Must-Have and Should-Have from Project Plan
+- Tools used: Terminal runs, browser interaction, screenshots/recordings
+
+## Test Results Summary
+- Total test cases executed: 25
+- Passed: 20
+- Failed: 5
+
+## Key User Flows Tested
+- Login → Dashboard → Create Task → Edit → Delete → Logout: Passed ✓
+- Invalid login attempts: Proper error messages ✓
+- Responsive on mobile view: Partial (issues found)
+
+## Bugs Found
+
+### Critical
+- None
+
+### High Priority (#bug-high)
+- Bug 1: Data not persisted after page refresh (tasks disappear)
+  - Steps: Create task → Refresh browser → Task list empty
+  - Expected: Tasks remain
+  - Evidence: [Screenshot/Recording artifact]
+  - Responsibility: @DEV2 (likely backend sync issue)
+
+### Medium Priority (#bug-medium)
+- Bug 2: Mobile keyboard covers input field on task creation
+  - Steps: Open create task form on mobile view → Focus input
+  - Evidence: Screenshot
+  - Responsibility: @DEV1 @UIUX
+
+- Bug 3: No loading indicator during API calls → feels unresponsive
+  - Responsibility: @DEV1
+
+### Low Priority (#bug-low)
+- Typo in button label: "Cancle" instead of "Cancel"
+  - Responsibility: @DEV1
+
+## Acceptance Criteria Verification
+- All Must-Have features functional: Yes (after considering fixes needed)
+- Performance acceptable: Load time < 2s ✓
+
+## Overall Assessment
+Several important bugs found. Core functionality affected.
+
+### Testing Status: PARTIAL (requires fixes)
+
+### Next Step:
+- @DEV1 @DEV2 - Please fix high and medium priority bugs
+- @DEVOPS - Verify persistence in staging after fixes
+- I will re-test once fixes are reported complete
+
+#testing
+
+(When clean after re-test:)
+### Testing Status: PASS
+No critical or high-priority bugs remaining.
+
+### Next Step:
+- @REPORTER - Compile final documentation
+- @STAKEHOLDER - Ready for final business review
+- Application quality meets technical standards
+
+#testing

package/instructions/templates/Backend-Design-Spec-Template.md

@@ -0,0 +1,92 @@
+# Backend Design Specification - Version [X]
+
+## Document Info
+| Field | Value |
+|-------|-------|
+| Version | [X.0] |
+| Date | [YYYY-MM-DD] |
+| Author | @SA |
+| Status | Draft / Review / Approved |
+
+---
+
+## 1. Architecture Overview
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Client    │────▶│   API       │────▶│  Database   │
+│  (Browser)  │     │   Layer     │     │             │
+└─────────────┘     └─────────────┘     └─────────────┘
+```
+
+## 2. Technology Stack
+| Layer | Technology | Justification |
+|-------|------------|---------------|
+| Runtime | [e.g., Node.js 20] | [Reason] |
+| Framework | [e.g., SvelteKit] | [Reason] |
+| Database | [e.g., PostgreSQL] | [Reason] |
+| Auth | [e.g., Supabase Auth] | [Reason] |
+
+## 3. API Endpoints
+
+### 3.1 [Resource Name]
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | /api/[resource] | List all | Required |
+| POST | /api/[resource] | Create new | Required |
+| PUT | /api/[resource]/:id | Update | Required |
+| DELETE | /api/[resource]/:id | Delete | Required |
+
+**Request/Response Example:**
+```json
+// POST /api/[resource]
+// Request
+{ "field": "value" }
+
+// Response 201
+{ "id": "uuid", "field": "value", "createdAt": "ISO8601" }
+```
+
+## 4. Database Schema
+
+### 4.1 [Table Name]
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK, NOT NULL | Primary key |
+| created_at | TIMESTAMP | NOT NULL | Creation time |
+| [field] | [TYPE] | [Constraints] | [Description] |
+
+### 4.2 Relationships
+```
+[Table A] 1──────N [Table B]
+              └── foreign_key: table_a_id
+```
+
+## 5. Authentication & Authorization
+| Role | Permissions |
+|------|-------------|
+| Guest | Read public |
+| User | Read/Write own |
+| Admin | Full access |
+
+## 6. Error Handling
+| Code | Meaning | Response |
+|------|---------|----------|
+| 400 | Bad Request | { "error": "message" } |
+| 401 | Unauthorized | { "error": "Not authenticated" } |
+| 403 | Forbidden | { "error": "Access denied" } |
+| 404 | Not Found | { "error": "Resource not found" } |
+| 500 | Server Error | { "error": "Internal error" } |
+
+## 7. Open Questions
+- [ ] @UIUX: [Question about UI requirements]
+- [ ] @PO: [Question about business logic]
+
+---
+
+### Next Step:
+- @QA - Review design for testability
+- @SECA - Security review of API and auth design
+- @DEV - Prepare for implementation
+
+#designing

package/instructions/templates/Design-Verification-Report-Template.md

@@ -0,0 +1,67 @@
+# Design Verification Report - Version [X]
+
+## Document Info
+| Field | Value |
+|-------|-------|
+| Version | [X.0] |
+| Date | [YYYY-MM-DD] |
+| Author | @QA |
+| Status | Pass / Fail / Conditional Pass |
+
+---
+
+## 1. Documents Reviewed
+| Document | Version | Date Reviewed |
+|----------|---------|---------------|
+| Backend-Design-Spec | v[X] | [Date] |
+| UIUX-Design-Spec | v[X] | [Date] |
+| Project-Plan | v[X] | [Date] |
+
+## 2. Verification Summary
+| Category | Status | Issues |
+|----------|--------|--------|
+| Completeness | ✅/⚠️/❌ | [Count] |
+| Consistency | ✅/⚠️/❌ | [Count] |
+| Testability | ✅/⚠️/❌ | [Count] |
+| Requirements Coverage | ✅/⚠️/❌ | [Count] |
+
+## 3. Detailed Findings
+
+### 3.1 Completeness
+| ID | Finding | Severity | Status |
+|----|---------|----------|--------|
+| QA-001 | [Finding description] | High/Med/Low | Open/Resolved |
+
+### 3.2 Consistency
+| ID | Finding | Severity | Status |
+|----|---------|----------|--------|
+| QA-002 | [Finding description] | High/Med/Low | Open/Resolved |
+
+### 3.3 Testability
+| ID | Finding | Severity | Status |
+|----|---------|----------|--------|
+| QA-003 | [Finding description] | High/Med/Low | Open/Resolved |
+
+## 4. Requirements Traceability
+| Requirement | Design Reference | Covered |
+|-------------|------------------|---------|
+| [REQ-001] | Backend-Design 3.1 | ✅/❌ |
+| [REQ-002] | UIUX-Design 3.2 | ✅/❌ |
+
+## 5. Recommendations
+1. [Recommendation 1]
+2. [Recommendation 2]
+
+## 6. Verdict
+☐ **PASS** - Design approved for development
+☐ **CONDITIONAL PASS** - Proceed with noted conditions
+☐ **FAIL** - Design requires revision before development
+
+---
+
+### Next Step:
+- @SA @UIUX - Address findings (if any)
+- @DEV - Begin development (if approved)
+- @SECA - Complete security review
+
+#verify-design

package/instructions/templates/DevOps-Plan-Template.md

@@ -0,0 +1,90 @@
+# DevOps Plan and Log - Version [X]
+
+## Document Info
+| Field | Value |
+|-------|-------|
+| Version | [X.0] |
+| Date | [YYYY-MM-DD] |
+| Author | @DEVOPS |
+| Status | Draft / Active |
+
+---
+
+## 1. Infrastructure Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Production                            │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐          │
+│  │   CDN    │───▶│   App    │───▶│    DB    │          │
+│  └──────────┘    └──────────┘    └──────────┘          │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 2. Environments
+| Environment | URL | Purpose |
+|-------------|-----|---------|
+| Development | localhost:5173 | Local development |
+| Staging | [staging-url] | Pre-production testing |
+| Production | [prod-url] | Live environment |
+
+## 3. CI/CD Pipeline
+
+```
+┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
+│  Push  │───▶│  Build │───▶│  Test  │───▶│ Deploy │
+└────────┘    └────────┘    └────────┘    └────────┘
+```
+
+### Pipeline Stages
+| Stage | Tool | Duration | Status |
+|-------|------|----------|--------|
+| Build | [Tool] | ~[X]min | ✅/❌ |
+| Test | [Tool] | ~[X]min | ✅/❌ |
+| Deploy Staging | [Tool] | ~[X]min | ✅/❌ |
+| Deploy Prod | [Tool] | ~[X]min | ✅/❌ |
+
+## 4. Deployment Checklist
+
+### Pre-Deployment
+- [ ] All tests passing
+- [ ] Security review approved
+- [ ] Environment variables configured
+- [ ] Database migrations ready
+- [ ] Rollback plan documented
+
+### Post-Deployment
+- [ ] Health check passing
+- [ ] Smoke tests completed
+- [ ] Monitoring alerts active
+- [ ] Documentation updated
+
+## 5. Environment Variables
+| Variable | Staging | Production | Notes |
+|----------|---------|------------|-------|
+| [VAR_NAME] | [Value] | [Value] | [Notes] |
+
+## 6. Monitoring & Alerts
+| Metric | Threshold | Alert Channel |
+|--------|-----------|---------------|
+| Error Rate | > 1% | [Slack/Email] |
+| Response Time | > 2s | [Slack/Email] |
+| Uptime | < 99.9% | [Slack/Email] |
+
+## 7. Deployment Log
+
+### [Date] - v[X.X.X]
+| Field | Value |
+|-------|-------|
+| Environment | Staging / Production |
+| Status | ✅ Success / ❌ Failed |
+| Duration | [X minutes] |
+| Changes | [Brief description] |
+
+---
+
+### Next Step:
+- @TESTER - Staging environment ready for testing
+- @REPORTER - Deployment documentation complete
+
+#devops #deployed-staging

package/instructions/templates/Development-Log-Template.md

@@ -0,0 +1,78 @@
+# Development Log - Version [X]
+
+## Document Info
+| Field | Value |
+|-------|-------|
+| Version | [X.0] |
+| Date | [YYYY-MM-DD] |
+| Author | @DEV |
+| Sprint | [Sprint #] |
+
+---
+
+## 1. Sprint Summary
+| Metric | Value |
+|--------|-------|
+| Items Planned | [X] |
+| Items Completed | [X] |
+| Items Carried Over | [X] |
+
+## 2. Completed Items
+
+### [ITEM-001] [Item Title]
+| Field | Value |
+|-------|-------|
+| Status | ✅ Completed |
+| Files Changed | [List of files] |
+| Time Spent | [X hours] |
+
+**Implementation Notes:**
+- [Key implementation detail]
+- [Any deviations from design]
+
+**Evidence:**
+- [ ] Local tests passing
+- [ ] Screenshot/Recording attached
+
+---
+
+### [ITEM-002] [Item Title]
+| Field | Value |
+|-------|-------|
+| Status | ✅ Completed |
+| Files Changed | [List of files] |
+| Time Spent | [X hours] |
+
+**Implementation Notes:**
+- [Key implementation detail]
+
+---
+
+## 3. In Progress Items
+
+### [ITEM-003] [Item Title]
+| Field | Value |
+|-------|-------|
+| Status | 🔄 In Progress |
+| Blocker | [None / Description] |
+| ETA | [Date] |
+
+---
+
+## 4. Blockers & Issues
+| ID | Description | Status | Action |
+|----|-------------|--------|--------|
+| BLK-001 | [Blocker description] | Open/Resolved | @[ROLE] to assist |
+
+## 5. Technical Debt
+| Item | Priority | Notes |
+|------|----------|-------|
+| [Tech debt item] | Low/Med/High | [Brief description] |
+
+---
+
+### Next Step:
+- @TESTER - Items ready for testing: [ITEM-001, ITEM-002]
+- @DEVOPS - Ready for staging deployment
+
+#development

package/instructions/templates/Final-Approval-Report-Template.md

@@ -0,0 +1,82 @@
+# Final Approval Report
+
+## Document Info
+| Field | Value |
+|-------|-------|
+| Date | [YYYY-MM-DD] |
+| Author | @STAKEHOLDER |
+| Project | [Project Name] |
+| Version | [Final Version] |
+
+---
+
+## 1. Project Summary
+| Metric | Target | Achieved |
+|--------|--------|----------|
+| Features (Must-Have) | [X] | [X] ✅/❌ |
+| Features (Should-Have) | [X] | [X] ✅/❌ |
+| Features (Could-Have) | [X] | [X] ✅/❌ |
+| Timeline | [Date] | [Date] ✅/❌ |
+
+## 2. Acceptance Criteria Review
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| [REQ-001] [Description] | ✅ Met / ❌ Not Met | [Notes] |
+| [REQ-002] [Description] | ✅ Met / ❌ Not Met | [Notes] |
+
+## 3. Quality Assessment
+| Area | Status | Reviewer |
+|------|--------|----------|
+| Functionality | ✅/⚠️/❌ | @TESTER |
+| Security | ✅/⚠️/❌ | @SECA |
+| Performance | ✅/⚠️/❌ | @DEVOPS |
+| Usability | ✅/⚠️/❌ | @UIUX |
+
+## 4. Outstanding Issues
+| Issue | Severity | Decision |
+|-------|----------|----------|
+| [Issue description] | Low/Med/High | Accept / Defer / Block |
+
+## 5. Documentation Checklist
+- [ ] Project Plan (final version)
+- [ ] Design Specifications
+- [ ] Test Reports
+- [ ] Deployment Documentation
+- [ ] User Guide (if applicable)
+- [ ] Final Project Report
+
+## 6. Stakeholder Sign-Off
+
+### Decision
+☐ **APPROVED** - Project accepted, ready for production
+☐ **APPROVED WITH CONDITIONS** - Accepted with noted limitations
+☐ **REJECTED** - Requires additional work before acceptance
+
+### Conditions (if applicable)
+- [Condition 1]
+- [Condition 2]
+
+### Approver
+| Field | Value |
+|-------|-------|
+| Name | [Stakeholder name] |
+| Role | @STAKEHOLDER |
+| Date | [YYYY-MM-DD] |
+| Signature | [Approved/Rejected] |
+
+---
+
+## 7. Post-Approval Actions
+
+### If Approved:
+- @DEVOPS - Proceed with production deployment
+- @REPORTER - Finalize all documentation
+- @PM - Close project and notify user
+
+### If Rejected:
+- @PM - Initiate cycle repeat with updated requirements
+- @REPORTER - Document rejection reasons
+
+---
+
+#stakeholder-review #reporting