eadb4452a8
- Renamed todo/queued/scaffold.md to todo/completed/scaffold.md to indicate task completion. - Added todo/queued/interactive-agent.md with details for the next priority feature: a persistent conversational agent mode for Grokkit.
88 lines
4.7 KiB
Markdown
88 lines
4.7 KiB
Markdown
# `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.
|