@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/workflows/beads-integration/examples/basic-task-generation.md

@@ -0,0 +1,293 @@
+# Basic Task Generation Examples
+
+## Overview
+
+This document demonstrates basic task generation with examples showing the transformation from a simple specification to a comprehensive Beads task. It includes before/after comparisons and configuration examples.
+
+## Example 1: Simple Feature Specification
+
+### Input Specification
+
+```markdown
+# Feature: User Profile Picture Upload
+
+Users should be able to upload a profile picture. The picture should be displayed on their profile page.
+```
+
+### Step-by-Step Decomposition
+
+#### Step 1: Identify Core Requirements
+- File upload functionality
+- Image storage
+- Profile page display
+- Validation (file type, size)
+
+#### Step 2: Break Down into Tasks
+1. Backend: File upload endpoint
+2. Backend: Image storage and retrieval
+3. Frontend: Upload UI component
+4. Frontend: Display profile picture
+
+#### Step 3: Apply Core Rules
+
+For Task 1 (Backend: File upload endpoint):
+
+**Title**: Create profile picture upload endpoint
+
+**Description**: Implement POST /api/users/:id/profile-picture endpoint that accepts image uploads, validates file type and size, and stores the image.
+
+**Prerequisites**:
+- [ ] File storage service configured (S3 or local storage)
+- [ ] Image processing library installed (sharp or jimp)
+- [ ] User authentication middleware implemented
+
+**Steps**:
+1. Create POST /api/users/:id/profile-picture route
+2. Add multer middleware for file upload handling
+3. Validate file type (JPEG, PNG, GIF only)
+4. Validate file size (max 5MB)
+5. Resize image to 400x400px
+6. Generate unique filename
+7. Store image in file storage
+8. Update user record with image URL
+9. Return image URL in response
+
+**Verification**:
+- [ ] Endpoint accepts valid image files
+- [ ] Endpoint rejects invalid file types
+- [ ] Endpoint rejects files > 5MB
+- [ ] Image is resized to 400x400px
+- [ ] Image URL is stored in user record
+- [ ] Endpoint returns 400 for invalid requests
+- [ ] Endpoint returns 200 with image URL for valid requests
+
+**Success Metrics**:
+- Upload success rate > 99%
+- Upload time < 2 seconds
+- Image quality maintained after resize
+- No security vulnerabilities (file type validation)
+
+### Before/After Comparison
+
+#### ❌ BEFORE: Minimal Task (Unacceptable)
+
+```markdown
+# Task: Add profile picture upload
+
+## Description
+Users can upload profile pictures
+
+## Steps
+1. Create upload endpoint
+2. Store image
+3. Display on profile
+
+## Verification
+- Upload works
+```
+
+**Problems**:
+- No specific endpoint details
+- No validation requirements
+- No error handling
+- No measurable success criteria
+- Missing prerequisites
+- Vague steps
+
+#### ✅ AFTER: Comprehensive Task (Acceptable)
+
+```markdown
+# Task: Create profile picture upload endpoint
+
+## Description
+Implement POST /api/users/:id/profile-picture endpoint that accepts image uploads, validates file type and size, resizes images, and stores them securely.
+
+## Context
+Users need to personalize their profiles with pictures. This endpoint will handle the upload, validation, and storage of profile pictures.
+
+## Prerequisites
+- [ ] File storage service configured (AWS S3 or local storage)
+- [ ] Image processing library installed (sharp npm package)
+- [ ] User authentication middleware implemented
+- [ ] User model includes profilePictureUrl field
+
+## Inputs
+- **User ID**: From URL parameter (:id)
+- **Image File**: Multipart form data (field name: "profilePicture")
+- **Auth Token**: JWT token in Authorization header
+
+## Outputs
+- **Success Response**: { "imageUrl": "https://..." }
+- **Error Response**: { "error": "Invalid file type" }
+
+## Steps
+1. **Create route handler**
+   - Add POST /api/users/:id/profile-picture route
+   - Apply authentication middleware
+   - Apply authorization check (user can only upload own picture)
+
+2. **Configure multer middleware**
+   - Set up multer with memory storage
+   - Configure file size limit (5MB)
+   - Set field name to "profilePicture"
+
+3. **Implement validation**
+   - Check file exists in request
+   - Validate MIME type (image/jpeg, image/png, image/gif)
+   - Validate file size <= 5MB
+   - Return 400 error if validation fails
+
+4. **Process image**
+   - Use sharp to resize image to 400x400px
+   - Maintain aspect ratio with cover fit
+   - Convert to JPEG format
+   - Compress to 80% quality
+
+5. **Store image**
+   - Generate unique filename (userId-timestamp.jpg)
+   - Upload to S3 or save to local storage
+   - Get public URL for image
+
+6. **Update user record**
+   - Update user.profilePictureUrl with image URL
+   - Save user record to database
+
+7. **Return response**
+   - Return 200 with { "imageUrl": "..." }
+   - Include appropriate headers
+
+## Dependencies
+### Blocks
+- `bd-auth`: User authentication middleware must be implemented
+- `bd-storage`: File storage service must be configured
+
+### Related
+- `bd-profile-display`: Profile page will display this image
+
+## Edge Cases
+### Case 1: User uploads non-image file
+- **Condition**: File MIME type is not image/*
+- **Handling**: Return 400 error with message "Invalid file type"
+- **Expected Outcome**: Upload rejected, user notified
+
+### Case 2: File size exceeds limit
+- **Condition**: File size > 5MB
+- **Handling**: Multer rejects upload, return 400 error
+- **Expected Outcome**: Upload rejected before processing
+
+### Case 3: Storage service unavailable
+- **Condition**: S3 or storage service returns error
+- **Handling**: Return 500 error, log error, retry once
+- **Expected Outcome**: User notified, error logged for investigation
+
+## Error Handling
+### Error 1: Invalid file type
+- **Cause**: User uploads non-image file
+- **Detection**: MIME type check fails
+- **Resolution**: Return 400 with clear error message
+- **Prevention**: Client-side validation (accept="image/*")
+
+### Error 2: Storage failure
+- **Cause**: S3 unavailable or disk full
+- **Detection**: Storage operation throws error
+- **Resolution**: Return 500, log error, alert ops team
+- **Prevention**: Monitor storage health and capacity
+
+## Verification
+- [ ] Endpoint accepts JPEG, PNG, GIF files
+- [ ] Endpoint rejects non-image files (400 error)
+- [ ] Endpoint rejects files > 5MB (400 error)
+- [ ] Image is resized to 400x400px
+- [ ] Image quality is acceptable after processing
+- [ ] Image URL is stored in user.profilePictureUrl
+- [ ] Endpoint requires authentication
+- [ ] User can only upload own profile picture
+- [ ] Storage errors handled gracefully
+- [ ] Response includes correct image URL
+
+## Success Metrics
+- **Upload Success Rate**: > 99% for valid files
+- **Upload Time**: < 2 seconds (p95)
+- **Image Quality**: SSIM > 0.95 after resize
+- **Error Rate**: < 1% for valid requests
+
+## Testing
+### Unit Tests
+- Validate file type validation logic
+- Validate file size validation logic
+- Test image resize function
+- Test filename generation
+
+### Integration Tests
+- Upload valid JPEG file - success
+- Upload valid PNG file - success
+- Upload PDF file - 400 error
+- Upload 10MB file - 400 error
+- Upload without authentication - 401 error
+- Upload to another user's profile - 403 error
+
+## Documentation
+- [ ] API endpoint documented in API docs
+- [ ] Error codes documented
+- [ ] File size and type limits documented
+- [ ] Example request/response added
+
+## Rollback Plan
+1. Remove route from API
+2. Revert user model changes
+3. Clean up uploaded images (if any)
+4. Verify API works without endpoint
+
+## Estimated Effort
+- **Time**: 4-6 hours
+- **Complexity**: Medium
+- **Risk**: Low
+
+## Resources
+- [Multer documentation](https://github.com/expressjs/multer)
+- [Sharp documentation](https://sharp.pixelplumbing.com/)
+- [AWS S3 SDK](https://docs.aws.amazon.com/sdk-for-javascript/)
+```
+
+**Improvements**:
+- ✅ Specific endpoint and method
+- ✅ Detailed validation requirements
+- ✅ Comprehensive error handling
+- ✅ Measurable success criteria
+- ✅ Clear prerequisites
+- ✅ Step-by-step instructions
+- ✅ Edge cases documented
+- ✅ Testing requirements specified
+
+## Configuration Example for Basic Mode
+
+```json
+{
+  "mode": "basic",
+  "features": {
+    "task_generation": true,
+    "openspec_integration": false,
+    "typescript_commands": false,
+    "effectiveness_rules": true
+  },
+  "rules": {
+    "task_detail_level": "standard",
+    "require_dependencies": true,
+    "require_verification": true,
+    "require_prerequisites": true,
+    "require_success_metrics": false
+  }
+}
+```
+
+## Summary
+
+Basic task generation transforms simple specifications into comprehensive, actionable tasks by:
+1. **Identifying** core requirements
+2. **Breaking down** into atomic tasks
+3. **Applying** core rules and effectiveness standards
+4. **Adding** all necessary context and details
+5. **Ensuring** tasks are complete, clear, and testable
+
+**Key Takeaway**: Never create bare-minimum task skeletons. Always provide comprehensive, actionable task descriptions.
+

