Greg Gauthier
65f67ff7b1
- 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
110 lines
4.4 KiB
Markdown
110 lines
4.4 KiB
Markdown
# 🔨 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 \<todo_item_title\>" |
|
|
| --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/<title>.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
|
|
```
|