name: feature-module-architect description: Scaffolds feature modules following feature-based architecture with colocation principle and 500 LOC file limit. Use when creating new features or refactoring large files into modular structure.

Feature Module Architect

Quick Start

This skill scaffolds feature modules following project architecture:

Feature structure: Standard directory layout with components, hooks, services, types, utils
File size limit: 500 LOC maximum per file (hard limit)
Colocation: Keep related code together within feature directory
Public API: Export only what other features need via index.ts

When to Use

Creating new feature modules
Refactoring files exceeding 500 LOC
Organizing scattered feature code
Need feature architecture guidance

Standard Feature Structure

src/features/{feature-name}/
├── components/           # React components for this feature
│   ├── FeatureComponent.tsx
│   ├── FeatureComponent.test.tsx
│   └── index.ts
├── hooks/               # Custom React hooks
│   ├── useFeatureData.ts
│   ├── useFeatureData.test.ts
│   └── index.ts
├── services/            # Business logic and API calls
│   ├── featureService.ts
│   ├── featureService.test.ts
│   └── index.ts
├── types/               # TypeScript interfaces and types
│   ├── feature.types.ts
│   └── index.ts
├── utils/               # Pure utility functions
│   ├── featureUtils.ts
│   ├── featureUtils.test.ts
│   └── index.ts
└── index.ts             # Public API (exports for other features)

Existing Feature Examples

AI Generation (src/features/ai-generation/):

Components: GenerationForm, GenerationHistory
Hooks: useGeneration, useAIProvider
Services: generationService, aiGatewayClient
Types: GenerationRequest, GenerationResponse

Project Management (src/features/project-management/):

Components: ProjectCard, ProjectList, ProjectForm
Hooks: useProjects, useProjectMutations
Services: projectService
Types: Project, ProjectMetadata

World Building (src/features/world-building/):

Components: WorldMap, LocationEditor
Hooks: useWorldState
Services: worldService
Types: WorldElement, Location

File Size Enforcement

Hard Limit: 500 LOC per file (from AGENTS.md)

Check file sizes:

# Count lines in all TypeScript files
wc -l src/features/**/*.ts src/features/**/*.tsx

# Find files exceeding 500 LOC
find src/features -name "*.ts" -o -name "*.tsx" | xargs wc -l | awk '$1 > 500'

Refactoring Strategy

When a file exceeds 500 LOC, split by responsibility:

Before (600 LOC component):

// ProjectDashboard.tsx (600 LOC) ❌
export const ProjectDashboard: React.FC = () => {
  // 100 LOC of state/hooks
  // 200 LOC of handlers
  // 300 LOC of JSX
};

After (split into 3 files, each <200 LOC):

// useProjectDashboard.ts (100 LOC)
export function useProjectDashboard() {
  // State and effects
}

// projectDashboardHandlers.ts (100 LOC)
export function createHandlers(projects: Project[]) {
  // Event handlers
}

// ProjectDashboard.tsx (150 LOC)
export const ProjectDashboard: React.FC = () => {
  const state = useProjectDashboard();
  const handlers = createHandlers(state.projects);
  return <div>{/* JSX */}</div>;
};

Colocation Principle

Keep related code together:

✅ Good - Feature-specific code within feature:

src/features/ai-generation/
├── components/GenerationForm.tsx
├── hooks/useGeneration.ts          # Only used by GenerationForm
└── types/generation.types.ts        # Only used by this feature

❌ Bad - Scattered across global directories:

src/
├── components/GenerationForm.tsx
├── hooks/useGeneration.ts           # Generic hooks directory
└── types/generation.types.ts        # Generic types directory

Public API Pattern

Each feature exports a public API via index.ts:

// src/features/ai-generation/index.ts
export { GenerationForm } from './components/GenerationForm';
export { useGeneration } from './hooks/useGeneration';
export type {
  GenerationRequest,
  GenerationResponse,
} from './types/generation.types';

// Keep internal utilities private (don't export)

Usage by other features:

// ✅ Import from feature public API
import { GenerationForm, useGeneration } from '@/features/ai-generation';

// ❌ Import from internal paths (breaks encapsulation)
import { GenerationForm } from '@/features/ai-generation/components/GenerationForm';

Component Organization

Small Components (<100 LOC)

Keep component and styles together:

// Button.tsx (80 LOC)
export const Button: React.FC<ButtonProps> = ({ children, ...props }) => {
  return (
    <button
      className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
      {...props}
    >
      {children}
    </button>
  );
};

Large Components (>100 LOC)

Extract hooks and handlers:

// useProjectForm.ts
export function useProjectForm(initialValues: Project) {
  const [values, setValues] = useState(initialValues);
  const [errors, setErrors] = useState({});

  const handleChange = (field: string, value: any) => {
    setValues(prev => ({ ...prev, [field]: value }));
  };

  return { values, errors, handleChange };
}

// ProjectForm.tsx (<150 LOC)
export const ProjectForm: React.FC<ProjectFormProps> = ({ initialValues }) => {
  const { values, errors, handleChange } = useProjectForm(initialValues);

  return (
    <form>
      {/* JSX using values, errors, handleChange */}
    </form>
  );
};

Scaffolding Checklist

When creating a new feature:

Create feature directory: src/features/{feature-name}/
Add components/ with index.ts
Add hooks/ with index.ts (if needed)
Add services/ with index.ts
Add types/ with index.ts
Add utils/ with index.ts (if needed)
Create root index.ts with public API exports
Add test files next to implementation files
Verify no file exceeds 500 LOC
Update feature integration points

Common Patterns

Service Pattern

// src/features/projects/services/projectService.ts
import { db } from '@/lib/database';
import type { Project } from '../types/project.types';

export const projectService = {
  async getAll(): Promise<Project[]> {
    return db.select().from('projects');
  },

  async getById(id: string): Promise<Project | null> {
    const result = await db.select().from('projects').where('id', id);
    return result[0] ?? null;
  },

  async create(data: Omit<Project, 'id'>): Promise<Project> {
    const id = crypto.randomUUID();
    await db.insert({ id, ...data }).into('projects');
    return { id, ...data };
  },
};

Hook Pattern

// src/features/projects/hooks/useProjects.ts
import { useQuery } from '@tanstack/react-query';
import { projectService } from '../services/projectService';

export function useProjects() {
  return useQuery({
    queryKey: ['projects'],
    queryFn: () => projectService.getAll(),
  });
}

Type Pattern

// src/features/projects/types/project.types.ts
export interface Project {
  id: string;
  title: string;
  description?: string;
  genre: ProjectGenre;
  createdAt: number;
  updatedAt: number;
}

export type ProjectGenre = 'fantasy' | 'scifi' | 'mystery' | 'romance';

export interface ProjectMetadata {
  wordCount: number;
  chapterCount: number;
}

Success Criteria

All files under 500 LOC
Feature code colocated within feature directory
Public API clearly defined in root index.ts
Test files next to implementation files
Consistent directory structure across features
No cross-feature internal imports

References

AGENTS.md - Colocation principle and file size limits
Existing features in src/features/ - Reference implementations

feature-module-architect

SKILL.md