gur Workflow Skill

This skill teaches effective use of gur, a task management CLI designed for AI agent workflows.

Core Concepts

Task Lifecycle

code

open -> in_progress -> closed -> archived

•open: Task is ready to be worked on
•in_progress: Actively being worked on
•closed: Completed with a close reason
•archived: Historical record, can be compacted to save context

Priority Levels

•P0 (Critical): Drop everything, fix now
•P1 (High): Important, address soon
•P2 (Medium): Normal priority (default)
•P3 (Low): Nice to have
•P4 (Lowest): Backlog

Task Types

•task: General work item (default)
•bug: Defect to fix
•feature: New functionality
•epic: Large initiative containing subtasks

Command Patterns

Creating Tasks

Basic task:

bash

gur create "Implement user authentication"

With full context:

bash

gur create "Fix login timeout bug" \
  --type bug \
  --priority 1 \
  --label security \
  --label auth \
  --assignee agent

From template:

bash

gur create "Add payment processing" --template feature-checklist

Working With Subtasks

Create parent epic:

bash

gur create "User management system" --type epic
# Returns: gur-a1b2c3d4

Add subtasks:

bash

gur create "Design user schema" --parent gur-a1b2c3d4
gur create "Implement CRUD endpoints" --parent gur-a1b2c3d4
gur create "Add validation" --parent gur-a1b2c3d4

Subtasks get hierarchical IDs: gur-a1b2c3d4.1, gur-a1b2c3d4.2, etc.

Managing Dependencies

Block a task until another completes:

bash

# "auth" blocks "dashboard" (dashboard can't close until auth is done)
gur dep add gur-auth123 gur-dash456

Check what's blocking:

bash

gur show gur-dash456  # Shows "Blocked by: gur-auth123"

Find unblocked tasks ready for work:

bash

gur ready

Quality Gates

Gates enforce checks before task closure.

Create a gate:

bash

gur gate create "Unit tests pass" --type test --command "go test ./..."
gur gate create "Code review approved" --type review
gur gate create "Security scan clean" --type approval --priority 0

Link gate to task:

bash

gur gate link gate-abc123 gur-task456

Record gate results:

bash

gur gate pass gate-abc123 --by agent --notes "All 42 tests passing"
gur gate fail gate-abc123 --by agent --notes "3 tests failing in auth module"

Attempt to close (will check gates):

bash

gur close gur-task456 "Implementation complete"
# Error: Cannot close - failing gates: "Unit tests pass"

Task Updates

Update status:

bash

gur update gur-abc123 --status in_progress

Add notes (timestamped):

bash

gur update gur-abc123 --note "Found root cause - null pointer in line 42"

Change priority:

bash

gur update gur-abc123 --priority 0  # Escalate to critical

Searching and Filtering

Search by keyword:

bash

gur search "authentication"

List with filters:

bash

gur list --status open --priority 0,1  # Critical and high priority
gur list --type bug --assignee agent
gur list --label security

Closing Tasks

Simple close:

bash

gur close gur-abc123 "Fixed by commit abc123"

Force close (skip gate checks):

bash

gur close gur-abc123 "Closing as won't fix" --force

Reopen if needed:

bash

gur reopen gur-abc123

Linking Skills and Agents

Associate domain knowledge:

bash

gur update gur-abc123 --skill security-audit --skill go-testing

Assign agents:

bash

gur update gur-abc123 --agent Explore --agent Plan

History and Audit

View task history:

bash

gur history gur-abc123

Archive old closed tasks:

bash

gur archive --before 30d

Compact to save context:

bash

gur compact --all  # Summarize and clear verbose fields

Statistics

View project stats:

bash

gur stats

Session summary:

bash

gur summary

Best Practices

1. Break Down Large Tasks

Instead of one massive task, create an epic with subtasks:

bash

# Bad: One huge task
gur create "Build entire payment system"

# Good: Epic with focused subtasks
gur create "Payment system" --type epic
gur create "Payment model and migrations" --parent gur-xxx
gur create "Stripe integration" --parent gur-xxx
gur create "Payment API endpoints" --parent gur-xxx
gur create "Payment UI components" --parent gur-xxx

2. Use Dependencies for Ordering

When tasks must be done in sequence:

bash

gur create "Design API schema"      # gur-design
gur create "Implement API"          # gur-impl
gur create "Write API tests"        # gur-tests

gur dep add gur-design gur-impl     # impl waits for design
gur dep add gur-impl gur-tests      # tests wait for impl

Then gur ready shows only unblocked tasks.

3. Use Gates for Quality Checks

For tasks requiring verification:

bash

gur gate create "Tests pass" --type test
gur gate create "Reviewed" --type review
gur gate link gate-tests gur-feature
gur gate link gate-review gur-feature

This prevents premature closure.

4. Add Context in Notes

Document discoveries and decisions:

bash

gur update gur-abc123 --note "Investigated: issue is in the cache layer, not DB"
gur update gur-abc123 --note "Decision: using Redis instead of Memcached"

5. Use Labels for Cross-Cutting Concerns

bash

gur create "Fix XSS vulnerability" --label security --label frontend
gur create "Add CSRF protection" --label security --label backend
gur list --label security  # Find all security tasks

6. Close with Meaningful Reasons

bash

# Good close reasons
gur close gur-abc123 "Fixed in commit a1b2c3d - added null check"
gur close gur-def456 "Won't fix - feature deprecated in v2"
gur close gur-ghi789 "Duplicate of gur-xyz000"

# Bad close reasons
gur close gur-abc123 "Done"  # No context

7. Archive and Compact Regularly

Keep context window clean:

bash

# Archive tasks closed more than 30 days ago
gur archive --before 30d

# Compact archived tasks to minimal form
gur compact --all

8. Use JSON Output for Automation

bash

gur list --json | jq '.[] | select(.priority <= 1)'
gur show gur-abc123 --json

Common Workflows

Bug Triage

bash

# Create bug with details
gur create "App crashes on login" --type bug --priority 1 --label crash

# Investigate and update
gur update gur-xxx --status in_progress
gur update gur-xxx --note "Reproduced: happens with special chars in password"

# Fix and close
gur close gur-xxx "Fixed in commit abc - escaped special characters"

Feature Development

bash

# Plan as epic
gur create "Add dark mode" --type feature --type epic

# Break into subtasks
gur create "Add theme context" --parent gur-xxx
gur create "Create dark color palette" --parent gur-xxx
gur create "Add theme toggle component" --parent gur-xxx
gur create "Persist theme preference" --parent gur-xxx

# Add quality gates
gur gate create "Dark mode tests" --type test
gur gate link gate-xxx gur-xxx

# Work through subtasks
gur ready  # See what's unblocked

Code Review Workflow

bash

# Create gate for reviews
gur gate create "PR approved" --type review

# Link to task
gur gate link gate-review gur-feature

# After review
gur gate pass gate-review --by "reviewer" --notes "LGTM, approved"

# Now task can be closed
gur close gur-feature "Merged in PR #123"

GitHub Integration

Setup

bash

gur config github
# Enter: owner/repo
# Enter: GitHub token (stored in system keyring)

Sync to GitHub Issues

bash

# Push all tasks as issues
gur sync push --all

# Push only open tasks
gur sync push --open

# Dry run first
gur sync push --all --dry-run

Tasks sync bidirectionally - GitHub issue numbers are tracked for updates.