from_scratch

Greenfield Bootstrap - LLM-Assisted Development

A complete framework for starting new projects from scratch with LLM assistance. Features modular architecture, automatic test generation, and structured workflows for greenfield development.

Based on the original Claude Code Project Template by ktnyt, adapted for greenfield development with automatic test coverage.

Overview

This framework helps you start new projects with LLMs (like Claude) by providing:

• Project Genesis - Interactive wizard for project setup
• Architecture Definition - Module boundaries and interfaces first
• Modular Development - Implement modules in isolation
• Automatic Testing - 85%+ coverage without manual test writing
• Technology Selection - Smart defaults with customization
• Multiple Project Types - Web API, CLI Tool, Library

Key Differences from Feature-Driven Template

Aspect	Feature-Driven	Greenfield Bootstrap
Starting Point	Existing codebase	Empty directory
First Step	Create work-item	Initialize project
Architecture	Discover existing	Define from scratch
Tech Stack	Assumed	Interactive selection
Modules	Modify existing	Create new
Build Order	Feature by feature	Layer by layer

Quick Start

1. Initialize Project

# Start interactive wizard
/claude init-project

# You'll be prompted for:
# - Project name
# - Description
# - Technology stack (with smart defaults)
# - Project type (Web API / CLI / Library)

2. Define Architecture

# Design module boundaries
/claude define-architecture

# Creates:
# - docs/architecture/README.md
# - docs/architecture/interfaces/*.md
# - Module dependency graph

3. Implement Core (Layer 0)

# Build foundation first
/claude implement-module core

# Includes:
# - Configuration management
# - Logging setup
# - Base exceptions
# - Database connection (if applicable)

4. Implement Domain Modules (Layer 1)

# Implement domain modules in parallel
/claude implement-module users
/claude implement-module orders
/claude implement-module products

5. Implement Services (Layer 2)

# Build service layer
/claude implement-module payment_service
/claude implement-module email_service

6. Integrate Everything

# Wire modules together
/claude integrate-modules

# Creates:
# - Dependency injection
# - API routes (Web API) or CLI commands
# - Integration tests

Workflow

/init-project           →  Create project structure
/define-architecture   →  Design modules and interfaces
/implement-module      →  Build module with auto-testing
/integrate-modules     →  Assemble complete system
/add-migrations        →  Add database migrations (optional)

Project Types

Web API (FastAPI + PostgreSQL)

Best for: HTTP APIs, microservices, backend services

Stack:

• FastAPI - Modern async web framework
• Pydantic - Data validation
• SQLAlchemy 2.0 - Database ORM
• PostgreSQL - Production database
• pytest - Testing
• Docker - Development environment

Structure:

project/
├── src/project/
│   ├── main.py          # FastAPI app
│   ├── dependencies.py  # DI container
│   ├── core/            # Config, logging
│   ├── models/          # Database models
│   ├── services/        # Business logic
│   └── api/             # Route handlers
├── tests/
│   ├── unit/
│   └── integration/
└── docker-compose.yml

CLI Tool (Typer + SQLite)

Best for: Command-line utilities, scripts, tools

Stack:

• Typer - CLI framework
• Rich - Terminal output
• Pydantic - Settings
• SQLite - File-based DB (optional)
• pytest - Testing

Structure:

project/
├── src/project/
│   ├── cli.py           # Entry point
│   ├── core/            # Config
│   ├── commands/        # CLI commands
│   └── services/        # Business logic
├── tests/
└── Dockerfile

Library

Best for: Reusable packages, SDKs, tools

Stack:

• Pure Python
• Minimal dependencies
• Clean public API
• Examples directory
• Comprehensive tests

Structure:

project/
├── src/project/
│   ├── __init__.py      # Public API
│   ├── core/            # Base classes
│   └── modules/         # Functionality
├── tests/
└── examples/            # Usage examples

Architecture

Layer Cake Pattern

Build in layers, bottom-up:

Layer 3: API/CLI       (depends on 0-2)
Layer 2: Services      (depends on 0-1)
Layer 1: Domains       (depends on 0)
Layer 0: Core          (no dependencies)

Module Isolation

Each module:

• Has defined interface contract
• Can be implemented independently
• Tested in isolation (mock dependencies)
• Integrated via dependency injection

Interface-First Design

Before implementation:

1. Define interface in docs/architecture/interfaces/{module}.md
2. Specify functions, types, exceptions
3. Document behavior and examples
4. Then implement to spec

Automatic Test Generation

Coverage Target: 85%

Every module automatically gets tests:

• Happy paths
• Error cases
• Edge cases
• Input validation

What's Tested

• Business logic
• Error handling
• Validation rules
• Database operations
• External calls

What's Excluded

• Third-party libraries
• Standard library
• Dataclass definitions
• Constants
• Type hints
• Import statements

Approval Checkpoints

Every implementation has 6 user checkpoints:

1. Implementation Plan - Review strategy
2. Code Implementation - Review changes
3. Test Generation - Approve test plan
4. Coverage Gap - Handle <85% (if needed)
5. Review Findings - Approve code review
6. Final Staging - Commit or reset

