grokkit/docs/developer-guide/overview.md

🛠️ 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

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

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 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 (scope: repo).
• Optional: Branch protection → Require "Auto-complete TODO" status check.

Result: No manual post-merge steps needed!