grokkit/docs/user-guide/workon.md

🔨 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

# 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:

[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

# 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