From c33578b9af4ff8def6dd1f3c6f4e290fc6d19f5c Mon Sep 17 00:00:00 2001 From: Greg Gauthier Date: Mon, 2 Mar 2026 22:39:13 +0000 Subject: [PATCH] feat(scaffold): add spec for grokkit scaffold command to queued tasks 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. --- todo/queued/scaffold.md | 86 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 todo/queued/scaffold.md diff --git a/todo/queued/scaffold.md b/todo/queued/scaffold.md new file mode 100644 index 0000000..1b28fbc --- /dev/null +++ b/todo/queued/scaffold.md @@ -0,0 +1,86 @@ +# `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.