@mytechtoday/augment-extensions 0.4.0 → 0.7.0

package/augment-extensions/workflows/beads-integration/rules/core-rules.md

@@ -0,0 +1,219 @@
+# Core Rules for Beads Task Generation
+
+## Overview
+
+This document defines the universal guidelines that apply to all Beads task generation. These core rules ensure consistency, quality, and effectiveness across all tasks created by AI agents.
+
+## 1. Task Structure Requirements
+
+### 1.1 Required Sections
+
+Every Beads task MUST include:
+
+1. **Title**: Clear, concise, action-oriented (verb + object)
+2. **Description**: Comprehensive explanation of what needs to be done
+3. **Prerequisites**: What must be completed or available before starting
+4. **Steps**: Detailed, ordered list of actions to complete the task
+5. **Verification**: Clear criteria for determining task completion
+6. **Success Metrics**: Measurable outcomes that define success
+
+### 1.2 Description Format
+
+```markdown
+## Description
+
+[Comprehensive explanation of the task]
+
+## Prerequisites
+
+- [ ] Prerequisite 1
+- [ ] Prerequisite 2
+
+## Steps
+
+1. Step 1 with details
+2. Step 2 with details
+3. Step 3 with details
+
+## Verification
+
+- [ ] Verification criterion 1
+- [ ] Verification criterion 2
+
+## Success Metrics
+
+- Metric 1: [measurable outcome]
+- Metric 2: [measurable outcome]
+```
+
+### 1.3 Title Guidelines
+
+**DO**:
+- ✅ Use action verbs: "Implement", "Create", "Update", "Fix", "Refactor"
+- ✅ Be specific: "Create user authentication module" not "Work on auth"
+- ✅ Keep concise: 50-80 characters maximum
+
+**DON'T**:
+- ❌ Use vague language: "Handle stuff", "Do things"
+- ❌ Be overly verbose: "Create a comprehensive and detailed user authentication module with all necessary features"
+- ❌ Use passive voice: "Authentication should be implemented"
+
+## 2. Quality Standards
+
+### 2.1 Clarity
+
+Tasks MUST be:
+- **Unambiguous**: No room for multiple interpretations
+- **Specific**: Concrete actions, not abstract concepts
+- **Actionable**: Clear what to do, not just what to achieve
+
+### 2.2 Completeness
+
+Tasks MUST include:
+- **All necessary information**: No missing context
+- **All required resources**: Links, references, examples
+- **All edge cases**: Known exceptions and special scenarios
+
+### 2.3 Actionability
+
+Tasks MUST be:
+- **Immediately executable**: No additional research required
+- **Self-contained**: All information needed is present
+- **Properly scoped**: Not too large, not too small
+
+## 3. Versioning and Logging
+
+### 3.1 Task Versioning
+
+- Use semantic versioning for task updates: MAJOR.MINOR.PATCH
+- Document changes in task comments
+- Track task evolution over time
+
+### 3.2 Logging Requirements
+
+Every task update MUST log:
+- **What changed**: Specific modifications made
+- **Why it changed**: Reason for the update
+- **Who changed it**: Author of the update
+- **When it changed**: Timestamp of the update
+
+## 4. Dependency Management
+
+### 4.1 Explicit Dependencies
+
+Tasks MUST declare:
+- **Blocking dependencies**: Tasks that must complete first
+- **Blocked tasks**: Tasks that depend on this task
+- **Related tasks**: Tasks in the same feature/epic
+
+### 4.2 Dependency Format
+
+```json
+{
+  "dependencies": [
+    {
+      "issue_id": "bd-child",
+      "depends_on_id": "bd-parent",
+      "type": "blocks"
+    }
+  ]
+}
+```
+
+## 5. Error Handling Standards
+
+### 5.1 Error Scenarios
+
+Tasks MUST document:
+- **Known failure modes**: What can go wrong
+- **Error handling**: How to handle failures
+- **Rollback procedures**: How to undo changes if needed
+
+### 5.2 Error Documentation Format
+
+```markdown
+## Error Handling
+
+### Scenario 1: [Error description]
+- **Cause**: [What causes this error]
+- **Detection**: [How to detect this error]
+- **Resolution**: [How to fix this error]
+- **Prevention**: [How to prevent this error]
+```
+
+## 6. Examples
+
+### Example 1: Well-Structured Task
+
+**Title**: Implement user authentication module
+
+**Description**: Create a user authentication module with email/password login, JWT token generation, and session management.
+
+**Prerequisites**:
+- [ ] Database schema for users table created
+- [ ] JWT library installed
+- [ ] Environment variables configured
+
+**Steps**:
+1. Create User model with email and password fields
+2. Implement password hashing using bcrypt
+3. Create login endpoint that validates credentials
+4. Generate JWT token on successful login
+5. Implement token verification middleware
+6. Add session management with refresh tokens
+
+**Verification**:
+- [ ] User can register with email and password
+- [ ] User can login with correct credentials
+- [ ] Login fails with incorrect credentials
+- [ ] JWT token is generated and valid
+- [ ] Protected routes require valid token
+
+**Success Metrics**:
+- All authentication tests pass (100% coverage)
+- Login response time < 200ms
+- Token expiration works correctly
+
+### Example 2: Task with Dependencies
+
+**Title**: Create user profile page
+
+**Description**: Build user profile page displaying user information and allowing profile updates.
+
+**Prerequisites**:
+- [ ] User authentication module completed (bd-auth)
+- [ ] User model includes profile fields
+- [ ] Frontend routing configured
+
+**Dependencies**:
+- Blocks: bd-auth (user authentication module)
+- Related: bd-settings (user settings page)
+
+**Steps**:
+1. Create profile component with user data display
+2. Add form for editing profile information
+3. Implement profile update API endpoint
+4. Add validation for profile fields
+5. Connect frontend to backend API
+
+**Verification**:
+- [ ] Profile page displays user information
+- [ ] User can edit and save profile changes
+- [ ] Validation prevents invalid data
+- [ ] Changes persist after page reload
+
+**Success Metrics**:
+- Profile update success rate > 99%
+- Form validation catches all invalid inputs
+- UI responsive on mobile and desktop
+
+## Summary
+
+These core rules ensure that all Beads tasks are:
+- **Structured**: Follow consistent format
+- **Complete**: Include all necessary information
+- **Clear**: Unambiguous and actionable
+- **Traceable**: Versioned and logged
+- **Connected**: Properly linked with dependencies
+- **Robust**: Handle errors gracefully
+

