automaker/docs/prd-to-features-guide.md

PRD to Automaker Features Guide

This guide helps Claude generate properly structured Automaker features from a Product Requirements Document (PRD). Use this in new projects to create feature folders that Automaker can execute.

Quick Start

1. Place your PRD file in the project (e.g., PRD.md or .automaker/context/PRD.md)
2. Create .automaker/features/ directory
3. Use this guide to generate feature.json files for each feature phase
4. Run features in Automaker sequentially or in parallel based on dependencies

---

Feature JSON Schema

Minimal Required Fields

{
  "id": "feature-unique-identifier",
  "category": "Core",
  "title": "Feature Title",
  "description": "Detailed description of what needs to be implemented",
  "status": "backlog",
  "priority": 1,
  "imagePaths": [],
  "textFilePaths": []
}

Complete Feature Schema

{
  "id": "feature-unique-identifier",
  "category": "Core | UI/UX | AI Agent | Infrastructure | Testing | From GitHub",
  "title": "Short descriptive title",
  "description": "Detailed implementation description with requirements",
  "status": "backlog | pending | running | completed | failed | verified | waiting_approval",
  "priority": 1,
  "complexity": "simple | moderate | complex",
  "dependencies": ["feature-id-1", "feature-id-2"],
  "createdAt": "2026-01-23T00:00:00.000Z",
  "updatedAt": "2026-01-23T00:00:00.000Z",
  "branchName": null,
  "descriptionHistory": [],
  "skipTests": false,
  "model": "claude-sonnet | claude-opus | claude-haiku",
  "thinkingLevel": "none | low | medium | high | ultrathink",
  "reasoningEffort": "none | low | medium | high",
  "imagePaths": [],
  "textFilePaths": [],
  "planningMode": "none | spec | full",
  "requirePlanApproval": false,
  "workMode": "auto | custom"
}

---

Field Descriptions

Core Fields

Field	Type	Required	Description
id	string	Yes	Unique identifier. Use format: feature-{descriptive-name} or phase-{n}-{name}
category	string	Yes	Grouping category for the feature
title	string	Yes	Short, descriptive title (3-8 words)
description	string	Yes	Detailed implementation requirements
status	string	Yes	Current state. Must be backlog for Automaker to execute
priority	number	Yes	Execution priority (1 = highest, higher numbers = lower priority)
imagePaths	array	Yes	Must be empty [] - Automaker populates this automatically
textFilePaths	array	Yes	Must be empty [] - Automaker populates this automatically

Optional Fields

Field	Type	Default	Description
complexity	string	moderate	simple (< 1 hour), moderate (1-4 hours), complex (> 4 hours)
dependencies	string[]	[]	Array of feature IDs that must complete first
skipTests	boolean	false	Skip test execution during verification
model	string	-	AI model: claude-sonnet (balanced), claude-opus (complex), claude-haiku (simple)
thinkingLevel	string	none	Extended thinking: none, low, medium, high, ultrathink
planningMode	string	none	none (direct), spec (generate spec first), full (spec + tool exploration)
requirePlanApproval	boolean	false	Pause for human approval before execution
workMode	string	auto	auto (continuous), custom (step-by-step)

---

Writing Effective Descriptions

Structure for Complex Features

## Overview

Brief summary of what this feature accomplishes.

## Requirements

- Requirement 1: Specific implementation detail
- Requirement 2: Another specific detail
- Requirement 3: Edge case to handle

## Technical Approach

- Use existing pattern from X
- Modify files A, B, C
- Follow the Y architectural pattern

## Acceptance Criteria

- GIVEN condition, WHEN action, THEN expected result
- GIVEN another condition, WHEN action, THEN expected result

## Files to Modify

- `path/to/file1.ts` - Purpose
- `path/to/file2.tsx` - Purpose

## Edge Cases

- Handle empty state
- Handle error conditions
- Handle concurrent operations

Structure for Simple Features

Add [feature] to [location].

Requirements:

- Specific requirement 1
- Specific requirement 2

Files: `path/to/main/file.ts`

---

Phasing Strategy

When to Create Phases

Create separate features (phases) when:

