Grits

A Git-native, local-first issue tracker designed for AI Agents and humans.

Status: v3.0.0 — "Active State Store"

Quick Start

Prerequisites

Rust (latest stable)
Git

Install CLI

# Via Cargo (recommended)
cargo install grits-cli

# Or download binary from Releases
# https://github.com/babybirdprd/grits/releases

Initialize a Project

cd your-project
gr onboard

🤖 The State Store Protocol (Planner/Coder)

Grits transforms from a passive tracker into an Active State Store (World Model) for agents. It enforces a strict separation between research and execution to minimize LLM "halucinations" and context drift.

The Lifecycle of an Issue

User Intent (description): The high-level goal set by a human or orchestrator.
Planner Agent: Analyzes the intent, researches the code via gr star, and populates the Implementation Plan (design).
Coder Agent: Wakes up to a Rich Pulse JSON. If design is present, it begins coding. It logs every iteration/rollout to the Execution Log (notes) via gr update --append.

Key Commands for Agents

gr pulse: Returns a full Rich Context JSON (Intent + Plan + Rules + History).
gr update --append: Persistent append-only logging for the Lab Notebook (notes).
gr workon: Automatically warns if a Coder starts work without a design.

Core Workflow

1. Check Pulse

Hydrate your session (or your agent's context) with the current project status.

gr pulse

2. Create Issue

gr create "Fix login bug" --description "intent" --design "plan" --start-work

3. Hierarchy & Linking

Link existing tasks or migrate them into a hierarchy.

gr dep add gr-child123 gr-parentabc --migrate
# ✅ Result: Child is renamed to gr-parentabc.n

4. Context Awareness (Blind Assembly)

Bundle relevant code even if you don't have a topology map yet.

gr context assemble --symbols "README.md,src/main.rs"

CLI Reference (v3.1.0)

Field	Purpose	Agent Map
`description`	The User's Intent	Intent
`design`	Implementation Plan	Strategy
`acceptance_criteria`	Success Definitions	Proof
`notes`	Execution Log (Append-only)	Memory

Command	Purpose
`gr show <id>`	Displays Rich Context + Execution Log
`gr update --append`	Marks notes as append-only (Lab Notebook)
`gr pulse`	Rich Context JSON for Session Hydration
`gr context assemble`	Fallback "Blind" assembly for raw file paths

Agent Skills

Grits separates logic into two specialized roles to enforce the Planner/Coder protocol.

Planner Skill: .agent/skills/grits-plan/SKILL.md — For Architecture & Design.
Coder Skill: .agent/skills/grits-code/SKILL.md — For Implementation & Logging.
Agent Guide: AGENTS.md
Standard: Follows the Agent Skills open specification.

Architecture

Twin Engine:

SQLite (.grits/grits.db) — Fast local queries.
JSONL (.grits/issues.jsonl) — Git-versioned source of truth.

Graph-Lite:

Uses a lightweight AST parser to build a dependency graph.
Supports Blind Assembly fallback for non-topological file access.

License

MIT

grits-core 3.1.0