Configuration

.claude/
├── product/            # Product structure (choose one)
│   ├── index.md        # Option 1: Flat - all features
│   ├── domains/        # Option 2: Hierarchical - by domain
│   │   └── auth/
│   │       ├── index.md
│   │       └── features/
│   │           ├── login.md
│   │           └── register.md
│   ├── EXAMPLES.md     # Feature writing examples
│   └── README.md       # Structure guide
├── agents/             # Agent definitions
├── commands/           # Slash commands
├── skills/             # Domain skills
└── settings.json       # Hooks and permissions

your-project/
├── PRODUCT.md          # All features in one file
├── src/
└── package.json

your-project/
├── .claude/
│   └── product/
│       └── index.md    # All features in one file
├── src/
└── package.json

# My App
 
## Features
 
### 1. User Authentication - CRITICAL
- Login with email/password
- JWT token handling
- Password reset
 
### 2. User Profile - HIGH
- Edit profile information
- Upload avatar
 
### 3. Dashboard - MEDIUM
- Display user stats
- Recent activity

your-project/
├── .claude/
│   └── product/
│       ├── index.md              # Product overview
│       └── domains/
│           ├── authentication/
│           │   ├── index.md      # Domain overview
│           │   └── features/
│           │       ├── login.md
│           │       └── register.md
│           └── user-management/
│               ├── index.md
│               └── features/
│                   └── profile.md

# My App
 
A full-stack application for user management.
 
## Domains
- Authentication (CRITICAL)
- User Management (HIGH)
- Dashboard (MEDIUM)

# Authentication Domain
 
Handles user identity and access control.
 
## Features
- Login
- Register
- Password Reset

# Feature: Login
 
Priority: CRITICAL
 
## Subtasks
1. Create login UI
2. Implement login API
3. Add JWT handling
4. Write tests

# Phase 1: Quick Start
PRODUCT.md (all features in one file)
 
# Phase 2: Organize (optional)
.claude/product/index.md (move to .claude directory)
 
# Phase 3: Scale Up (when needed)
.claude/product/domains/ (split by domain)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit 2>&1 | head -5 || true"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f .agentful/state.json ]; then jq -r '.current_phase // \"idle\"' .agentful/state.json 2>/dev/null || echo 'idle'; else echo 'idle'; fi"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "Bash(git:*)",
      "Bash(cat:*)",
      "Bash(echo:*)",
      "Bash(jq:*)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(rm -rf ~/.*)",
      "Bash(rm -rf /.*)",
      "Bash(dd:*)",
      "Bash(mkfs:*)"
    ]
  }
}

{
  "matcher": "Edit|Write",
  "hooks": [
    {
      "type": "command",
      "command": "npx tsc --noEmit 2>&1 | head -5 || true"
    }
  ]
}

// For Python
{
  "command": "python -m mypy . 2>&1 | head -5 || true"
}
 
// For Go
{
  "command": "go build ./... 2>&1 | head -5 || true"
}
 
// Disable TypeScript checking
{
  "command": "echo 'TypeScript checking disabled'"
}

"allow": [
  "Bash(npm:*)",      // Run npm commands
  "Bash(npx:*)",      // Run npx commands
  "Bash(git:*)",      // Run git commands
  "Bash(cat:*)",      // Read files
  "Bash(jq:*)",       // Process JSON
  "Bash(pnpm:*)"      // Add pnpm support
]

"deny": [
  "Bash(rm -rf /)",   // Prevent deleting root
  "Bash(rm -rf ~/.*)", // Prevent deleting home dir
  "Bash(dd:*)",       // Prevent disk destruction
  "Bash(mkfs:*)"      // Prevent filesystem formatting
]

"allow": [
  "Bash(npm:*)",
  "Bash(yarn:*)",           // Add Yarn support
  "Bash(python:*)",         // Add Python support
  "Bash(ruby:*)",           // Add Ruby support
  "Bash(docker:*)",         // Add Docker support
  "Bash(make:*)"            // Add make support
]