package/augment-extensions/workflows/beads-integration/module.json

@@ -0,0 +1,75 @@
+{
+  "name": "beads-integration",
+  "version": "1.0.0",
+  "displayName": "Beads Integration Workflow",
+  "description": "Comprehensive guidelines and automation for AI-driven Beads task generation, OpenSpec decomposition, and workflow integration",
+  "type": "workflow",
+  "tags": [
+    "beads",
+    "task-management",
+    "openspec",
+    "workflow",
+    "automation",
+    "ai-integration",
+    "task-generation"
+  ],
+  "dependencies": {
+    "workflows/openspec": ">=1.0.0",
+    "workflows/beads": ">=1.0.0"
+  },
+  "augment": {
+    "characterCount": 0,
+    "priority": "high",
+    "category": "workflow",
+    "appliesTo": {
+      "filePatterns": [
+        ".beads/**/*",
+        "openspec/**/*",
+        "**/*.md"
+      ],
+      "languages": ["markdown", "json", "typescript"]
+    }
+  },
+  "installation": {
+    "required": false,
+    "steps": [
+      "Link module: augx link workflows/beads-integration",
+      "Configure mode in config/defaults.json (basic, advanced, or custom)",
+      "Enable desired features in configuration"
+    ]
+  },
+  "features": {
+    "task_generation": {
+      "enabled": true,
+      "description": "AI-driven comprehensive task generation with quality standards"
+    },
+    "openspec_integration": {
+      "enabled": true,
+      "description": "Automated OpenSpec-to-Beads decomposition"
+    },
+    "typescript_commands": {
+      "enabled": true,
+      "description": "TypeScript automation commands for validation and generation"
+    },
+    "effectiveness_rules": {
+      "enabled": true,
+      "description": "Effectiveness standards ensuring high-quality task content"
+    }
+  },
+  "contents": [
+    "rules/core-rules.md - Universal guidelines for all beads task generation",
+    "rules/task-generation.md - Comprehensive task generation guidelines",
+    "rules/effectiveness-standards.md - Quality and effectiveness criteria",
+    "rules/openspec-integration.md - OpenSpec decomposition automation",
+    "rules/typescript-commands.md - TypeScript command framework",
+    "config/schema.json - Configuration schema",
+    "config/defaults.json - Default configuration",
+    "examples/basic-task-generation.md - Basic task generation examples",
+    "examples/advanced-decomposition.md - Advanced decomposition examples",
+    "examples/typescript-automation.md - TypeScript automation examples",
+    "scripts/validators/ - Validation commands",
+    "scripts/generators/ - Generation commands",
+    "scripts/integrations/ - Integration commands"
+  ]
+}
+

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
+