🐑 Sheep It

Git workflow orchestrator for solo devs. Plan with Issues, ship with PRs.

Sheep It manages your entire Git workflow: branches, commits, PRs, and releases. Use GitHub Issues as specs, let adapters handle implementation, while Sheep It orchestrates everything from /sheep:task to /sheep:it.

30-Second Install

# 1. Install Sheep It
curl -fsSL https://raw.githubusercontent.com/Xavier-IV/sheep-it/master/install.sh | bash

# 2. Authenticate GitHub (if not already)
gh auth login && gh auth refresh -h github.com -s project,read:project

# 3. Setup in your project
/sheep:init

Requires Claude Code and GitHub CLI.

See It In Action

Step 1: Create a task (Two modes)

Default: Quick spec with OpenSpec

/sheep:task "Add user login"

Fast spec generation → OpenSpec creates complete spec (proposal, specs, design) → GitHub Issue. Best for most features.

Deep: Research mode

/sheep:task "Add payments" --deep

Parallel research agents → OpenSpec exploration → Detailed spec → GitHub Issue. Best for complex features needing investigation.

Step 2: Implement (Hybrid Approach)

Option A: Adapter-Powered (Recommended)

/sheep:start 22

Sheep It creates the branch and assigns the issue. If you have an adapter configured (like OpenSpec), it delegates implementation to the adapter. Sheep It handles all Git operations: commits, branch management, and tracking.

Option B: Basic Mode

/sheep:start 22

Without an adapter, Claude implements directly using the issue as the spec. Still gets branch creation, incremental commits, and acceptance criteria tracking.

Step 3: Ship it

/sheep:it 22

Creates a PR linked to the issue, with proper formatting and labels. When merged, issue auto-closes. Done.

Adapters: Extend Your Workflow

Sheep It focuses on Git workflow orchestration. For implementation, it can delegate to specialized adapters.

Why Adapters?

Sheep It excels at:

• Branch management and Git operations
• PR creation with proper formatting
• Issue tracking and progress updates
• Release management
• Commit conventions

Adapters excel at:

• Structured spec creation (PRDs, technical designs)
• Domain-specific implementation patterns
• Code generation from specs
• Advanced validation and checks

Together, they create a complete workflow: Sheep It handles Git, adapters handle code.

Supported Adapters

Adapter	Description	Integration
OpenSpec	Structured spec creation with PRDs	Quick: ff / Research: explore → apply → archive

How It Works

When an adapter is configured:

/sheep:task "Add login"     →  Sheep It: Creates branch
                               Adapter: Generates detailed spec
                               Sheep It: Creates GitHub issue

/sheep:start 22             →  Sheep It: Checkout branch, assign issue
                               Adapter: Implements from spec
                               Sheep It: Commits with conventions

/sheep:it 22                →  Sheep It: Creates PR
                               Adapter: Finalizes documentation
                               Sheep It: Links issue, adds labels

Division of responsibilities:

• Sheep It: All Git operations (branch, commit, PR, release)
• Adapter: Spec creation and implementation strategy
• GitHub: Single source of truth (issues, PRs, milestones)

Configuration

Add to .sheeprc.yml:

adapter:
  enabled: true
  name: "openspec"
  quick_mode: "opsx:ff"          # Fast spec (/sheep:task default)
  research_mode: "opsx:explore"  # Deep research (/sheep:task --deep)
  apply: "opsx:apply"            # Implementation (/sheep:start)
  verify: "opsx:verify"          # Verification (/sheep:verify, auto in /sheep:it)
  archive: "opsx:archive"        # Finalization (/sheep:it)

Adapters are auto-detected from available Claude Code skills. To disable:

adapter:
  enabled: false

Without an Adapter (Basic Mode)

Don't have an adapter? No problem. Sheep It still provides:

• Branch creation and management
• Issue-driven workflow
• Incremental commits with proper messages
• PR creation and linking
• Progress tracking

The adapter system is optional but recommended for complex projects.

Why I Built This

I'm a solo dev who wanted something simple. I kept losing context when Claude reset, and managing .planning/ folders felt like overhead for my small projects.

GitHub Issues already have everything I need:

• They survive Claude context resets (your spec is always there)
• Built-in tracking: checkboxes, labels, milestones, projects
• /sheep:resume recovers state instantly by reading git + issues
• No extra files to manage

This is just a personal tool I built for myself. If it helps you too, great!

---

Commands

All Commands Reference

