agentleFS
jblosseyjblossey/houserules/.claude/skills/finishing-a-feature/SKILL.md

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

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
  1. Very specific:

    Write the output of every houserules command to a file in the batch workspace, a folder of the workspaces location (default …

    line 18
  2. Distinctive:

    Do not start this procedure on a branch that is not yet green — fix tests and lint first.

    line 29
  3. Very specific:

    Verify the branch is green: Run the project's full test and lint gates, including houserules check-knowledge and houserules check-backlog.

    line 34
  4. Very specific:

    Update the backlog: Run houserules set <id> status=done batch=<n> for every delivered item.

    line 37
  5. Very specific:

    If a rebase drops a commit that origin/main already holds, the lists differ in length: pair the rest by subject.

    line 86
  6. Very specific:

    Run the final gate set once at the head, each gate through houserules capture.

    line 113
  7. Very specific:

    When the request template of the project holds other sections, add them to the file first.

    line 138
  8. Distinctive:

    All checks must pass before continuing.

    line 152
  9. Very specific:

    Read the drift line the command prints, kit <old> -> <new>.

    line 178

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-knowledge and houserules check-backlog included).
  • 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

  1. Verify the branch is green. Run the project's full test and lint gates, including houserules check-knowledge and houserules check-backlog.
  2. Update the backlog. Run houserules set <id> status=done batch=<n> for every delivered item. Set the status state of the batch record to done, and run houserules check-backlog. The record lives in the tracker: on the JSON tracker, edit its entry in backlog/batches.json; on the GitHub tracker, edit the status in the houserules block of the issue labelled houserules:batch and close it; on the Beads tracker, do the same on the issue of the custom type houserules-batch. The orchestrating skill gives the layout. Commit the files that this update changed.
  3. 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 archive does 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-backlog
    archive moves every knowledge entry the ruling above just retired into knowledge/archive/ and, on the JSON tracker, every done item and batch into backlog/archive/; the GitHub and Beads trackers keep closed items in place. Running it is safe even when nothing qualifies yet. render regenerates the houserules blocks of the AGENTS.md files and, in an install with the Claude renderer, .claude/rules/*.md and the project-knowledge skill: a sweep that moves a rendered (standing or area-file) knowledge entry leaves those generated files stale, and check-knowledge fails on that drift if you skip this step. If either check still fails after render, 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.
  4. Aggregate commits. Fetch first: git fetch origin main. If git merge-base --is-ancestor origin/main HEAD fails, main moved: rebuild the branch on origin/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 the orchestrating skill):
    git 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.txt
    If a rebase drops a commit that origin/main already holds, the lists differ in length: pair the rest by subject. When interactive rebase is unavailable, aggregate with a soft reset instead:
    git reset --soft $(git merge-base origin/main HEAD)
    Then build 1-5 clean, logical Conventional Commits from the staged result (git restore --staged . and re-stage per logical group as needed). Write one Work-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.

  1. 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 with houserules 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.
    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>
    Open the request with the CLI of the host, and give it the bundle as its description. On GitHub:
    gh pr create --title "<title>" --body-file <workspace>/bundle.md
    On GitLab:
    glab mr create --title "<title>" --description-file <workspace>/bundle.md
    When the request template of the project holds other sections, add them to the file first. A project that runs houserules bundle check in its CI fails a request without a bundle. To see the same lines before you open the request, run houserules bundle check --body <workspace>/bundle.md --base <merge base> --head HEAD.
  2. Wait for CI. On GitHub:
    gh pr checks --watch
    On GitLab:
    glab ci status --live
    All checks must pass before continuing.
  3. Merge from the CLI, per the project's own discipline. The default here is fast-forward-only, never a UI merge button:
    git switch main && git pull --ff-only
    git merge --ff-only <branch>
    git push origin main
    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.
  4. 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.json records the houserules version this project runs. That stamp goes stale when the version changes: a release does this in the kit repository itself; a newer houserules binary on PATH does 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.
    houserules update --dir .
    Read the drift line the command prints, 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
  5. Delete the branch.
    git push origin --delete <branch>
    git branch -d <branch>

Common Mistakes

  • Main moved since branching. git merge --ff-only will fail. Run git fetch origin main, rebuild the branch with git 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: and Deferred: 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.