A GitHub issue-driven AI orchestration system that transforms labeled issues into working code through coordinated AI agent collaboration.

Kiro Krew watches a GitHub repository for issues with a configured label, then spawns AI agents to implement solutions automatically:

GitHub Issue (labeled) → Watcher detects → Krew-Lead orchestrates
    → Architect designs → Builder implements → Validator verifies → PR created

The system uses kiro-cli agents working in isolated git worktrees. Each issue gets its own branch, and on success a pull request is created automatically.

• Go 1.21+
• GitHub CLI (gh) — authenticated via gh auth login
• Kiro CLI (kiro-cli) — for running AI agents

go install github.com/jbrinkman/kiro-krew@latest

# For AMD64 (x86_64)
curl -L https://github.com/jbrinkman/kiro-krew/releases/latest/download/kiro-krew-linux-amd64 -o kiro-krew
chmod +x kiro-krew
sudo mv kiro-krew /usr/local/bin/

# For ARM64 (aarch64)
curl -L https://github.com/jbrinkman/kiro-krew/releases/latest/download/kiro-krew-linux-arm64 -o kiro-krew
chmod +x kiro-krew
sudo mv kiro-krew /usr/local/bin/

# Check your architecture
uname -m  # x86_64 = AMD64, aarch64/arm64 = ARM64

git clone https://github.com/jbrinkman/kiro-krew.git
cd kiro-krew

# Using Task (recommended)
task build

# Or using Go directly
go build ./cmd/kiro-krew

This project uses Task for build automation:

task build    # Build optimized binary with version metadata
task dev      # Development build (faster compilation)
task test     # Run tests with coverage
task clean    # Clean build artifacts
task lint     # Run linters and formatters

cd your-project
kiro-krew init

This creates:

• .kiro-krew/config.yaml — watcher configuration
• .kiro-krew/scripts/ — worktree management scripts
• .kiro/agents/ — agent configurations (krew-lead, architect, builder, validator, documenter)

Edit .kiro-krew/config.yaml:

repo: owner/repo-name
label: kiro-krew
poll_interval: 5m
max_retries: 3

kiro-krew

This starts the interactive REPL. From there, start the watcher:

kiro-krew> watch start
kiro-krew> status

# Display version and exit
kiro-krew --version

# Initialize project with agent configs and templates (skips existing files)
kiro-krew init

# Force-update templates (overwrites all files except config.yaml)
kiro-krew update

# Start interactive REPL (default when no arguments)
kiro-krew

Press Ctrl+Alt+P (or Ctrl+Option+P on macOS) to toggle between console and planning modes:

• Console Mode: Main Kiro Krew interface for managing watchers and agents
• Planning Mode: Interactive AI-assisted issue creation and planning

Both modes preserve their state when you switch, allowing seamless workflow transitions. See docs/hotkey-toggle.md for detailed usage information.

When the watcher detects a labeled issue:

1. Krew-Lead — Orchestrates the workflow. Creates a git worktree, delegates to other agents, manages the lifecycle from issue to PR.
2. Architect — Reads the issue, explores the codebase, and produces a design specification at .kiro-krew/specs/issue-<number>-<slug>.md.
3. Builder — Implements code changes according to the architect's specification. Focused on a single task at a time.
4. Validator — Read-only agent that verifies the implementation meets acceptance criteria. Runs tests and checks.
5. Documenter — Generates documentation in app_docs/ for completed features.

The manager spawns agents as kiro-cli processes:

kiro-cli chat --agent krew-lead --no-interactive --trust-all-tools "Process issue #N from repo owner/name. Worktree name: issue-N-<pid>"

Each agent runs with environment variables: ISSUE_NUMBER, REPO, and KIRO_KREW_WATCHER_PID.

Each issue is processed in an isolated git worktree named issue-<number>-<pid> (where <pid> is the watcher process ID):

• .kiro-krew/scripts/worktree-create.sh <name> — creates .worktrees/<name>/ on branch spec/<name>
• .kiro-krew/scripts/worktree-merge.sh <name> — merges back, removes worktree, deletes branch
• Orphaned worktrees (from crashed processes) are cleaned up automatically by checking if the PID is still running

Issues with kiro-krew-done or kiro-krew-failed labels are excluded from polling. The done/failed labels are derived from the configured label (e.g., if label is my-label, done becomes my-label-done).

The system has two layers of retry:

1. Global retries (watcher level) — Persisted in .kiro-krew/retries/issue-<number>.count. The watcher skips issues that have reached max_retries attempts and survives process restarts.
2. Per-agent retries (manager level) — When an agent exits with a non-zero code, the manager retries with exponential backoff (delay = retry count × 1 second) up to max_retries.

After exhausting retries, the issue is labeled <label>-failed.

Agent configs live in .kiro/agents/. Each agent has a JSON config and a prompt markdown file.

krew-lead.json (orchestrator):

{
  "name": "krew-lead",
  "tools": ["read", "shell", "subagent", "todo_list"],
  "toolsSettings": {
    "subagent": {
      "trustedAgents": ["architect", "builder", "validator", "documenter"]
    }
  },
  "model": "claude-sonnet-4"
}

builder.json (worker):

{
  "name": "builder",
  "description": "Focused engineering agent that executes ONE task at a time.",
  "prompt": "file://./builder-prompt.md",
  "tools": ["read", "write", "shell"],
  "allowedTools": ["read", "write", "shell"],
  "model": "claude-sonnet-4"
}

validator.json (read-only verifier):

{
  "name": "validator",
  "description": "Read-only validation agent that verifies task completion.",
  "prompt": "file://./validator-prompt.md",
  "tools": ["read", "shell"],
  "allowedTools": ["read", "shell"],
  "toolsSettings": {
    "shell": { "autoAllowReadonly": true }
  },
  "model": "claude-sonnet-4"
}

Kiro Krew uses the gh CLI for all GitHub operations — no API tokens to configure. Ensure you're authenticated:

gh auth login
gh auth status

The system calls:

• gh issue list — poll for labeled issues
• gh issue view — read issue details
• gh issue edit — add labels (kiro-krew-done, kiro-krew-failed)
• gh pr create — create pull requests

See LICENSE.