YourAKShaw/CutWater

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, / / - 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
mermaid
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]