From 41c6062fc349ca7bb1fce12b1c148a74938453a0 Mon Sep 17 00:00:00 2001 From: Jonathan Hult Date: Wed, 13 May 2026 20:38:16 -0500 Subject: [PATCH 1/2] chore: enhance skill --- .claude/skills/grite.md | 163 +++++++++++++++++++++------------------- 1 file changed, 84 insertions(+), 79 deletions(-) diff --git a/.claude/skills/grite.md b/.claude/skills/grite.md index fb23b94..038bb80 100644 --- a/.claude/skills/grite.md +++ b/.claude/skills/grite.md @@ -1,128 +1,133 @@ --- name: grite -description: Git-backed issue tracker with CRDT merging, designed for AI coding agents -version: 0.3.0 +description: >- + Official skill for grite, a local-first dependency-aware issue tracker for AI + agents. Use when creating issues, triaging backlogs, managing dependencies, + finding ready work, updating status, or syncing to git. +license: MIT +domain: project-management +role: specialist +scope: operations +output-format: commands +model: haiku +triggers: + - grite + - issue tracker + - issue triage + - backlog + - dependencies + - ready work +metadata: + author: jhult + version: 1.0.0 --- -# Grite Skill +# grite — Issue Tracker (Official Skill) -This repository uses **Grite** as the canonical task and memory system. **Always use grite commands** (not git) for task/issue tracking. +> **Grite is NOT GitHub Issues, gh, Linear, or Jira.** It's a standalone git-backed tracker. When asked to create/manage issues, use `grite` commands — never fall back to other tools. -## When to use grite +## Critical Rules for Agents -- "What tasks are done/open?" -> `grite issue list` -- "What did I work on?" -> `grite issue list --state closed` -- "What do I know about X?" -> `grite issue list --label memory` -- "What should I work on next?" -> `grite issue dep topo --state open` -- "What does function X do?" -> `grite context query X` -- Starting a new task -> `grite issue create` -- Making progress -> `grite issue comment` -- Task A depends on B -> `grite issue dep add` +- **ALWAYS use `--json`** — structured output for parsing +- **IDs can be prefixed** — `abc123ef` → `abc123` (any prefix works) +- **Sync is EXPLICIT** — `grite sync --push` exports to git only when called -## Startup routine - -Run at the beginning of each session: +## Quick Workflow ```bash +# 1. Sync latest grite sync --pull --json -grite issue list --json + +# 2. Find work (in dependency order) grite issue dep topo --state open --json -``` -## Creating tasks/memories +# 3. Read the issue +grite issue show --json -```bash -# Create a task -grite issue create --title "Task title" --body "Description" --label agent:todo --json +# 4. Plan (comment before coding) +grite issue comment --body "Plan: ..." --json + +# 5. Work... then checkpoint +grite issue comment --body "Progress: ..." --json -# Store a discovery as memory -grite issue create --title "[Memory] Topic" --body "What you learned..." --label memory --json +# 6. Close and sync +grite issue close --json +grite sync --push --json ``` -## Working on issues +## Essential Commands + +### Finding Work ```bash -# Add a comment with your plan before coding -grite issue comment --body "Plan: ..." --json +# Unblocked work in dependency order (use this first) +grite issue dep topo --state open --json -# Add checkpoint comments after milestones -grite issue comment --body "Checkpoint: what changed, why, tests run" --json +# All open issues +grite issue list --state open --json -# Close when done -grite issue close --json -grite sync --push --json +# Read a specific issue +grite issue show --json ``` -## Querying tasks +### Issue Lifecycle ```bash -# All issues -grite issue list --json +# Create issue +grite issue create --title "Title" --body "Description" --label todo --json -# Open tasks -grite issue list --state open --json +# Comment (progress updates, plans, blockers) +grite issue comment --body "..." --json -# Completed tasks -grite issue list --state closed --json +# Close when done +grite issue close --json -# Memories -grite issue list --label memory --json +# Re-open if needed +grite issue reopen --json ``` -## Dependencies - -Track task ordering and blockers with a dependency DAG: +### Dependencies ```bash -# Task A depends on Task B (B must complete first) +# A depends on B (A cannot start until B is done) grite issue dep add --target --type depends_on --json -# Task A blocks Task B (A must complete first) +# A blocks B (B cannot start until A is done) grite issue dep add --target --type blocks --json -# Mark tasks as related (no ordering constraint) +# A is related to B (non-blocking connection, for context) grite issue dep add --target --type related_to --json -# List what an issue depends on -grite issue dep list --json - -# List what depends on an issue (reverse) -grite issue dep list --reverse --json - -# Get execution order (topological sort of open tasks) +# Get execution order (always respects full dependency graph) grite issue dep topo --state open --json ``` -**Always run `dep topo`** at session start to determine which task to work on next. +**Critical:** Always use `dep topo` to find the right starting task — never skip past blockers. -## Context store - -Index and query codebase structure for fast navigation: +### Sync (EXPLICIT — never automatic) ```bash -# Index all tracked files (skips unchanged files) -grite context index --json - -# Index specific files or patterns -grite context index --path src/main.py --json -grite context index --pattern "*.rs" --json - -# Query for a symbol (function, class, struct, etc.) -grite context query --json - -# Show all symbols in a file -grite context show --json +grite sync --pull --json # Import from git (after git pull) +grite sync --push --json # Export to git (before git commit) +``` -# Set project-level context (conventions, architecture notes) -grite context set --json +Always sync after `git pull` and before `git commit`. -# View all project context -grite context project --json -``` +## Issue Labels -**Index after significant code changes** to keep the symbol database current. +| Label | Use | +|-------|-----| +| `todo` | Available work | +| `in-progress` | Currently being worked on | +| `blocked` | Cannot proceed (needs external input) | +| `bug` | Something broken | +| `feature` | New functionality | +| `memory` | Project knowledge to persist across sessions (discoveries, decisions, gotchas) | -## Key flags +## Anti-Patterns -- `--json` - Use for all commands (machine-readable output) -- `--quiet` - Suppress human output +- Using `gh issue`, GitHub Issues, Linear, Jira, or any other tracker (grite is the ONLY tracker) +- Forgetting `grite sync --push` before git commit +- Skipping `grite issue comment` for plan documentation +- Closing issues without evidence in the comment +- Starting work without checking `dep topo` first (may skip dependencies) From 34343fb101f3bbf336ae319cc904c311e46e2d62 Mon Sep 17 00:00:00 2001 From: Jonathan Hult Date: Wed, 13 May 2026 20:44:05 -0500 Subject: [PATCH 2/2] chore(agents): reference /grite skill instead of duplicating content Simplify AGENTS.md generation to point users to the /grite skill for documentation rather than maintaining parallel content. Recommends installing via grite install-skill if needed. --- crates/grite/src/agents_md.rs | 117 ++-------------------------------- 1 file changed, 5 insertions(+), 112 deletions(-) diff --git a/crates/grite/src/agents_md.rs b/crates/grite/src/agents_md.rs index ef8c044..9312515 100644 --- a/crates/grite/src/agents_md.rs +++ b/crates/grite/src/agents_md.rs @@ -1,124 +1,17 @@ /// Template content for the Grite section in AGENTS.md pub const GRITE_AGENTS_SECTION: &str = r#"## Grite -This repository uses **Grite** as the canonical task and memory system. **Always use grite commands** (not git) for task/issue tracking. +This repo uses **Grite** (NOT GitHub Issues, gh, Linear, or Jira) as the canonical task and issue tracker system. Use the `/grite` skill for **ALL** task and issue tracking. -### When to use grite - -- **"What tasks are done/open?"** → `grite issue list` -- **"What did I work on?"** → `grite issue list --state closed` -- **"What do I know about X?"** → `grite issue list --label memory` -- **"What should I work on next?"** → `grite issue dep topo --state open` -- **"What does function X do?"** → `grite context query X` -- **Starting a new task** → `grite issue create` -- **Making progress** → `grite issue comment` -- **Task A depends on B** → `grite issue dep add` - -### Startup routine - -Run at the beginning of each session: +If the skill is not installed, run: ```bash -grite sync --pull --json -grite issue list --json -grite issue dep topo --state open --json +grite install-skill ``` -### Creating tasks/memories +For complete documentation, invoke: -```bash -# Create a task -grite issue create --title "Task title" --body "Description" --label agent:todo --json - -# Store a discovery as memory -grite issue create --title "[Memory] Topic" --body "What you learned..." --label memory --json ``` - -### Working on issues - -```bash -# Add a comment with your plan before coding -grite issue comment --body "Plan: ..." --json - -# Add checkpoint comments after milestones -grite issue comment --body "Checkpoint: what changed, why, tests run" --json - -# Close when done -grite issue close --json -grite sync --push --json +/grite ``` - -### Querying tasks - -```bash -# All issues -grite issue list --json - -# Open tasks -grite issue list --state open --json - -# Completed tasks -grite issue list --state closed --json - -# Memories -grite issue list --label memory --json -``` - -### Dependencies - -Track task ordering and blockers with a dependency DAG: - -```bash -# Task A depends on Task B (B must complete first) -grite issue dep add --target --type depends_on --json - -# Task A blocks Task B (A must complete first) -grite issue dep add --target --type blocks --json - -# Mark tasks as related (no ordering constraint) -grite issue dep add --target --type related_to --json - -# List what an issue depends on -grite issue dep list --json - -# List what depends on an issue (reverse) -grite issue dep list --reverse --json - -# Get execution order (topological sort of open tasks) -grite issue dep topo --state open --json -``` - -**Always run `dep topo`** at session start to determine which task to work on next. - -### Context store - -Index and query codebase structure for fast navigation: - -```bash -# Index all tracked files (skips unchanged files) -grite context index --json - -# Index specific files or patterns -grite context index --path src/main.py --json -grite context index --pattern "*.rs" --json - -# Query for a symbol (function, class, struct, etc.) -grite context query --json - -# Show all symbols in a file -grite context show --json - -# Set project-level context (conventions, architecture notes) -grite context set --json - -# View all project context -grite context project --json -``` - -**Index after significant code changes** to keep the symbol database current. - -### Key flags - -- `--json` - Use for all commands (machine-readable output) -- `--quiet` - Suppress human output "#;