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

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