Skip to content

GEMINI.md

Latest commit

 

History

History
130 lines (105 loc) · 5.59 KB

GEMINI.md

File metadata and controls

130 lines (105 loc) · 5.59 KB
Raw

Rig - Developer Workflow Automation CLI

Project Overview

Rig is a modern, extensible Go CLI tool designed to streamline developer workflows. It replaces complex bash scripts with a maintainable, feature-rich application that automates:

  • Git Worktrees: Automatic isolated workspaces per ticket/branch.
  • Tmux Sessions: Configurable multi-window terminal sessions.
  • Documentation: Markdown note creation (Obsidian-style) with JIRA and Beads integration.
  • History Tracking: Command history analysis and timeline export using SQLite.
  • AI Integration: Support for various AI providers (Anthropic, Gemini, Groq, Ollama) for workflow assistance.

Key Technologies

  • Language: Go (1.25+)
  • CLI Framework: Cobra
  • Configuration: Viper
  • Database: SQLite (modernc.org/sqlite)
  • Integrations: Git, Tmux, JIRA, Beads, Obsidian, GitHub
  • Error Handling: cockroachdb/errors

Directory Structure

  • cmd/: CLI command implementations (e.g., work.go, hack.go, session.go).
  • pkg/: Core logic packages.
    • pkg/git/: Git worktree and repository management.
    • pkg/tmux/: Tmux session automation.
    • pkg/jira/: JIRA integration (API & CLI).
    • pkg/beads/: Beads issue tracker integration.
    • pkg/history/: Command history tracking (zsh-histdb/atuin).
    • pkg/config/: Configuration handling and security warnings.
    • pkg/notes/: Markdown note templates and management.
    • pkg/ai/: AI provider implementations.
    • pkg/github/: GitHub API and CLI client.
  • main.go: Application entry point.
  • project.yaml: Project metadata and governance.

Building and Running

Build

go build -o rig

Run

./rig --help

Test

The project emphasizes comprehensive test coverage using table-driven tests and mocks.

go test ./...          # Run all tests
go test -v ./...       # Verbose output
golangci-lint run      # Run linters

Configuration

Rig uses a TOML configuration file, typically located at ~/.config/rig/config.toml. It also supports repository-local overrides via .rig.toml.

Key Config Sections

  • [notes]: Path to Obsidian/Markdown notes and templates.
  • [git]: Base branch configuration.
  • [jira]: JIRA credentials and mode (API vs ACLI).
  • [beads]: Beads integration settings.
  • [tmux]: Session window layouts and commands.
  • [history]: Database path for command history.
  • [ai]: AI provider and model settings.

Development Conventions

  • Style: Follow standard Go idioms.
  • Naming:
    • Fields/Files: snake_case
    • Directories: kebab-case
    • Enums: SCREAMING_SNAKE
  • Testing:
    • Mandatory for new features.
    • Prefer table-driven tests.
    • Use interfaces for mocking external dependencies (Git, JIRA, Tmux).
  • Architecture: Keep CLI logic in cmd/ minimal; delegate business logic to pkg/.
  • Linting: Strict mode using golangci-lint.

Key Commands

  • rig work <ticket>: Start a complete workflow (Worktree + Tmux + Note).
  • rig hack <name>: Start a lightweight non-ticket workflow.
  • rig list: Show active worktrees and sessions.
  • rig clean: Remove old worktrees and sessions.
  • rig sync <ticket>: Update notes with latest JIRA/Beads info.
  • rig timeline <ticket>: Export command history for a ticket.
  • rig history query: Search through command history.

Lessons Learned & Architectural Truths

AI Provider Patterns

  • Lazy Initialization: Use sync.Once and an init(ctx) method for providers requiring SDK setup or context. This avoids passing context.Context to constructors and defers initialization until first use.
  • Interface-Based Mocking: Test AI providers by injecting and mocking the underlying SDK model interfaces (e.g., Genkit's ai.Model). This enables fast, deterministic testing of message mapping and token usage.
  • Translation Layer: Maintain internal ai.Message and ai.Response abstractions. Map these to SDK-specific types within the provider implementation to protect the codebase from underlying SDK breaking changes.

AI Configuration

Providers are configured in ~/.config/rig/config.toml.

Gemini (Google AI)

Uses the native Genkit for Go SDK.

[ai]
provider = "gemini"
gemini_model = "gemini-1.5-flash" # Optional
gemini_api_key = "your-api-key"   # Or use GOOGLE_GENAI_API_KEY

Anthropic / Groq

[ai]
provider = "anthropic"
api_key = "your-api-key" # Or use ANTHROPIC_API_KEY / GROQ_API_KEY

Configuration Traps

  • Isolated Secret Resolution: Use isolated resolution functions for each provider to prevent "cross-provider contamination" (e.g., using an Anthropic key for Gemini).
  • Security Warning Accuracy: When implementing security warnings for config-stored secrets, ensure all valid environment variable sources (e.g., RIG_AI_*) are checked to avoid false positives.

Architectural Decisions

  • SDK-First: Prefer official Go SDKs (like Genkit for Google AI) over CLI wrappers for stability and robust streaming support.
  • Safe Deprecation: Use non-blocking configuration warnings (via CheckSecurityWarnings) instead of silent removal when deprecating keys to ensure a smooth user migration.

Documentation Conventions

  • Historical Accuracy: Never modify old release notes or historical documentation to reflect current state. Always treat past records as immutable snapshots.
  • Consolidated AI Context: Keep AI provider configuration examples and architectural truths in GEMINI.md to provide a single source of truth for future agent sessions.