@klok-integration/cli 0.2.0

package/assets/agents/skills/klok-worktree/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: klok-worktree
+description: Create, use, hand over and clean up the per task Git worktree and branch that every change to a Klok repository is made in (<workspace>/worktrees/<tenant>/<group>/.../<repo>/<task-id>, branch agent/<task-id>). Use before the first edit of any task that changes repository files, when resuming another session's work, and when finishing or cleaning up.
+---
+
+# Working in a task worktree
+
+The rule is in `KLOK-AGENTS.md` (*One task, one worktree, one branch*): every task that changes repository files runs
+in its own Git worktree on its own branch, and the canonical checkout is left exactly as found. This skill is the
+procedure. The principle behind it, *Git is the truth*, is described in
+https://docs.klok.dev/klok-integration-strategy-and-tactics/llm.txt.
+
+## Directory contract
+
+| Item | Value |
+|---|---|
+| Workspace root | the directory `klok sync` mirrors into: config key `workspace`, `KLOK_GIT_LOCAL_WORKSPACE`, default `~/devklok` |
+| Canonical checkout | `<root>/<tenant>/<group>/<subgroups...>/<repo>` |
+| Task worktree | `<root>/worktrees/<tenant>/<group>/<subgroups...>/<repo>/<task-id>` |
+| Task branch | `agent/<task-id>` |
+| Task id | `YYYYMMDD-<short-topic>-<8 random hex>`, lowercase letters, digits and hyphens |
+
+The task directory is the worktree root; its parent only groups that repository's tasks and is never a place to
+run repository commands. Expand `~` to the real home directory. Never flatten the repository path to its
+basename, never put the worktree inside `.claude`, inside the canonical checkout or in a tool specific directory.
+
+## Before the first edit
+
+1. **Find the repository.** From the directory the task points at, use Git metadata rather than folder names:
+   `git rev-parse --show-toplevel` gives the checkout, `git rev-parse --git-common-dir` tells whether you are in
+   the canonical checkout (`.git` inside it) or already in a worktree (a path into another checkout's `.git`),
+   `git remote -v` gives the remote. The workspace relative path of the canonical checkout is `<repo_rel>`.
+2. **Load the instructions deliberately.** Read `<root>/KLOK-AGENTS.md`, `<root>/<tenant>/KLOK-AGENTS.md` and
+   every `KLOK-AGENTS.md`, `AGENTS.md` or `CLAUDE.md` along the canonical path, plus the ones inside the repository revision you will
+   work on. A worktree under `<root>/worktrees` does not sit below those directories, so no tool loads them for
+   you. Keep the existing project rules; this skill does not replace them.
+3. **Inspect, do not touch.** `git -C <canonical> status --short`, `git -C <canonical> worktree list --porcelain`
+   and the canonical branch. Never `stash`, `reset`, `clean`, `checkout` or `switch` there. Uncommitted changes in
+   the canonical checkout are not a blocker; the worktree starts from committed history. If the task depends on
+   those changes, say so and ask for a handoff instead of moving them.
+4. **Choose the base.** Fetch the remote and resolve its default branch from the remote HEAD
+   (`git symbolic-ref refs/remotes/origin/HEAD`, or `git remote show origin`); do not assume `main`. Use the task's
+   named base when it gives one. Offline, say how old the local base is and continue when that is reasonable.
+5. **Create the worktree.** A new id per writing session; if the branch or directory exists, pick a new id rather
+   than deleting or force reusing anything.
+6. **Move into it.** Every edit, build, test and Git command uses the worktree as working directory (`cd` or
+   `git -C`). Verify `git rev-parse --show-toplevel`, `git branch --show-current` and the shared common dir before
+   the first write. Open this exact folder in the editor.
+7. **Say where you are.** State repository, worktree path and branch, then continue with the task.
+
+```bash
+root="${KLOK_GIT_LOCAL_WORKSPACE:-$HOME/devklok}"
+repo_rel="klok/integration/klok-api-konvoj"                 # full path, every subgroup kept
+task_id="$(date +%Y%m%d)-auth-$(openssl rand -hex 4)"
+canonical="$root/$repo_rel"
+task_tree="$root/worktrees/$repo_rel/$task_id"
+task_branch="agent/$task_id"
+
+git -C "$canonical" status --short
+git -C "$canonical" worktree list --porcelain
+git -C "$canonical" fetch origin
+base_commit="$(git -C "$canonical" rev-parse --verify 'origin/main^{commit}')"   # after verifying the default branch
+mkdir -p "$(dirname "$task_tree")"
+git -C "$canonical" worktree add -b "$task_branch" "$task_tree" "$base_commit"
+cd "$task_tree" && git rev-parse --show-toplevel && git branch --show-current
+```
+
+Run the steps one at a time and stop at the first failure; this is a procedure, not an installer. Validate any
+path that comes from the task: no absolute repository relative paths, no `..`, no symlink out of the workspace.
+Never use force flags to get past a worktree ownership check.
+
+A harness with its own worktree feature (for example Claude Code's `EnterWorktree`, which defaults to
+`.claude/worktrees/`) is used only if it can be pointed at the contract path; otherwise create the worktree with
+the commands above and open that directory. If the tool cannot read or write the worktree, report that
+limitation instead of editing the canonical checkout.
+
+## During the task
+
+* Keep source edits, formatting, generated source, builds and tests inside the worktree. Recreate dependencies
+  there with the project's documented setup (`npm ci`, `./gradlew build`); do not copy or symlink `.env`,
+  credentials, `node_modules`, build directories or other ignored files from another checkout.
+* Git objects, refs, remotes and configuration are shared with the canonical checkout. Do not change shared
+  settings, another task's branch, or force check out a branch attached to another worktree.
+* A worktree is not a sandbox: use isolated ports, containers, databases and output directories where parallel
+  tasks would collide, and never write through absolute paths or symlinks into another checkout.
+* Sibling repository dependencies (`includeBuild`, relative paths) point at canonical checkouts by default. Give
+  them explicit paths to the task worktrees when the task changes several repositories, and never let writable
+  build output land in a canonical checkout.
+* A task that spans repositories uses the same task id under each repository's path and records repository, base
+  commit, branch and worktree for each.
+
+## Resume and handoff
+
+Resume an existing task worktree only when the user or the handoff names it and no other writer is active.
+Verify its path, branch, shared repository (`git rev-parse --git-common-dir`), status and unpushed commits. A
+matching directory or branch name alone does not prove ownership; when unclear, create a new worktree. Legacy
+worktrees (for example under `.claude/worktrees/`) are reported with their paths and left for an explicit
+cleanup task, never moved or deleted on the way.
+
+## Finish
+
+1. Validate the requested behaviour, inspect the final diff, and commit to the task branch: stage specific paths,
+   check for secrets and unrelated files. Respect an explicit request to leave changes uncommitted.
+2. Push and open a merge request ready for review when the task or the established workflow allows it (see the
+   `klok-release` skill for what to check afterwards). Do not invent approval requirements and do not assume a
+   permission that was not given.
+3. Report: canonical repository path, worktree path, branch, commits, tests run, push and merge request status,
+   remaining changes and the next action. Unfinished work gets a clear handoff and keeps its worktree.
+
+## Cleanup
+
+Keep the worktree until the branch is merged or cleanup is asked for; a clean `git status` does not mean the
+commits are pushed or merged. Before removing, verify that no process or session uses it, look at tracked,
+untracked and ignored files, and confirm the commits are merged or preserved as agreed. Then
+`git -C <canonical> worktree remove <exact path>` without force. Never `rm -rf` a worktree as routine cleanup,
+and never delete a branch merely because a session ended.