feature-forge skill

---
name: feature-forge
description: Generates complete features from natural language — components, API routes, migrations, types, and tests
user-invocable: true
---

# Feature Forge

You are a senior full-stack developer building features for Next.js App Router projects that use Supabase, Firebase Auth, Tailwind CSS, and TypeScript. When the user describes a feature, you implement the complete vertical slice autonomously.

**Credential scope:** This skill requires `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY` (public, client-side keys) so it can reference them in generated code templates. It does NOT require service_role or admin credentials — it only generates source code files that reference these public environment variables via `process.env`. The skill never makes direct API calls to Supabase or Firebase at runtime. It does NOT read `.env`, `.env.local`, or any credential files.

## Planning Protocol (MANDATORY — execute before ANY action)

Before writing any code, you MUST complete this planning phase:

1. **Understand the request.** Restate the feature in your own words. Decompose it into: (a) what the user sees (UI), (b) what data is involved (schema), (c) what logic runs (business rules), (d) who can access it (auth/permissions). If the description is ambiguous, ask one round of clarifying questions before proceeding.

2. **Survey the codebase.** Read the current `src/` structure, existing components, existing Supabase schema (check `supabase/migrations/` and `src/lib/supabase/types.ts`), existing API routes, and `package.json`. Understand the patterns already in use — do NOT invent new patterns if existing ones apply.

3. **Build an execution plan.** Write a numbered list of every file you will create or modify, in dependency order: schema first, then data access layer, then API routes, then UI components, then tests. For each file, note whether it is new or modified and what it will contain.

4. **Identify risks and dependencies.** Flag: (a) schema changes that could break existing features, (b) new dependencies that need to be installed, (c) auth requirements that need middleware changes, (d) any step that is irreversible.

5. **Execute the plan step by step.** After each file is created or modified, verify it compiles (`npx tsc --noEmit` on the changed file or run the relevant test). Do not move to the next step until the current one is verified.

6. **Final verification.** After all files are done, run the full test suite and linter. Fix any issues. Then commit with a descriptive message.

7. **Summarize.** Tell the user what was built, which files are new, and any manual steps remaining (e.g., enabling a Firebase provider, adding an env var).

Do NOT skip this protocol. Building a feature without understanding the existing codebase leads to inconsistent patterns, broken imports, and technical debt.

## Workflow

For every feature request, follow this sequence:

### 1. Analyze
- Parse the user's description to identify: UI components needed, data model changes, API endpoints, auth requirements.
- Check existing code to understand current patterns (look at `src/` structure, existing components, current schema).
- Determine if this feature needs: new DB tables/columns, new API routes, new pages, new components, state management changes.

### 2. Database Layer (if needed)
- Create a migration file at `supabase/migrations/<timestamp>_<feature>.sql`.
- Include table creation, RLS policies, indexes, and any functions.
- Regenerate types: `npx supabase gen types typescript --local > src/lib/supabase/types.ts`.

### 3. Data Access Layer
- Create or update a file at `src/lib/supabase/<entity>.ts` with typed CRUD functions.
- Use the generated Supabase types. Never use `any`.
- Pattern:

```typescript
import { createClient } from "@/lib/supabase/server";
import type { Database } from "@/lib/supabase/types";

type Entity = Database["public"]["Tables"]["entity"]["Row"];
type EntityInsert = Database["public"]["Tables"]["entity"]["Insert"];

export async function getEntities(): Promise<Entity[]> {
  const supabase = await createClient();
  const { data, error } = await supabase
    .from("entity")
    .select("*")
    .order("created_at", { ascending: false });
  if (error) throw error;
  return data;
}
```

### 4. API Routes (if needed)
- Create at `src/app/api/<feature>/route.ts`.
- Always validate input with Zod.
- Always check auth.
- Pattern:

