chore(todo): add priorities to queued items and new tool integration plans

- Added priority markers (e.g., "Priority: X of 12") to existing queued TODOs like audit, changelog, profile, scaffold. - Introduced new detailed TODO markdowns for agent integrations: cnotes, git-chglog, gotools, make, pprof, rg, tea. - Enhances planning for grokkit agent tooling ecosystem.
2026-03-02 23:42:06 +00:00 · 2026-03-02 23:42:06 +00:00 · b884f32758
commit b884f32758
parent c33578b9af
12 changed files with 491 additions and 0 deletions
--- a/todo/queued/TODO_ITEM.md
+++ b/todo/queued/TODO_ITEM.md
@ -1,4 +1,5 @@
 # TODO ITEM 1
+## Priority: 12 of 12
 - [ ] 1 step one
 - [ ] 2 step two
 - [ ] 3 step three
--- a/todo/queued/audit.md
+++ b/todo/queued/audit.md
@ -1,4 +1,5 @@
 # `grokkit audit`
+## Priority: 3 of 12
 **Description**: Comprehensive AI-powered code audit for security, performance, best practices, and potential bugs across single files or entire projects.

 **Benefits**:
--- a/todo/queued/changelog.md
+++ b/todo/queued/changelog.md
@ -1,4 +1,5 @@
 # `grokkit changelog`
+## Priority: 9 of 12
 **Description**: AI-generated CHANGELOG.md updates from git history (commits/tags).

 **Benefits**:
