From 65f67ff7b1871c71983e60c720fd0b40315bbbe9 Mon Sep 17 00:00:00 2001 From: Greg Gauthier Date: Tue, 31 Mar 2026 22:23:35 +0100 Subject: [PATCH] feat(workon): implement automated todo workflow with AI plans and branch management - Add workon command to automate starting/completing todos/fixes - Generate AI-powered work plans and handle git branching - Update README and user docs with workon guide - Move workon todo item to completed --- README.md | 1 + docs/user-guide/analyze.md | 2 +- docs/user-guide/index.md | 5 +- docs/user-guide/workon.md | 109 ++++++++++++++++++++++++++++ todo/{doing => completed}/workon.md | 0 5 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 docs/user-guide/workon.md rename todo/{doing => completed}/workon.md (100%) diff --git a/README.md b/README.md index fd6a74b..707cfa5 100644 --- a/README.md +++ b/README.md @@ -185,6 +185,7 @@ Generate shell completions for faster command entry: - ✅ **AI unit test generation** - Go (table-driven), Python (pytest), C (Check), C++ (GTest) - ✅ **AI file scaffolding** - Create new files with project-aware style matching - ✅ **Transactional Recipes** - Markdown-based multi-step AI workflows +- ✅ **Automated Workon** - AI-powered todo/fix workflow with branch management, work plan generation, and completion tracking ### Quality & Testing - ✅ **Test coverage 54%+** - Comprehensive unit tests including all command message builders diff --git a/docs/user-guide/analyze.md b/docs/user-guide/analyze.md index 9107178..7af61d7 100644 --- a/docs/user-guide/analyze.md +++ b/docs/user-guide/analyze.md @@ -35,7 +35,7 @@ grokkit analyze --model grok-4 | Flag | Short | Description | Default | |----------|-------|----------------------------|-------------------| | --dir | | Repository root to analyze | Current directory | -| --output | -o | Output file (- for stdout) | analyze.md | +| --output | -o | Output file (- for stdout) | .grokkit/analysis.md | | --yes | -y | Skip confirmation prompt | false | | --model | -m | Override model | from config | diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index bf77e00..9b0fc70 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -24,12 +24,15 @@ Welcome to the full user documentation for **Grokkit** — a fast, native Go CLI - **[📋 PR-Describe](pr-describe.md)** — Generate full PR descriptions. - **[📜 History](history.md)** — Summarize recent git history. +### Productivity Commands +- **[🔨 Workon](workon.md)** — Automate starting and completing todo items and fixes with AI work plans. + ### Other Useful Commands - **[💬 Chat](chat.md)** — Full interactive chat with history and streaming - **[🤖 Query](query.md)** — One-shot programming-focused queries - **[🔍 Review](review.md)** — AI code review of the current repo/directory - **[🔧 Lint](lint.md)** — Lint + AI-suggested fixes -- - **[🔎 Analyze](analyze.md)** — Deep educational analysis of any codebase with custom language prompts. +- **[🔎 Analyze](analyze.md)** — Deep educational analysis of any codebase with custom language prompts. - **[📖 Docs](docs.md)** — Generate documentation comments - **[Completion](completion.md)** — Generate shell completion scripts - **[🏷️ Version](version.md)** — Print version information diff --git a/docs/user-guide/workon.md b/docs/user-guide/workon.md new file mode 100644 index 0000000..ed87da2 --- /dev/null +++ b/docs/user-guide/workon.md @@ -0,0 +1,109 @@ +# 🔨 Workon Guide + +The `workon` command automates starting and completing work on todo items and fixes. It integrates with Grokkit's in-repo todo system, Git branching, and Grok AI to keep your workflow uniform and consistent. + +### Why use Workon? + +- **Automated Workflow**: Moves todo items, creates branches, generates work plans, and commits — all in one command. +- **AI Work Plans**: Grok generates a concrete, numbered implementation plan tailored to each item. +- **Branch Conventions**: Automatically prefixes branches with `feature/` or `fix/` for clean git history. +- **Completion Tracking**: Moves items to completed, updates the todo index, and commits the change. +- **Optional Integrations**: Logs work start via `cnadd` and opens your configured IDE automatically. + +### Usage + +```bash +# Start working on a queued todo item +grokkit workon my-todo-item + +# Start a fix (creates a new .md in doing/) +grokkit workon my-bugfix -f + +# Custom commit message +grokkit workon my-feature -M "feat: begin API redesign" + +# Complete a todo item (move to completed/, update index) +grokkit workon my-todo-item -c + +# Complete a fix (move to completed/, no index update) +grokkit workon my-bugfix -c -f +``` + +### Options + +| Flag | Short | Description | Default | +|-----------|-------|-----------------------------------------------------|------------------------------------------| +| --message | -M | Custom commit message | "Start working on \" | +| --fix | -f | Treat as fix instead of todo | false | +| --complete| -c | Complete the item (cannot be combined with -M) | false | + +### How It Works + +#### Starting Work (default) + +1. **Bootstraps todo structure** — Creates `todo/queued/`, `todo/doing/`, and `todo/completed/` directories if they don't exist. +2. **Moves or creates the item**: + - **Todo mode** (default): Moves `todo/queued/.md` to `todo/doing/<title>.md`. + - **Fix mode** (`-f`): Creates a new `todo/doing/<title>.md` with a skeleton `## Work Plan` heading. +3. **Creates a git branch** — `feature/<title>` for todos, `fix/<title>` for fixes. If the branch already exists, checks it out instead. +4. **Generates a Work Plan** — Sends the item content to Grok and appends a numbered implementation plan to the markdown file. +5. **Commits** — Stages the `todo/` directory and commits with the default or custom message. +6. **Optional post-steps** (graceful fallbacks if unavailable): + - Logs the start of work via `cnadd` (if installed). + - Opens the repository in your configured IDE. + +#### Completing Work (`-c`) + +1. Moves `todo/doing/<title>.md` to `todo/completed/<title>.md`. +2. For non-fix items: updates `todo/README.md` — removes the entry from `## Queued` and appends it to `## Completed`. +3. Commits the change with the message `Complete work on <title>`. + +### Todo Folder Structure + +Workon assumes and maintains this in-repo ticketing layout: + +``` +todo/ + README.md # Index of all items (Queued / Completed sections) + queued/ # Items waiting to be worked on + my-feature.md + another-item.md + doing/ # Items currently in progress + active-item.md + completed/ # Finished items + done-item.md +``` + +If the `todo/` folder doesn't exist, `workon` creates it automatically. + +### Configuration + +The workon command respects two config keys in `~/.config/grokkit/config.toml`: + +```toml +[commands] + workon.model = "grok-4-1-fast-non-reasoning" # Model for work plan generation + workon.ide = "code" # IDE command to open repo (e.g. "code", "goland", "nvim") +``` + +If `workon.ide` is empty or unset, the IDE step is silently skipped. If `cnadd` is not installed, logging is silently skipped. + +### Title Handling + +- Spaces in the title are automatically replaced with dashes. +- The title is used as both the markdown filename (without prefix) and the branch name (with `feature/` or `fix/` prefix). + +### Examples + +```bash +# Full workflow: queue an item, work on it, complete it +echo "# Add caching" > todo/queued/add-caching.md +grokkit workon add-caching +# ... do the work ... +grokkit workon add-caching -c + +# Quick fix workflow +grokkit workon fix-null-pointer -f +# ... fix the bug ... +grokkit workon fix-null-pointer -c -f +``` diff --git a/todo/doing/workon.md b/todo/completed/workon.md similarity index 100% rename from todo/doing/workon.md rename to todo/completed/workon.md