# 🛠️ Development Overview

This document provides a comprehensive overview of the development process for Grokkit, including build instructions, project structure, and the standard TODO workflow.

## Development

```bash
# All tests pass without XAI_API_KEY (unit tests only)

# Run tests
make test

# Agent-specific tests
make test-agent

# Run tests with coverage report
make test-cover
open build/coverage.html

# Linting (matches CI, uses .golangci.yml config)
make lint
# Install golangci-lint if needed:
# go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run specific tests
go test -run TestEditCommand ./cmd -v

# Build binary
make build

# Install locally
make install

# Clean build artifacts
make clean
```

### Project Structure

```
grokkit/
├── cmd/              # CLI commands (Cobra)
│   ├── docs.go       # grokkit docs — AI documentation generation
│   ├── lint.go       # grokkit lint — AI-powered linting
│   ├── recipe.go     # grokkit recipe — transactional recipe runner
│   ├── scaffold.go   # grokkit scaffold — project-aware file generation
│   └── ...           # chat, edit, commit, review, history, pr-describe, agent
├── config/           # Viper configuration
├── docs/             # Documentation
├── .grokkit/         # Project-local Grokkit data
│   └── recipes/      # Custom AI workflows (recipes)
├── todo/             # TODO tracking: queued/ (pending) and completed/ (historical record)
│   ├── queued/       # Pending TODO items
│   └── completed/    # Completed TODO items with history
├── internal/
│   ├── errors/       # Custom error types
│   ├── git/          # Git operations
│   ├── grok/         # xAI Grok API client
│   ├── linter/       # Multi-language linting
│   ├── logger/       # Structured slog logging
│   ├── recipe/       # Recipe loading and execution engine
│   └── version/      # Build/version info
├── main.go           # Application entrypoint
├── go.mod            # Dependencies
├── Makefile          # Build automation
├── .golangci.yml     # Golangci-lint configuration
└── scripts/          # Install scripts
```

## TODO Workflow

**Policy:**  
From now on, the only thing to be committed directly to the `master` branch will be to-do items (.md files in `todo/queued/`).

**Process:**  
1. When deciding to work on a to-do item: create a branch, implement on the branch, submit PR to `master`.  
2. After PR merge: move the item to `todo/completed/`.

**Example workflow:**  
```bash
git checkout -b feature/some-todo
# Implement changes, test with make test lint
git add .
git commit -m "feat: implement some-todo"
git push -u origin feature/some-todo
# Create and merge PR to master

# Post-merge:
git checkout master
git pull
mv "todo/queued/SOME_TODO.md" "todo/completed/SOME_TODO.md"
git add todo/
git commit -m "chore: complete some-todo"
git push origin master
```

### Gitea Actions Automation *(automates post-merge above)*

[`.gitea/workflows/auto-complete-todo.yml`](../../.gitea/workflows/auto-complete-todo.yml) triggers on PR `opened`/`synchronize`:

- Branches `feature/some-todo`: moves `todo/queued/some-todo.md` → `completed/`.

**One-time setup** (Gitea → Repo → Settings → Secrets & Variables → Actions):
- New Secret: `PAT_TOKEN` = [Personal Access Token](https://gitea.example.com/user/settings/tokens) (scope: `repo`).
- Optional: Branch protection → Require "Auto-complete TODO" status check.

**Result**: No manual post-merge steps needed!