Compare commits
No commits in common. "3b620ef7e3436dbf5551252e7d147611e3de4e66" and "1c69a5bc299eecdd5cb0a74072447f8232c3db97" have entirely different histories.
3b620ef7e3
...
1c69a5bc29
|
|
@ -1,81 +0,0 @@
|
|||
---
|
||||
name: worktree-aware
|
||||
description: >
|
||||
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.:
|
||||
|
||||
```yaml
|
||||
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
|
||||
12
CLAUDE.md
12
CLAUDE.md
|
|
@ -180,15 +180,3 @@ Before any new or changed service is considered ready:
|
|||
- Services: kebab-case (`stability-agent`, `zigbee2mqtt`)
|
||||
- Container names must match service names
|
||||
- Always `restart: unless-stopped` unless `service.yaml` says otherwise
|
||||
|
||||
## Multi-agent worktree mode
|
||||
|
||||
`~/homelab-codex-ws` (main checkout) is **deploy-only** and belongs to the human operator.
|
||||
Parallel agent tasks run in isolated git worktrees created by `scripts/dev/agent.sh new <name>`.
|
||||
|
||||
If `.agent-task` exists in your current working directory, you are in a task worktree.
|
||||
**You must immediately read `.agent-task` and load `.claude/skills/worktree-aware/SKILL.md`
|
||||
before taking any action.** That skill defines all branch-hygiene rules for task worktrees.
|
||||
|
||||
Worktree lifecycle commands: `agent.sh new | list | merge | clean`.
|
||||
Agents never invoke these — only the human does.
|
||||
|
|
|
|||
|
|
@ -1,359 +0,0 @@
|
|||
#!/usr/bin/env bash
|
||||
# Multi-agent worktree manager.
|
||||
# EXIT: 0 ok, 1 preflight, 2 operation failed.
|
||||
set -euo pipefail
|
||||
|
||||
RESERVED_NAMES=(master main HEAD list merge clean new)
|
||||
MAX_WORKTREES=4
|
||||
|
||||
die() { echo "ERROR: $*" >&2; exit "${2:-2}"; }
|
||||
prefail(){ echo "PREFLIGHT: $*" >&2; exit 1; }
|
||||
|
||||
# ── helpers ──────────────────────────────────────────────────────────────────
|
||||
|
||||
is_main_checkout() {
|
||||
local git_dir common_dir
|
||||
git_dir=$(git rev-parse --git-dir 2>/dev/null) || return 1
|
||||
common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || return 1
|
||||
[ "$git_dir" = "$common_dir" ]
|
||||
}
|
||||
|
||||
require_main_checkout() {
|
||||
is_main_checkout || prefail "must run from the main checkout, not a worktree"
|
||||
}
|
||||
|
||||
require_master_branch() {
|
||||
local branch
|
||||
branch=$(git rev-parse --abbrev-ref HEAD)
|
||||
[ "$branch" = "master" ] || prefail "must be on master (currently on '$branch')"
|
||||
}
|
||||
|
||||
require_clean_tree() {
|
||||
local dirty
|
||||
dirty=$(git status --porcelain)
|
||||
[ -z "$dirty" ] || prefail "working tree is not clean — stash or commit first"
|
||||
}
|
||||
|
||||
worktree_count() {
|
||||
# count registered worktrees that are NOT the main checkout
|
||||
local main_path
|
||||
main_path=$(git rev-parse --show-toplevel)
|
||||
git worktree list --porcelain \
|
||||
| awk '/^worktree /{p=$2} /^$/{print p}' \
|
||||
| grep -cv "^${main_path}$"
|
||||
}
|
||||
|
||||
worktree_paths() {
|
||||
# list worktree paths (excluding main)
|
||||
local main_path
|
||||
main_path=$(git rev-parse --show-toplevel)
|
||||
git worktree list --porcelain \
|
||||
| awk '/^worktree /{p=$2} /^$/{print p}' \
|
||||
| grep -v "^${main_path}$"
|
||||
}
|
||||
|
||||
branch_exists_local() { git show-ref --verify --quiet "refs/heads/$1"; }
|
||||
branch_exists_remote() { git ls-remote --exit-code origin "$1" >/dev/null 2>&1; }
|
||||
|
||||
utc_now() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
|
||||
|
||||
age_str() {
|
||||
local created_utc="$1"
|
||||
local now_ts created_ts diff_s
|
||||
now_ts=$(date -u +%s)
|
||||
# strip Z, replace T with space for `date -d`
|
||||
created_ts=$(date -u -d "${created_utc//T/ }" +%s 2>/dev/null) || { echo "?"; return; }
|
||||
diff_s=$(( now_ts - created_ts ))
|
||||
if (( diff_s < 60 )); then echo "${diff_s}s"
|
||||
elif (( diff_s < 3600 )); then echo "$(( diff_s/60 ))m"
|
||||
elif (( diff_s < 86400 )); then echo "$(( diff_s/3600 ))h"
|
||||
else echo "$(( diff_s/86400 ))d"
|
||||
fi
|
||||
}
|
||||
|
||||
validate_name() {
|
||||
local name="$1"
|
||||
[[ "$name" =~ ^[a-z][a-z0-9-]*$ ]] || prefail "name '$name' must match ^[a-z][a-z0-9-]*$"
|
||||
for r in "${RESERVED_NAMES[@]}"; do
|
||||
[ "$name" = "$r" ] && prefail "'$name' is a reserved word"
|
||||
done
|
||||
}
|
||||
|
||||
# ── subcommands ───────────────────────────────────────────────────────────────
|
||||
|
||||
cmd_new() {
|
||||
local name="${1:-}"
|
||||
[ -n "$name" ] || { usage; exit 1; }
|
||||
|
||||
validate_name "$name"
|
||||
require_main_checkout
|
||||
require_master_branch
|
||||
require_clean_tree
|
||||
|
||||
# worktree limit
|
||||
local count
|
||||
count=$(worktree_count)
|
||||
if (( count >= MAX_WORKTREES )); then
|
||||
echo "ERROR: already at maximum of $MAX_WORKTREES active worktrees:" >&2
|
||||
cmd_list
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# branch collision
|
||||
if branch_exists_local "task/$name"; then
|
||||
prefail "branch task/$name already exists locally"
|
||||
fi
|
||||
git fetch origin master --quiet
|
||||
if branch_exists_remote "refs/heads/task/$name"; then
|
||||
prefail "branch task/$name already exists on origin"
|
||||
fi
|
||||
|
||||
# directory collision
|
||||
local main_path wt_path
|
||||
main_path=$(git rev-parse --show-toplevel)
|
||||
wt_path="$(dirname "$main_path")/homelab-codex-ws-${name}"
|
||||
[ ! -e "$wt_path" ] || prefail "directory $wt_path already exists"
|
||||
|
||||
# create worktree
|
||||
git worktree add -b "task/$name" "$wt_path" origin/master \
|
||||
|| die "git worktree add failed"
|
||||
|
||||
# write marker
|
||||
local parent_commit
|
||||
parent_commit=$(git rev-parse origin/master)
|
||||
cat > "$wt_path/.agent-task" <<EOF
|
||||
task: $name
|
||||
branch: task/$name
|
||||
parent_commit: $parent_commit
|
||||
created_utc: $(utc_now)
|
||||
worktree_path: $wt_path
|
||||
EOF
|
||||
|
||||
echo ""
|
||||
echo "Worktree created: $wt_path"
|
||||
echo "Branch: task/$name"
|
||||
echo ""
|
||||
echo "── Start Claude Code in this worktree ──────────────────────────────────────"
|
||||
echo "cd ~/homelab-codex-ws-${name} && claude --dangerously-skip-permissions \"Jesteś w worktree task '${name}' (branch task/${name}). NAJPIERW przeczytaj .agent-task i .claude/skills/worktree-aware/SKILL.md, dopiero potem zacznij pracę. Commituj wyłącznie na swoją gałąź; nie pushuj origin master.\""
|
||||
echo "─────────────────────────────────────────────────────────────────────────────"
|
||||
}
|
||||
|
||||
cmd_list() {
|
||||
local main_path
|
||||
main_path=$(git rev-parse --show-toplevel)
|
||||
|
||||
# fetch to get up-to-date ahead/behind
|
||||
git fetch origin master --quiet 2>/dev/null || true
|
||||
|
||||
local paths
|
||||
paths=$(worktree_paths)
|
||||
|
||||
if [ -z "$paths" ]; then
|
||||
echo "(no active task worktrees)"
|
||||
return
|
||||
fi
|
||||
|
||||
printf "%-20s %-25s %-10s %-8s %-8s %-7s %s\n" \
|
||||
"NAME" "BRANCH" "CREATED" "AGE" "STATUS" "A/B" "PARENT"
|
||||
|
||||
while IFS= read -r wt_path; do
|
||||
[ -z "$wt_path" ] && continue
|
||||
|
||||
local marker="$wt_path/.agent-task"
|
||||
local task_name branch parent_commit created_utc
|
||||
if [ -f "$marker" ]; then
|
||||
task_name=$( grep '^task:' "$marker" | awk '{print $2}')
|
||||
branch=$( grep '^branch:' "$marker" | awk '{print $2}')
|
||||
parent_commit=$(grep '^parent_commit:' "$marker" | awk '{print $2}')
|
||||
created_utc=$(grep '^created_utc:' "$marker" | awk '{print $2}')
|
||||
else
|
||||
task_name="(no marker)"
|
||||
branch=$(git -C "$wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "?")
|
||||
parent_commit="?"
|
||||
created_utc=""
|
||||
fi
|
||||
|
||||
local status="clean"
|
||||
local dirty
|
||||
dirty=$(git -C "$wt_path" status --porcelain 2>/dev/null || echo "?")
|
||||
[ -n "$dirty" ] && status="dirty"
|
||||
|
||||
local ahead behind ab
|
||||
ahead=$(git -C "$wt_path" rev-list --count "origin/master..${branch}" 2>/dev/null || echo "?")
|
||||
behind=$(git -C "$wt_path" rev-list --count "${branch}..origin/master" 2>/dev/null || echo "?")
|
||||
ab="+${ahead}/-${behind}"
|
||||
|
||||
local age=""
|
||||
[ -n "$created_utc" ] && age=$(age_str "$created_utc")
|
||||
|
||||
local short_parent="${parent_commit:0:7}"
|
||||
local short_created="${created_utc:0:10}"
|
||||
|
||||
printf "%-20s %-25s %-10s %-8s %-8s %-7s %s\n" \
|
||||
"$task_name" "$branch" "$short_created" "$age" "$status" "$ab" "$short_parent"
|
||||
done <<< "$paths"
|
||||
}
|
||||
|
||||
cmd_merge() {
|
||||
local name="${1:-}"
|
||||
[ -n "$name" ] || { usage; exit 1; }
|
||||
|
||||
require_main_checkout
|
||||
require_master_branch
|
||||
require_clean_tree
|
||||
|
||||
git fetch origin --quiet
|
||||
|
||||
branch_exists_local "task/$name" || die "branch task/$name not found locally" 1
|
||||
|
||||
local main_path wt_path
|
||||
main_path=$(git rev-parse --show-toplevel)
|
||||
wt_path="$(dirname "$main_path")/homelab-codex-ws-${name}"
|
||||
|
||||
# attempt ff-only merge
|
||||
local merge_failed=0
|
||||
git merge --ff-only "task/$name" || merge_failed=1
|
||||
|
||||
if (( merge_failed )); then
|
||||
# abort any partial merge state
|
||||
git merge --abort 2>/dev/null || true
|
||||
echo ""
|
||||
echo "ERROR: task/$name cannot be fast-forwarded into master." >&2
|
||||
echo " The branch has likely diverged from master." >&2
|
||||
echo "" >&2
|
||||
echo "Diagnose with:" >&2
|
||||
echo " git log master..task/$name # commits only on task branch" >&2
|
||||
echo " git log task/$name..master # commits master has that task doesn't" >&2
|
||||
echo "" >&2
|
||||
echo "Then decide: rebase task/$name onto master, or merge manually." >&2
|
||||
echo "Worktree and branch are preserved — no changes made." >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
echo "Merged task/$name into master (fast-forward)."
|
||||
|
||||
git push origin master || die "git push origin master failed"
|
||||
echo "Pushed master to origin."
|
||||
|
||||
if [ -d "$wt_path" ]; then
|
||||
git worktree remove "$wt_path" || die "git worktree remove $wt_path failed"
|
||||
echo "Removed worktree: $wt_path"
|
||||
else
|
||||
echo "(worktree directory $wt_path not found — skipping worktree remove)"
|
||||
fi
|
||||
|
||||
git branch -d "task/$name" || die "git branch -d task/$name failed"
|
||||
echo "Deleted local branch task/$name."
|
||||
|
||||
git push origin --delete "task/$name" 2>/dev/null \
|
||||
&& echo "Deleted remote branch task/$name." \
|
||||
|| echo "(remote branch task/$name not found — nothing to delete)"
|
||||
|
||||
echo ""
|
||||
echo "Done. task/$name merged and cleaned up."
|
||||
}
|
||||
|
||||
cmd_clean() {
|
||||
local main_path
|
||||
main_path=$(git rev-parse --show-toplevel)
|
||||
git fetch origin --quiet 2>/dev/null || true
|
||||
|
||||
local to_remove=()
|
||||
|
||||
# orphaned registered worktrees: branch deleted or fully merged into master
|
||||
local paths
|
||||
paths=$(worktree_paths)
|
||||
while IFS= read -r wt_path; do
|
||||
[ -z "$wt_path" ] && continue
|
||||
local branch
|
||||
branch=$(git -C "$wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
|
||||
[ -z "$branch" ] && { to_remove+=("worktree:$wt_path (unreadable branch)"); continue; }
|
||||
|
||||
# branch gone locally?
|
||||
if ! branch_exists_local "$branch"; then
|
||||
to_remove+=("worktree:$wt_path (branch $branch no longer exists)")
|
||||
continue
|
||||
fi
|
||||
|
||||
# branch fully merged into master?
|
||||
local ahead
|
||||
ahead=$(git rev-list --count "origin/master..${branch}" 2>/dev/null || echo "1")
|
||||
if [ "$ahead" = "0" ]; then
|
||||
to_remove+=("worktree:$wt_path (branch $branch fully merged into origin/master)")
|
||||
fi
|
||||
done <<< "$paths"
|
||||
|
||||
# dangling directories: ../homelab-codex-ws-* not registered
|
||||
local registered_paths
|
||||
registered_paths=$(git worktree list --porcelain | awk '/^worktree /{print $2}')
|
||||
local parent_dir
|
||||
parent_dir=$(dirname "$main_path")
|
||||
while IFS= read -r candidate; do
|
||||
[ -d "$candidate" ] || continue
|
||||
if ! echo "$registered_paths" | grep -qF "$candidate"; then
|
||||
to_remove+=("dangling:$candidate")
|
||||
fi
|
||||
done < <(find "$parent_dir" -maxdepth 1 -name "homelab-codex-ws-*" -type d 2>/dev/null)
|
||||
|
||||
if [ ${#to_remove[@]} -eq 0 ]; then
|
||||
echo "Nothing to clean."
|
||||
return 0
|
||||
fi
|
||||
|
||||
echo "Found ${#to_remove[@]} item(s) to clean:"
|
||||
for entry in "${to_remove[@]}"; do
|
||||
echo " $entry"
|
||||
done
|
||||
echo ""
|
||||
|
||||
local overall_rc=0
|
||||
for entry in "${to_remove[@]}"; do
|
||||
local kind="${entry%%:*}"
|
||||
local path="${entry#*:}"
|
||||
# strip trailing annotation in parens
|
||||
local raw_path
|
||||
raw_path="${path%% (*}"
|
||||
|
||||
local confirm
|
||||
read -r -p "Remove $kind '$raw_path'? [y/N] " confirm
|
||||
if [[ "$confirm" =~ ^[Yy]$ ]]; then
|
||||
if [ "$kind" = "worktree" ]; then
|
||||
git worktree remove --force "$raw_path" 2>/dev/null \
|
||||
|| { echo " WARNING: git worktree remove failed, trying rm -rf"; rm -rf "$raw_path" || true; }
|
||||
else
|
||||
rm -rf "$raw_path"
|
||||
fi
|
||||
echo " Removed."
|
||||
else
|
||||
echo " Skipped."
|
||||
fi
|
||||
done
|
||||
|
||||
return $overall_rc
|
||||
}
|
||||
|
||||
usage() {
|
||||
cat <<'EOF'
|
||||
Usage: agent.sh <subcommand> [args]
|
||||
|
||||
agent.sh new <name> Create a new task worktree (branch task/<name>)
|
||||
agent.sh list List active task worktrees with status
|
||||
agent.sh merge <name> Fast-forward merge task/<name> into master and clean up
|
||||
agent.sh clean Remove orphaned or dangling worktrees (interactive)
|
||||
|
||||
EXIT: 0 ok, 1 preflight, 2 operation failed.
|
||||
EOF
|
||||
}
|
||||
|
||||
# ── dispatch ──────────────────────────────────────────────────────────────────
|
||||
|
||||
SUBCOMMAND="${1:-}"
|
||||
shift || true
|
||||
|
||||
case "$SUBCOMMAND" in
|
||||
new) cmd_new "$@" ;;
|
||||
list) cmd_list "$@" ;;
|
||||
merge) cmd_merge "$@" ;;
|
||||
clean) cmd_clean "$@" ;;
|
||||
*) usage; exit 1 ;;
|
||||
esac
|
||||
Loading…
Reference in a new issue