# 🏗️ Scaffold Guide

The `scaffold` command allows you to quickly generate new files using AI that matches your project's existing coding style, naming conventions, and patterns.

### Features

- **Project context harvesting**: Analyzes siblings and directory structure for style matching.
- **Optional test generation**: Use `--with-tests` to generate a basic test file.
- **Safety checks**: Won't overwrite existing files without `--force`.
- **Language detection** and overrides (`--lang`).

### Usage

Scaffold a new file with Grok using project context for style matching.

```bash
# Basic usage
grokkit scaffold internal/git/utils.go "git wrapper for listing tags"

# Scaffold with a basic test file
grokkit scaffold app.py "Flask route for health checks" --with-tests

# Preview without writing
grokkit scaffold main.go "simple CLI entrypoint" --dry-run
```

### Options

| Flag | Description |
|------|-------------|
| `--with-tests` | Also generate a basic test file (e.g., `utils_test.go`) |
| `--dry-run` | Preview the generated code without writing any files |
| `--yes`, `-y` | Skip the confirmation prompt and write files immediately |
| `--force` | Overwrite the destination file if it already exists |
| `--lang` | Manually specify the language (e.g., "Go", "Python", "TypeScript") |
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |

### How it Works

1. **Context Harvesting**: Grokkit reads existing files in the same directory to understand your project's "vibe."
2. **Language Detection**: It automatically detects the language based on the file extension.
3. **AI Generation**: It sends the description and project context to Grok.
4. **Style Matching**: Grok is instructed to match the project's exact style.
5. **Confirmation**: You review the code and confirm before it's saved.

### Tips for Better Results

- **Be descriptive**: Instead of "a logger", try "a structured logger using slog that writes to a rotating file".
- **Use extensions**: Ensure your file path has the correct extension so Grokkit can detect the language.
- **Project layout**: Run `scaffold` in a directory that already contains some code for best style matching.