Using task branches

Skill augments-labs/sdlc-skills/skills/common/using-task-branches

Use before starting repo edits or implementation, or when work needs isolation from the current checkout, so a git worktree, harness workspace, or meaningful task branch exists according to user or project preference. Fires on start on this ticket and let's build X inside a repository, even if nobody says branch or worktree. Skip read-only work, and skip when the current branch or workspace is already dedicated to this task.From its SKILL.md

Install

npx -y skills add augments-labs/sdlc-skills --skill using-task-branches

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

7.4 KB, as published. Nobody here has run it

<EXTREMELY-IMPORTANT> NEVER START REPO EDITS ON `main`/`master`, `dev`/`develop`, A RELEASE BRANCH, OR AN UNRELATED TASK BRANCH. Create or enter a dedicated workspace — a git worktree unless the user or project says otherwise — *before* the first edit, unless the user explicitly okayed the current checkout. </EXTREMELY-IMPORTANT>

Using Task Branches

When to use

You are about to edit files, implement a feature/fix/refactor, execute a plan, or dispatch agents.
Runtime or review isolation matters: parallel agents, risky changes, separate ports, databases, fixtures, or long-running app state.
Skip for read-only investigation, when the user explicitly says to stay in the current checkout, or when the current branch/workspace is already dedicated to this task with known ownership, base, and baseline.

Procedure

Each step fills the matching section of assets/workspace-record.md. Open it now and write as you go — the fields it asks for are the ones a later step, and whatever finishes the branch, cannot re-derive from the repository alone.

Understand what you are already in

Detect the real checkout — repository root, status, branch or detached HEAD, git-dir and common-dir, registered worktrees, a submodule superproject, and any harness-native workspace metadata.

A detached or host-owned checkout may already be isolated. Until you know its owner and permitted lifecycle, do not nest inside it, attach to it, switch it, or clean it.
Classify ownership of every resource and dirty change: created by this task, or pre-existing, user-owned, shared, or host-owned. Unknown provenance counts as the latter, and blocks switching or cleanup.
Separate planning state from implementation state. Planning may stay in an approved planning or native workspace. Before the first product edit, re-run this check and bind implementation to its own branch or workspace and its own exact base. Plan approval says nothing about code isolation.

Establish the base

Prove the intended base from direct user or project guidance, and record its revision and remote freshness. Gate inputs that live outside the source tree — ignored, generated, external — belong in the record too; the revision does not capture them.

Any install or baseline command runs under the contract in references/baseline-contract.md. Read it before running anything, not after: it decides whether the command may run in the current checkout at all.

Create the workspace

Default to a git worktree, without nesting. User instruction wins, then project guidance, then an existing native workspace. Failing those, create a worktree — do not git switch -c or git checkout -b in a shared checkout: switching rewires it, so the user, a second agent, or a running app working in it is blocked or collides until you switch back. Switch branches in place only in a checkout dedicated to this task alone.
Validate the name and its collisions. Follow project naming, or use feature/{{short-task}}, fix/{{short-task}}, or docs/{{short-task}}. Validate the ref, then check local branches, remote-tracking refs, and attached worktrees. Never overwrite or silently reuse a collision.
Create only from the proven base. Keep a worktree outside scanned paths, or gitignored. A submodule needs an owned branch and an explicit plan for the parent gitlink.

Baseline it

Isolate runtime state, then run the real baseline in the chosen workspace. references/baseline-contract.md owns what "real" requires here: the pre-run inspection, the distinct runtime identities, the pre/post capture, and how each red cell is bound before work continues.

The rule that survives without the reference: a red cell you cannot attribute blocks work. So do uncontained effects.
Report the record. Hand over the completed assets/workspace-record.md — identity, inventory, external gate inputs, baseline evidence and side effects, runtime identities, and the task-owned resources that may later be cleaned up.

Pressure points

The thought	The reality
"I'll just inspect first"	For edit requests, branch/status is the first inspection.
"It's only a small change"	Small changes still land on the wrong branch. Create the branch first.
"git switch -c is lighter than a worktree"	Switching rewires the shared checkout — anyone else working in it is blocked until you switch back. A worktree is the default; switch in place only in a checkout dedicated to this task.
"The harness made a detached checkout, so I'll add my own worktree"	First determine whether the host already owns isolation and cleanup.
"I'll make the branch after the first edit"	After the edit, you may already have mixed unrelated state.

Checkpoint while you work

<EXTREMELY-IMPORTANT> COMMIT LOCALLY AS YOU GO — after each independently testable piece, not once at the end. The authority is already granted; do not ask again for each checkpoint. A checkpoint never grants push, publication, or integration authority. </EXTREMELY-IMPORTANT>

Committing is not the last step of the task. It is a step you owe after each independently testable piece, and the authority for it already exists: local task-branch commits are authorized repository edits unless higher-priority user or project policy withholds them or requires approval not yet given.

After each coherent piece a reviewer could accept or reject separately, invoke verifying-completion, run its smallest real gate, and commit locally. Do not wait for the final candidate, and do not ask again for each checkpoint.
Stop there. A checkpoint is neither reviewed nor done and grants no push, publication, or integration authority. finishing-a-branch may rewrite its history only with authority established there. Hand it the recorded workspace, base, and ownership; do not integrate, discard, delete, or clean here.

The thought	The reality
"I'll commit once it all works"	One terminal commit cannot be reviewed or reverted in pieces, and every good intermediate state is gone.
"Nothing is finished, so there is nothing to commit"	The unit is an independently testable change, not a finished feature. If a gate can accept it, it can be a checkpoint.
"I should ask before each commit"	The authority is already granted. Asking again per checkpoint spends the user's turn re-deciding what they decided.
"The gate is slow — I'll run it once at the end"	Then a red gate at the end leaves every change a suspect. The smallest gate per checkpoint is what keeps that cheap.
"It passes locally, so committing can wait"	An uncommitted passing state is one crash, wrong checkout, or overwrite away from not existing.
"A mid-task commit looks unfinished"	It claims nothing. Nothing reads a checkpoint as done until `finishing-a-branch` runs.