# `grokkit scaffold`
## Priority: 1 of 12

**Description**: AI-powered code generation that creates new files from natural language descriptions, learning from your existing codebase patterns to produce idiomatic, ready-to-compile output.

## Problem It Solves

Every existing grokkit command operates on *existing* files (`edit`, `agent`, `lint`, `docs`, `testgen`). There is no command to *create* a new file from scratch. Developers spend significant time writing boilerplate for new handlers, services, models, CLI commands, middleware, etc. `scaffold` fills this gap.

## Benefits

- **Pattern-aware**: Reads similar existing files for package names, import styles, error handling conventions, struct naming, and logger usage before generating.
- **Idiomatic output**: Produces code that looks like it was written by the same developer — same patterns as the rest of the codebase, not generic AI output.
- **Multi-language**: Works for any language the project already supports (Go, Python, JS/TS, etc.), with lang detected from the output path or `--lang` flag.
- **Optional test companion**: With `--with-tests`, also generates a corresponding test file using the same testgen prompt logic.
- **Safe preview**: Shows a diff/preview before writing, requires confirmation (or `--yes` to skip).
- **No overwrites**: Refuses to overwrite an existing file unless `--force` is passed.

## CLI Examples

```bash
# Generate a new Cobra CLI command file
grokkit scaffold cmd/export.go "export command that writes chat history to JSON or CSV"

# New internal package
grokkit scaffold internal/cache/cache.go "simple in-memory LRU cache with TTL support"

# Generate with a companion test file
grokkit scaffold internal/git/tag.go "functions to list and create git tags" --with-tests

# Python module
grokkit scaffold src/auth/jwt.py "JWT encode/decode utilities using PyJWT"

# Skip confirmation
grokkit scaffold cmd/webhook.go "webhook command that posts PR descriptions to Slack" --yes

# Preview only (no write)
grokkit scaffold cmd/watch.go "file watcher that reruns lint on save" --dry-run
```

## High-Level Implementation

1. **Input validation**: Check target path doesn't already exist (error unless `--force`). Detect language from file extension.
2. **Context harvesting**: Walk sibling files in the same directory and the most structurally similar files in the project (e.g., other `cmd/*.go` if generating a command). Read them for patterns.
3. **Prompt construction**:
   - System: "You are an expert Go/Python/etc. engineer. Given existing code samples, generate a new file that matches the codebase's conventions exactly. Return only the file content — no explanations, no markdown."
   - User: paste harvested sibling files as context + target path + description.
4. **Streaming response**: Use `client.StreamSilent` (same as `edit`/`testgen`).
5. **Clean output**: Run through `grok.CleanCodeResponse` to strip any markdown fences.
6. **Preview**: Print file content with a header showing the target path. Prompt `(y/n)`.
7. **Write**: Create parent directories if needed (`os.MkdirAll`), write file.
8. **Optional test generation**: If `--with-tests`, reuse testgen logic to generate companion test file with the same preview/confirm flow.

## Flags

| Flag | Description |
|---|---|
| `--with-tests` | Also generate companion test file |
| `--yes` / `-y` | Skip confirmation prompt |
| `--dry-run` | Preview only, do not write |
| `--force` | Overwrite if target file already exists |
| `--lang` | Override language detection (go, python, js, ts, rust, ruby) |
| `--model` / `-m` | Override model |
| `--context-files` | Comma-separated paths to use as context (overrides auto-detection) |

## Implementation Notes

- **Context size**: Cap harvested context at ~4000 tokens to avoid prompt bloat. Prefer the most relevant files (same directory, same `package` name for Go).
- **Go specifics**: Extract `package` name from sibling files and inject it at the top of the prompt so the AI uses the correct package declaration.
- **Reuse existing patterns**: Share `internal/linter.DetectLanguage`, `grok.CleanCodeResponse`, and the standard preview/confirm UX from `edit.go`.
- **Effort**: Medium (~250–350 LOC). Most complexity is in the context-harvesting logic.

## ROI

**High**. This closes the only remaining gap in grokkit's file lifecycle coverage:

| Lifecycle stage | Command |
|---|---|
| Create new file | **scaffold** ← missing |
| Edit existing file | `edit` |
| Multi-file changes | `agent` |
| Review changes | `review` |
| Document code | `docs` |
| Generate tests | `testgen` |
| Commit | `commit` |

Developers scaffold new files multiple times per day. Making that AI-assisted and pattern-aware is a force multiplier for the entire tool.