1. Features have clear dependencies (Phase 2 needs Phase 1's types)
2. Different complexity levels (separate simple setup from complex logic)
3. Different areas of codebase (backend vs frontend)
4. Risk isolation (core changes separate from UI changes)

Recommended Phase Structure

Phase 1: Foundation / Types / Schema
Phase 2: Backend / Service Layer
Phase 3: API Routes / Endpoints
Phase 4: Frontend / UI Components
Phase 5: Integration / Testing
Phase 6: Polish / Documentation

Phase Naming Convention

phase-1-foundation
phase-2-backend-service
phase-3-api-routes
phase-4-frontend-ui
phase-5-integration

---

Example: Converting PRD to Features

Input PRD Section

## User Authentication Feature

Users should be able to log in with email/password and OAuth providers.
The system should support session management and secure token storage.

Output Feature Files

Phase 1: Types and Schema

{
  "id": "phase-1-auth-types",
  "category": "Core",
  "title": "Authentication Types and Schema",
  "description": "Define TypeScript types and database schema for authentication.\n\nRequirements:\n- Add User, Session, and AuthToken types to @automaker/types\n- Create database migration for users and sessions tables\n- Define AuthProvider enum (email, google, github)\n\nFiles:\n- libs/types/src/auth.ts\n- libs/types/src/index.ts\n- apps/server/src/db/migrations/",
  "status": "backlog",
  "priority": 1,
  "complexity": "simple",
  "dependencies": [],
  "model": "claude-sonnet",
  "planningMode": "none"
}

Phase 2: Backend Service

{
  "id": "phase-2-auth-service",
  "category": "Core",
  "title": "Authentication Service Layer",
  "description": "Implement authentication service with email/password and OAuth support.\n\nRequirements:\n- Create AuthService class with login, logout, register methods\n- Implement password hashing with bcrypt\n- Add OAuth provider integration (Google, GitHub)\n- Session management with secure token generation\n\nAcceptance Criteria:\n- GIVEN valid credentials, WHEN user logs in, THEN session token is returned\n- GIVEN invalid credentials, WHEN user logs in, THEN appropriate error is returned\n- GIVEN OAuth callback, WHEN user authenticates, THEN user is created/updated and session started\n\nFiles:\n- apps/server/src/services/auth-service.ts\n- apps/server/src/services/oauth-service.ts\n- apps/server/src/lib/password.ts",
  "status": "backlog",
  "priority": 1,
  "complexity": "complex",
  "dependencies": ["phase-1-auth-types"],
  "model": "claude-opus",
  "thinkingLevel": "medium",
  "planningMode": "spec"
}

Phase 3: API Routes

{
  "id": "phase-3-auth-routes",
  "category": "Core",
  "title": "Authentication API Endpoints",
  "description": "Create REST API endpoints for authentication.\n\nEndpoints:\n- POST /api/auth/login - Email/password login\n- POST /api/auth/register - New user registration\n- POST /api/auth/logout - End session\n- GET /api/auth/me - Get current user\n- GET /api/auth/oauth/:provider - OAuth initiation\n- GET /api/auth/oauth/:provider/callback - OAuth callback\n\nFiles:\n- apps/server/src/routes/auth/index.ts\n- apps/server/src/routes/auth/routes/*.ts",
  "status": "backlog",
  "priority": 1,
  "complexity": "moderate",
  "dependencies": ["phase-2-auth-service"],
  "model": "claude-sonnet",
  "planningMode": "spec"
}

Phase 4: Frontend UI

{
  "id": "phase-4-auth-ui",
  "category": "UI/UX",
  "title": "Authentication UI Components",
  "description": "Create login, register, and profile UI components.\n\nComponents:\n- LoginForm with email/password fields and OAuth buttons\n- RegisterForm with validation\n- UserMenu dropdown showing logged-in user\n- AuthProvider context for app-wide auth state\n\nRoutes:\n- /login - Login page\n- /register - Registration page\n- /profile - User profile page\n\nFiles:\n- apps/ui/src/components/auth/*.tsx\n- apps/ui/src/routes/login.tsx\n- apps/ui/src/routes/register.tsx\n- apps/ui/src/hooks/use-auth.ts\n- apps/ui/src/store/auth-store.ts",
  "status": "backlog",
  "priority": 1,
  "complexity": "moderate",
  "dependencies": ["phase-3-auth-routes"],
  "model": "claude-sonnet",
  "planningMode": "spec"
}

---

Parallel vs Sequential Execution

Features that CAN run in parallel

• Different areas of codebase with no shared files
• Independent bug fixes
• Documentation updates
• UI components that don't share state
• Separate service implementations

Features that MUST run sequentially

• Type definitions before implementations
• Backend before frontend (if frontend calls backend)
• Database schema before data access
• Shared utilities before consumers

Expressing Dependencies

{
  "id": "feature-frontend",
  "dependencies": ["feature-types", "feature-backend"]
}

Features with dependencies won't start until all dependencies are completed.

---

Model Selection Guide

Complexity	Recommended Model	Thinking Level	Planning Mode
Simple (< 1 hour)	claude-haiku or claude-sonnet	none	none
Moderate (1-4 hours)	claude-sonnet	none or low	spec
Complex (> 4 hours)	claude-opus	medium or high	spec or full
Critical/Architecture	claude-opus	ultrathink	full

---

Directory Structure

.automaker/
└── features/
    ├── phase-1-foundation/
    │   └── feature.json
    ├── phase-2-backend/
    │   └── feature.json
    ├── phase-3-api/
    │   └── feature.json
    └── phase-4-frontend/
        └── feature.json

Each feature gets its own directory. The directory name should match the feature ID.

---

Automation Script

Create features programmatically with this pattern:

#!/bin/bash
# create-feature.sh

FEATURE_ID=$1
TITLE=$2
DESCRIPTION=$3
PRIORITY=${4:-1}

mkdir -p ".automaker/features/$FEATURE_ID"
cat > ".automaker/features/$FEATURE_ID/feature.json" << EOF
{
  "id": "$FEATURE_ID",
  "category": "Core",
  "title": "$TITLE",
  "description": "$DESCRIPTION",
  "status": "backlog",
  "priority": $PRIORITY,
  "complexity": "moderate",
  "dependencies": [],
  "createdAt": "$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")",
  "updatedAt": "$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")",
  "model": "claude-sonnet",
  "planningMode": "spec"
}
EOF