No automatic commits - you control git history.

Context Management

Modular Context Loading

Each skill loads minimal context:

init-project:

• User inputs only
• Template files

define-architecture:

• Project structure
• No source code (doesn't exist yet)

implement-module:

• Interface contract only
• Core module (if needed)
• No other modules

integrate-modules:

• All interfaces
• Integration points only

Benefits

• Prevents context exhaustion
• Enables parallel module work
• Keeps LLM focused
• Faster iterations

Technology Defaults

Web API Defaults

• Framework: FastAPI
• Validation: Pydantic v2
• Database: PostgreSQL + asyncpg
• ORM: SQLAlchemy 2.0 (async)
• Auth: JWT + bcrypt
• Testing: pytest + async support
• Linting: ruff
• Types: mypy
• Container: Docker + docker-compose

CLI Defaults

• Framework: Typer
• Output: Rich
• Config: Pydantic Settings
• DB: SQLite (optional)
• Testing: pytest
• Linting: ruff
• Types: mypy

Library Defaults

• Minimal: Pure Python
• Validation: Pydantic (optional)
• Testing: pytest
• Linting: ruff
• Types: mypy

All defaults are customizable during initialization.

Directory Structure

project/
├── src/{project_name}/
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── dependencies.py      # DI (Web API)
│   ├── cli.py               # Entry point (CLI)
│   ├── core/                # Layer 0
│   │   ├── __init__.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── exceptions.py
│   │   └── logging.py
│   └── {modules}/           # Layers 1-2
│       ├── __init__.py
│       ├── models.py
│       ├── service.py
│       └── exceptions.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py          # Fixtures
│   ├── test_core_*.py
│   └── test_{module}_*.py
├── docs/
│   ├── architecture/
│   │   ├── README.md
│   │   └── interfaces/
│   │       ├── core.md
│   │       └── {module}.md
│   └── decisions/           # ADRs
├── alembic/                 # Migrations (optional)
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
├── .pre-commit-config.yaml
├── .gitignore
└── README.md

Skills Reference

/init-project

• Interactive wizard
• Tech stack selection
• Project scaffolding
• Docker setup
• Git initialization (optional)

/define-architecture

• Module boundary design
• Interface contracts
• Dependency graph
• Build order
• ASCII diagrams

/implement-module <name>

• Reads interface contract
• Implements all functions
• Generates tests (85%)
• 6 approval checkpoints
• Stages changes

/integrate-modules

• Verifies all modules
• Creates DI container
• Implements API/CLI layer
• Creates integration tests
• End-to-end verification

/add-migrations

• Alembic setup
• Initial migration
• Docker integration
• Command documentation

Best Practices

Module Design

• Single responsibility
• Clear interfaces
• Dependency injection
• No circular dependencies

Testing

• Test behavior, not implementation
• Mock external dependencies
• Test error paths
• 85% coverage minimum

Documentation

• Living docs (evolve with code)
• Interface contracts as spec
• ADRs for decisions
• Code is truth (after implementation)

Development Flow

1. Define interface first
2. Implement in isolation
3. Test thoroughly
4. Integrate at the end
5. Review and finalize

Comparison with Other Templates

Template	Best For	Starting Point	Key Feature
Greenfield	New projects	Empty directory	Architecture-first
Feature-Driven	Existing code	Working codebase	Automatic tests
Sprint-Based	Team planning	Existing codebase	Sprint ceremonies

Example Session

# 1. Initialize
$ /claude init-project
> Project name: ecommerce-api
> Type: Web API
> Accept defaults? Yes

# 2. Define architecture
$ /claude define-architecture
> Modules: users, products, orders
> Services: payment, email

# 3. Implement core
$ /claude implement-module core
> Coverage: 94%
> Status: Approved

# 4. Implement domains (parallel)
$ /claude implement-module users  # Coverage: 87%
$ /claude implement-module products  # Coverage: 91%
$ /claude implement-module orders  # Coverage: 89%

# 5. Implement services
$ /claude implement-module payment_service  # Coverage: 92%

# 6. Integrate
$ /claude integrate-modules
> All tests pass
> Coverage: 88%

# 7. Add migrations
$ /claude add-migrations
> Initial migration created

Tips for Success

Start small:

• Fewer modules = faster iteration
• Add complexity incrementally

Interface contracts are binding:

• Define carefully
• Change before implementation is cheap
• Change after is expensive

Test as you go:

• Each module standalone
• Integration at the end
• Full system verification

Use dependency injection:

• Makes testing easy
• Enables parallel work
• Clean separation

Troubleshooting

"Module not found" during implement-module:

• Run /define-architecture first
• Check interface file exists

"Dependency not ready":

• Build bottom-up (Layer 0 → 1 → 2 → 3)
• Core module must be complete first

"Coverage below 85%":

• Normal for complex modules
• Can accept lower with documentation
• Or run more test generation cycles

License

This is a template/framework. Use it however you want for your projects.

Acknowledgments

This framework is based on the Claude Code Project Template by ktnyt, completely redesigned for greenfield development with architecture-first approach and automatic test generation.