AI agents that build features and fix bugs for you. Handles the tedious stuff from requirements to PRs so you can focus on the interesting problems.
Two workflows:
- 🎨 Feature Development - Spec → Plan → Code → Tests → PR (all automated)
- 🐛 Bug Resolution - RCA → Solution → Fix → Tests → PR (with actual investigation)
Key stuff:
- Stack analysis caches so you're not burning tokens analyzing the same codebase repeatedly
- Adaptive clarification (asks 3-12 questions depending on complexity, or uses defaults)
- UI validation loop (vision model grades your UI and auto-fixes it until it doesn't look like shit)
- Quality gates (linting, tests, builds, accessibility)
- Resumable (interrupt anywhere, pick up later)
- Human-in-loop or full auto mode (your choice)
Type one command, get a production-ready feature. Reviews at each step if you want, or let it run.
# Manual mode - you review and approve each phase
/feature-start "Add user authentication with OAuth providers" user-auth
# Auto mode - fully automated from idea to PR
/feature-start "Add real-time notifications" notifications --autoAgent: feat-orchestrator
- Creates workspace:
.agents/features/user-auth/ - Loads config from
.claude/feat-config.json - Initializes state tracking for resumability
- Determines feature type (frontend/backend/full-stack)
Output: Feature workspace ready, workflow configured
Agent: feat-stack-analyzer
Analyzes your codebase once, caches everything:
- Scans
package.json, lock files,tsconfig.json - Analyzes directory structure and file organization
- Samples actual code files to extract patterns
- Identifies: Framework (Next.js 14), UI library (React + Tailwind), Database (Convex), Auth (Clerk)
- Documents: Component patterns, naming conventions, error handling, import aliases
- Generates recommendations: "When adding components, place in
components/features/{name}/"
Result: Complete stack profile saved to .agents/stack-profile.json
This runs once. Every feature after uses the cache. Saves 80% of tokens.
Intervention: None (cached on subsequent runs)
Agent: feat-clarification
Asks questions based on complexity:
Simple CRUD (3-5 questions):
1. Primary user flow in 2-3 sentences?
2. Main success outcome?
3. Critical edge cases to handle?
Complex Feature (9-12 questions):
1. Describe the complete user journey
2. Which user roles interact with this?
3. Real-time updates needed?
4. Integration with existing features?
5. Scale expectations (users/requests)?
6. Data privacy considerations?
7. Mobile-first or desktop-first?
8. Accessibility requirements (WCAG)?
9. Performance budget?
10. Third-party services needed?
Questions adapt to feature type. Skips obvious stuff by using the stack profile. Auto mode uses defaults.
Output: .agents/features/user-auth/user-auth-clarifications.md
Intervention Point: Review answers, modify if needed
Agent: feat-spec
Generates a complete PRD with:
- Executive Summary: Business value, technical approach
- Problem Statement: Current limitations, user pain points
- Goals & Objectives: SMART objectives with KPIs
- User Stories: Complete with acceptance criteria
US-001: As an unauthenticated user, I want to sign in with Google - Priority: High - Acceptance Criteria: ✓ OAuth flow completes in <5s ✓ Session persists across page reloads ✓ Error states handled gracefully - Technical Requirements: Uses your actual stack from profile
- "Framework: Next.js 14.2 with App Router"
- "Auth: Clerk (already in stack)"
- "Database: Convex with existing schema patterns"
- System Architecture: Component diagrams, data flow
- API Specifications: Full endpoint definitions with Zod schemas
- Security Requirements: Authentication, authorization, encryption
- Data Models: Complete schema with relationships
- Testing Strategy: Unit, integration, E2E coverage
- Success Metrics: Measurable KPIs
Not generic. Uses your actual stack and patterns from the profile.
Output: .agents/features/user-auth/user-auth-tech-spec.md
Intervention Point: Review spec, request changes
Agent: feat-plan
Breaks spec into atomic tasks:
### Phase 1: Foundation
- [ ] TASK-001: Create Convex schema for User entity
- Details: Add to convex/schema.ts following existing patterns
- Acceptance: Schema compiles, migrations run
- Dependencies: None
- [ ] TASK-002: Create TypeScript types for auth
- Details: Define in types/auth.ts with Zod schemas
- Acceptance: Types exported, importable
- Dependencies: TASK-001
### Phase 2: Backend
- [ ] TASK-003: Implement OAuth callback handler
- Details: Create app/api/auth/callback/route.ts using Clerk
- Acceptance: Callback handles Google/GitHub, creates user
- Dependencies: TASK-001, TASK-002
### Phase 3: Frontend
- [ ] TASK-010: Build SignIn component
- Details: Use shadcn/ui Button, integrate Clerk SignIn
- Acceptance: Renders, handles OAuth flow, error states
- Dependencies: TASK-003
### Phase 4: Testing
- [ ] TASK-020: Unit tests for auth helpers
- [ ] TASK-021: E2E test for complete OAuth flowEach task: 1-4 hours, references actual files, maps to spec requirements, tracks dependencies.
Output: .agents/features/user-auth/user-auth-plan.md
Intervention Point: Adjust tasks, priorities, estimates
Agent: feat-implement
Executes tasks one by one:
🚀 Starting TASK-001: Create Convex schema for User entity
Reading existing schema patterns from convex/schema.ts...
Creating User table with fields: id, email, name, avatar, provider...
Adding indexes on email and provider...
Running schema validation...
✅ TASK-001 completed (12:34:56)
🚀 Starting TASK-002: Create TypeScript types...
Respects dependencies. Tests after each task. Manual mode asks after each, auto mode runs 10 at a time.
Output:
- Files modified: 12
- Files created: 8
- Lines added: 1,247
- Updated plan with checkmarks:
[x] TASK-001 [COMPLETED: 2025-09-30 14:23:45]
Intervention Point: Review code changes, continue or adjust
Agent: feat-validate
Runs quality checks:
Gate 1: Linting & Formatting
Running: biome check --apply
✅ Pass (2.3s) - 3 auto-fixes appliedGate 2: Type Checking
Running: tsc --noEmit
✅ Pass (5.1s) - No errorsGate 3: Tests
Running: bun test
✅ Pass (12.7s) - 42/42 tests, 85% coverageGate 4: Build
Running: bun run build
✅ Pass (45.2s) - Build successfulGate 5: UI Validation (Frontend features only)
Vision model grades your UI and fixes it:
📸 Capturing screenshots...
✅ Desktop (1920x1080)
✅ Tablet (768x1024)
✅ Mobile (375x667)
🎨 Iteration 1/3: Analyzing UI quality with vision model...
Score: 5/10
Issues Found:
- Button alignment inconsistent
- Text contrast too low (WCAG fail)
- Spacing not using design tokens
🔧 Applying fixes...
- Adjusted flex alignment
- Increased text color contrast
- Applied consistent gap-4 spacing
🎨 Iteration 2/3: Re-analyzing...
Score: 6/10
Issues Found:
- Minor spacing inconsistency in mobile view
🔧 Applying fixes...
🎨 Iteration 3/3: Final validation...
Score: 8/10 ✨
✅ Meets quality threshold (≥7)
Grades 1-10, auto-fixes issues, iterates up to 3x until it's ≥7. Prevents shipping ugly UIs.
Gate 6: Accessibility
Running: axe-core accessibility tests
✅ Pass - WCAG AA compliant
✓ Keyboard navigation
✓ Screen reader compatible
✓ Color contrast (4.5:1 minimum)
✓ Focus management
✓ ARIA labels correctOutput: .agents/features/user-auth/validation/
validation-report.md- Complete resultsscreenshots/- Before/after imagesui-grade.json- Scoring historyaccessibility-report.json- WCAG compliance
Intervention Point: Review validation results, fix any remaining issues
Agent: feat-finish
Ship it!
Step 1: Git Commit
Staging 20 changed files...
Creating commit with message:
"feat(auth): Add OAuth authentication with Google and GitHub
- Implemented OAuth callback handlers
- Created user session management
- Added protected route middleware
- Built sign-in UI with Clerk integration
Generated by feature workflow
See: .agents/features/user-auth/"
✅ Commit created: abc123fStep 2: CHANGELOG Update
## [Unreleased] - 2025-09-30
### Added
- **User Authentication**: OAuth-based authentication system
- Google and GitHub sign-in support
- Session management with 7-day expiry
- Protected route middleware
- Responsive sign-in UIStep 3: Pull Request
Creating PR: feat(auth): Add OAuth authentication
Title: feat(auth): Add OAuth authentication with Google and GitHub
Body:
## Summary
Implements complete OAuth authentication system with Google and GitHub providers.
## Changes
- ✅ OAuth callback handlers (Clerk integration)
- ✅ User session management
- ✅ Protected route middleware
- ✅ Sign-in UI components
- ✅ Comprehensive test coverage (42 tests)
## Testing
- TypeScript: ✅ Pass
- Tests: ✅ Pass (42/42, 85% coverage)
- Linting: ✅ Pass
- Build: ✅ Pass
- UI Quality: ✅ 8/10
- Accessibility: ✅ WCAG AA
## Validation
See: .agents/features/user-auth/validation/validation-report.md
## Tasks Completed
All 28 tasks from implementation plan completed.
See: .agents/features/user-auth/user-auth-plan.md
✅ PR created: #142
Step 4: Archive
Moving feature docs to shipped archive...
.agents/features/user-auth/ → .agents/features/shipped/user-auth-20250930/
✅ Feature archivedFinal Output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Feature Complete: user-auth
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Summary:
Mode: Manual
Duration: 4h 23m
Tasks: 28/28 ✅
Files: 20 changed (+1,247 lines)
Tests: 42 passing (85% coverage)
📋 Deliverables:
✅ Tech Spec (comprehensive PRD)
✅ Implementation Plan (28 atomic tasks)
✅ Code Implementation (production-ready)
✅ Tests & Validation (all gates passed)
✅ Documentation (PR, changelog, archives)
🔗 Pull Request: #142
https://github.com/user/repo/pull/142
📦 Archived:
.agents/features/shipped/user-auth-20250930/
👏 Merge when ready! Feature is production-ready.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Stack Profile Caching
- Analyze project once, cache forever
- 80% reduction in analysis time
- Consistent recommendations across all features
- Sub-agents inherit full project context
2. Adaptive Clarification
- Simple CRUD: 3-5 questions
- Complex features: 9-12 questions
- Auto mode uses intelligent defaults
- Learns from existing similar features
3. UI Validation Loop
- Vision model scores design quality (1-10)
- Auto-fixes design issues iteratively
- Up to 3 improvement cycles
- Ensures professional-looking UIs
4. Resumable State
- Interrupt at any phase
- Resume with
/feat-resume user-auth - All progress saved to
status.json - Pick up exactly where you left off
5. Intervention Points
- Configure review points in
feat-config.json - Manual mode: review each phase
- Auto mode: runs end-to-end
- Hybrid: custom intervention mix
Stop wasting hours debugging. Let AI investigate, design the fix, implement it, and ship it - all with a single command.
# Manual mode - review RCA and solution before implementing
/bug-start "Users getting logged out after 5 minutes" auth-token-expiry
# Auto mode - from incident to PR without intervention
/bug-start "Payment fails during high load" payment-race --autoAgent: bug-rca
Systematic incident investigation:
Step 1: Information Gathering
📋 Analyzing Problem Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Problem: Users getting logged out after 5 minutes
Severity: High (affects all users)
🔍 Gathering Evidence
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Searching codebase for:
- Authentication code (lib/auth/, middleware/)
- Session management (session, token, expiry)
- Recent changes (git log --since="1 week ago")
Step 2: Investigation
📂 Found Relevant Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
lib/auth/session.ts
- createSession() sets maxAge: 5 * 60 * 1000 ❌
- Expected: 7 days (604800000)
- Actual: 5 minutes (300000)
middleware.ts
- Uses session.maxAge for validation
- No refresh logic present
git blame lib/auth/session.ts
- Changed in commit abc123f (2 days ago)
- PR #138: "Quick fix for session timeout"
- INCORRECT: Developer used 5 minutes instead of 5 days
Step 3: Timeline Reconstruction
🕐 Timeline of Events
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
T-2 days: PR #138 merged with incorrect session timeout
T-2 days: Deployed to production
T-1 day: First user complaints start
T-now: Affecting all authenticated users
Step 4: Impact Analysis
💥 Impact Assessment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Severity: HIGH
Affected Users: 100% of authenticated users
User Experience: Forced re-login every 5 minutes
Data Loss: No (sessions cleanly expired)
Security Risk: None
Business Impact: High user frustration, support tickets
Step 5: Root Cause Identification
🎯 Root Cause
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PRIMARY: Incorrect session maxAge value in lib/auth/session.ts
- Line 42: maxAge: 5 * 60 * 1000 (5 minutes)
- Should be: 7 * 24 * 60 * 60 * 1000 (7 days)
CONTRIBUTING FACTORS:
- No unit test for session duration
- PR review missed the error
- No staging validation before production deploy
Output: .agents/debugging/auth-token-expiry/auth-token-expiry-rca.md
# Root Cause Analysis: auth-token-expiry
## Executive Summary
Users are being logged out every 5 minutes due to incorrect session
maxAge value in authentication code. Simple fix: change 5 minutes to 7 days.
## Problem Statement
**Reported**: 2025-09-30 14:00
**Impact**: 100% of authenticated users
**Severity**: HIGH
Users report being forced to re-authenticate every 5 minutes during
normal application usage, severely impacting user experience.
## Investigation
### Code Analysis
**File**: lib/auth/session.ts
**Line**: 42
**Issue**: maxAge set to 5 * 60 * 1000 (5 minutes)
**Expected**: 7 * 24 * 60 * 60 * 1000 (7 days)
### Timeline
- **2025-09-28**: PR #138 merged with incorrect timeout value
- **2025-09-29**: First user complaints received
- **2025-09-30**: Issue escalated to engineering
### Evidence
git blame shows commit abc123f changed session duration
PR review comments show no discussion of timeout value
No test coverage for session expiration logic
## Root Cause
**PRIMARY CAUSE**: Developer error in PR #138
- Intended to set 5 days, wrote 5 minutes
- Calculation error: 5 * 60 * 1000 instead of 5 * 24 * 60 * 60 * 1000
**CONTRIBUTING FACTORS**:
1. Missing unit test for session duration constant
2. PR review did not catch calculation error
3. No automated validation of session timeout ranges
4. No staging environment testing before production
## Impact
**User Impact**: HIGH
- All authenticated users affected
- Forced re-login every 5 minutes
- Interrupts workflow, causes frustration
**Business Impact**: MEDIUM
- Increased support ticket volume (50+ tickets)
- User complaints on social media
- No data loss or security breach
**Technical Impact**: LOW
- Isolated to session management
- No database issues
- No cascade failures
## Recommendations
**Immediate Fix** (Priority: CRITICAL):
1. Change maxAge to 7 * 24 * 60 * 60 * 1000
2. Deploy hotfix within 1 hour
3. Monitor user session stability
**Short-term** (Priority: HIGH):
1. Add unit test for session duration
2. Add validation: if (maxAge < 1 hour || maxAge > 30 days) throw
3. Code review checklist: verify time calculations
**Long-term** (Priority: MEDIUM):
1. Implement staging environment validation
2. Add session duration monitoring/alerting
3. Consider using time constants library (ms, timestring)Intervention Point: Review RCA, confirm root cause before proceeding
Agent: bug-solution
Comprehensive fix design:
Step 1: Solution Strategy
🎯 Solution Design
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Primary Fix: Correct session maxAge calculation
Secondary: Add safeguards to prevent recurrence
Risk Level: LOW (simple constant change)
Rollback Plan: Revert single commit
Step 2: Technical Design
🔧 Implementation Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Change 1: lib/auth/session.ts (Line 42)
Before: maxAge: 5 * 60 * 1000
After: maxAge: 7 * 24 * 60 * 60 * 1000 // 7 days in milliseconds
Change 2: Add time constants (NEW FILE: lib/constants/time.ts)
export const TIME = {
FIVE_MINUTES: 5 * 60 * 1000,
ONE_HOUR: 60 * 60 * 1000,
ONE_DAY: 24 * 60 * 60 * 1000,
SEVEN_DAYS: 7 * 24 * 60 * 60 * 1000,
}
Change 3: Update session.ts to use constant
import { TIME } from '@/lib/constants/time'
maxAge: TIME.SEVEN_DAYS
Change 4: Add validation
if (maxAge < TIME.ONE_HOUR) {
throw new Error('Session timeout too short')
}
Change 5: Add unit test (NEW FILE: lib/auth/session.test.ts)
describe('Session Duration', () => {
it('should set session to 7 days', () => {
const session = createSession(user)
expect(session.maxAge).toBe(7 * 24 * 60 * 60 * 1000)
})
it('should reject sessions < 1 hour', () => {
expect(() => createSession(user, { maxAge: 30000 }))
.toThrow('Session timeout too short')
})
})
Step 3: Testing Strategy
🧪 Testing Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Unit Tests:
✓ Session duration is 7 days
✓ Validation rejects < 1 hour
✓ Validation rejects > 30 days
Manual Testing:
1. Create session, verify cookie maxAge
2. Wait 6 minutes, verify still logged in
3. Check session expiration after 7 days
Production Validation:
1. Deploy to staging
2. Monitor session metrics for 1 hour
3. Deploy to production
4. Monitor user session stability
Output: .agents/debugging/auth-token-expiry/auth-token-expiry-solution.md
Intervention Point: Review solution design, approve approach
Agent: bug-implement
Systematic fix execution:
🚀 Implementing Fix: auth-token-expiry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 Task 1: Create time constants
Creating: lib/constants/time.ts
✅ Constants defined and exported
📝 Task 2: Fix session maxAge
Editing: lib/auth/session.ts
- Changed: maxAge: TIME.SEVEN_DAYS
- Added: import statement
- Added: validation logic
✅ Session timeout corrected
📝 Task 3: Add unit tests
Creating: lib/auth/session.test.ts
- Test: session duration is 7 days
- Test: validation rejects short durations
✅ Tests written (2 tests)
📝 Task 4: Run tests
Running: bun test lib/auth/session.test.ts
✅ All tests passing (2/2)
📝 Task 5: Verify no regressions
Running: bun test
✅ All tests passing (44/44)
📝 Task 6: Build verification
Running: bun run build
✅ Build successful
Files Changed:
lib/auth/session.ts(modified)lib/constants/time.ts(created)lib/auth/session.test.ts(created)
Output: Implementation complete with tests
Intervention Point: Review code changes, run manual tests
Agent: bug-orchestrator (with shared-pr-description, shared-changelog)
Git workflow:
🔀 Git Workflow
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Creating branch: fix/auth-token-expiry
Staging changes: 3 files
Creating commit:
"fix(auth): Correct session timeout from 5 minutes to 7 days
Root cause: Developer error in PR #138 set maxAge to 5 minutes
instead of 7 days due to calculation error (5 * 60 * 1000).
Changes:
- Corrected session maxAge to 7 days (604800000ms)
- Added time constants to prevent future calculation errors
- Added validation to reject session timeouts < 1 hour
- Added unit tests for session duration and validation
Testing:
- Unit tests: 44/44 passing
- Manual testing: Session persists beyond 5 minutes
- Build: Successful
Impact: Resolves immediate issue affecting 100% of users
Prevention: Time constants and validation prevent recurrence
Related: .agents/debugging/auth-token-expiry/"
✅ Committed: abc123f
CHANGELOG Update:
## [Unreleased] - 2025-09-30
### Fixed
- **Session Timeout**: Corrected authentication session timeout from
5 minutes to 7 days. Users will no longer be unexpectedly logged out.
- Added time constants to prevent calculation errors
- Added validation for session duration ranges
- Added comprehensive unit testsPull Request:
🎯 Creating Pull Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title: fix(auth): Correct session timeout from 5 minutes to 7 days
Body:
## 🐛 Bug Fix: Session Timeout Issue
### Problem
Users were being logged out every 5 minutes due to incorrect session
maxAge value in `lib/auth/session.ts`.
### Root Cause
Developer error in PR #138: Set timeout to 5 * 60 * 1000 (5 minutes)
instead of 7 * 24 * 60 * 60 * 1000 (7 days).
See: .agents/debugging/auth-token-expiry/auth-token-expiry-rca.md
### Solution
1. ✅ Corrected session maxAge to 7 days
2. ✅ Created time constants library to prevent future errors
3. ✅ Added validation (rejects < 1 hour, > 30 days)
4. ✅ Added comprehensive unit tests
See: .agents/debugging/auth-token-expiry/auth-token-expiry-solution.md
### Changes
- `lib/auth/session.ts` - Corrected maxAge, added validation
- `lib/constants/time.ts` - NEW: Time duration constants
- `lib/auth/session.test.ts` - NEW: Unit tests
### Testing
- ✅ Unit tests: 44/44 passing (2 new tests)
- ✅ Manual: Session persists > 5 minutes
- ✅ Build: Successful
- ✅ Linting: Clean
### Impact
- **Users**: Immediate resolution, no more forced logouts
- **Prevention**: Constants + validation prevent recurrence
- **Risk**: LOW (simple constant change, well-tested)
### Rollback Plan
Revert commit abc123f if any issues observed
Labels: bug, high-priority, hotfix
Reviewers: @tech-lead
✅ PR Created: #143
https://github.com/user/repo/pull/143
Final Output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Bug Fix Complete: auth-token-expiry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Summary:
Mode: Manual
Duration: 45 minutes
Files Changed: 3 (2 new, 1 modified)
Tests: +2 new tests (44/44 passing)
📋 Deliverables:
✅ Root Cause Analysis (comprehensive investigation)
✅ Solution Architecture (detailed fix design)
✅ Implementation (code + tests)
✅ Validation (all checks passed)
✅ Documentation (PR + changelog)
🔗 Pull Request: #143
https://github.com/user/repo/pull/143
🚀 Ready to Merge
- Priority: HIGH (hotfix)
- Risk: LOW (well-tested)
- Impact: Immediate resolution for all users
📦 Artifacts Archived:
.agents/debugging/auth-token-expiry/
- RCA document
- Solution architecture
- Implementation plan
👏 Merge ASAP to restore normal user experience!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Systematic Investigation
- Searches codebase for relevant code
- Analyzes git history for recent changes
- Reconstructs timeline of events
- Identifies primary and contributing factors
2. Evidence-Based RCA
- Not guesswork - actual file analysis
- git blame for change attribution
- Impact assessment (users, business, technical)
- Clear recommendations (immediate, short-term, long-term)
3. Comprehensive Solutions
- Not just fix the symptom - prevent recurrence
- Adds validation, constants, tests
- Considers rollback plans
- Risk assessment
4. Validated Implementation
- Tests added for the specific bug
- Full regression testing
- Build verification
- Manual testing checklist
5. Complete Documentation
- RCA explains what happened and why
- Solution documents the approach
- PR has full context for reviewers
- Changelog updated for users
Developer writes feature spec (2 hours)
→ Manual planning (1 hour)
→ Coding (8 hours)
→ Oh shit, forgot tests (2 hours)
→ Manual linting/formatting (30 min)
→ Fix failing tests (1 hour)
→ Write PR description (15 min)
→ Update changelog (10 min)
→ Realize UI looks bad, fix design (2 hours)
→ Submit for review
Total: ~17 hours
Quality: Inconsistent
Documentation: Rushed
/feature-start "description" identifier --auto
Total: ~2 hours (mostly AI working)
Quality: Validated at every step
Documentation: Comprehensive, auto-generated
Time Saved: 85% reduction Quality Gained: 10x improvement Consistency: 100% across all features
Developer investigates (2 hours)
→ Finds potential cause (maybe)
→ Implements fix without full context (1 hour)
→ Submits PR with vague description
→ Reviewer asks "but what was the root cause?"
→ Developer goes back to investigate more
→ Eventually ships fix
Total: ~4 hours
Quality: Fix might miss edge cases
Documentation: Minimal
/bug-start "problem description" identifier
Total: ~45 minutes
Quality: Systematic RCA, comprehensive fix
Documentation: Complete audit trail
Time Saved: 80% reduction Quality Gained: RCA-driven, not guess-driven Prevention: Adds safeguards for recurrence
- Clone this repo:
git clone https://github.com/yourusername/vai_prompts
cd vai_prompts- Verify structure:
ls .claude/
# Should see: agents/, commands/, feat-config.json, bug-config.json- Configure your workflows (optional):
# Edit feature workflow settings
code .claude/feat-config.json
# Edit bug workflow settings
code .claude/bug-config.jsonStart with something simple to see the magic:
/feature-start "Add an about page with company info" about-page --autoWatch as it:
- ✅ Analyzes your stack (cached for future use)
- ✅ Uses smart defaults for clarification
- ✅ Generates complete tech spec
- ✅ Creates implementation plan
- ✅ Implements the code
- ✅ Validates with all quality gates
- ✅ Creates PR with full documentation
Time: ~30 minutes (mostly AI working)
Try debugging a real issue:
/bug-start "Describe the problem you're seeing" descriptive-nameFollow the workflow:
- ✅ Review RCA (comprehensive investigation)
- ✅ Approve solution (detailed fix design)
- ✅ Watch implementation (code + tests)
- ✅ Validate fixes (all checks pass)
- ✅ Ship PR (complete documentation)
Time: ~45 minutes (thorough investigation + fix)
- Feature System: .claude/agents/README.md
- Bug System: .claude/agents/TESTING.md
- Architecture: feature-agent-swarm.md
- Master README: .claude/README.md
This repo also includes a curated collection of AI prompts for Claude Code. See prompts.png for visualization.
🧠 Enhanced with Thinking: Most prompts include advanced thinking capabilities. Enable by saying "think deeply" in your conversation.
This is open-source magic. Contribute:
- New agent workflows
- Improved validation gates
- Better error handling
- Documentation improvements
Place prompts in .claude/commands/ and agents in .claude/agents/.
We're just getting started. Planned improvements:
- Visual regression testing (Percy/Chromatic integration)
- Cost & performance budgets (track token usage, API costs)
- Feature flag automation (auto-wrap features in flags)
- Dependency impact analysis (detect affected features)
- Learning feedback loops (improve from past implementations)
- v0 integration (AI-generated UI components)
- React Scan integration (detect unnecessary re-renders)
The future of software development is multi-agent orchestration. 🤮
But ya, this is cool stuff. Multi-agent workflows that actually work. No hype, just automation that saves you hours while maintaining quality. Try it and see for yourself.
Now go build something. 🚀