**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."
| `--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.
