grokkit/todo/completed/scaffold.md

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

# 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.