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

Installation

# Install globally from npm
npm install -g feature-architect-agent

# Or for local development
cd HACKATHON_FEATURE_ARCHITECT_AGENT
npm install && npm run build && npm link

API Key / Provider Setup

Option 1: Use FREE cloud models (Recommended for hackathons!)

# MiniMax M2.5 - FREE tier available!
export MINIMAX_API_KEY=xxx

# Z AI GLM - FREE tier available!
export ZAI_API_KEY=xxx

Option 2: Use FREE local models

# OpenCode / Ollama - No API key needed!
export OPENCODE_BASE_URL=http://localhost:11434/v1
export OPENCODE_MODEL=llama3.2

Option 3: Use cloud providers

# Gemini (Google)
export GOOGLE_API_KEY=xxx

# OpenAI (GPT-4, etc.)
export OPENAI_API_KEY=sk-xxx

# Claude (Anthropic)
export ANTHROPIC_API_KEY=sk-ant-xxx

For persistent configuration, add to ~/.bashrc or ~/.zshrc:

echo 'export MINIMAX_API_KEY=xxx' >> ~/.bashrc
source ~/.bashrc

Verify Installation

You can override the built-in key with your own:

# 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:

echo 'export ANTHROPIC_API_KEY=sk-ant-xxx' >> ~/.bashrc
source ~/.bashrc

One-Time Setup (Per Project)

# 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

# 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:

   export const API_CONFIG = {
     openai: {
       apiKey: 'sk-your-actual-team-openai-key-here',
     },
   };

2. Update package name in package.json:

   {
     "name": "@your-org/feature-architect"
   }

3. Build and publish:

   npm run build
   npm publish

Detailed Publishing Guide

See 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

# 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

-- 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

// 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

// 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

interface UserProfileProps {
  userId: string;
  editable?: boolean;
}

// Routes:
// /users/:id/profile        - View mode
// /users/:id/profile/edit   - Edit mode

PhotoUpload.tsx

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

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

$ 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. MINIMAX_API_KEY → MiniMax M2.5 (FREE - no signup required!)
2. ZAI_API_KEY → Z AI GLM (FREE tier available!)
3. OPENCODE_BASE_URL → OpenCode/Ollama (FREE - local!)
4. GOOGLE_API_KEY → Gemini
5. OPENAI_API_KEY → OpenAI (GPT-4, etc.)
6. ANTHROPIC_API_KEY → Claude (Anthropic)
7. AI_API_KEY → Generic fallback

Force specific provider:

# Use MiniMax (free M2.5 model)
feature-architect plan "user profile" --provider minimax

# Use Z AI (free GLM models)
feature-architect plan "user profile" --provider zai

# Use OpenCode (free local models)
feature-architect plan "user profile" --provider opencode

# Use Gemini
feature-architect plan "user profile" --provider gemini

# Use OpenAI
feature-architect plan "user profile" --provider openai

# Use Claude
feature-architect plan "user profile" --provider claude

Incremental Updates

# Re-analyze after code changes
feature-architect update

# See what changed
feature-architect diff

Context Sharing

# 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 | Setup and configuration | | USAGE.md | Command reference and workflows | | TEAM_GUIDE.md | Guide for team members | | AI_PROVIDERS.md | AI provider configuration | | EXAMPLES.md | Real-world examples |

🚦 Getting Started

1. Install: npm install -g feature-architect-agent
2. Set Provider: export MINIMAX_API_KEY=xxx (FREE!)
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

# 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

# 1. Install globally (one-time setup)
npm install -g feature-architect-agent

# 2. Set your provider (add to ~/.bashrc or ~/.zshrc)
export OPENCODE_BASE_URL=http://localhost:11434/v1  # FREE!

# 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 to set up
2. Read TEAM_GUIDE.md for team usage
3. Check 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