--- a/todo/queued/cnotes.md
+++ b/todo/queued/cnotes.md
@ -0,0 +1,74 @@
+# `grokkit agent` cnotes integration
+## Priority: 6 of 12
+
+**Description**: Wrappers for your `cnotes` CLI logging suite. Allows Grok to automatically log coding sessions, notes, progress during agent workflows (e.g., "start work on feature", "log bug found").
+
+## Problem It Solves
+
+Developers track time/effort manually. Integrate `cnotes` (cnadd/cndump/etc.) for AI-assisted logging: timestamps, descriptions, stats—seamless with code edits.
+
+## Benefits
+
+- **Automated logging**: Grok logs at key points (start/edit/commit).
+- **Queryable**: Search/dump stats via AI ("Show time on agent tasks today").
+- **Safe**: Append-only (`cnadd`), read-only queries (`cnfind`/`cncount`); no deletes.
+- **Terminal-native**: Fast C impl, no deps.
+- **Workflow boost**: "Refactor → log changes → stats".
+
+## Agent Tool Examples
+
+```
+grokkit agent "Start logging session, fix main.go, log completion"
+# Grok: cnadd "start: agent refactor main.go" → edits → cnadd "done: fixed errors"
+```
+
+```
+grokkit agent "Log today's coding stats before planning"
+# Grok: cncount → cnfind "today" → "2h on edits, 3 sessions"
+```
+
+## High-Level Implementation
+
+1. **Detect cnotes**: Run `cnhelp` or `which cnotes`.
+2. **Tool schemas**:
+   - `log_note(message: string) → ok`
+   - `list_notes(filter?: string) → string`
+   - `session_stats() → string`
+3. **Wrappers** in `internal/tools/cnotes.go`:
+   ```go
+   func LogNote(ctx context.Context, args map[string]any) (string, error)
+   ```
+4. **Agent integration**: Auto-log on milestones; user-prompted.
+5. **Safety**:
+   - Only `cnadd`/`cndump`/`cnfind`/`cncount`.
+   - Preview log message.
+   - Config: `[tools.cnotes.enabled]`.
+6. **Parsing**: Stdout JSON? Or simple text.
+
+## Flags / Config
+
+| Key | Description |
+|-----|-------------|
+| `tools.cnotes.enabled` | Enable cnotes tools |
+| `--auto-log` | Log start/end automatically |
+
+## Implementation Notes
+
+- **Commands**: cnadd (log), cndump (all), cnfind (search), cncount (stats), cndel (archive—whitelist carefully).
+- **Extend agent**: Tool calls in loop.
+- **Errors**: Custom CnotesError.
+- **Tests**: Mock `exec.Command`, table-driven.
+- **Effort**: Low (~150 LOC). Simple exec wrappers.
+- **Prereq**: cnotes in PATH (`cnhelp` verifies).
+
+## ROI
+
+**High**. Personal logging elevates from code tool to **dev productivity hub**:
+
+| Stage | Covered |
+|-------|---------|
+| Logging | **cnotes** ← new |
+| Code | `agent` ✓ |
+| Repo | tea (sibling) |
+
+Quantifiable: Track hours/features automatically.
--- a/todo/queued/git-chglog.md
+++ b/todo/queued/git-chglog.md
@ -0,0 +1,62 @@
+# `grokkit agent` git-chglog integration
+## Priority: 11 of 12
+
+**Description**: Wrapper for git-chglog CLI: generates CHANGELOG.md from conventional commits/tags. AI-enhanced parsing/validation.
+
+## Problem It Solves
+
+changelog.md is AI-from-git-log; git-chglog is standard tool—wrapper adds agent control/previews.
+
+## Benefits
+
+- **Standard**: git-chglog config + AI tweaks.
+- **Validate**: Check changelog before release.
+- **Safe**: Dry-run, output preview.
+- **Integrate**: "Generate changelog v0.2.0, commit".
+
+## Agent Tool Examples
+
+```
+grokkit agent "Generate changelog for next release from commits"
+# Grok: git-chglog --next-tag v0.2.0 → preview → append to CHANGELOG.md
+```
+
+## High-Level Implementation
+
+1. **Detect**: `git-chglog --version`.
+2. **Tool schemas**:
+   - `generate(tag: string) → changelog_md`
+   - `validate() → issues`
+3. **Wrappers** in `internal/tools/git-chglog.go`:
+   ```go
+   func Generate(ctx context.Context, args map[string]any) (string, error)
+   ```
+4. **Agent integration**: Release workflows.
+5. **Safety**:
+   - --dry-run flag.
+   - Config file respect.
+   - Config: `[tools.git-chglog.enabled]`.
+
+## Flags / Config
+
+| Key | Description |
+|-----|-------------|
+| `tools.git-chglog.enabled` | Enable git-chglog |
+
+## Implementation Notes
+
+- **Commands**: `git-chglog --output CHANGELOG.md --next-tag vX.Y.Z`.
+- **Parsing**: Markdown output.
+- **Errors**: ChglogError.
+- **Tests**: Mock exec.
+- **Effort**: Low (~110 LOC). Complements changelog.md.
+- **Prereq**: git-chglog installed.
+
+## ROI
+
+**Medium-High**. Release polish:
+
+| Stage | Covered |
+|-------|---------|
+| Changelog | **git-chglog** ← new |
+| Release | changelog.md ✓ |
--- a/todo/queued/gotools.md
+++ b/todo/queued/gotools.md
@ -0,0 +1,65 @@
+# `grokkit agent` Go tools integration
+## Priority: 7 of 12
+
+**Description**: Wrappers for `go` subcommands: mod tidy, generate, vet, fmt. Ensures hygiene post-agent edits.
+
+## Problem It Solves
+
+Agent changes may break deps/fmt/vet—manual fixes. Auto-run + fix loops.
+
+## Benefits
+
+- **Hygiene auto**: Tidy deps, fmt code, vet issues.
+- **Generate**: Run go:generate for boilerplate.
+- **Safe mutations**: Preview changes (git diff).
+- **Workflow**: Edit → gotools tidy → test.
+
+## Agent Tool Examples
+
+```
+grokkit agent "Add new import, tidy mods, vet all"
+# Grok: edits → go mod tidy → go vet → reports clean
+```
+
+## High-Level Implementation
+
+1. **Detect**: `go version`.
+2. **Tool schemas**:
+   - `tidy() → changes`
+   - `vet(path?) → issues`
+   - `generate() → output`
+   - `fmt_diff() → diff`
+3. **Wrappers** in `internal/tools/gotools.go`:
+   ```go
+   func Tidy(ctx context.Context, args map[string]any) (string, error)
+   ```
+4. **Agent integration**: Post-edit hygiene step.
+5. **Safety**:
+   - Dry-run where possible (go fmt -d).
+   - Whitelist subcmds.
+   - Config: `[tools.gotools.enabled]`.
+
+## Flags / Config
+
+| Key | Description |
+|-----|-------------|
+| `tools.gotools.enabled` | Enable Go tools |
+
+## Implementation Notes
+
+- **Commands**: `go mod tidy`, `go vet ./...`, `go generate ./...`.
+- **Parsing**: Diff output, error lists.
+- **Errors**: GoToolError.
+- **Tests**: Mock, table-driven.
+- **Effort**: Low (~130 LOC).
+- **Prereq**: Go workspace.
+
+## ROI
+
+**High**. Go-specific polish:
+
+| Stage | Covered |
+|-------|---------|
+| Hygiene | **gotools** ← new |
+| Search | rg (sibling) |
+| Build | make (sibling) |
--- a/todo/queued/make.md
+++ b/todo/queued/make.md
@ -0,0 +1,74 @@
+# `grokkit agent` make integration
+## Priority: 2 of 12
+
+**Description**: Wrappers for Makefile targets (test/lint/build/cover). Enables Grok to run/verify builds mid-agent workflow (e.g., "edit, test, fix loops").
+
+## Problem It Solves
+
+Agent edits code but can't auto-verify compilation/tests—manual `make test` context-switch.
+
+## Benefits
+
+- **Automated verification**: Post-edit `make test` + analyze failures.
+- **Dry-runs**: Preview `make build` output.
+- **Safe**: Whitelisted targets, timeout, project-dir.
+- **Parse results**: Extract pass/fail, coverage, errors for next agent step.
+- **Workflow**: "Refactor → test → fix → commit".
+
+## Agent Tool Examples
+
+```
+grokkit agent "Fix lint errors in cmd/, run make lint to verify, then test"
+# Grok: edits → make lint → "All green!" → make test → fixes failures
+```
+
+```
+grokkit agent "Benchmark changes before commit"
+# Grok: make test-cover → "Coverage drop 2%" → optimizations
+```
+
+## High-Level Implementation
+
+1. **Detect**: `test -f Makefile` or `make --version`.
+2. **Tool schemas**:
+   - `run_target(target: string) → {output: string, success: bool}`
+   - `dry_run(target: string) → simulated_output`
+3. **Wrappers** in `internal/tools/make.go`:
+   ```go
+   func RunTarget(ctx context.Context, args map[string]any) (string, error)
+   ```
+4. **Agent integration**: Tool call → parse stdout → feed to Grok ("Tests failed: fix?").
+5. **Safety**:
+   - Whitelist: test, lint, build, test-cover, install.
+   - 300s timeout.
+   - No sudo/privileged.
+   - Config: `[tools.make.enabled]`.
+6. **Parsing**: Grep for "PASS/FAIL", coverage %.
+
+## Flags / Config
+
+| Key | Description |
+|-----|-------------|
+| `tools.make.enabled` | Enable make tools |
+| `tools.make.timeout` | Per-target timeout (s) |
+
+## Implementation Notes
+
+- **Commands**: `make TARGET` (no args).
+- **Extend agent**: Loop includes make calls post-edit.
+- **Errors**: MakeError with output.
+- **Tests**: Mock exec, table-driven (success/fail outputs).
+- **Effort**: Low (~120 LOC). Std exec + parsing.
+- **Prereq**: Makefile present.
+
+## ROI
+
+**High**. Agent verification loop:
+
+| Stage | Covered |
+|-------|---------|
+| Edit | `agent` ✓ |
+| Verify | **make** ← new |
+| Repo/log | tea/cnotes |
+
+Instant feedback elevates agent reliability.
--- a/todo/queued/pprof.md
+++ b/todo/queued/pprof.md
@ -0,0 +1,63 @@
+# `grokkit agent` pprof integration
+## Priority: 10 of 12
+
+**Description**: Go pprof profiling wrappers (CPU/memory/allocs). Captures profiles during agent runs, AI-analyzes hotspots.
+
+## Problem It Solves
+
+Profile.md is high-level; pprof enables raw data + AI opts for slow cmds (agent loops).
+
+## Benefits
+
+- **Capture**: `go test -cpuprofile` or runtime/pprof.
+- **Analyze**: Feed pprof text/top to Grok ("Optimize this flamegraph").
+- **Safe**: Temp .pprof files, no web UI.
+- **Integrate**: Auto-profile long agents.
+
+## Agent Tool Examples
+
+```
+grokkit agent "Profile cmd/agent.go benchmark, suggest fixes"
+# Grok: pprof cpu → "30% in StreamSilent, batch calls"
+```
+
+## High-Level Implementation
+
+1. **Detect**: `go tool pprof --version`.
+2. **Tool schemas**:
+   - `cpu_profile(duration: int) → pprof_text`
+   - `analyze(profile_data: string) → suggestions`
+3. **Wrappers** in `internal/tools/pprof.go`:
+   ```go
+   func CPUProfile(ctx context.Context, args map[string]any) (string, error)
+   ```
+4. **Agent integration**: Flag-triggered profiling.
+5. **Safety**:
+   - Tempdir files (os.TempDir).
+   - No --http/--pdf.
+   - Config: `[tools.pprof.enabled]`.
+
+## Flags / Config
+
+| Key | Description |
+|-----|-------------|
+| `tools.pprof.enabled` | Enable pprof tools |
+| `--profile-cpu` | Auto-cpu on agent |
+
+## Implementation Notes
+
+- **Capture**: runtime/pprof.StartCPUProfile, or `go test -cpuprofile`.
+- **Parse**: `go tool pprof -text`.
+- **Errors**: PprofError.
+- **Tests**: Mock profiles.
+- **Effort**: Medium (~180 LOC). Ties to profile.md.
+- **Prereq**: Go stdlib pprof.
+
+## ROI
+
+**High** for perf:
+
+| Stage | Covered |
+|-------|---------|
+| Profile | **pprof** ← new |
+| Analyze | profile.md ✓ |
--- a/todo/queued/profile.md
+++ b/todo/queued/profile.md
@ -1,4 +1,5 @@
 # `grokkit profile`
