feature-architect-agent 1.0.0

package/README.md

@@ -0,0 +1,704 @@
+# Feature Planning Architect Agent
+
+> **CLI-based AI agent for systematic feature planning and architecture design**
+
+---
+
+## 🎯 What Is It?
+
+A command-line tool that helps developers plan new features systematically. Instead of jumping straight to coding, the agent:
+
+1. **Analyzes your entire codebase** (one-time setup)
+2. **Understands your architecture patterns**
+3. **Plans new features** with complete technical specs
+4. **Generates flow diagrams** and visual documentation
+5. **Creates implementation context** for any AI tool to use
+
+---
+
+## 💡 Why Use It?
+
+### The Problem
+
+```
+❌ Developer gets feature request
+❌ Starts coding immediately
+❌ Misses edge cases
+❌ No database planning
+❌ API design on the fly
+❌ Frontend/backend mismatch
+❌ Rework required
+```
+
+### The Solution
+
+```
+✅ Developer gets feature request
+✅ Runs: plan-feature "user profile editing"
+✅ Agent analyzes codebase context
+✅ Generates complete feature plan:
+   - Use cases covered
+   - Database schema
+   - API endpoints
+   - Frontend components
+   - Flow diagrams
+✅ Developer has clear blueprint
+✅ Implementation is smooth
+```
+
+---
+
+## 🚀 Quick Start
+
+### For Team Members (Published Package)
+
+```bash
+# Install globally from your team's private registry
+npm install -g @your-org/feature-architect
+
+# Verify installation
+feature-architect verify
+
+# That's it! The built-in team API key handles everything.
+# No individual API key setup needed!
+```
+
+### For Developers (Local Development)
+
+```bash
+# 1. Navigate to the agent directory
+cd HACKATHON_FEATURE_ARCHITECT_AGENT
+
+# 2. Install dependencies
+npm install
+
+# 3. Build the package
+npm run build
+
+# 4. Link globally (makes command available everywhere)
+npm link
+
+# Now you can use `feature-architect` from ANY directory!
+```
+
+### Verify Installation
+
+```bash
+feature-architect verify
+```
+
+Checks for:
+- Context file existence
+- API key configuration (built-in or user-provided)
+- Output directory
+
+### API Key Configuration
+
+**Team members using the published package:**
+- No setup needed! The built-in team API key is included.
+- Works out of the box after installation.
+
+**Optional: Use your own API key:**
+
+You can override the built-in key with your own:
+
+```bash
+# Claude (Anthropic)
+export ANTHROPIC_API_KEY=sk-ant-xxx
+
+# OpenAI (GPT-4, etc.)
+export OPENAI_API_KEY=sk-xxx
+
+# Gemini (Google)
+export GOOGLE_API_KEY=xxx
+
+# Generic fallback
+export AI_API_KEY=xxx
+```
+
+**For persistent configuration**, add to your `~/.bashrc` or `~/.zshrc`:
+
+```bash
+echo 'export ANTHROPIC_API_KEY=sk-ant-xxx' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### One-Time Setup (Per Project)
+
+```bash
+# Navigate to your project
+cd your-project
+
+# Analyze your codebase (do this once)
+feature-architect init
+
+# This will:
+# 1. Scan your codebase
+# 2. Extract patterns (API routes, DB schemas, components)
+# 3. Build context index
+# 4. Store in .feature-architect/context.json
+```
+
+### Plan Your First Feature
+
+```bash
+# Plan a new feature
+feature-architect plan "Add user profile with photo upload"
+
+# Output: Complete feature plan saved to
+# docs/features/user-profile-photo-upload.md
+```
+
+---
+
+## 📦 For Team Admins: Publishing the Package
+
+This section is for team admins who want to publish the package with built-in team API keys.
+
+### Overview
+
+The package includes a built-in API key so team members don't need to set up their own keys. This makes onboarding seamless - just install and use!
+
+### Security First
+
+⚠️ **Only publish to PRIVATE registries!**
+- GitHub Packages (recommended)
+- npm Private Packages
+- Verdaccio (self-hosted)
+- Azure Artifacts
+- GitLab Package Registry
+
+**DO NOT publish to public npm** with real API keys!
+
+### Quick Publish Steps
+
+1. **Configure the team API key** in `src/config/api.config.ts`:
+   ```typescript
+   export const API_CONFIG = {
+     openai: {
+       apiKey: 'sk-your-actual-team-openai-key-here',
+     },
+   };
+   ```
+
+2. **Update package name** in `package.json`:
+   ```json
+   {
+     "name": "@your-org/feature-architect"
+   }
+   ```
+
+3. **Build and publish**:
+   ```bash
+   npm run build
+   npm publish
+   ```
+
+### Detailed Publishing Guide
+
+See [PUBLISHING_GUIDE.md](./PUBLISHING_GUIDE.md) for:
+- Setting up private registries (GitHub, npm, Verdaccio)
+- Creating team API keys with usage limits
+- Cost estimation and budget monitoring
+- Security best practices
+- Troubleshooting
+
+---
+
+## 📋 What It Generates
+
+### Example Output
+
+```markdown
+# Feature Plan: User Profile with Photo Upload
+
+## Overview
+Allow users to create and manage their profiles including photo upload.
+
+## Use Cases
+| ID | Description | Priority |
+|----|-------------|----------|
+| UC1 | User can view their profile | Must Have |
+| UC2 | User can edit profile fields | Must Have |
+| UC3 | User can upload profile photo | Must Have |
+| UC4 | User can delete profile photo | Should Have |
+
+## Database Design
+
+### New Tables
+```sql
+CREATE TABLE user_profiles (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  bio TEXT,
+  location VARCHAR(100),
+  website VARCHAR(255),
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(user_id)
+);
+
+CREATE TABLE profile_photos (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  storage_key VARCHAR(255) NOT NULL,
+  mime_type VARCHAR(50),
+  file_size_bytes INTEGER,
+  width INTEGER,
+  height INTEGER,
+  uploaded_at TIMESTAMP DEFAULT NOW(),
+  is_active BOOLEAN DEFAULT TRUE,
+  UNIQUE(user_id, is_active) WHERE is_active = TRUE
+);
+
+CREATE INDEX idx_profile_photos_user ON profile_photos(user_id, is_active);
+```
+
+### Modified Tables
+```sql
+-- Add to users table
+ALTER TABLE users ADD COLUMN has_profile BOOLEAN DEFAULT FALSE;
+ALTER TABLE users ADD COLUMN profile_photo_url VARCHAR(255);
+```
+
+## Backend API
+
+### New Endpoints
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/api/v1/users/:id/profile` | Get user profile | Required |
+| PUT | `/api/v1/users/:id/profile` | Update profile | Own/Admin |
+| POST | `/api/v1/users/:id/photo` | Upload photo | Own |
+| DELETE | `/api/v1/users/:id/photo` | Delete photo | Own |
+
+### Request/Response Examples
+
+#### GET /api/v1/users/:id/profile
+```typescript
+// Response (200)
+interface UserProfileResponse {
+  user_id: string;
+  bio: string | null;
+  location: string | null;
+  website: string | null;
+  photo_url: string | null;
+  created_at: string;
+  updated_at: string;
+}
+```
+
+#### PUT /api/v1/users/:id/profile
+```typescript
+// Request
+interface UpdateProfileRequest {
+  bio?: string;
+  location?: string;
+  website?: string;
+}
+
+// Response (200)
+interface UpdateProfileResponse {
+  success: true;
+  data: UserProfileResponse;
+}
+```
+
+## Frontend Components
+
+### Component Structure
+```
+src/features/user-profile/
+├── UserProfile.tsx           # Main container
+├── ProfileView.tsx           # Display mode
+├── ProfileEdit.tsx           # Edit form
+├── PhotoUpload.tsx           # Photo upload widget
+├── PhotoCropper.tsx          # Crop functionality
+├── hooks/
+│   ├── useUserProfile.ts     # Data fetching
+│   └── usePhotoUpload.ts     # Upload logic
+└── types.ts                  # TypeScript types
+```
+
+### Component Specs
+
+#### UserProfile.tsx
+```typescript
+interface UserProfileProps {
+  userId: string;
+  editable?: boolean;
+}
+
+// Routes:
+// /users/:id/profile        - View mode
+// /users/:id/profile/edit   - Edit mode
+```
+
+#### PhotoUpload.tsx
+```typescript
+interface PhotoUploadProps {
+  userId: string;
+  currentPhoto?: string;
+  onUploadSuccess: (photoUrl: string) => void;
+  maxSize?: number; // bytes
+  allowedTypes?: string[];
+}
+
+// Features:
+// - Drag and drop
+// - Crop before upload
+// - Preview
+// - Progress indicator
+```
+
+## Architecture Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Frontend
+    participant API
+    participant DB
+    participant Storage
+
+    User->>Frontend: View Profile
+    Frontend->>API: GET /api/v1/users/:id/profile
+    API->>DB: Query user_profiles
+    DB-->>API: Profile data
+    API-->>Frontend: Profile + photo_url
+    Frontend-->>User: Display profile
+
+    User->>Frontend: Upload Photo
+    Frontend->>Storage: Upload image
+    Storage-->>Frontend: storage_key
+    Frontend->>API: POST /api/v1/users/:id/photo
+    API->>DB: Insert profile_photos
+    API->>Storage: Get signed URL
+    API-->>Frontend: photo_url
+    Frontend-->>User: Show new photo
+```
+
+## Implementation Tasks
+
+### Phase 1: Database (1 day)
+- [ ] Create migration for user_profiles table
+- [ ] Create migration for profile_photos table
+- [ ] Update users table
+- [ ] Run migrations
+- [ ] Seed test data
+
+### Phase 2: Backend (2 days)
+- [ ] Create UserProfile model
+- [ ] Create ProfilePhoto model
+- [ ] Implement GET /api/v1/users/:id/profile
+- [ ] Implement PUT /api/v1/users/:id/profile
+- [ ] Implement POST /api/v1/users/:id/photo
+- [ ] Implement DELETE /api/v1/users/:id/photo
+- [ ] Add file upload handling
+- [ ] Add validation
+- [ ] Write tests
+
+### Phase 3: Storage Integration (1 day)
+- [ ] Set up Azure Blob Storage
+- [ ] Implement upload service
+- [ ] Implement delete service
+- [ ] Add signed URL generation
+
+### Phase 4: Frontend (3 days)
+- [ ] Create UserProfile component
+- [ ] Create ProfileView component
+- [ ] Create ProfileEdit component
+- [ ] Create PhotoUpload component
+- [ ] Add routing
+- [ ] Implement hooks
+- [ ] Add error handling
+- [ ] Add loading states
+
+## Dependencies
+
+### External Services
+- Azure Blob Storage (or S3)
+- Image processing service (optional)
+
+### Internal Services
+- Existing: Auth service, User service
+- New: Profile service, Storage service
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| User uploads non-image | Validate MIME type, reject |
+| File too large | Reject with error message |
+| No storage space | Return 503, retry later |
+| Concurrent photo uploads | Use last-write-wins, notify user |
+| Profile doesn't exist | Auto-create on first view |
+| Invalid URL in website | Validate format, store as-is |
+
+## Testing Checklist
+
+### Backend
+- [ ] CRUD operations for profiles
+- [ ] File upload limits
+- [ ] File type validation
+- [ ] Authorization checks
+- [ ] Error handling
+
+### Frontend
+- [ ] View profile
+- [ ] Edit profile
+- [ ] Upload photo (valid)
+- [ ] Upload photo (invalid type)
+- [ ] Upload photo (too large)
+- [ ] Delete photo
+- [ ] Loading states
+- [ ] Error messages
+
+## Open Questions
+
+1. Should we support multiple photos per user?
+   - Decision: No for MVP, single photo only
+
+2. Max photo size?
+   - Decision: 5MB
+
+3. Allowed formats?
+   - Decision: JPG, PNG, WEBP
+
+4. Photo aspect ratio?
+   - Decision: Accept any, crop to 1:1 for display
+```
+
+---
+
+## 🔧 How It Works
+
+### 1. Codebase Analysis (One-Time)
+
+```bash
+$ feature-architect init
+
+🔍 Analyzing codebase...
+   Scanning 245 files
+   ├── 45 TypeScript files
+   ├── 32 SQL files
+   ├── 12 React components
+   └── 156 other files
+
+📊 Building context index...
+   ├── Detected: PostgreSQL database
+   ├── Detected: Express.js API
+   ├── Detected: React frontend
+   ├── Detected: Azure Blob Storage
+   └── Found 23 API endpoints
+
+💾 Storing context...
+   Vector database: ~/.feature-architect/vectors/
+   Context size: 2.3MB
+   Index time: 45 seconds
+
+✅ Codebase analyzed and indexed!
+   You can now plan features with full context awareness.
+```
+
+### 2. Feature Planning
+
+```bash
+$ feature-architect plan "Add user comments"
+
+🧠 Analyzing feature request...
+   Feature: Add user comments
+   Similar features found: 3
+   Relevant code patterns: 12
+
+📋 Generating feature plan...
+   Use cases: 5 identified
+   Database changes: 2 tables
+   API endpoints: 5 endpoints
+   Frontend components: 4 components
+
+📊 Creating diagrams...
+   Flow diagram: Generated
+   ER diagram: Generated
+
+💾 Saving plan...
+   Output: docs/features/user-comments.md
+   Context: docs/features/user-comments.context.json
+
+✅ Feature plan ready!
+   View: cat docs/features/user-comments.md
+```
+
+---
+
+## 🎯 Key Features
+
+### AI-Provider Agnostic (Auto-Detection)
+
+The agent automatically detects which API key is available and uses the appropriate provider. No manual selection needed!
+
+**Priority order:**
+1. `ANTHROPIC_API_KEY` → Claude (Anthropic)
+2. `OPENAI_API_KEY` → OpenAI (GPT-4, etc.)
+3. `GOOGLE_API_KEY` → Gemini
+4. `AI_API_KEY` → Generic fallback (uses Claude)
+
+**Force specific provider:**
+```bash
+# Use Claude explicitly
+feature-architect plan "user profile" --provider claude
+
+# Use OpenAI explicitly
+feature-architect plan "user profile" --provider openai
+
+# Use Gemini explicitly
+feature-architect plan "user profile" --provider gemini
+```
+
+### Incremental Updates
+
+```bash
+# Re-analyze after code changes
+feature-architect update
+
+# See what changed
+feature-architect diff
+```
+
+### Context Sharing
+
+```bash
+# Export context for team
+feature-architect export-context --output team-context.json
+
+# Import shared context
+feature-architect import-context --input team-context.json
+```
+
+---
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [INSTALLATION.md](./INSTALLATION.md) | Setup and configuration |
+| [USAGE.md](./USAGE.md) | Command reference and workflows |
+| [TEAM_GUIDE.md](./TEAM_GUIDE.md) | Guide for team members |
+| [AI_PROVIDERS.md](./AI_PROVIDERS.md) | AI provider configuration |
+| [EXAMPLES.md](./EXAMPLES.md) | Real-world examples |
+
+---
+
+## 🚦 Getting Started
+
+1. **Install**: `cd HACKATHON_FEATURE_ARCHITECT_AGENT && npm install && npm run build && npm link`
+2. **Set API Key**: `export ANTHROPIC_API_KEY=your-key-here`
+3. **Setup**: `cd your-project && feature-architect init`
+4. **Plan**: `feature-architect plan "your feature here"`
+5. **Implement**: Use the generated plan as your blueprint
+
+---
+
+## 🤝 Team Usage
+
+### For Team Leads
+
+```bash
+# Share context with team
+cat .feature-architect/context.json > team-context.json
+
+# Commit to repo or share via drive
+git add team-context.json
+git commit -m "feat: add shared context for feature planning"
+```
+
+### For Developers
+
+```bash
+# 1. Install globally (one-time setup)
+cd HACKATHON_FEATURE_ARCHITECT_AGENT
+npm install && npm run build && npm link
+
+# 2. Set your API key (add to ~/.bashrc or ~/.zshrc)
+export ANTHROPIC_API_KEY=your-key-here
+
+# 3. Navigate to your project
+cd your-project
+
+# 4. Import team context (optional - skip if doing init)
+mkdir -p .feature-architect
+cp team-context.json .feature-architect/context.json
+
+# 5. Plan features
+feature-architect plan "my feature"
+```
+
+---
+
+## 📊 What Makes This Different
+
+| Traditional Approach | Feature Architect Agent |
+|---------------------|-------------------------|
+| Ad-hoc planning | Systematic approach |
+| Missed edge cases | Comprehensive coverage |
+| DB design after coding | DB design first |
+| API design on the fly | Complete API contracts |
+| Frontend/backend disconnect | Aligned architecture |
+| Tribal knowledge | Documented patterns |
+| "Just figure it out" | Clear blueprint |
+
+---
+
+## 🎁 Bonus Features
+
+### Diagrams
+
+Automatically generates:
+- Flow diagrams (Mermaid)
+- ER diagrams (Mermaid)
+- Sequence diagrams
+- Component trees
+
+### Pattern Recognition
+
+Learns from your codebase:
+- API patterns
+- Database conventions
+- Component structure
+- Error handling
+- Validation patterns
+
+### Context Generation
+
+Creates ready-to-use context for:
+- AI coding assistants
+- New team members
+- Code reviews
+- Documentation
+
+---
+
+## 📖 Next Steps
+
+1. Read [INSTALLATION.md](./INSTALLATION.md) to set up
+2. Read [TEAM_GUIDE.md](./TEAM_GUIDE.md) for team usage
+3. Check [EXAMPLES.md](./EXAMPLES.md) for sample outputs
+4. Start planning your first feature!
+
+---
+
+## 🏆 Why This Wins
+
+**Real problems, real solutions:**
+
+✅ Developers actually plan before coding
+✅ Consistent architecture across features
+✅ Faster onboarding for new devs
+✅ Better documentation
+✅ Fewer bugs and rework
+✅ AI-tool agnostic (use what you want)
+
+**Built for teams:**
+✅ CLI-based (works everywhere)
+✅ Shareable context
+✅ Version controlled plans
+✅ Works with any AI provider

package/bin/feature-architect.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli/index.js');

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}