finishing-a-feature
Skill2 starsChanged 22 days agoMITView on GitHub
Use when a feature branch is complete, tests and lint are green, and the branch is ready to merge to main. Merges are fast-forward-only via CLI and commits carry no co-author lines by default, unless the project has ruled its own merge and attribution discipline.
- Deletes or force-pushes
- Commits and pushes
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- template/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- template/CLAUDE.mdCLAUDE.md
- designingSkill
- houserules-stepSkill
- migrating-knowledgeSkill
- orchestratingSkill
- planningSkill
- project-knowledgeSkill
- readme-reworkSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 18
Write the output of every houserules command to a file in the batch workspace, a folder of the workspaces location (default …
- Distinctive: line 29
Do not start this procedure on a branch that is not yet green — fix tests and lint first.
- Very specific: line 34
Verify the branch is green: Run the project's full test and lint gates, including houserules check-knowledge and houserules check-backlog.
- Very specific: line 37
Update the backlog: Run houserules set <id> status=done batch=<n> for every delivered item.
- Very specific: line 86
If a rebase drops a commit that origin/main already holds, the lists differ in length: pair the rest by subject.
- Very specific: line 113
Run the final gate set once at the head, each gate through houserules capture.
- Very specific: line 138
When the request template of the project holds other sections, add them to the file first.
- Distinctive: line 152
All checks must pass before continuing.
- Very specific: line 178
Read the drift line the command prints, kit <old> -> <new>.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Finishing a Feature
Overview
This procedure produces clean aggregated commits and merges them from the
CLI. It ships with two defaults a project may override by ruling its own
discipline instead (elicited by the migrating-knowledge skill's "Elicit
your own operating discipline" step, recorded as its own knowledge entry):
fast-forward-only (ff-only) merges, and no co-author lines. When
interactive rebase is not available, commit aggregation uses git reset
--soft instead.
Write the output of every houserules command to a file in the batch
workspace, a folder of the workspaces location (default
.houserules/work/), and read the file with your file-read tool. Treat a
<< marker or a "more items" note as a lost read and read the source file.
When to Use
- The feature branch's work is done and the project's test and lint gates pass
(
houserules check-knowledgeandhouserules check-backlogincluded). - The branch needs to go from "done" to "merged into main."
Do not start this procedure on a branch that is not yet green — fix tests and lint first.
Procedure
- Verify the branch is green. Run the project's full test and lint gates,
including
houserules check-knowledgeandhouserules check-backlog. - Update the backlog. Run
houserules set <id> status=done batch=<n>for every delivered item. Set thestatusstate of the batch record todone, and runhouserules check-backlog. The record lives in the tracker: on the JSON tracker, edit its entry inbacklog/batches.json; on the GitHub tracker, edit thestatusin thehouserulesblock of the issue labelledhouserules:batchand close it; on the Beads tracker, do the same on the issue of the custom typehouserules-batch. Theorchestratingskill gives the layout. Commit the files that this update changed. - Sweep the archive. Confirm every batch entry you are about to sweep
has its acceptance ruling homed (a decision record in the tracker or the
batch's own ledger) —
houserules archivedoes not check this itself; it trusts the operator to run the sweep only after rulings land, which is why this step comes after step 2. Then, in order:houserules archive houserules render houserules check-knowledge houserules check-backlogarchivemoves every knowledge entry the ruling above just retired intoknowledge/archive/and, on the JSON tracker, every done item and batch intobacklog/archive/; the GitHub and Beads trackers keep closed items in place. Running it is safe even when nothing qualifies yet.renderregenerates the houserules blocks of theAGENTS.mdfiles and, in an install with the Claude renderer,.claude/rules/*.mdand theproject-knowledgeskill: a sweep that moves a rendered (standing or area-file) knowledge entry leaves those generated files stale, andcheck-knowledgefails on that drift if you skip this step. If either check still fails afterrender, the finding is real — fix it (or revert the sweep) before continuing; do not proceed to step 4 with a red gate. Commit the sweep and the regenerated files together, with the backlog update or in the branch that closes next — never skip the sweep itself outright. - Aggregate commits. Fetch first:
git fetch origin main. Ifgit merge-base --is-ancestor origin/main HEADfails, main moved: rebuild the branch onorigin/main, re-verify green, and only then aggregate. The rebuild keeps the old branch under a new name and writes the old-to-new sha map to its own workspace file (the sha-map rule of theorchestratingskill):
If a rebase drops a commit thatgit branch <branch>-pre-rebuild git rebase origin/main git log --reverse --format=%H origin/main..<branch>-pre-rebuild > <workspace>/old-shas.txt git log --reverse --format=%H origin/main..<branch> > <workspace>/new-shas.txt paste <workspace>/old-shas.txt <workspace>/new-shas.txt > <workspace>/sha-map.txtorigin/mainalready holds, the lists differ in length: pair the rest by subject. When interactive rebase is unavailable, aggregate with a soft reset instead:
Then build 1-5 clean, logical Conventional Commits from the staged result (git reset --soft $(git merge-base origin/main HEAD)git restore --staged .and re-stage per logical group as needed). Write oneWork-Item: <id>trailer for each item that an aggregated commit delivers, in the last paragraph of its message, one trailer per line. Never include a co-author line, in this or any commit, unless the project has ruled its own attribution convention.
4b. Sweep interim SHAs. Grep the aggregated diff for commit-SHA
citations (git diff origin/main...HEAD | grep -oE '\b[0-9a-f]{7,40}\b',
judged in context): a SHA that will not survive the aggregation
restates to a durable locator or to the aggregated commit.
4c. Check the commits. Run houserules check-commit --from <merge base>
before the merge, even when the commit-msg hook skipped it. The merge
base is the output of git merge-base origin/main HEAD. The hook skips
the check when houserules check-commit --help fails (no houserules on
PATH, or one without the check-commit subcommand), when it cannot
resolve the install root of the hook, and when the parent of the hook
directory holds no .houserules.json.
- Write the evidence bundle, push, and open the pull or merge request.
Run the final gate set once at the head, each gate through
houserules capture. Then write the bundle withhouserules bundle write. It copies the header line of each capture whole, so no header passes through a model. The bundle holds:- the intent (
--intent <source>:<ref>) or the purpose (--purpose), from the spec; - the work items of the batch, one
--work-item <id>for each; - the tier and the criterion, from the plan (
--tier,--criterion); - the captures of the final gate run at the head, one
--capture <file>for each.
Open the request with the CLI of the host, and give it the bundle as its description. On GitHub:houserules bundle write --intent file:docs/plans/<plan>.md \ --work-item <id> --tier <tier> --criterion "<criterion>" \ --capture <workspace>/<gate>.txt --out <workspace>/bundle.md git push -f -u origin <branch>
On GitLab:gh pr create --title "<title>" --body-file <workspace>/bundle.md
When the request template of the project holds other sections, add them to the file first. A project that runsglab mr create --title "<title>" --description-file <workspace>/bundle.mdhouserules bundle checkin its CI fails a request without a bundle. To see the same lines before you open the request, runhouserules bundle check --body <workspace>/bundle.md --base <merge base> --head HEAD. - the intent (
- Wait for CI. On GitHub:
On GitLab:gh pr checks --watch
All checks must pass before continuing.glab ci status --live - Merge from the CLI, per the project's own discipline. The default
here is fast-forward-only, never a UI merge button:
A project that has ruled a different merge discipline (a merge commit, a squash) follows that ruling instead. The host marks the request merged once the commits reach main.git switch main && git pull --ff-only git merge --ff-only <branch> git push origin main - After merging a release-please PR, or any merge that changes the
houserules version, restamp the kit version. Skip this step for
every other merge.
.houserules.jsonrecords the houserules version this project runs. That stamp goes stale when the version changes: a release does this in the kit repository itself; a newerhouserulesbinary onPATHdoes it elsewhere. In a project that installs the kit, install the new release first — through whichever channel you installed houserules with (the shell installer, mise, or a direct download) — otherwise the command below still runs the old binary and reads no drift.
Read the drift line the command prints,houserules update --dir .kit <old> -> <new>. Equal sides mean nothing to commit. Different sides mean the stamp changed:git add .houserules.json git commit -m "chore(release): restamp the kit version" git push - Delete the branch.
git push origin --delete <branch> git branch -d <branch>
Common Mistakes
- Main moved since branching.
git merge --ff-onlywill fail. Rungit fetch origin main, rebuild the branch withgit rebase origin/main(step 4), re-verify green, then aggregate commits as in step 4. - Force-pushing main. Force-push (
-f) is only ever for feature branches. Never force-push main. - Adding a co-author line without a ruling that allows it. The default
here is no co-author trailers, in aggregated commits or anywhere else in
this procedure; change it only by ruling the project's own attribution
convention first. The
Work-Item:andDeferred:trailers are no co-author lines. - Merging via a UI button without a ruling that allows it. The default here is always ff-only from the CLI; change it only by ruling the project's own merge discipline first.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