package/augment-extensions/workflows/beads-integration/rules/effectiveness-standards.md

@@ -0,0 +1,256 @@
+# Effectiveness Standards for Beads Tasks
+
+## Overview
+
+This document defines effectiveness rules ensuring high-quality task content. These standards ensure tasks are atomic, complete, clear, testable, and maintainable.
+
+## 1. Atomicity Principles
+
+### 1.1 Single-Purpose Tasks
+
+Each task MUST focus on ONE specific objective.
+
+**✅ GOOD - Atomic Task**:
+```
+Title: Implement user login endpoint
+Description: Create POST /api/auth/login endpoint with email/password validation and JWT token generation
+```
+
+**❌ BAD - Non-Atomic Task**:
+```
+Title: Implement authentication system
+Description: Create login, registration, password reset, email verification, and session management
+```
+
+### 1.2 Decomposition Guidelines
+
+If a task description requires "and" more than twice, it should be split:
+
+**Split this**:
+- "Create user model AND add validation AND implement CRUD endpoints AND write tests"
+
+**Into these**:
+1. "Create user model with validation"
+2. "Implement user CRUD endpoints"
+3. "Write tests for user endpoints"
+
+### 1.3 Scope Boundaries
+
+Tasks should be completable in:
+- **Small tasks**: 1-4 hours
+- **Medium tasks**: 4-8 hours
+- **Large tasks**: 8-16 hours (max)
+
+If a task exceeds 16 hours, it MUST be decomposed.
+
+## 2. Completeness Requirements
+
+### 2.1 All Necessary Information
+
+Tasks MUST include:
+- **What**: Clear description of deliverable
+- **Why**: Context and purpose
+- **How**: Detailed steps
+- **When**: Prerequisites and dependencies
+- **Where**: Affected files/components
+- **Who**: Required skills/expertise
+
+### 2.2 No Missing Context
+
+**✅ GOOD - Complete Context**:
+```markdown
+## Description
+Implement rate limiting middleware to prevent API abuse. Current system allows unlimited requests, causing server overload during traffic spikes. Rate limit should be 100 requests per minute per IP address.
+
+## Context
+Recent DDoS attack caused 3-hour outage. Rate limiting will prevent similar incidents and protect server resources.
+```
+
+**❌ BAD - Missing Context**:
+```markdown
+## Description
+Add rate limiting
+```
+
+### 2.3 Resource Completeness
+
+Tasks MUST include:
+- Links to relevant documentation
+- References to related code
+- Examples or templates
+- Configuration requirements
+
+## 3. Clarity Standards
+
+### 3.1 Unambiguous Instructions
+
+Every step MUST be clear and specific.
+
+**✅ GOOD - Clear Instructions**:
+```markdown
+1. Create `src/middleware/rateLimit.ts` file
+2. Import `express-rate-limit` package
+3. Configure rate limiter with 100 requests per minute
+4. Apply middleware to all `/api/*` routes
+```
+
+**❌ BAD - Ambiguous Instructions**:
+```markdown
+1. Add rate limiting
+2. Configure it
+3. Use it
+```
+
+### 3.2 Terminology Consistency
+
+Use consistent terminology throughout:
+- **User** vs **Customer** vs **Account** - Pick ONE
+- **Endpoint** vs **Route** vs **API** - Pick ONE
+- **Database** vs **DB** vs **Data Store** - Pick ONE
+
+### 3.3 Avoid Jargon
+
+Explain technical terms or provide links:
+
+**✅ GOOD**:
+```markdown
+Implement JWT (JSON Web Token) authentication. See: https://jwt.io/introduction
+```
+
+**❌ BAD**:
+```markdown
+Implement JWT auth
+```
+
+## 4. Testability Criteria
+
+### 4.1 Clear Success Metrics
+
+Every task MUST have measurable success criteria.
+
+**✅ GOOD - Measurable**:
+```markdown
+## Success Metrics
+- Rate limiter blocks requests after 100 per minute
+- Response time < 50ms for rate limit check
+- 429 status code returned when limit exceeded
+- Rate limit resets after 1 minute
+```
+
+**❌ BAD - Not Measurable**:
+```markdown
+## Success Metrics
+- Rate limiting works
+- Performance is good
+```
+
+### 4.2 Verification Checklist
+
+Tasks MUST include specific, testable verification criteria.
+
+**✅ GOOD - Testable Verification**:
+```markdown
+## Verification
+- [ ] Send 100 requests in 1 minute - all succeed
+- [ ] Send 101st request - receives 429 status
+- [ ] Wait 1 minute - rate limit resets
+- [ ] Different IPs have independent limits
+```
+
+**❌ BAD - Not Testable**:
+```markdown
+## Verification
+- [ ] Rate limiting works
+- [ ] System is protected
+```
+
+### 4.3 Test Coverage Requirements
+
+Tasks MUST specify required tests:
+- **Unit tests**: For individual functions/methods
+- **Integration tests**: For component interactions
+- **End-to-end tests**: For complete workflows
+
+## 5. Maintainability Guidelines
+
+### 5.1 Documentation Requirements
+
+Tasks MUST specify documentation updates:
+- **Code comments**: Inline documentation
+- **API docs**: Endpoint documentation
+- **README**: User-facing documentation
+- **Runbooks**: Operational procedures
+
+### 5.2 Versioning Requirements
+
+Tasks MUST include:
+- **Version number**: Semantic versioning
+- **Changelog entry**: What changed and why
+- **Migration guide**: If breaking changes
+
+### 5.3 Future-Proofing
+
+Tasks SHOULD consider:
+- **Extensibility**: Can this be extended later?
+- **Backwards compatibility**: Will this break existing code?
+- **Deprecation path**: If replacing existing functionality
+
+## 6. Effectiveness Checklist
+
+### 6.1 Before Creating a Task
+
+- [ ] **Atomic**: Does this task have a single, clear purpose?
+- [ ] **Complete**: Is all necessary information included?
+- [ ] **Clear**: Are instructions unambiguous and specific?
+- [ ] **Testable**: Are success criteria measurable?
+- [ ] **Maintainable**: Are documentation requirements specified?
+
+### 6.2 After Creating a Task
+
+- [ ] Can someone unfamiliar execute this task without questions?
+- [ ] Are all edge cases documented?
+- [ ] Are all error scenarios handled?
+- [ ] Is the scope appropriate (not too large, not too small)?
+- [ ] Are dependencies explicitly declared?
+
+## 7. Measurement Criteria
+
+### 7.1 Task Quality Metrics
+
+**High-Quality Task**:
+- Completeness score: 100% (all sections present)
+- Clarity score: > 90% (minimal ambiguity)
+- Testability score: 100% (all criteria measurable)
+- Execution time: Within estimated range
+
+**Low-Quality Task**:
+- Completeness score: < 70% (missing sections)
+- Clarity score: < 60% (ambiguous instructions)
+- Testability score: < 70% (vague criteria)
+- Execution time: 2x+ estimated time
+
+### 7.2 Effectiveness Indicators
+
+**Effective Task**:
+- ✅ Executed without clarification questions
+- ✅ Completed within estimated time
+- ✅ All verification criteria met
+- ✅ No rework required
+
+**Ineffective Task**:
+- ❌ Multiple clarification questions needed
+- ❌ Significantly over/under estimated time
+- ❌ Verification criteria unclear or incomplete
+- ❌ Rework required due to missing requirements
+
+## Summary
+
+Effectiveness standards ensure tasks are:
+- **Atomic**: Single-purpose, appropriately scoped
+- **Complete**: All information present, no missing context
+- **Clear**: Unambiguous, specific, consistent terminology
+- **Testable**: Measurable success criteria, specific verification
+- **Maintainable**: Documentation requirements, versioning, future-proofing
+
+**Remember**: An effective task is one that can be executed successfully without additional clarification or research.
+