+## Priority: 8 of 12
 **Description**: Run Go benchmarks/pprof, get AI-suggested performance optimizations.

 **Benefits**:
--- a/todo/queued/rg.md
+++ b/todo/queued/rg.md
@ -0,0 +1,73 @@
+# `grokkit agent` ripgrep (rg) integration
+## Priority: 4 of 12
+
+**Description**: Fast search wrapper for ripgrep (`rg`). Enables agent to grep project for symbols/patterns/context before edits.
+
+## Problem It Solves
+
+Agent lacks quick codebase search—relies on full file scans or manual `grep`. rg is 10x faster, regex-aware.
+
+## Benefits
+
+- **Lightning search**: Multi-line, git-ignored, type-aware (`--type=go`).
+- **Context gathering**: "rg 'err handling' → snippets for prompt".
+- **Safe**: Read-only, project-only, no filespecs.
+- **Stats**: Count matches, paths.
+- **Workflow**: "Search todos → prioritize → edit".
+
+## Agent Tool Examples
+
+```
+grokkit agent "Find all error returns in cmd/, improve handling"
+# Grok: rg 'return err' cmd/ → analyzes → targeted edits
+```
+
+```
+grokkit agent "Count test coverage gaps: rg 't.Skip' or untested funcs"
+# Grok: rg --type=go '_test\.go' → stats → testgen suggestions
+```
+
+## High-Level Implementation
+
+1. **Detect**: `rg --version`.
+2. **Tool schemas**:
+   - `search(pattern: string, path?: string) → matches[]`
+   - `count(pattern: string) → int`
+3. **Wrappers** in `internal/tools/rg.go`:
+   ```go
+   func Search(ctx context.Context, args map[string]any) (string, error)
+   ```
+4. **Agent integration**: Pre-plan search → richer context.
+5. **Safety**:
+   - Args whitelist: --type, --no-heading, project root.
+   - Max 100 matches.
+   - Config: `[tools.rg.enabled]`.
+6. **Parsing**: JSON output (`--json`), or lines → structured.
+
+## Flags / Config
+
+| Key | Description |
+|-----|-------------|
+| `tools.rg.enabled` | Enable rg tools |
+| `tools.rg.max_matches` | Limit results |
+
+## Implementation Notes
+
+- **Commands**: `rg PATTERN [PATH] --no-heading --colors=never`.
+- **Extend agent**: Optional search phase in planning.
+- **Errors**: RgError.
+- **Tests**: Mock, table-driven patterns.
+- **Effort**: Low (~100 LOC).
+- **Prereq**: rg installed (`apt install ripgrep`).
+
+## ROI
+
+**High**. Search is dev superpower:
+
+| Stage | Covered |
+|-------|---------|
+| Search | **rg** ← new |
+| Edit | `agent` ✓ |
+| Verify | make (sibling) |
+
+Agent plans smarter with instant intel.
--- a/todo/queued/scaffold.md
+++ b/todo/queued/scaffold.md
@ -1,4 +1,5 @@
 # `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.

