sr-harness

sr-harness

A custom coding-agent harness for designing how your AI assistant works — not the other way around.

English | 한국어 | Interactive Workflow →

---

Why

When working with coding agents day-to-day, the same patterns keep breaking down:

• Principles exist as background rules — they load into context but don't get enforced when it matters
• Issue-Driven Development lives in a project memory file, disconnected from the actual workflow
• Brainstorming, planning, and implementation feel like separate sessions, not one continuous flow

sr-harness structures these into a single workflow where each stage enforces the right behavior automatically.

---

How it works

Instead of relying on rules loaded somewhere in context, each skill applies checkpoints at stage entry.

execute: before touching code
  [ ] Is the request clear? If not → ask first
  [ ] Is there a simpler path? If yes → propose it
  [ ] Is there a success criterion? If not → define it

execute: when editing existing code
  [ ] Read the file before writing
  [ ] Only touch lines directly related to the request
  [ ] Leave surrounding code, comments, and formatting as-is

From idea to PR, each skill hands off naturally to the next.

---

Installation

sr-harness ships manifests for both Claude Code and Codex:

• Claude Code: .claude-plugin/plugin.json
• Codex: .codex-plugin/plugin.json

Claude Code

# Add marketplace
claude plugins marketplace add https://github.com/SeokRae/sr-harness.git

# Install
claude plugins install sr-harness@sr-harness

Verify:

claude plugins list
#   ❯ sr-harness@sr-harness
#     Version: 0.18.0
#     Scope: user
#     Status: ✔ enabled

Codex

Codex support is manifest-ready through .codex-plugin/plugin.json. Install it through your Codex plugin marketplace or local plugin source configuration. Once installed, the shared skills/*/SKILL.md files are available to Codex.

Runtime-specific behavior is documented in docs/RUNTIME-COMPATIBILITY.md.

---

Lifecycle

The full lifecycle — state transitions, the skill map, resolved gaps, and the remaining roadmap — is documented in docs/LIFECYCLE.md.

Workflow

start
      │  Identify task type, load session plan, route to the right skill
      │
      ├─ brainstorm
      │    Not: dump all ideas at once
      │    But: one round = one concrete output + one clarifying question
      │    Exit: idea is small enough to fit in a single GitHub Issue
      │
      ├─ plan
      │    Every step must have a verify condition
      │    Format: "do X → verify: [done criteria]"
      │    No verify = step doesn't go in the plan
      │
      ├─ issue
      │    Create GitHub Issue → branch from origin/main
      │    Rule: 1 Issue = 1 Branch = 1 PR
      │    No chain branches. No multi-issue branches.
      │
      ├─ execute ←─────────────────────────┐
      │    Karpathy checkpoints at stage entry       │
      │    step → verify → commit → next step       │
      │                                              │
      ├─ debug  ──────────────────────────  ┘
      │    Diagnose before touching code
      │    Never retry the same failing approach twice
      │
      ├─ analyze
      │    Intent check: Issue requirements ↔ git diff
      │    coverage gap · scope creep · contradiction
      │
      ├─ verify
      │    Integration check before submitting
      │    git status · changed files · test suite
      │
      ├─ submit
      │    push → PR with "Closes #N" in body
      │    Stops here. User reviews the PR.
      │
      ├─ review
      │    Receive review feedback → back to execute
      │
      └─ finish
           Merge + delete branch + pull main
           The work is truly done.

---

Skills