An issue-first GitHub workflow for AI coding agents.
Every change traced from issue to branch to commits to pull request, and you always merge.
Explore the skill · Documentation · Usage guide · Contribute · Get help · Security
Agents change code faster than anyone can trace it
Ask a coding agent to "fix the login bug" and you often get a pile of edits on whatever branch was checked out. There is no issue saying what was wrong, no criteria for done, and commit messages nobody will search. If you say "merge it", it might. Ask it to "also add dark mode" halfway through, and the bug fix and the feature end up in one unrevertable PR.
cutwater is an Agent Skill that gives the agent a professional, GitHub-native workflow, through the gh CLI and git:
Phase 0 audits the repository and sets up whatever is missing, with your approval. Then every task runs issue → branch → Conventional Commits → pull request. Scope changes are classified and recorded on the issue. The agent never merges.
The name: a ship's cutwater is the forward edge of the bow, the part that goes first. This skill always goes first with setup, then keeps every change on a clear line.
⚙️ What it brings to your agent
| Capability | What it means in practice |
|---|
| Repository setup that is idempotent | Audits 16 items (README, LICENSE, CONTRIBUTING, Contributor Covenant 3.0, SECURITY, issue forms, PR template, CODEOWNERS, CI, Dependabot, ignore files, labels, ruleset, manifest). A one-round interview, a plan you approve, and a second run that changes nothing. |
| Never overwrites blindly | Existing files get a unified diff and a per-file yes. A file edited after planning is refused (compare-and-set). |
| Issue-first traceability | Structured issue bodies, <login>/<type>/<n>-<slug> branches, linted Conventional Commits referencing #n, and PRs with Closes #n, testing evidence and a mandatory Not verified section. |
| Interruption discipline | "Also handle the empty state" → edit the issue and log it. "Add dark mode" → a new issue and branch. Each decision is stated in one line. |
| Safety by construction | Merging is forbidden; destructive actions are gated; issue, PR and CI-log text is read only through a fenced reader that withholds non-collaborators' text by default and flags injection attempts; every call is pinned to one repository; outgoing bodies are secret-scanned. |
| Deterministic helper | A zero-dependency Node.js 18+ CLI does the fragile work, with --json, --dry-run, typed errors and stable exit codes. The agent runs it, never reads it. |
| Portable | Spec-only frontmatter works in Claude Code, Codex, Antigravity and other Agent Skills clients, with agents/openai.yaml for Codex. |
🧩 How it works
flowchart TD
A[Invocation] --> B[Preflight: git, gh auth, login, repo]
B --> C{Audit A1–A16}
C -- fully set up --> D[✅ Setup is complete → upgrades or a task?]
C -- partial / not set up --> E[One-round interview] --> F[Plan: diffs for every existing file]
F --> G[Apply what you approved → manifest] --> H[Commit: direct on empty repo, else setup PR]
D --> I[Task]
H --> I
I --> J[1 Issue] --> K[2 Branch] --> L[3 Linted commits]
L --> M{4 Scope change?}
M -- clarification --> N[Comment]
M -- same goal --> O[Edit issue + log]
M -- new goal --> P[New issue + branch]
N --> L
O --> L
L --> Q[5 PR: Closes #n, evidence, Not verified]
Q --> R[You review and merge]
📥 Get started
The skill lives in skills/cutwater/. Keep that folder intact. You need git, an authenticated gh, and Node.js 18+.
Claude Code: plugin
/plugin marketplace add YourAKShaw/CutWater
/plugin install cutwater@cutwater
Claude Code, Codex, Antigravity: copy the folder
git clone https://github.com/YourAKShaw/CutWater.git
cp -R CutWater/skills/cutwater ~/.claude/skills/ # Claude Code
cp -R CutWater/skills/cutwater ~/.agents/skills/ # Codex
cp -R CutWater/skills/cutwater ~/.gemini/antigravity/skills/ # Antigravity
Project-level paths, the Claude app ZIP upload, explicit-only invocation and troubleshooting are in the usage guide.
Check it
node ~/.claude/skills/cutwater/scripts/cutwater.mjs preflight
💬 Put it to work
/cutwater set up this repo
Start a task to add rate limiting to the public API.
Actually, make it OAuth instead of passwords.
What's the status of my open PRs and branches?
Update the wiki with an architecture page.
Looks good, merge it for me. (It will give you the command instead.)
This is the beginning of the README. Read the rest at the original. Read the full README ↗
