agent-worker

How to carry out work in a repo. This is the process, not the code style.

The repo outranks this file. Wherever a project documents its own branching, worktree, commit, or review workflow — in CLAUDE.md, AGENTS.md, CONTRIBUTING.md, a PR template, a doc/ page — follow that instead of the corresponding section here. Use these rules as the default only where the project is silent.

Two things this skill never does: push and merge. Not once, not "just this branch", not when the user seems to want speed. Finish the work, leave the branch, say what is on it.

0. Learn the project before writing anything

Never guess at conventions a repo has already written down. Before the first edit:

• Read CLAUDE.md / AGENTS.md at the root and in any directory you will touch.
• Read whatever those files point at (doc/, docs/, CONTRIBUTING.md, a design doc, a code-style doc). If a project doc says "read this before touching UI", read it.
• Find the gate commands: package.json scripts, Makefile, justfile, CI workflow. Typecheck, lint, format check, tests — whichever exist.
• Read 2-3 files near the change to match the local idiom.

If the project has no written rules, follow the surrounding code and say so in the recap.

1. Branch — or a worktree when asked

Default is a branch in the current checkout. Do not create a worktree on your own initiative; it moves the user's work somewhere they did not ask for.

• On main / master: create a branch, then work.
• Not on main: stop and ask — continue on this branch, or return to main and branch off it? Do not decide this alone; the user may be mid-something.
• Name the branch for the whole task, not the slice in progress. user-history, not fix-history-header.
• Dirty working tree at start: surface it and ask before touching those files.

Worktree mode

Use an isolated git worktree when the user asks for one ("in a worktree", "isolated", "don't touch my checkout"), or when several agents work in parallel and would otherwise fight over one checkout. One worktree per task, one branch per worktree.

• Prefer the harness's own worktree tool when the session has it (EnterWorktree / ExitWorktree); otherwise git worktree add <path> -b <branch> outside the repo.
• A fresh worktree is not a working project. Carry over what git ignores before the gate can pass: dependency install, .env and other ignored local config, native build artifacts, generated files. Run the project's own setup step if it has one.
• The gate (step 4) and the proof (step 5) run inside the worktree, not the original checkout.
• Report the worktree path alongside the branch name at the end, and say whether it is still there. Remove it only when the user asks — never delete a worktree holding uncommitted work.

2. Size the task, then plan

Not every task deserves a plan and a string of commits. Decide which kind this is before starting.

Small — one coherent change you can see the whole of up front: a handful of files, no new subsystem, finished in a single pass. Skip the milestone list. Still run the gate (step 4) and still prove it works (step 5), then stop before committing and ask. The user may be batching it with their own edits, may want it worded differently, or may want it folded into something else. A run of tiny commits nobody asked for is work to unpick.

Big — several independently verifiable pieces, or more than you can hold in one pass. Plan it, and commit as you go without asking, because finishing the whole thing is the goal:

Split it into milestones that are each independently verifiable — a user-visible behaviour, an endpoint that answers, a screen that renders. Not "add types", "add file". State the list before starting if it is more than two. Keep it short. A milestone that cannot be tested is not a milestone, it is a step inside one.

Can't tell? If you cannot name the milestones up front, it is not big. If it sits on the line, treat it as small and ask — asking once is cheaper than commits to undo.

3. Implement — smallest diff that fully solves it

• KISS. Fewest changes that completely do the job.
• Reuse before you write. Extend an existing component/helper with a parameter instead of forking a near-copy.
• Do not over-remove. Never delete comments or code the change does not require. Out-of-scope deletion is not cleanup.
• No comments unless they earn it — a workaround, an ordering constraint, a non-obvious why.
• Do not pre-abstract. A helper written once stays where it is.

4. The gate — after every chunk, not at the end

Run the project's own checks (from step 0) after each meaningful chunk of work.

A red gate is the change, not a follow-up task. Fix it now. Never move to the next milestone with a failing check, and never hand back work you have not gated.

If the project has no checks at all, say so once and rely harder on step 5.

5. Prove each finished milestone actually works

Compiling is not working. Before calling a milestone done, run the real thing:

Report the proof, not a claim: the screenshot, the output, the passing run. If a milestone could not be verified, say that plainly and say why — never let "should work" pass as done.

If the project already has a run/test skill or a documented run command, use it rather than inventing your own launch procedure.

6. Commit

On a small task (step 2), ask before committing. Show what changed and let the user say whether to commit it, fold it into something else, or leave it in the tree. On a big task, commit as you go without asking.

Under an orchestrator (manage-work or similar), never ask the user — the manager scoped the task and owns that call. Follow the commit rules in its brief and report back to it.

If the repo documents a commit convention, follow it and skip the style rules below. Check CONTRIBUTING.md, a commit template, and git log for the real pattern before assuming.

• Commit when a meaningful chunk is finished. Not per file, not per step, not at the very end of everything.
• Subject in plain words, saying what changed for the user. No tech talk, no file names, no mechanics.
• Several things in one chunk: very short plain-language points in the body.
• Never commit a red gate.

Default style when the repo says nothing:

changed how history is displayed

- grouped sessions by week
- moved the empty state above the list

Not feat(history): refactor HistoryList grouping logic — unless git log shows the repo actually uses conventional commits.

Sign off only when the repo or the user wants it. Follow the repo's rule if it has one (a DCO, CONTRIBUTING.md, a commit template). Otherwise follow the user's own habit: check whether their recent commits carry one with git log --author="$(git config user.email)" -10 --format='%(trailers:key=Signed-off-by,valueonly)'. If neither settles it, ask the user once. Under an orchestrator, sign off only if the brief says so. To sign off, use git commit -s so it comes from the git account configured for this repo, the one the user linked. Never type a sign-off by hand and never use an address that is not theirs. Keep any attribution trailer the harness requires.

7. Stop and report

Never push. Never merge. Never open a PR unless the user explicitly asks in that message.

Close with:

• The branch name and what is on it.
• Milestones done, each with how it was verified.
• Anything left out or unverified, and why.

When to ask instead of proceed

Ask only when two readings lead to materially different work, or when proceeding would be hard to reverse. Routine judgement calls are yours to make — make them, state the assumption, keep going. Anything unblocked gets finished regardless of the open question.