# gentle-ai-branch-pr

Adopt this skill: https://proskills.md/skills/other/gentleman-programming-gentle-ai-skills-branch-pr

Page: https://proskills.md/skills/other/gentleman-programming-gentle-ai-skills-branch-pr
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/branch-pr/SKILL.md
size: 8047
upstream: https://github.com/gentleman-programming/gentle-ai/blob/main/skills/branch-pr/SKILL.md

````text
---
name: gentle-ai-branch-pr
description: "Create Gentle AI pull requests with issue-first checks. Trigger: creating, opening, or preparing PRs for review."
license: Apache-2.0
metadata:
  author: gentleman-programming
  version: "2.0"
---

# Gentle AI — Branch & PR Skill

## When to Use

Load this skill whenever you need to:
- Create a branch for a new fix or feature
- Open a pull request on [Gentleman-Programming/gentle-ai](https://github.com/Gentleman-Programming/gentle-ai)
- Prepare changes for review

## Critical Rules

1. **Every PR MUST visibly link an approved base-repository issue** — `Closes/Fixes/Resolves #<N>` closes it on merge; `Refs #<N>` is non-closing. Every accepted reference MUST have `status:approved`; malformed, cross-repository, or mixed closing/non-closing references for the same issue are rejected by CI.
2. **Ordinary `type:*` categorization** — CI rejects zero or multiple type labels. Route it through the canonical issue-creation workflow contract: a current direct human instruction binds the exact target/action, target-host capability is verified, and it uses one bounded mutation and target-host readback; otherwise wait without mutation.
3. **Protected policy labels** — Adding or removing `status:approved` or `size:exception` requires authenticated actor target-host `viewerPermission` `MAINTAIN` or `ADMIN` and a current direct human instruction binding the exact target/action. Here verified policy authority means that actor permission and exact direct instruction, not separate target-host proof of the instruction-giver's identity; do not mutate automatically. `size:exception` additionally requires documented over-budget rationale and a human-selected exception.
4. **400-line review budget** — keep PRs within 400 changed lines (`additions + deletions`) or document the rationale required for a `size:exception` label.
5. **REQUIRED checks must pass** — establish requiredness from the target branch rulesets/branch protection and current run status; see Automated Checks below.
6. **No `Co-Authored-By` trailers** — never add AI attribution to commits.
7. **No force-push to main/master** — protected branch.

## Workflow

Before any target-host read, obtain explicit authorization for the remote destination (exact target), operation (including metadata/status reads), and credential/session. Do not probe ambient credentials. After authorization reuse fresh target-bound approved-issue, default branch, `type:*` label and check evidence rather than re-asking verified facts. Missing or stale evidence remains unknown.

1. Confirm the base-repository issue has `status:approved` on the authorized target. Resolve its current default/base branch from target metadata; do not assume `main`.
2. Ask the human whether the PR should close the issue on merge. Preserve the human-selected `Closes/Fixes/Resolves #N` closing intent or `Refs #N` non-closing intent; do not substitute one for the other.
3. Implement authorized work and run applicable local checks. Do not auto commit, push, create a PR, merge, select a chain strategy or exception, or give native RDD consent. Each operation needs its own human authority.
4. Draft against the template. Declare one `type:*` result; any label mutation follows the canonical issue-creation workflow contract and exact direct instruction. Mark checkboxes only after observed readback.
5. Determine REQUIRED CI from current target branch rulesets/branch protection and current run status before calling a PR merge-ready. CodeRabbit is optional unless target policy makes it required; a pending optional run is not a blocker. Unknown requiredness is not merge-ready.

For baseline attribution compare the same failing command/environment on a comparable isolated clean base, without disturbing user changes. If not compared, report baseline unverified; do not use stash/pop.

---

## Branch Naming

Branch names **must** match this pattern:

```
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
```

| Type | Example |
|------|---------|
| `feat/` | `feat/user-login` |
| `fix/` | `fix/duplicate-observation-insert` |
| `docs/` | `docs/api-reference-update` |
| `refactor/` | `refactor/extract-query-sanitizer` |
| `chore/` | `chore/bump-bubbletea-v0.26` |
| `style/` | `style/fix-linter-warnings` |
| `perf/` | `perf/optimize-catalog-loading` |
| `test/` | `test/add-pipeline-coverage` |
| `build/` | `build/update-goreleaser-config` |
| `ci/` | `ci/add-e2e-docker-job` |
| `revert/` | `revert/undo-model-picker-change` |

**Rules:**
- All lowercase
- Use hyphens, dots, or underscores as separators (no spaces, no uppercase)
- Description must be short and descriptive

---

## PR Body Format

Use the current `.github/PULL_REQUEST_TEMPLATE.md` as authority. The following is a non-executable schematic, not a complete PR body or a publication command. Include all sections required by the actual template (including Automated Checks and Notes for Reviewers when present). Fill only observed facts, leave unverified boxes unchecked and record pending actions separately.

```markdown
## 🔗 Linked Issue

<human-selected Closes/Fixes/Resolves #N or Refs #N> (closing vs non-closing intent must be asked, not inferred)

## 🏷️ PR Type

- [ ] `type:bug` — Bug fix (non-breaking change that fixes an issue)
- [ ] `type:feature` — New feature (non-breaking change that adds functionality)
- [ ] `type:docs` — Documentation only
- [ ] `type:refactor` — Code refactoring (no functional changes)
- [ ] `type:chore` — Build, CI, or tooling changes
- [ ] `type:breaking-change` — Breaking change

## 📝 Summary

<!-- Clear description of what this PR does and why. -->

## 📂 Changes

| File / Area | What Changed |
|-------------|-------------|
| `path/to/file` | Brief description |

## 🧪 Test Plan

<!-- Replace examples below with commands actually run and their observed outcomes. -->

**Unit Tests**
\`\`\`bash
go test ./...
\`\`\`

**Go Format**
\`\`\`bash
go run ./internal/gofmtcheck
\`\`\`

**E2E Tests** (Docker required)
\`\`\`bash
cd e2e && ./docker-test.sh
\`\`\`

- [ ] Unit tests pass (`go test ./...`)
- [ ] Go format passes (`go run ./internal/gofmtcheck`)
- [ ] E2E tests pass (`cd e2e && ./docker-test.sh`)
- [ ] Manually tested locally

## ✅ Contributor Checklist

- [ ] PR is linked to an issue with `status:approved`
- [ ] PR stays within 400 changed lines, or the human-selected `size:exception` rationale, current direct human instruction for the exact target/action and actor `MAINTAIN`/`ADMIN` are documented
- [ ] API read-back confirms exactly one appropriate `type:*` label on this PR
- [ ] Unit tests pass (`go test ./...`)
- [ ] E2E tests pass (`cd e2e && ./docker-test.sh`)
- [ ] I have updated documentation if necessary
- [ ] My commits follow Conventional Commits format
- [ ] My commits do not include `Co-Authored-By` trailers

## Automated Checks

<!-- Record current target-required checks and observed statuses only. -->

## Notes for Reviewers

<!-- Describe dependencies or pending actions where applicable. -->
```

---

## Automated Checks

These workflows may run on a PR. Establish which are REQUIRED from current target branch rulesets/branch protection and run status before asserting merge readiness. CodeRabbit is optional unless required by target policy; unknown requiredness blocks a merge-ready claim:

| Check | What It Verifies | How to Fix |
|-------|-----------------|------------|
| **Check PR Cognitive Load** | PR stays within 400 changed lines (`additions + deletions`) or has `size:exception` | Split the PR, or document the human-selected `size:exception` rationale and verify actor `MAINTAIN`/`ADMIN` plus a current direct human instruction for the exact target/action before its canonical workflow action |
| **Check Issue Reference** | PR body contains a visible, well-formed base-repository `Closes/Fixes/Resolves #N` or `Refs #N` | Add one valid reference; malformed, cross-repository, and mixed closing/non-closing re
````

## File: README.md
upstream: https://github.com/gentleman-programming/gentle-ai/blob/main/README.md

```text
<!-- markdownlint-disable-next-line MD041 -->
<a id="top"></a>

<div align="center">

<img width="100%" alt="Gentle-AI neon rose banner: the rose blooms in, the GENTLE-AI wordmark is written on, and the tagline Ecosystem, Framework, Workflows appears" src="docs/assets/brand/gentle-ai-banner.gif" />

<h1>Gentle-AI™</h1>

<p><strong>The deterministic engineering environment for the AI agent you already use.</strong></p>

<p>
<a href="https://github.com/Gentleman-Programming/gentle-ai/releases"><img src="https://img.shields.io/github/v/release/Gentleman-Programming/gentle-ai?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="Release"></a>
<a href="https://github.com/Gentleman-Programming/gentle-ai/stargazers"><img src="https://img.shields.io/github/stars/Gentleman-Programming/gentle-ai?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="Stars"></a>
<img src="https://img.shields.io/badge/agents-18-F095C8?style=for-the-badge&labelColor=1A1218" alt="18 agents">
<img src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="Platform">
<a href="LICENSE"><img src="https://img.shields.io/badge/MIT-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="License: MIT"></a>
</p>

<p>
<a href="https://trendshift.io/repositories/24855?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-24855" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/24855" alt="Gentleman-Programming%2Fgentle-ai | Trendshift" width="250" height="55"/></a>
<a href="https://trendshift.io/repositories/24855?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-24855" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/24855/weekly?language=Go" alt="Gentleman-Programming%2Fgentle-ai | Trendshift" width="250" height="55"/></a>
<a href="https://trendshift.io/repositories/24855?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-24855" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/24855/monthly?language=Go" alt="Gentleman-Programming%2Fgentle-ai | Trendshift" width="250" height="55"/></a>
</p>

<p>
<a href="https://gentlemanprogramming.com/"><strong>Website</strong></a> &bull;
<a href="docs/quickstart.md"><strong>Quickstart</strong></a> &bull;
<a href="docs/intended-usage.md"><strong>Docs</strong></a> &bull;
<a href="https://gentle-ai-wiki.gentlemanprogramming.com/"><strong>Wiki</strong></a>
</p>

<br/>

<p>
Your agent writes code, then forgets everything. It has no opinion about your project,
and no way to prove what it did beyond asking you to read every line.
<strong>Gentle-AI gives it memory, a workflow, and evidence.</strong>
</p>

<p>
 <h3>See it in action</h3>

   <p>
   One prompt, from idea to reviewed commit: memory, workflow, and evidence in a real session.
   </p>

https://github.com/user-attachments/assets/fa5c0cfe-06e7-4c0d-bd6e-8ac7cb934339

   <p>Prefer Spanish subtitles?</p>
   

https://github.com/user-attachments/assets/6d2bc422-a4dd-4ecf-a04b-fcd3bea7fea9

</p>

<br/>

<!--
  HERO SLOT — the only animation on this page. Features is all still: four
  diagrams for the concepts, two captures as proof the thing runs. Motion is
  spent once, here, right after the pitch lands.

  Uncomment when docs/assets/features/hero-pi.gif exists. It is a real-time capture
  of the complete Pi startup: banner, extensions, skills and startup output, never
  trimmed. A stripped startup does not look like the real thing.

<img width="100%" src="docs/assets/features/hero-pi.gif" alt="Gentle-AI starting up inside Pi" />

<br/>
-->

<sub><strong>If Gentle-AI made your agent worth trusting, a star helps other people find it.</strong></sub>

<!--
  sealed_token is a GitHub fine-grained token encrypted against Star History's
  public key, so only the encrypted value is published here. It is required
  because GitHub restricted the stargazers API to a repository's admins and
  collaborators on 2026-06-30; without it the chart renders an error placeholder.
  Regenerate it at https://www.star-history.com/?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left
-->

<a href="https://www.star-history.com/?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fgentle-ai&type=date&theme=dark&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
    <img width="620" alt="Star History Chart" src="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
  </picture>
</a>

<br/>

<sub><strong>WORKS WITH THE AGENT YOU ALREADY HAVE</strong></sub>

<strong><a href="docs/agents.md#pi">Pi</a></strong> ·
<strong><a href="docs/agents.md#opencode">OpenCode</a></strong> ·
<strong><a href="docs/agents.md#claude-code">Claude Code</a></strong> ·
<strong><a href="docs/agents.md#codex">Codex</a></strong> ·
<strong><a href="docs/agents.md#cursor">Cursor</a></strong> ·
<strong><a href="docs/agents.md#vs-code-copilot">VS Code Copilot</a></strong> ·
<strong><a href="docs/agents.md#gemini-cli">Gemini CLI</a></strong> ·
<strong><a href="docs/agents.md#kilo-code">Kilo Code</a></strong><br/>
<strong><a href="docs/agents.md#kimi-code">Kimi Code</a></strong> ·
<strong><a href="docs/agents.md#kiro-ide">Kiro IDE</a></strong> ·
<strong><a href="docs/agents.md#qwen-code">Qwen Code</a></strong> ·
<strong><a href="docs/agents.md#hermes">Hermes</a></strong> ·
<strong><a href="docs/agents.md#antigravity">Antigravity</a></strong> ·
<strong><a href="docs/agents.md#windsurf">Windsurf</a></strong> ·
<strong><a href="docs/agents.md#openclaw">OpenClaw</a></strong> ·
<strong><a href="docs/agents.md#trae">Trae</a></strong> ·
<strong><a href="docs/agents.md#conductor">Conductor</a></strong>

<sub>17 integrations · native configuration · <a href="docs/agents.md">compare capabilities →</a></sub>

</div>

<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>

## Support the project

<div align="center">

<a href="https://github.com/sponsors/Gentleman-Programming"><img width="100%" src="docs/assets/brand/sponsor-banner.svg" alt="Free forever, independent by choice. No investors, no paywalls: Gentle AI, Engram and Gentle Shell are funded by the people who use them. Sponsor on GitHub, monthly or one-time."></a>

<p>
We deliberately don't depend on investors: no outside agenda deciding the roadmap and no features locked behind paywalls.<br/>
Donations through <a href="https://github.com/sponsors/Gentleman-Programming"><strong>GitHub Sponsors</strong></a> go straight into maintenance, new features and keeping everything free and ours.
</p>

<p>Can't donate? A ⭐, a bug report or a pull request helps too.</p>

<sub>Sponsorship never buys rankings, default selections or endorsements; see <a href="TRADEMARKS.md">TRADEMARKS.md</a>.</sub>

</div>

<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>

## Features

---

### Engram™ — Keep your project context
```
