oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/.claude/skills/worktree-aware/SKILL.md
Oskar Kapala 745e52723c feat(skills): worktree-aware skill for Claude Code 
Encodes branch hygiene for CC running in task worktrees: commit only to
assigned branch, no push origin master, no touching main checkout, no
git add -A, no worktree management, mandatory final report.
2026-06-03 17:41:35 +02:00

2.9 KiB
Raw Blame History

name description
worktree-aware Use when working in a git worktree checkout for a parallel agent task. The presence of an .agent-task file in the current working directory indicates a task worktree (NOT the main checkout). Encodes branch hygiene: commit only to the assigned task branch, NEVER push origin master, NEVER touch the main checkout at ~/homelab-codex-ws, NEVER manage worktrees yourself. On task completion, report the branch name verbatim and stop — the human merges via scripts/dev/agent.sh.

When this applies

  • .agent-task present in your cwd → you are in a task worktree. Apply all rules below.
  • .agent-task absent → you are in the main checkout. Do NOT treat yourself as a task agent. In the main checkout these rules do not apply.

Reading the marker

.agent-task is a YAML file. Your assigned branch is the value of the branch: key, e.g.:

task: my-feature
branch: task/my-feature
parent_commit: abc1234
created_utc: 2026-06-03T10:00:00Z
worktree_path: /home/oskar/homelab-codex-ws-my-feature

Always read this file first before taking any action.

Rules

  1. Commit only to your branch. Before any git commit, run git status and confirm it says On branch task/<name>. If it does not, stop immediately and report the discrepancy.

  2. Push only to your branch. The only permitted push is git push origin task/<name>. NEVER git push origin master or any other branch.

  3. Do not touch the main checkout. ~/homelab-codex-ws/ is the main checkout — deploy-only, owned by the human. Do not read from, write to, or execute commands inside it.

  4. Stay scoped. Only change files directly related to your assigned task. If you notice other problems, report them in your final summary as separate follow-up proposals. Do not fix them in this worktree.

  5. Never git add -A. Always stage specific files by name: git add path/to/file.

  6. Do not manage worktrees. Never run git worktree add/remove or invoke scripts/dev/agent.sh. Worktree lifecycle is the human's responsibility.

  7. Final report before stopping. When the task is done, provide a structured report containing:

    • Files changed (path and one-line summary of change)
    • Tests run and results
    • All commit hashes on the task branch
    • Branch name verbatim (copy-paste ready)
    • Follow-up items as bulleted proposals for separate tasks

Definition of Done

  • All commits are on task/<name> (verify with git log --oneline master..task/<name>)
  • Test suite passes
  • Branch pushed: git push origin task/<name>
  • Full report delivered in conversation

What you do NOT do

  • Merge branches
  • Create or push tags
  • Run deploys or healthchecks against production nodes
  • Delete branches or worktrees
  • Modify files in other worktrees
  • Push to origin master under any circumstances