.claude/agents/
├── orchestrator.md    # Main coordinator
├── architect.md       # Tech stack analyzer
├── backend.md         # Backend specialist
├── frontend.md        # Frontend specialist
├── tester.md          # Test writer
├── reviewer.md        # Quality validator
└── fixer.md           # Issue fixer

## Your Scope
 
- **UI Components** - Reusable component library
- **Pages** - Route pages and views
- **Hooks** - Custom React hooks
- **State Management** - Context, Zustand, Redux, etc.
- **Forms** - Form handling and validation
- **Styling** - Tailwind, CSS Modules, styled-components, etc.
- **Client-side Logic** - User interactions, animations
- **Animation** - Framer Motion, GSAP, CSS animations  ← NEW

## NOT Your Scope (delegate or skip)
 
- Backend API routes → @backend
- Database operations → @backend
- Tests → @tester
- Code review → @reviewer
- State Management → @state-manager  ← DELEGATE INSTEAD

## Quality Gates
 
Code must pass ALL gates before completion:
 
- ✅ All tests passing
- ✅ No type errors (adapts to stack)
- ✅ No lint errors
- ✅ No dead code (unused exports, files, dependencies)
- ✅ Test coverage ≥ 80%
- ✅ No security issues
- ✅ Bundle size < 200KB (gzip)  ← NEW
- ✅ Lighthouse score ≥ 90      ← NEW

---
name: database
version: 1.0.0
---
 
# Database Agent
 
You are the **Database Agent**. You handle all database-related operations.
 
## Your Scope
 
- **Schema Design** - Database models and relationships
- **Migrations** - Database migrations and rollbacks
- **Queries** - Complex queries and optimization
- **Seeding** - Database seeding and test data
- **Backups** - Database backup strategies
 
## NOT Your Scope (delegate or skip)
 
- API routes → @backend
- Business logic → @backend
- Tests → @tester
 
## Implementation Pattern
 
### Schema Design (Prisma)
 
```prisma
// prisma/schema.prisma
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  posts     Post[]
}

npx prisma migrate dev --name add_users_table

// Efficient query with select
const users = await prisma.user.findMany({
  select: {
    id: true,
    name: true,
    _count: {
      select: { posts: true }
    }
  }
});

 
**Use the new agent:**
 
In commands, reference with `@database`:
```markdown
The database schema is missing. @database, please create the User model.

.claude/commands/
├── agentful-start.md      # Begin development
├── agentful-status.md     # Check progress
├── agentful-decide.md     # Answer decisions
└── agentful-validate.md   # Run quality checks

---
name: agentful-deploy
description: Deploy project to production
---
 
# Deploy Command
 
Deploys the project to production after validation.
 
## Usage

 
## What It Does
 
1. Runs full validation (`/agentful-validate`)
2. Checks if all gates pass
3. Runs build command
4. Deploys to configured platform
5. Runs smoke tests
6. Reports deployment URL
 
## Requirements
 
- All quality gates must pass
- Build must succeed
- No uncommitted changes
 
## Platforms
 
Detects platform from configuration:
 
- **Vercel**: Runs `vercel deploy --prod`
- **Netlify**: Runs `netlify deploy --prod`
- **Railway**: Runs `railway up`
- **Custom**: Runs `npm run deploy`
 
## Example Output

 
## Configuration
 
Add to `PRODUCT.md`:
 
```markdown
## Deployment
- **Platform**: Vercel
- **Build Command**: npm run build
- **Output Directory**: .next

 
**Use the command:**
```bash
/agentful-deploy

.claude/skills/
├── product-tracking/
│   └── SKILL.md
└── validation/
    └── SKILL.md

---
name: testing
version: 1.0.0
---
 
# Testing Skill
 
Provides testing capabilities for agentful agents.
 
## What This Skill Does
 
- Writes unit tests
- Writes integration tests
- Writes E2E tests
- Generates test data
- Creates test fixtures
- Measures coverage
 
## Usage
 
Agents can invoke this skill:

 
## Test Templates
 
### Unit Test (Vitest)
 