Command	Description
Setup
/sheep:init [name]	Create/setup project (private by default)
/sheep:config	Configure project settings
Planning
/sheep:task "title"	Brainstorm → refine → create issue
/sheep:milestone "v1.0"	Create milestone with due date
Working
/sheep:start [issue]	Start work: branch + assign + implement (delegates to adapter if configured)
/sheep:resume	Continue after context reset
/sheep:status	Quick "where am I?" check
/sheep:verify [issue]	Verify against acceptance criteria
/sheep:sync	Sync branch with main (rebase/merge)
Shipping
/sheep:it [issue]	Ship it! Create PR
/sheep:release <version>	Create GitHub release
Tracking
/sheep:tasks	List open issues
/sheep:milestones	List milestones with progress
/sheep:progress	Detailed progress view
/sheep:board	View project board
Collaboration
/sheep:review [PR]	Review a pull request
/sheep:help	Show all commands

Configuration (Optional)

Create .sheeprc.yml or run /sheep:config:

branch:
  prefix: "feature"
  format: "{prefix}/{issue}-{slug}"

commits:
  style: "conventional"  # feat:, fix:, chore:

auto_update:
  check_criteria: true   # Auto-check acceptance criteria
  progress_comments: true

# Adapter integration (optional)
adapter:
  enabled: true
  name: "openspec"
  quick_mode: "opsx:ff"          # Fast spec
  research_mode: "opsx:explore"  # Deep research
  apply: "opsx:apply"            # Implementation
  verify: "opsx:verify"          # Verification
  archive: "opsx:archive"        # Finalization

Git Workflow Examples

Sheep It automates common Git workflows. Here are real-world examples:

Branch Management

Automatic branch creation with conventions:

/sheep:start 22
# Creates: feature/22-descriptive-slug
# Checks out from latest main/master
# Handles branch conflicts automatically

Sync with main during long-running work:

/sheep:sync
# Fetches origin, rebases/merges with main
# Handles conflicts interactively
# Keeps your feature branch up-to-date

Commit Workflows

Atomic commits with issue traceability:

# Sheep It creates atomic commits automatically:
feat(#22): add working hours model
feat(#22): add configuration UI
test(#22): add model specs
docs(#22): update API documentation

# Every commit references the issue
# Git history is fully traceable

Conventional commits by default:

# Configure in .sheeprc.yml
commits:
  style: "conventional"  # feat:, fix:, chore:, docs:, test:

PR Creation

Formatted PRs with proper linking:

/sheep:it 22
# Creates PR with:
# - Title: "feat: [Issue title] (#22)"
# - Body: "Closes #22" + summary
# - Labels: from issue
# - Auto-linked to issue (closes on merge)

PR template integration:

# .github/pull_request_template.md
Sheep It respects your PR templates and fills in:
- Issue reference
- Summary from commits
- Checklist from acceptance criteria

Release Workflows

Automated releases from milestones:

/sheep:release v1.0.0
# Creates GitHub release with:
# - Tag: v1.0.0
# - Release notes from milestone issues
# - Commit log since last release
# - Auto-generated changelog

Progress Tracking

Live progress in issues:

# As Sheep It works, it updates the issue:
# - Checks off acceptance criteria ✅
# - Posts progress comments
# - Updates labels (in progress → ready for review)
# - Links commits and branches

Resume after context loss:

/sheep:resume
# Reads git status + GitHub state
# Shows: current branch, issue, progress
# Continues exactly where you left off

Workflow Hooks

Integrate with your CI/CD:

# .sheeprc.yml
hooks:
  pre_commit:
    - "npm run lint"
    - "npm run test"

  pre_pr:
    - "npm run build"
    - "npm run test:e2e"

  post_release:
    - "./deploy.sh"

Philosophy

Git-first workflow orchestration. GitHub already has all the infrastructure: issues, PRs, milestones, projects. Sheep It orchestrates the Git workflow around these primitives:

• Issues → Your PRD / spec
• Branches → Feature isolation (auto-created, convention-based)
• Commits → Incremental progress (atomic, traceable to issues)
• PRs → Code review and shipping (formatted, linked, labeled)
• Releases → Version milestones (automated from tags)
• Projects → Kanban board
• Git state → Single source of truth for progress

Separation of concerns:

• Sheep It → Git workflow orchestration
• Adapters → Implementation strategy (optional)
• GitHub → Single source of truth

Keep it simple. Use what's already there. Focus on the workflow, not the tooling.

---

Uninstall

To remove Sheep It from your system:

curl -fsSL https://raw.githubusercontent.com/Xavier-IV/sheep-it/master/uninstall.sh | bash

This removes the ~/.claude/commands/sheep directory. Your project files and GitHub data are untouched.

---

MIT License

🐑 Don't be sheepish, ship it!