echo "Created feature: $FEATURE_ID"

---

Best Practices

DO

• Keep descriptions detailed but focused
• Include specific file paths when known
• Use GIVEN/WHEN/THEN format for acceptance criteria
• Set realistic complexity estimates
• Define clear dependencies between phases
• Use spec planning mode for moderate+ complexity
• Include edge cases in descriptions

DON'T

• Create features that are too large (> 8 hours)
• Leave descriptions vague ("make it better")
• Skip dependency definitions
• Use ultrathink for simple tasks (wastes tokens)
• Create circular dependencies
• Put multiple unrelated changes in one feature
• Put values in imagePaths or textFilePaths (must be empty [], Automaker populates them)

---

Validation Checklist

Before running features, verify:

• Each feature has a unique ID
• All dependencies exist and are spelled correctly
• No circular dependencies
• Priorities are assigned meaningfully
• Complex features have appropriate model/thinking level
• Descriptions include enough context for implementation
• File paths match actual project structure

---

Quick Reference: Status Flow

backlog → pending → running → completed → verified
                           ↘ failed
                           ↘ waiting_approval → completed

Important: Features must start in backlog status to be executable by Automaker. The system moves them through the pipeline automatically.

---

Template: New Feature

Copy and customize:

{
  "id": "feature-CHANGE-ME",
  "category": "Core",
  "title": "CHANGE ME: Feature Title",
  "description": "## Overview\nBrief description.\n\n## Requirements\n- Requirement 1\n- Requirement 2\n\n## Files\n- path/to/file.ts",
  "status": "backlog",
  "priority": 1,
  "complexity": "moderate",
  "dependencies": [],
  "createdAt": "2026-01-23T00:00:00.000Z",
  "updatedAt": "2026-01-23T00:00:00.000Z",
  "imagePaths": [],
  "textFilePaths": [],
  "model": "claude-sonnet",
  "planningMode": "spec",
  "skipTests": false,
  "workMode": "auto"
}