From 0a93f7dd7e63602eb7fa7774ce9316fc9d9ef0aa Mon Sep 17 00:00:00 2001 From: swp Date: Fri, 3 Apr 2026 20:50:43 +0100 Subject: [PATCH] feat: add comprehensive workflow commands for development pipeline --- .kilo/commands/ask.md | 265 +++++++++++++++++++++++++++++++- .kilo/commands/code.md | 161 +++++++++++++++++++- .kilo/commands/debug.md | 310 +++++++++++++++++++++++++++++++++++++- .kilo/commands/feature.md | 246 ++++++++++++++++++++++++++++++ .kilo/commands/hotfix.md | 261 ++++++++++++++++++++++++++++++++ .kilo/commands/plan.md | 91 ++++++++++- .kilo/commands/review.md | 232 ++++++++++++++++++++++++++++ 7 files changed, 1562 insertions(+), 4 deletions(-) create mode 100644 .kilo/commands/feature.md create mode 100644 .kilo/commands/hotfix.md create mode 100644 .kilo/commands/review.md diff --git a/.kilo/commands/ask.md b/.kilo/commands/ask.md index e1f6fdf..8d5d0d9 100644 --- a/.kilo/commands/ask.md +++ b/.kilo/commands/ask.md @@ -7,4 +7,267 @@ color: "#8B5CF6" # Ask Command -Answers developer questions about the codebase. \ No newline at end of file +Intelligent Q&A system for codebase exploration, concept explanation, and development guidance. + +## Purpose + +- Explain code behavior +- Answer architecture questions +- Find code locations +- Clarify concepts +- Suggest best practices +- Debug understanding + +## Workflow + +### Step 1: Parse Question + +Identify question type: +- **Location**: "Where is X implemented?" +- **Explanation**: "How does X work?" +- **Concept**: "What is X?" +- **Best Practice**: "How should I do X?" +- **Comparison**: "What's the difference between X and Y?" +- **Debug Understanding**: "Why does X behave this way?" + +### Step 2: Search Codebase + +Use appropriate tools: + +```bash +# Find files +glob "**/filenamePattern" + +# Find code +grep "pattern" --include="*.ext" + +# Find function/class definitions +grep "function name|class Name" + +# Find usages +grep "import.*name|from.*name" +``` + +### Step 3: Read Context + +- Read relevant files +- Understand surrounding code +- Check related components +- Identify patterns and conventions + +### Step 4: Formulate Answer + +- Be concise and direct +- Include code references with line numbers +- Provide examples when helpful +- Link related concepts + +## Question Types & Responses + +### Location Questions + +``` +Q: "Where is the user authentication implemented?" + +A: Authentication is implemented in: + +- `src/auth/AuthService.ts:15-89` - Main authentication service +- `src/middleware/auth.ts:5-42` - Auth middleware +- `src/routes/auth.ts:10-78` - Auth endpoints +``` + +### Explanation Questions + +``` +Q: "How does the caching system work?" + +A: The caching system uses a two-tier approach: + +1. **In-Memory Cache** (`src/cache/MemoryCache.ts:12-45`) + - LRU eviction + - TTL support + - Max 1000 entries + +2. **Redis Cache** (`src/cache/RedisCache.ts:8-67`) + - Distributed caching + - Persistence across restarts + - Pub/Sub invalidation + +Flow: +Request → Memory cache → Redis cache → Source +``` + +### Concept Questions + +``` +Q: "What is a Repository pattern?" + +A: Repository pattern separates data access from business logic: + +```typescript +// Definition at src/repositories/BaseRepository.ts:5 +interface Repository { + findById(id: string): Promise; + findAll(): Promise; + create(entity: T): Promise; + update(id: string, entity: T): Promise; + delete(id: string): Promise; +} + +// Usage at src/services/UserService.ts:23 +const user = await userRepository.findById(userId); +``` + +Benefits: +- Abstracts data source +- Easier testing (mock repositories) +- Centralized query logic +``` + +### Best Practice Questions + +``` +Q: "How should I handle errors in async functions?" + +A: Project conventions (see `src/utils/async.ts`): + +```typescript +// Preferred pattern +async function fetchData(id: string): Promise> { + try { + const data = await repository.findById(id); + if (!data) { + return { ok: false, error: 'NOT_FOUND' }; + } + return { ok: true, value: data }; + } catch (error) { + logger.error('fetchData failed', { id, error }); + return { ok: false, error: 'INTERNAL_ERROR' }; + } +} +``` + +Avoid: +- Throwing in normal flow +- Silent catch blocks +- Unhandled promise rejections +``` + +### Comparison Questions + +``` +Q: "What's the difference between useState and useReducer?" + +A: +| Aspect | useState | useReducer | +|--------|----------|------------| +| Best for | Simple state | Complex state | +| Updates | Direct value | via actions | +| Logic | In handlers | In reducer | +| Testing | Harder | Easier | + +Use `useState` when: +- Simple values (string, number, boolean) +- Single update logic + +Use `useReducer` when: +- Complex state objects +- Multiple related values +- Complex update logic +- Need testable state transitions +``` + +## Response Format + +### For Location Questions +```markdown +## Found: [What] + +### Locations +- `path/to/file.ts:start-end` - [Brief description] +- `path/to/other.ts:start-end` - [Brief description] +``` + +### For Explanation Questions +```markdown +## [Concept/Feature] + +### Overview +[1-2 sentence summary] + +### Details +[Explanation with code examples] + +### Key Files +- `file:line` - [Purpose] +``` + +### For Concept Questions +```markdown +## [Concept] + +### Definition +[Clear definition] + +### How It Works +[Explanation with example] + +### In This Codebase +- Used in `file:line` +- Pattern: [How it's used here] +``` + +### For Best Practice Questions +```markdown +## Best Practice: [Topic] + +### Recommended Approach +```[code]``` + +### Why +[Reasoning] + +### In This Project +[How it's implemented here] + +### Avoid +[Anti-patterns to avoid] +``` + +## Best Practices + +- Minimize output tokens while being thorough +- Include file paths with line numbers +- Show code snippets for clarity +- Reference patterns used in the codebase +- Don't explain unrelated concepts +- Answer in the language asked + +## Search Strategies + +By Question Type: +- "Where is...": Use `glob` for files, `grep` for code +- "How does...": Read implementation files +- "What is...": Check docs, explain concept +- "Why does...": Read related code, analyze patterns +- "Should I...": Check similar code, explain tradeoffs + +## Examples + +**User**: "Where is the API rate limiting implemented?" + +**Search**: +```bash +grep -r "rateLimit\|rate-limit\|throttle" src/ +``` + +**Response**: +Rate limiting is implemented in: + +- `src/middleware/rateLimiter.ts:15-78` - Main rate limiter middleware +- `src/config/rateLimits.ts:1-45` - Configuration + +Key features: +- Token bucket algorithm +- Configurable per-endpoint limits +- Redis-backed for distributed systems \ No newline at end of file diff --git a/.kilo/commands/code.md b/.kilo/commands/code.md index 16f6aa8..48cc0e9 100644 --- a/.kilo/commands/code.md +++ b/.kilo/commands/code.md @@ -7,4 +7,163 @@ color: "#10B981" # Code Command -Quick code generation for small tasks. \ No newline at end of file +Quick code generation for small, well-defined tasks following existing patterns and conventions. + +## When to Use + +- Small, isolated changes +- Bug fixes with known solution +- Adding similar functionality to existing code +- Refactoring small code blocks +- Utility functions + +## When NOT to Use + +- New features → Use `/feature` +- Complex bugs → Use `/debug` +- Architecture changes → Use `/plan` +- Large refactors → Use `/plan` + +## Workflow + +### Step 1: Understand Request + +- Parse what needs to be implemented +- Identify the type of change: + - New function + - Bug fix + - Refactor + - Configuration + - Test + +### Step 2: Find Patterns + +- Search for similar code: `grep "pattern" src/` +- Find related files: `glob "**/related*"` +- Read neighboring code for conventions +- Check imports for available libraries + +```bash +# Find existing patterns +grep -r "similar_function" src/ +glob "**/similar*.ts" +``` + +### Step 3: Check Dependencies + +- Read `package.json` / `cargo.toml` / equivalent +- Verify required libraries exist +- Do NOT add new dependencies without asking +- Use existing utilities when available + +### Step 4: Implement + +- Follow existing code style exactly +- Use early returns to reduce nesting +- Handle edge cases: + - Null/undefined inputs + - Empty collections + - Boundary values + - Error conditions +- Keep functions small and focused +- NO comments unless explicitly requested + +### Step 5: Test + +- Create test if appropriate +- Run existing tests to verify no regressions +- Handle errors gracefully + +## Code Style Guidelines + +### Variable Naming +```javascript +const userCount = users.length; +const isValidEmail = email.includes('@'); +const httpClient = createHttpClient(); +``` + +### Early Returns +```javascript +function processUser(user) { + if (!user) return null; + if (!user.active) return inactiveResponse(); + return processActiveUser(user); +} +``` + +### Error Handling +```javascript +function fetchData(id) { + if (!id) throw new Error('id is required'); + + return repository.findById(id) + .then(data => data || null) + .catch(err => { + logger.error('Failed to fetch', { id, error: err.message }); + throw err; + }); +} +``` + +### Small Functions +```javascript +function validateUser(user) { + if (!user.email) return false; + if (!user.name) return false; + return user.age >= 18; +} +``` + +## Implementation Checklist + +- [ ] Follows existing patterns +- [ ] Uses existing dependencies +- [ ] Handles edge cases +- [ ] Uses early returns +- [ ] Clear naming +- [ ] No unnecessary comments +- [ ] No secrets hardcoded + +## Examples + +### Adding a Function +``` +User: Add a function to validate email format + +Result: Search for validation patterns, implement using existing validation utilities, handle edge cases +``` + +### Bug Fix +``` +User: Fix the null pointer in getUserProfile + +Result: Locate function, identify null check missing, add defensive code +``` + +### Small Feature +``` +User: Add logging to the payment service + +Result: Check existing logging library, add appropriate log statements at key points +``` + +## Output Format + +```markdown +## Implementation Complete + +### Changes +- [File path]: [Description of change] + +### Reasoning +- [Why this approach] +- [Pattern followed] + +### Edge Cases Handled +- [Case 1]: [How handled] +- [Case 2]: [How handled] + +### Tests +- [Test file if created] +``` \ No newline at end of file diff --git a/.kilo/commands/debug.md b/.kilo/commands/debug.md index f711a2f..6c33db3 100644 --- a/.kilo/commands/debug.md +++ b/.kilo/commands/debug.md @@ -7,4 +7,312 @@ color: "#EF4444" # Debug Command -Analyzes and fixes bugs in the codebase. \ No newline at end of file +Systematic debugging workflow for analyzing and fixing bugs in the codebase. + +## Debugging Philosophy + +1. **Reproduce** - Make the bug happen consistently +2. **Isolate** - Narrow down the location +3. **Understand** - Find the root cause +4. **Fix** - Make minimal, targeted changes +5. **Verify** - Ensure fix works and no regressions + +## Workflow + +### Step 1: Gather Information + +- Collect error details: + - Error messages + - Stack traces + - Console output + - Log files + - User-reported symptoms +- Ask clarifying questions: + - When does it occur? + - What triggers it? + - What was expected? + - Environment details? + +```markdown +## Bug Report Template + +### Error Message +``` +[Full error/stack trace] +``` + +### Context +- Environment: [dev/staging/prod] +- Expected: [What should happen] +- Actual: [What happens] +- Frequency: [Always/Sometimes/Under condition] + +### Reproduction +1. [Step 1] +2. [Step 2] +3. [Step 3] +``` + +### Step 2: Reproduce Issue + +- Create reproduction steps +- Verify bug exists +- Isolate minimal case: + - Remove dependencies + - Simplify input + - Create isolated test + +```javascript +// Minimal reproduction test +describe('Bug reproduction', () => { + it('should reproduce the bug', () => { + // Minimal code to trigger bug + const result = buggyFunction(minimalInput); + expect(result).toBe(expectedValue); // Should fail + }); +}); +``` + +### Step 3: Locate Bug + +- Trace error to source: + - Follow stack trace + - Check related files +- Search strategies: + ```bash + # Find error source + grep -r "errorMessage" src/ + + # Find related function + grep -r "functionName" src/ + + # Find similar patterns + grep -A5 -B5 "pattern" src/file.js + ``` +- Use logging: + ```javascript + console.log('Variable state:', variable); + console.log('Function entry:', params); + console.log('Decision point:', { condition, value }); + ``` + +### Step 4: Root Cause Analysis + +Identify the category: +- **Logic Error**: Wrong condition, wrong calculation +- **Type Error**: Wrong type assumption, null/undefined +- **State Error**: Incorrect state mutation, race condition +- **Integration Error**: API mismatch, wrong contract +- **Data Error**: Corrupt data, missing data +- **Environment Error**: Config difference, missing dependency + +Analyze deeply: +```markdown +## Root Cause Analysis + +### Immediate Cause +[What directly causes the symptom] + +### Underlying Cause +[Why the immediate cause exists] + +### Trigger Condition +[What makes it happen] + +### Example +- Symptom: "Cannot read property 'id' of undefined" +- Immediate: user.id accessed when user is undefined +- Underlying: API returns null for non-existent user +- Trigger: User ID doesn't exist in database +``` + +### Step 5: Develop Fix + +- Propose minimal fix +- Explain reasoning +- Show before/after: + +```markdown +## Fix Proposal + +### Change +File: `src/services/user.js:45` + +### Before +```javascript +function getUserName(user) { + return user.name.toUpperCase(); +} +``` + +### After +```javascript +function getUserName(user) { + if (!user || !user.name) return 'Unknown'; + return user.name.toUpperCase(); +} +``` + +### Reasoning +1. user can be null when not found +2. user.name can be undefined for incomplete profiles +3. Defensive check prevents crash +4. Default value maintains user experience +``` + +### Step 6: Verify Fix + +- Run reproduction test (should pass now) +- Run all tests (check for regressions) +- Verify edge cases: + - Empty inputs + - Null/undefined + - Boundary values + - Error conditions + +```markdown +## Verification Results + +### Reproduction Test +- Before fix: [FAIL] +- After fix: [PASS] + +### Edge Cases +- null input: [PASS] - returns 'Unknown' +- undefined input: [PASS] - returns 'Unknown' +- empty object: [PASS] - returns 'Unknown' +- valid input: [PASS] - returns uppercased name + +### Regression Tests +- All existing tests: [PASS] +``` + +### Step 7: Prevent Recurrence + +- Add tests for bug case +- Consider additional validation +- Update documentation if needed +- Add monitoring if applicable + +```markdown +## Prevention + +### Tests Added +- `should return Unknown when user is null` +- `should return Unknown when name is undefined` +- `should handle empty user object` + +### Monitoring +- Log warning when null user encountered +- Track occurrence rate +``` + +## Common Bug Patterns + +### Null/Undefined Errors +```javascript +// Bad +const name = user.profile.name; + +// Good +const name = user?.profile?.name || 'Unknown'; +``` + +### Async/Await Errors +```javascript +// Bad - Unhandled promise rejection +async function getData() { + const data = await fetchData(); + return data.value; +} + +// Good +async function getData() { + try { + const data = await fetchData(); + return data?.value ?? null; + } catch (error) { + logger.error('getData failed', { error }); + return null; + } +} +``` + +### Race Conditions +```javascript +// Bad - State changed during async +let cached = null; +async function getData() { + if (!cached) { + cached = await fetch(); // Multiple calls might race + } + return cached; +} + +// Good - Single promise +let cachedPromise = null; +function getData() { + if (!cachedPromise) { + cachedPromise = fetch(); + } + return cachedPromise; +} +``` + +### Type Assumptions +```javascript +// Bad - Assumes array +function processItems(items) { + return items.map(i => i.value); +} + +// Good - Validates input +function processItems(items) { + if (!Array.isArray(items)) return []; + return items.map(i => i?.value).filter(Boolean); +} +``` + +## Debug Commands + +```bash +# Find recent changes +git log --oneline -10 + +# Find when bug was introduced +git bisect start +git bisect bad HEAD +git bisect good + +# Search code history +git log -p -S "buggyCode" --all + +# Check dependencies +npm ls package-name +``` + +## Output Format + +```markdown +# Debug Report + +## Summary +[Bug description and fix summary] + +## Root Cause +- Location: [File:line] +- Type: [Category] +- Cause: [Explanation] + +## Fix +[Code change] + +## Verification +- Reproduction test: PASS +- Edge cases: PASS +- Regressions: None + +## Prevention +- Tests added: [count] +- Monitoring: [if any] +``` \ No newline at end of file diff --git a/.kilo/commands/feature.md b/.kilo/commands/feature.md new file mode 100644 index 0000000..6aecfd4 --- /dev/null +++ b/.kilo/commands/feature.md @@ -0,0 +1,246 @@ +--- +description: Full feature development pipeline from requirements to release +mode: feature +model: ollama-cloud/deepseek-v3.2 +color: "#059669" +--- + +# Feature Command + +Executes the complete development pipeline for implementing new features, following TDD and quality gates. + +## Pipeline Flow + +``` +Requirements → History → Design → Tests → Implementation → Review → Performance → Security → Release +``` + +## Workflow + +### Step 1: Requirements Refinement +**Agent**: `@RequirementRefiner` + +- Transform vague ideas into strict User Stories +- Define INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) +- Document acceptance criteria as checkboxes +- Identify stakeholders and user personas +- Create user story format: + ``` + As a [user type] + I want [goal] + So that [benefit] + ``` + +### Step 2: History Check +**Agent**: `@HistoryMiner` + +- Search for duplicate or similar past work +- Query: `git log --all --oneline --grep=""` +- Code search: `git log -p --all -S ""` +- Review closed PRs for related work +- Identify reusable solutions +- Document lessons learned from past attempts + +### Step 3: System Design +**Agent**: `@SystemAnalyst` + +- Design technical specification +- Create architecture diagram (ASCII or markdown) +- Define data models and schemas +- Specify API contracts +- Identify integration points +- Document security considerations +- Create design document: + ```markdown + ## Technical Design + + ### Architecture + [Diagram description] + + ### Components + - Component A: [Purpose] + - Component B: [Purpose] + + ### Data Flow + 1. [Step 1] + 2. [Step 2] + + ### API Design + [Endpoints, contracts] + ``` + +### Step 4: Test Creation (TDD) +**Agent**: `@SDETEngineer` + +- Write tests BEFORE implementation +- Create test file near source file +- Cover unit tests: + - Happy path scenarios + - Edge cases (empty, null, boundaries) + - Error conditions +- Create integration tests if needed +- Ensure tests are deterministic and repeatable +- Run tests to confirm they fail (red phase) +- Test structure: + ```javascript + describe('FeatureName', () => { + describe('methodName', () => { + it('should [expected behavior] when [condition]', () => { + // Arrange + // Act + // Assert + }); + }); + }); + ``` + +### Step 5: Implementation +**Agent**: `@LeadDeveloper` + +- Implement minimum code to pass tests +- Follow existing code patterns and conventions +- Use early returns to reduce nesting +- Handle edge cases and errors +- No comments unless explicitly requested +- Check `package.json`/`cargo.toml` for dependencies +- Use existing utilities when available +- Run tests frequently (red-green-refactor) +- Commit atomically with clear messages + +### Step 6: Code Review +**Agent**: `@CodeSkeptic` + +- Review all changes adversarially +- Check for: + - Correctness and edge cases + - Security vulnerabilities (XSS, SQL injection, secrets) + - Performance issues (N+1 queries, memory leaks) + - Maintainability (naming, DRY) +- Generate review report: + ```markdown + ## Code Review Report + + ### Critical Issues + - [Issue]: [File:line] - [Description] - [Suggestion] + + ### Warnings + - [Issue]: [File:line] - [Description] + + ### Approved ✓ + - [List approved aspects] + ``` +- If FAIL: Route to `@TheFixer` → Return to Step 6 +- If PASS: Continue to Step 7 + +### Step 7: Performance Review +**Agent**: `@PerformanceEngineer` + +- Check for performance bottlenecks +- Analyze time and space complexity +- Review database query efficiency +- Identify unnecessary computations +- Check for proper use of caching +- Suggest optimizations only if needed +- Report format: + ```markdown + ## Performance Report + + ### Queries + - [Query]: [Complexity] - [Optimization suggestion if needed] + + ### Algorithms + - [Function]: [Time complexity] - [Improvement if critical] + + ### Status + - PASS / FAIL with reasons + ``` + +### Step 8: Security Audit +**Agent**: `@SecurityAuditor` + +- Scan for vulnerabilities: + - Input validation + - Authentication/Authorization + - Data exposure + - Injection attacks + - Sensitive data handling +- Check for hardcoded secrets +- Verify proper error handling +- Review dependencies for known CVEs +- Report format: + ```markdown + ## Security Audit + + ### Vulnerabilities Found + - Severity: [Critical/High/Medium/Low] + - Type: [Vulnerability type] + - Location: [File:line] + - Remediation: [Fix recommendation] + + ### Status + - PASS / FAIL with reasons + ``` + +### Step 9: Release Preparation +**Agent**: `@ReleaseManager` + +- Run linting and type checking +- Verify all tests pass +- Check code coverage thresholds +- Create/update changelog +- Prepare commit messages +- **Only commit if user explicitly requests** +- Commit message format: + ``` + feat: [brief description of feature] + + [Detailed explanation if needed] + ``` + +## Quality Gates + +Each step must PASS before proceeding: + +| Gate | Criteria | +|------|----------| +| Requirements | All acceptance criteria defined | +| History | No duplicate work identified | +| Design | Technical spec reviewed | +| Tests | All tests written and failing | +| Implementation | All tests passing | +| Review | No critical issues remaining | +| Performance | No critical bottlenecks | +| Security | No critical vulnerabilities | + +## Rollback Points + +If issues arise, roll back to: +- Design issues → Return to Step 3 +- Test failures → Return to Step 5 +- Security issues → Return to Step 5 +- Performance issues → Evaluate necessity + +## Final Output + +```markdown +# Feature Complete: [Name] + +## Summary +- Requirements: ✓ [Count] criteria defined +- History: ✓ No duplicates found +- Design: ✓ [Document link] +- Tests: ✓ [Count] tests passing +- Implementation: ✓ Complete +- Review: ✓ All issues resolved +- Performance: ✓ Optimized +- Security: ✓ No vulnerabilities + +## Files Modified +- [List of all modified files] + +## Tests Added +- [List of test files] + +## Next Steps +- [Release instructions or follow-up tasks] +``` \ No newline at end of file diff --git a/.kilo/commands/hotfix.md b/.kilo/commands/hotfix.md new file mode 100644 index 0000000..6254f0c --- /dev/null +++ b/.kilo/commands/hotfix.md @@ -0,0 +1,261 @@ +--- +description: Quick bug fix workflow for urgent production issues +mode: hotfix +model: ollama-cloud/minimax-m2.7 +color: "#DC2626" +--- + +# Hotfix Command + +Rapid response workflow for urgent production bug fixes with minimal, targeted changes. + +## Workflow + +### Step 1: Bug Analysis +**Agent**: `@TheFixer` + +- Collect bug report information: + - Error messages + - Stack traces + - User-reported symptoms + - Reproduction steps +- Identify impact: + - Severity: Critical / High / Medium / Low + - Affected users: Count and segments + - System components affected +- Determine urgency: + - Production down: Immediate + - Data loss risk: Very High + - User-facing bug: High + - Internal tool: Medium + +```markdown +## Bug Report + +### Symptom +[What is happening] + +### Expected +[What should happen] + +### Impact +- Severity: [Level] +- Affected: [Users/Components] +- Urgency: [Level] + +### Reproduction +1. [Step 1] +2. [Step 2] +3. [Step 3] +``` + +### Step 2: Locate Bug +**Agent**: `@TheFixer` + +- Search for error messages: `grep -r "error message" src/` +- Find related code: `grep "function_name" src/` +- Trace stack to source +- Identify root cause: + - Logic error + - Data issue + - Integration failure + - Environment difference +- Document findings: + ```markdown + ## Root Cause Analysis + + ### Location + - File: [path] + - Line: [number] + - Function: [name] + + ### Cause + [Technical explanation] + + ### Trigger + [What conditions cause the bug] + ``` + +### Step 3: Minimal Fix +**Agent**: `@TheFixer` + +- Principle: Smallest change that fixes the issue +- Do NOT refactor or improve surrounding code +- Do NOT add new features +- Fix must be: + - Targeted to specific bug + - Low risk + - Easy to review + - Reversible if needed +- Create fix with: + - Clear before/after behavior + - Focused change scope + +```markdown +## Fix Proposal + +### Change +- File: [path] +- Lines: [range] +- Type: [Logic fix / Condition update / Error handling] + +### Before +[code snippet] + +### After +[code snippet] + +### Reasoning +[Why this fix] +``` + +### Step 4: Test Fix +**Agent**: `@SDETEngineer` + +- Create reproduction test: + ```javascript + it('should [expected behavior] when [condition]', () => { + // This test reproduces the bug + // It should FAIL before fix, PASS after fix + }); + ``` +- Verify test fails without fix +- Apply fix +- Verify test passes with fix +- Run existing tests to check for regressions +- Document test: + ```markdown + ## Test Verification + + ### Reproduction Test + - File: [test file] + - Test: [test name] + - Fails without fix: ✓ + - Passes with fix: ✓ + + ### Regression Tests + - All tests pass: ✓ + - Failed tests: [List or None] + ``` + +### Step 5: Quick Review +**Agent**: `@CodeSkeptic` + +- Focus on: + - Does fix address root cause? + - Are there obvious side effects? + - Is change minimal? +- Skip for critical production down: + - If production is DOWN, proceed to deploy + - Schedule full review post-deploy +- Review checklist: + ```markdown + ## Hotfix Review + + ### Minimal Change + - Changes scope: [Lines changed] + - No unrelated changes: ✓/✗ + + ### Correctness + - Addresses root cause: ✓/✗ + - No side effects: ✓/✗ + + ### Tests + - Has reproduction test: ✓/✗ + - No regressions: ✓/✗ + + ### Verdict + - APPROVE / NEEDS_WORK + ``` + +### Step 6: Prepare for Merge +**Agent**: `@ReleaseManager` + +- Create hotfix branch from main +- Apply changes +- Update CHANGELOG.md: + ```markdown + ## [Unreleased] + + ### Fixed + - [Bug description] fixing #[issue] + ``` +- Commit with clear message: + ``` + fix: [brief description] + + - Root cause: [explanation] + - Fix: [what changed] + - Fixes #[issue] + ``` +- **Only merge if user explicitly requests** +- Post-merge actions: + - Monitor for issues + - Schedule retrospective + - Update documentation if needed + +## Hotfix Branch Strategy + +``` +main ───●───●───●───● + \ +hotfix/xxx ●───● + / +main ───────●───●───● (merge back) +``` + +1. Branch from main +2. Apply minimal fix +3. Test thoroughly +4. Merge to main +5. Tag release + +## Quality Gates for Hotfix + +| Gate | Requirement | +|------|-------------| +| Root cause identified | Must | +| Minimal change scope | Must | +| Reproduction test | Must | +| No regressions | Must | +| Reviewed | Unless production down | + +## Post-Hotfix Actions + +1. **Monitor**: Watch logs and metrics for 24-48 hours +2. **Document**: Update runbooks if applicable +3. **Retrospective**: Schedule bug postmortem +4. **Prevention**: Add checks to prevent recurrence: + - Additional tests + - Monitoring alerts + - Validation rules + +## Rollback Plan + +If hotfix causes issues: +1. Revert commit immediately +2. Restore previous version +3. Investigate regression +4. Create new hotfix if needed + +```bash +# Rollback command +git revert +git push origin main +``` + +## Time Targets + +| Severity | Target Resolution | +|----------|-------------------| +| Critical (prod down) | 30 minutes | +| High (user impact) | 2 hours | +| Medium (internal) | 4 hours | +| Low (minor) | Next sprint | + +## Escalation + +If fix is not straightforward: +- Complex fix needed → Upgrade to `/feature` workflow +- Requires redesign → Escalate to architect +- Data migration needed → Coordinate with DBA \ No newline at end of file diff --git a/.kilo/commands/plan.md b/.kilo/commands/plan.md index 2673a30..b7936f4 100644 --- a/.kilo/commands/plan.md +++ b/.kilo/commands/plan.md @@ -7,4 +7,93 @@ color: "#3B82F6" # Plan Command -Generates detailed implementation plans with task breakdown. \ No newline at end of file +Generates detailed implementation plans with task breakdown, complexity estimates, and dependency analysis. + +## Workflow + +### Step 1: Analyze Requirements +- Parse the user's request into clear objectives +- Identify functional requirements +- Identify non-functional requirements (performance, security, scalability) +- Clarify ambiguous points with follow-up questions +- Document acceptance criteria + +### Step 2: Check Git History +- Search for similar features: `git log --all --oneline --grep=""` +- Search for related code changes: `git log -p --all -S ""` +- Identify past solutions and patterns +- Note any blockers encountered previously +- Reference relevant commits for context + +### Step 3: Explore Codebase +- Use Glob to find relevant files: `glob "**/"` +- Use Grep to find related code: `grep ""` +- Identify existing patterns and conventions +- Locate reusable components and utilities +- Map component dependencies + +### Step 4: Create Task Breakdown +- Decompose into atomic, testable units +- Define clear deliverables for each task +- Establish task order and dependencies +- Assign to appropriate pipeline agents: + - `@LeadDeveloper` - Core implementation + - `@FrontendDeveloper` - UI components + - `@SDETEngineer` - Test creation + - `@SystemAnalyst` - Architecture decisions + +### Step 5: Estimate Complexity +- Rate each task: Simple (1-2h), Medium (2-4h), Complex (4h+) +- Consider technical debt and refactoring needs +- Account for testing and documentation +- Add buffer for unexpected issues (20%) + +### Step 6: Identify Dependencies +- List external dependencies (libraries, APIs, services) +- Identify internal dependencies (modules, components) +- Flag blocking dependencies +- Suggest parallel vs sequential execution paths + +## Output Format + +```markdown +# Implementation Plan: [Feature Name] + +## Summary +[Brief description of what will be built] + +## Acceptance Criteria +- [ ] Criterion 1 +- [ ] Criterion 2 +- [ ] Criterion 3 + +## Task Breakdown + +### Task 1: [Task Name] +- **Agent**: @LeadDeveloper +- **Complexity**: Simple/Medium/Complex +- **Dependencies**: None/List dependencies +- **Deliverables**: [What will be delivered] +- **Files affected**: [List files to modify] + +### Task 2: [Task Name] +... + +## Technical Decisions +- [Key decisions and rationale] + +## Risks & Mitigations +- **Risk**: [Description] → **Mitigation**: [Strategy] + +## Estimated Timeline +- Total: X hours +- Breakdown by phase +``` + +## Best Practices + +- Keep plans actionable and specific +- Include file paths and line references where applicable +- Reference existing code patterns +- Consider security implications early +- Plan for error handling and edge cases \ No newline at end of file diff --git a/.kilo/commands/review.md b/.kilo/commands/review.md new file mode 100644 index 0000000..aee189b --- /dev/null +++ b/.kilo/commands/review.md @@ -0,0 +1,232 @@ +--- +description: Comprehensive code review with tests, style, security, and performance checks +mode: review +model: ollama-cloud/gpt-oss-120b +color: "#F59E0B" +--- + +# Review Command + +Executes comprehensive code review across multiple dimensions: correctness, style, security, and performance. + +## Workflow + +### Step 1: Run Tests +**Agent**: `@SDETEngineer` + +- Execute full test suite +- Check for failing tests +- Verify test coverage +- Analyze test quality: + - Are edge cases covered? + - Are tests deterministic? + - Are tests readable? +- Generate test report: + ```markdown + ## Test Results + + ### Summary + - Total tests: X + - Passed: X + - Failed: X + - Coverage: X% + + ### Failures + - [Test name]: [Reason] + ``` + +### Step 2: Code Style Check +**Agent**: `@CodeSkeptic` + +- Run linter (eslint, ruff, prettier, etc.) +- Check formatter compliance +- Verify naming conventions: + - Variables: descriptive, consistent casing + - Functions: verb-based, clear purpose + - Classes/Types: noun-based, PascalCase +- Check code organization: + - File structure follows conventions + - Imports are organized + - No unused dependencies +- Generate style report: + ```markdown + ## Style Report + + ### Linting + - Status: PASS/FAIL + - Errors: [Count] + - Warnings: [Count] + + ### Conventions + - Naming: [Issues if any] + - Structure: [Issues if any] + ``` + +### Step 3: Correctness Review +**Agent**: `@CodeSkeptic` + +- Analyze logic correctness +- Check edge cases: + - Null/undefined handling + - Empty collections + - Boundary values + - Type mismatches +- Verify error handling: + - Try-catch blocks appropriate + - Error messages informative + - Graceful degradation +- Check data integrity: + - State mutations controlled + - Race conditions prevented + - Data validation present + +### Step 4: Security Scan +**Agent**: `@SecurityAuditor` + +- Input validation: + - All external inputs sanitized + - Type checking implemented + - Length limits enforced +- Injection prevention: + - SQL injection (parameterized queries) + - XSS (output encoding) + - Command injection (no shell execution) +- Authentication/Authorization: + - Proper auth checks + - Session management secure + - Privilege escalation prevented +- Secrets management: + - No hardcoded credentials + - Environment variables used + - Sensitive data encrypted +- Dependency vulnerabilities: + - Check for known CVEs + - Outdated packages flagged +- Generate security report: + ```markdown + ## Security Audit + + ### Critical + - [No critical issues OR list] + + ### High + - [Issue]: [File:line] - [Description] + + ### Medium + - [Issue]: [File:line] - [Description] + + ### Low + - [Issue]: [Description] + + ### Status + - PASS / FAIL + ``` + +### Step 5: Performance Review +**Agent**: `@PerformanceEngineer` + +- Algorithm complexity: + - Time complexity acceptable for use case + - Space complexity reasonable + - No unnecessary iterations +- Database queries: + - N+1 queries identified + - Indexes used properly + - Query optimization opportunities +- Memory usage: + - Memory leaks potential + - Large object creation unnecessary + - Proper cleanup implemented +- Concurrency: + - Race conditions prevented + - Deadlock potential + - Resource contention +- Generate performance report: + ```markdown + ## Performance Report + + ### Complexity Analysis + - [Function]: O(n) - [Acceptable/Needs attention] + + ### Database + - Query count: [Count] + - N+1 issues: [Yes/No] + + ### Memory + - Large allocations: [List if any] + - Leak potential: [Locations] + + ### Recommendations + - [Optimization suggestions] + ``` + +### Step 6: Generate Review Report +**Agent**: `@CodeSkeptic` + +Compile all findings into unified report: + +```markdown +# Code Review Report + +## Overview +- **Branch**: [branch name] +- **Files Changed**: [count] +- **Lines Added**: [count] +- **Lines Removed**: [count] + +## Summary + +| Category | Status | Issues | +|----------|--------|--------| +| Tests | ✅/⚠️/❌ | [count] | +| Style | ✅/⚠️/❌ | [count] | +| Correctness | ✅/⚠️/❌ | [count] | +| Security | ✅/⚠️/❌ | [count] | +| Performance | ✅/⚠️/❌ | [count] | + +## Critical Issues (Must Fix) +1. **[Category]**: [File:line] + - Issue: [Description] + - Suggestion: [Fix recommendation] + +## Warnings (Should Fix) +1. **[Category]**: [File:line] + - Issue: [Description] + +## Suggestions (Consider) +- [Improvement ideas] + +## Blocking Issues +- [Issues that prevent approval] + +## Approved Changes +- [List changes that passed review] + +## Verdict +- **APPROVE**: Ready to merge +- **APPROVE WITH COMMENTS**: Minor fixes needed, not blocking +- **REQUEST CHANGES**: Critical issues must be addressed +- **REJECT**: Fundamental problems, requires redesign +``` + +## Quality Gates + +| Gate | Must Pass | +|------|-----------| +| All tests pass | Yes | +| No linting errors | Yes | +| No critical security issues | Yes | +| No performance regressions | Yes | +| Code follows conventions | Yes | + +## Review Checklist + +- [ ] Tests pass and cover new code +- [ ] Linting passes without errors +- [ ] No critical security vulnerabilities +- [ ] No obvious performance issues +- [ ] Edge cases handled +- [ ] Error handling appropriate +- [ ] Code is readable and maintainable +- [ ] No secrets or credentials exposed +- [ ] Dependencies are justified and current \ No newline at end of file