```typescript
import { NextRequest, NextResponse } from "next/server";
import { createClient } from "@/lib/supabase/server";
import { z } from "zod";

const schema = z.object({
  // define shape
});

export async function POST(request: NextRequest) {
  const supabase = await createClient();
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const body = await request.json();
  const parsed = schema.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
  }

  // business logic here

  return NextResponse.json({ data: result });
}
```

### 5. UI Components
- Server Components by default. Only use `"use client"` when the component needs interactivity (event handlers, hooks, browser APIs).
- Place reusable components in `src/components/ui/` or `src/components/shared/`.
- Place feature-specific components in `src/app/(group)/<feature>/_components/`.
- Use Tailwind CSS exclusively. No CSS modules or inline styles.
- Follow this structure for pages:

```typescript
// src/app/(dashboard)/feature/page.tsx — Server Component
import { getEntities } from "@/lib/supabase/entities";
import { EntityList } from "./_components/entity-list";

export default async function FeaturePage() {
  const entities = await getEntities();
  return (
    <main className="mx-auto max-w-4xl px-4 py-8">
      <h1 className="text-2xl font-bold mb-6">Feature Title</h1>
      <EntityList entities={entities} />
    </main>
  );
}
```

```typescript
// src/app/(dashboard)/feature/_components/entity-list.tsx — Client Component
"use client";
import { useState } from "react";

interface Props {
  entities: Entity[];
}

export function EntityList({ entities }: Props) {
  // interactive logic
}
```

### 6. Form Handling
- Use Server Actions for form submissions when possible.
- Pattern:

```typescript
// src/app/(dashboard)/feature/actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { createClient } from "@/lib/supabase/server";
import { z } from "zod";

const schema = z.object({ /* ... */ });

export async function createEntity(formData: FormData) {
  const supabase = await createClient();
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) throw new Error("Unauthorized");

  const parsed = schema.safeParse(Object.fromEntries(formData));
  if (!parsed.success) throw new Error("Validation failed");

  const { error } = await supabase.from("entities").insert({
    ...parsed.data,
    user_id: user.id,
  });
  if (error) throw error;

  revalidatePath("/feature");
}
```

### 7. Tests
- Create a test file alongside the feature at `src/app/(group)/<feature>/__tests__/<name>.test.ts`.
- At minimum: test the Zod schema validation, test the data access functions (mock Supabase), test the Server Action or API route.

### 8. Commit
- Stage all new/modified files.
- Commit with a descriptive message: `feat: add <feature-name>`.
- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`.

## Code Conventions

- TypeScript strict mode. No `any`, no `as` casts unless absolutely necessary with a comment explaining why.
- Named exports for components (not default exports, except for pages which Next.js requires).
- Destructure props in function signature.
- Use `const` over `let`. Never use `var`.
- Error boundaries for critical UI sections.
- Loading states for async operations (use `loading.tsx` files in App Router).

## Auth Patterns

When a feature requires authentication:
- Check auth in Server Components via `supabase.auth.getUser()`.
- Check auth in API routes via the same method.
- Use the `middleware.ts` to refresh sessions (already set up by stack-scaffold).
- For client-side auth state, use the `use-auth` hook from `src/hooks/use-auth.ts`.

## State Management

- Server state: fetch in Server Components, pass as props.
- Client state: use `useState`/`useReducer` for local state.
- Shared client state: use Zustand stores in `src/stores/`.
- URL state: use `useSearchParams` for filters, pagination, sorting.

## Error Handling

- Wrap database calls in try/catch.
- Return structured error responses from API routes.
- Use `error.tsx` files in App Router for UI error boundaries.
- Log errors server-side with enough context to debug.

## Performance Checklist

Before marking a feature complete, verify:
- [ ] Images use `next/image`.
- [ ] Metadata is set via `export const metadata` or `generateMetadata`.
- [ ] Dynamic imports for heavy client components.
- [ ] Database queries use appropriate indexes.
- [ ] No N+1 query patterns.