--- a/todo/queued/tea.md
+++ b/todo/queued/tea.md
@ -0,0 +1,75 @@
+# `grokkit agent` tea integration
+## Priority: 5 of 12
+
+**Description**: Safe, AI-orchestrated wrappers for Gitea `tea` CLI commands. Enables Grok to manage repos (list/create PRs/issues, comments) as part of agent workflows, with previews and confirmations.
+
+## Problem It Solves
+
+Grokkit's `agent` excels at code edits but lacks repo mgmt. Developers context-switch to browser/CLI for Gitea actions. Integrate `tea` for seamless: "Review PRs, create issue for bugs, log progress".
+
+## Benefits
+
+- **Safe execution**: Whitelisted commands/args, dry-run previews, confirm destructive ops (merge/push).
+- **AI reasoning**: Grok decides *when* to call `tea` (e.g., "After edits, create PR").
+- **Logging**: All calls logged to `~/.config/grokkit/tools.log`.
+- **Repo-aware**: Combines with git (`internal/git`), code edits.
+- **No new deps**: Uses `os/exec` for `tea` (assume installed).
+
+## Agent Tool Examples
+
+```
+grokkit agent "List open PRs, pick one to work on, create branch"
+# Grok: tea pr ls → Analyzes → tea branch create fix-123 → edits files
+```
+
+```
+grokkit agent "Fix lint, create issue if high-risk changes"
+# Grok: Runs lint → tea issue create "High-risk refactor"
+```
+
+## High-Level Implementation
+
+1. **Detect tea**: Check `exec.Command("tea", "version")`.
+2. **Tool schemas** (Grok tool-calling JSON):
+   - `list_prs(state: "open") → string`
+   - `create_pr(title, body, base) → pr_url`
+   - `comment_pr(pr_id, body)`
+   - `merge_pr(pr_id)`
+3. **Wrapper funcs** in `internal/tools/tea.go`:
+   ```go
+   func ListPRs(ctx context.Context, args map[string]any) (string, error)
+   ```
+4. **Agent loop** (`cmd/agent.go`): Parse tool calls → Execute → Feed output back.
+5. **Safety**:
+   - Whitelist: pr ls/create/comment/merge, issue create/comment.
+   - Preview: Print `tea ...` + expected output.
+   - Confirm: User y/n for each.
+6. **Config**: `[tools.tea.enabled]`, `[tools.tea.gitea_url]`.
+
+## Flags / Config
+
+| Key | Description |
+|-----|-------------|
+| `tools.tea.enabled` | Enable tea tools |
+| `tools.tea.gitea_url` | Override repo URL |
+| `--dry-run` | Simulate tool calls |
+
+## Implementation Notes
+
+- **Extend agent**: Modify plan phase to include tool suggestions.
+- **Error handling**: `internal/errors` + GitError-like TeaError.
+- **Tests**: Table-driven `TestTeaTools` with mocks (`exec.Command` patching).
+- **Effort**: Medium (~200 LOC). Reuse `grok` client, agent UX.
+- **Prereq**: User installs `tea` (`go install github.com/go-tea/tea/cmd/tea@latest`).
+
+## ROI
+
+**High**. Closes workflow gap:
+
+| Stage | Covered |
+|-------|---------|
+| Code edit | `agent` ✓ |
+| Repo mgmt | **tea tools** ← new |
+| Logging | cnotes (next) |
+
+Force-multiplies daily PR/issue workflows.