```typescript
import { describe, it, expect } from 'vitest';
import { UserService } from '../UserService';
 
describe('UserService', () => {
  it('should create a user', async () => {
    const user = await UserService.create({
      email: 'test@example.com',
      name: 'Test User'
    });
 
    expect(user).toHaveProperty('id');
    expect(user.email).toBe('test@example.com');
  });
});

import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { prisma } from '@/lib/prisma';
 
describe('User API', () => {
  beforeAll(async () => {
    // Setup test database
  });
 
  afterAll(async () => {
    // Cleanup
    await prisma.user.deleteMany();
  });
 
  it('should create user via API', async () => {
    const response = await fetch('/api/users', {
      method: 'POST',
      body: JSON.stringify({
        email: 'test@example.com',
        name: 'Test User'
      })
    });
 
    expect(response.status).toBe(201);
  });
});

 
---
 
## Template Configuration
 
### 6. PRODUCT.md Template
 
Customize the default product template.
 
**Location:** `template/PRODUCT.md`
 
**Add custom sections:**
 
```markdown
## Custom Section
 
### Performance Requirements
 
- Page load < 2s
- Time to Interactive < 3s
- Lighthouse score > 90
 
### Accessibility Requirements
 
- WCAG 2.1 AA compliant
- Keyboard navigation
- Screen reader support
- Color contrast > 4.5:1
 
### Internationalization
 
- Support multiple languages
- Date/time localization
- Currency formatting
- RTL support for Arabic/Hebrew

## Coding Standards
 
### Naming Conventions
 
- Components: PascalCase (UserProfile.tsx)
- Utilities: camelCase (formatDate.ts)
- Constants: UPPER_SNAKE_CASE (API_BASE_URL)
- Hooks: use prefix (useAuth.ts)
 
### File Organization

 
### Git Conventions
 
- Commit messages: conventional commits
- Branch naming: feature/, fix/, chore/
- PR templates required

# Database
DATABASE_URL="postgresql://..."
 
# API Keys
NEXT_PUBLIC_API_URL="https://api.example.com"
API_SECRET_KEY="..."
 
# Auth
NEXTAUTH_SECRET="..."
NEXTAUTH_URL="http://localhost:3000"
 
# Features
NEXT_PUBLIC_FEATURE_FLAGS="new-ui,dark-mode"

## Environment Variables
 
Required environment variables:
 
- `DATABASE_URL` - PostgreSQL connection string
- `NEXTAUTH_SECRET` - Auth secret (generate with openssl)
- `API_SECRET_KEY` - API key for external services

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
  images: {
    domains: ['example.com'],
  },
  experimental: {
    serverActions: true,
  },
}
 
module.exports = nextConfig

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

## Coverage Thresholds
 
- Overall: ≥ 80%
- Critical paths: ≥ 90%
- UI components: ≥ 70%
- Utilities: ≥ 95%

// vitest.config.ts
export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 80,
        statements: 80,
      },
    },
  },
})

---
name: agentful-custom
description: Custom workflow for specific needs
---
 
# Custom Workflow
 
## Usage

 
## Workflow Steps
 
1. **Analysis Phase**
   - Review current state
   - Identify blockers
   - Prioritize tasks
 
2. **Implementation Phase**
   - Build features
   - Write tests
   - Document code
 
3. **Validation Phase**
   - Run quality gates
   - Security scan
   - Performance check
 
4. **Deployment Phase**
   - Build artifacts
   - Deploy to staging
   - Run smoke tests
 
## Custom Logic
 
Add your project-specific workflow here.

git add .claude/
git commit -m "Configure agentful agents and commands"

# Already in .gitignore
.agentful/

# agentful Configuration
 
## Custom Agents
 
- `@database` - Handles database operations
- `@analytics` - Analytics and tracking
 
## Custom Commands
 
- `/agentful-deploy` - Custom deployment workflow
 
## Modified Agents
 
- `@frontend` - Added animation support
- `@reviewer` - Added bundle size checks
 
## Quality Gates
 
- Coverage: 80% (was 75%)
- Bundle size: < 200KB
- Lighthouse: ≥ 90

# Use default config first
npx @itz4blitz/agentful init