Sharkrite Architecture | Sarah Wadley

One Command. Complete Automation.

Sharkrite takes a GitHub issue number and drives it through the entire development lifecycle — branching, implementation via Claude Code, PR creation, AI-powered review triage, iterative fixes, and merge — all from a single sharkrite <issue-number> invocation.

80% Less overhead

5 Phase workflow

10 Blocker rules

The Problem being Solved

Manual GitHub workflows are death by a thousand context switches.
Even with AI-assisted development, you're still manually branching, pushing, creating PRs, waiting for CI, reading reviews, fixing, re-pushing,and merging — all the ceremony that keeps your git history clean but destroys your focus. Every step breaks flow state.

Context switches: Jumping between editor, terminal, and browser dozens of times per issue

Missed feedback: Review comments lost in notification noise or forgotten across sessions

Refresh hell: Polling CI status, waiting for checks, manually re-running failed jobs

2–4 hours per issue: Manual lifecycle from branch to merge for even simple changes

System Overview

A single command triggers a 5-phase pipeline that takes an issue from assignment to merged PR:

┌─────────────────────────────────────────────────────────────┐
│                      Sharkrite CLI                          │
│                 sharkrite <issue-number>                    │
└──────────────────────┬──────────────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
     Single Issue  Batch Mode  Quick Mode
          │            │            │
          ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 1: Development (Claude Code in isolated worktree)    │
├─────────────────────────────────────────────────────────────┤
│  Phase 2: PR Creation (dynamic wait times)                  │
├─────────────────────────────────────────────────────────────┤
│  Phase 3: Review Assessment (3-state AI triage)             │
├──────────────────────────────────────────────────────────��──┤
│  Phase 4: Fix Loop (up to 3 iterations)                     │
├─────────────────────────────────────────────────────────────┤
│  Phase 5: Merge + Security Feedback Capture                 │
└─────────────────────────────────────────────────────────────┘

Key Features

3-State Review Triage

Claude CLI categorizes each review comment into one of three actionable states, eliminating noise and ensuring nothing important is missed:

ACTIONABLE_NOW — Fix in this PR. The review identifies a real issue that should be addressed before merge.
ACTIONABLE_LATER — Create a follow-up issue. Valid feedback, but out of scope for this change.
DISMISSED — Noise. Style preferences, false positives, or non-actionable commentary.

Security Feedback Loop

A persistent scratchpad captures security findings across sessions. Claude Code sees past issues on every run, learning from previous mistakes and avoiding repeat vulnerabilities. The feedback loop compounds — each session makes the next one safer.

Blocker Detection

10 configurable rules automatically pause the workflow for manual review when changes touch sensitive areas:

Infrastructure changes (Terraform, CDK, CloudFormation)
Database migrations and schema changes
Authentication and authorization modifications
CI/CD pipeline changes
Dependency updates and lock files

When a blocker triggers, Sharkrite creates a resume script for graceful recovery after manual review.

Worktree Isolation

Automatic git worktree management keeps each issue in its own isolated workspace. Auto-stash protects in-progress work, parallel worktrees enable concurrent development, and shared node_modules avoids redundant installs.

Configuration

Sharkrite uses a layered configuration system where each level overrides the previous:

Defaults — Sensible built-in values
Global config — ~/.sharkrite/config
Project config — .sharkrite/config in repo root
Environment variables — SHARKRITE_* overrides

# .sharkrite/config — per-project overrides
MAX_FIX_ATTEMPTS=5
BLOCKER_PATTERNS="migrations/|\.tf$|auth/"
AUTO_MERGE=false
WORKTREE_BASE="../.worktrees"

Technical Decisions

Decision	Choice	Rationale
Language	Bash	Zero dependencies, native to every dev environment, and Claude Code runs in a shell natively
Config format	Shell-sourceable	No parser needed — `source .sharkrite/config` loads everything
Review detection	Polling	No server, no webhooks, no infrastructure to maintain
Default mode	Full lifecycle	Prevents orphaned PRs and half-finished branches from accumulating

Source Code

Explore the full codebase, including the 5-phase pipeline and review triage system:

lifeunsubscribe/sharkrite on GitHub →