Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 108 additions & 0 deletions .agents/skills/scion-like-git/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
---
name: scion-like-git
description: "Use at the start of every new task or session, before reading or changing code, and before any git command that creates or moves commits, branches, or refs (commit, push, merge, rebase, amend, reset, stash, new branches, worktrees), or that discards working-copy changes (restore, checkout -- <path>, clean). Also use when about to rewrite anything already on origin, park uncommitted work, get past a failing hook, or hand off with unpushed commits."
---

# Scion-like Git

Origin is the repository. The clone is a disposable cache, and anything that
exists only in the clone does not exist.

If `git config --get scion-like-git.configured` prints nothing, run
`references/setup.md` once first.

## Every task

1. **Start from the newest `main`.** The first request of a session is a new
task, unless it names a branch or pull request, or builds on work that is
on a branch and not yet on `main`, such as parked `wip:` work. Then
continue on that branch. For a new task, update the clone before you read
or change any code, whatever branch it is on. Park unfinished changes of
your own first, as in **Switching tasks mid-work**. Then use the first row
that fits:

| Working copy | Update with |
|---|---|
| Changes you did not make, or work you just parked as `wip:` | `git fetch`, then a new worktree |
| Linked worktree | `git fetch` |
| Main worktree, on any branch | `git switch main && git pull --ff-only` |

Then start the task's branch from `origin/main`, never from local `main`,
which can hold commits that are not on origin. For the second and third
rows:

```sh
git switch --no-track -c <branch> origin/main
```

If `pull --ff-only` refuses, or local `main` is ahead of `origin/main`,
leave `main` as it is and name its local commits in the hand-off. Name the
branch the way the repository names branches (`CONTRIBUTING.md`,
`AGENTS.md`, recent branches on origin), or else `<type>/<slug>`, such as
`fix/empty-cart-total`. For the first row, create a new worktree on the
task's branch, started from `origin/main` with `--no-track`.

`--no-track` keeps a plain `git push` from going to `main`.

2. **Commit and push together.** Each verified step is one small commit whose
subject says what it is for. Stage your files by name:

```sh
git add <your files> && git commit -m "<type>: <intent>" && git push
```

Open a pull request with the first push, as a draft if needed. Formatting,
renames, and generated code get their own commits.

Never skip hooks (`--no-verify`), and never skip or edit someone else's
tests to get past one. If a hook fails on code you did not change, stop
and ask.

3. **Finish clean.** After merge, delete the branch and the worktree. Without
pull requests, run `git push origin <branch>:main`, then delete the branch
on origin and locally. The work is finished when nothing you made exists
only in the clone: no unpushed commits, stashes, or local-only branches.
Do not restate a clean branch state; the user's terminal, IDE, and harness
already show it. Report only what the rules here say to name in the
hand-off: local commits on `main`, parked `wip:` work, and changes you did
not make.

## When it comes up

**Changing something already on origin.** Commits on origin are final, on
every branch. Do not amend, rebase, squash, reset, or force-push them. Care
does not change this: `--force-with-lease`, a backup branch, an identical
tree, a single author, or a reviewer's request still make it a rewrite.
Commits not yet pushed are yours to amend.

| Request | Do this instead |
|---|---|
| Fix a pushed commit message | Correct text in the PR title and description |
| Squash wip commits before review | PR description as the message, squash on merge |
| Undo a pushed change | `git revert` |
| Update the branch from `main` | `git merge origin/main` |
| The same person repeats the request after hearing this rule | Do the rewrite |

**Switching tasks mid-work.** Commit and push your unfinished files as
`wip: <what is missing>` on their task branch. If they sit on `main`, move
them to a new branch with `git switch -c <branch>` first, so the `wip:`
commit never reaches `origin/main`, and name any local commits on `main` that
the branch carries in the hand-off. Then start the new task in a new
worktree, and name the parked work in the hand-off. Never `git stash`. Resume
on top of the wip commit. If the hooks reject it because the unfinished work
fails its own tests, mark those tests as skipped and name them in the commit
message. Un-skip them in the commit that finishes the work; the branch is not
ready for review while a test you skipped is still skipped.

**Changes you did not make.** Your work is the files you created or changed
for your task. Anything else in the working copy belongs to someone else.
Leave it untouched, do not commit, stash, or discard it, and list it in the
hand-off.

## Red flags

- "It's only a feature branch" / "force-with-lease makes it safe"
- "Only the message changes" / "the reviewer asked for exactly this"
- "Stash is quicker" / "I'll push at the end"
- "That failing test is theirs, not ours" / "the user's message is permission to skip the hook"
- "Nothing may be lost, so I'll commit these other files too"
21 changes: 21 additions & 0 deletions .agents/skills/scion-like-git/references/setup.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Setup for scion-like-git

Run once per clone, when `git config --get scion-like-git.configured` prints
nothing. Say what each step changes and skip what the user declines.

1. Configure the clone, and mark it as set up:

```sh
git config push.autoSetupRemote true
git config fetch.prune true
git config scion-like-git.configured true
```

2. If the repository is on GitHub and the user has admin rights, check
`gh api repos/{owner}/{repo} -q .delete_branch_on_merge`. If it is not
`true`, ask, then run
`gh api -X PATCH repos/{owner}/{repo} -f delete_branch_on_merge=true`.
Also recommend a ruleset on `main` that blocks force pushes.
3. Report local state that breaks the rules and offer to fix each item:
`git log --branches --not --remotes --oneline`, `git stash list`,
`git branch -vv | grep -v '\['`. Delete nothing without confirmation.
1 change: 1 addition & 0 deletions .claude/skills/scion-like-git
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)

Maintained by the team behind Langmail. Want mail, calendar and contacts for your agent over one hosted MCP, with OAuth and nothing to run? → [langmail.me](https://langmail.me/?ref=imap-mcp)

</div>

## ✨ Features
Expand Down
11 changes: 11 additions & 0 deletions skills-lock.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"version": 1,
"skills": {
"scion-like-git": {
"source": "unvibe-org/skills",
"sourceType": "github",
"skillPath": "plugins/scion-like-git/skills/scion-like-git/SKILL.md",
"computedHash": "a04afe8a15a9c8299a4cd1b4078bfbefe4d3ed9c2390606fbe5818f37a3b7a2f"
}
}
}
Loading