grokkit/todo/queued/tea.md

# `grokkit agent` tea integration
## Priority: 4 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.