From b884f32758bf972fa76c956ef7c387ceee61d633 Mon Sep 17 00:00:00 2001 From: Greg Gauthier Date: Mon, 2 Mar 2026 23:42:06 +0000 Subject: [PATCH] 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. --- todo/queued/TODO_ITEM.md | 1 + todo/queued/audit.md | 1 + todo/queued/changelog.md | 1 + todo/queued/cnotes.md | 74 ++++++++++++++++++++++++++++++++++++++ todo/queued/git-chglog.md | 62 ++++++++++++++++++++++++++++++++ todo/queued/gotools.md | 65 +++++++++++++++++++++++++++++++++ todo/queued/make.md | 74 ++++++++++++++++++++++++++++++++++++++ todo/queued/pprof.md | 63 ++++++++++++++++++++++++++++++++ todo/queued/profile.md | 1 + todo/queued/rg.md | 73 +++++++++++++++++++++++++++++++++++++ todo/queued/scaffold.md | 1 + todo/queued/tea.md | 75 +++++++++++++++++++++++++++++++++++++++ 12 files changed, 491 insertions(+) create mode 100644 todo/queued/cnotes.md create mode 100644 todo/queued/git-chglog.md create mode 100644 todo/queued/gotools.md create mode 100644 todo/queued/make.md create mode 100644 todo/queued/pprof.md create mode 100644 todo/queued/rg.md create mode 100644 todo/queued/tea.md diff --git a/todo/queued/TODO_ITEM.md b/todo/queued/TODO_ITEM.md index f812abc..c6eca1b 100644 --- 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 diff --git a/todo/queued/audit.md b/todo/queued/audit.md index 0dabf67..82ac279 100644 --- 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**: diff --git a/todo/queued/changelog.md b/todo/queued/changelog.md index bab881f..b58de12 100644 --- 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**: diff --git a/todo/queued/cnotes.md b/todo/queued/cnotes.md new file mode 100644 index 0000000..89de4e1 --- /dev/null +++ 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. \ No newline at end of file diff --git a/todo/queued/git-chglog.md b/todo/queued/git-chglog.md new file mode 100644 index 0000000..67906b1 --- /dev/null +++ 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 ✓ | \ No newline at end of file diff --git a/todo/queued/gotools.md b/todo/queued/gotools.md new file mode 100644 index 0000000..6ea14df --- /dev/null +++ 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) | \ No newline at end of file diff --git a/todo/queued/make.md b/todo/queued/make.md new file mode 100644 index 0000000..a872fb5 --- /dev/null +++ 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. \ No newline at end of file diff --git a/todo/queued/pprof.md b/todo/queued/pprof.md new file mode 100644 index 0000000..54a82db --- /dev/null +++ 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 ✓ | \ No newline at end of file diff --git a/todo/queued/profile.md b/todo/queued/profile.md index cf91ea3..8d633e9 100644 --- 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**: diff --git a/todo/queued/rg.md b/todo/queued/rg.md new file mode 100644 index 0000000..dd8f4cb --- /dev/null +++ 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. \ No newline at end of file diff --git a/todo/queued/scaffold.md b/todo/queued/scaffold.md index 1b28fbc..0ddb06e 100644 --- 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. diff --git a/todo/queued/tea.md b/todo/queued/tea.md new file mode 100644 index 0000000..8300cb9 --- /dev/null +++ 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. \ No newline at end of file