# 🔨 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
```