Greg Gauthier
c33578b9af
Queues a detailed specification for implementing the `grokkit scaffold` command, which enables AI-powered code generation for new files based on natural language descriptions and codebase patterns. Includes CLI examples, implementation notes, flags, and ROI analysis.
87 lines
4.6 KiB
Markdown
87 lines
4.6 KiB
Markdown
# `grokkit scaffold`
|
||
|
||
**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.
|