buddy-agent-harness 1.1.0 → 1.2.0

package/skills/init-buddy-agent-harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: init-buddy-agent-harness
-description: Use this skill when initializing, adopting, or migrating a repository's agent configuration to the open AGENTS.md and Agent Skills standards, so one canonical source works across Claude Code, Codex, Cursor, Copilot CLI, and other agent harnesses.
+description: Initializes, adopts, or migrates a repository's agent configuration to the open AGENTS.md and Agent Skills standards, so one canonical source works across Claude Code, Codex, Cursor, Copilot CLI, and other agent harnesses.
 argument-hint: '[--root <dir>] [--harness <names>] [--copy] [--force <targets>]'
 ---
 
@@ -76,6 +76,8 @@ Get explicit approval before any step that deletes, replaces, or rewrites a user
 
 `CLAUDE.md` is the one artifact where the generated copy is the harm rather than the safeguard: a copy left behind is read *instead of* `AGENTS.md`, so the consolidation would reach every harness but the one the file was written for. Offer to consolidate and **remove** it, or — where something in it is genuinely Claude-only — to consolidate the shared part and leave the file holding an `@AGENTS.md` import above whatever stays.
 
+**Offer the two agent-worktree settings where Claude Code is in use**, each on its own: **P1**, ignoring `.claude/worktrees/` in `.gitignore` and in each tree-scanning tool's config the repository has, and **P2**, setting `worktree.baseRef` to `"head"` in `.claude/settings.json`, with its trade-off explained before you ask. `references/agent-worktrees.md` has the lines, how to tell each is already covered, and the trade-off. Both are material: an owner who declines either keeps the repository as it was.
+
 A `CLAUDE.local.md` is its own case. It is personal, usually gitignored, and it suppresses `AGENTS.md` exactly as a committed `CLAUDE.md` does. Never consolidate it — it is not project content — and never delete it. Report it, and offer the one fix that keeps both: an `@AGENTS.md` import at the top of it.
 
 ## 4. Apply
@@ -84,14 +86,15 @@ A `CLAUDE.local.md` is its own case. It is personal, usually gitignored, and it
 2. Move approved skills and commands to `.agents/skills/<name>/SKILL.md`, preferring `git mv` so history follows. Fix frontmatter per `references/frontmatter.md` — this is where cross-harness portability is won or lost.
 3. Merge approved instruction content into `AGENTS.md`, preserving the author's wording. Append; do not restructure. Replace a harness file with a pointer only where approved. Content only some tasks need belongs in a skill, not in `AGENTS.md`.
 4. Apply the conversions that were approved, one at a time, and nothing else from the list. A rule approved as a skill moves to `.agents/skills/<name>/SKILL.md` with frontmatter per `references/frontmatter.md`; instruction content approved for consolidation is appended as in the step above and its harness file left as a generated copy — except a `CLAUDE.md`, which is removed or left holding the import, because a copy under that name is read instead of `AGENTS.md`. Everything declined, and everything with no candidate, stays exactly where it is.
-5. Run `node scripts/init.mjs` at the repository root, resolving that path against this skill's own directory: `scripts/init.mjs` is a self-contained bundle shipped inside this skill folder through the npm package, so it runs with nothing downloaded and no `node_modules` needed. Fall back to `npx -y buddy-agent-harness@1.1.0 init` when `scripts/init.mjs` is missing or cannot be run — the case for a skill installed from git rather than from the npm package, which does not carry the bundle. It links `.agents/skills` into the harnesses that need it and skips those that read it natively. Add harnesses the user names with `--harness codex,gemini-cli`.
+5. Run `node scripts/init.mjs` at the repository root, resolving that path against this skill's own directory: `scripts/init.mjs` is a self-contained bundle shipped inside this skill folder through the npm package, so it runs with nothing downloaded and no `node_modules` needed. Fall back to `npx -y buddy-agent-harness@1.2.0 init` when `scripts/init.mjs` is missing or cannot be run — the case for a skill installed from git rather than from the npm package, which does not carry the bundle. It links `.agents/skills` into the harnesses that need it and skips those that read it natively. Add harnesses the user names with `--harness codex,gemini-cli`.
 6. If the command reports a conflict, resolve the named target and retry. Pass the target to `--force` — `--force .claude/skills` replaces that projection and reports any other conflict untouched, where a bare `--force` replaces every conflicting target at once. Reach for the bare form only when replacing all of them is what you came for. Use `--copy` only where links are unavailable — a copy is a snapshot, not a live projection, so say so when you fall back.
 7. Apply the instruction work `init` does not do. Gemini CLI needs `AGENTS.md` added to `context.fileName` in `.gemini/settings.json` — the only bridge left, detailed in `references/harnesses/gemini-cli.md`, and only if you enabled it. Then remove each superseded `CLAUDE.md` the user approved, in every directory it was found in, and no others. Write no `CLAUDE.md` anywhere, at the root or beside a nested `AGENTS.md`: Claude Code reads both by itself, and a stub written beside one is the very file that would suppress it if anyone later put content in it.
-8. If a skills bridge now exists, write or restore the non-material region in `AGENTS.md` per `references/agents-md.md`, unless the markers are present and empty. Without it, an agent asked to change a skill edits `.claude/skills/<name>/SKILL.md` — which a link resolves back to canonical, but a copy silently forks. Skip this when every enabled harness reads `.agents/skills/` natively; with no bridge there is nothing to warn about.
+8. Apply the agent-worktree lines the owner approved, per `references/agent-worktrees.md`, and nothing they declined.
+9. If a skills bridge now exists, write or restore the non-material region in `AGENTS.md` per `references/agents-md.md`, unless the markers are present and empty. Without it, an agent asked to change a skill edits `.claude/skills/<name>/SKILL.md` — which a link resolves back to canonical, but a copy silently forks. Skip this when every enabled harness reads `.agents/skills/` natively; with no bridge there is nothing to warn about.
 
 ## 5. Verify and report
 
-Confirm each projection resolves into `.agents/skills`, that no `CLAUDE.md` is left carrying content beside an `AGENTS.md`, and that every migrated `SKILL.md` parses and has valid frontmatter. The command reports the enabled set itself; it records nothing on disk, so there is no file to reconcile against. Report what was created, consolidated, linked, and left canonical-only, with the reason each canonical-only artifact was left.
+Confirm each projection resolves into `.agents/skills`, that no `CLAUDE.md` is left carrying content beside an `AGENTS.md`, and that every migrated `SKILL.md` parses and has valid frontmatter. The command reports the enabled set itself; it records nothing on disk, so there is no file to reconcile against. Report what was created, consolidated, linked, and left canonical-only, with the reason each canonical-only artifact was left. Report each agent-worktree offer as written, declined, or already covered.
 
 Report the artifacts only one harness can read that are still there, split by why: declined, or no canonical form to convert into. Re-running `doctor` gives the same list, and a repository works toward having none of them — that is a direction, not a state anything here blocks on.
 
@@ -110,4 +113,4 @@ Then offer to continue with the `enhance` skill, which proposes guidance the rep
 - `init` writes `AGENTS.md` and `.agents/skills/`, and treats only those as standard: `.agents/skills/` is the one `.agents/` folder harnesses read. Other folders, such as `.agents/rules/`, `.agents/commands/`, or `.agents/agents/`, are the project's choice and outside what `init` scaffolds. Leave any that exist as they are, and do not describe them as standard.
 - Never merge a nested `AGENTS.md` into the root. Merging changes which files it governs.
 - Do not create `AGENTS.local.md`. The standard has no local-override file — two filenames and two meanings are still under discussion upstream. Personal instructions go in `CLAUDE.local.md`, gitignored, read by Claude Code alone — and that file suppresses `AGENTS.md` unless it opens with an `@AGENTS.md` import. Say so whenever you point anyone at it.
-- Local agent configuration only. Do not change workflows, GitHub Actions, repository settings, security scanning, branch rules, or unrelated project files.
+- Local agent configuration only. Do not change workflows, GitHub Actions, repository settings, security scanning, branch rules, or unrelated project files. The agent-worktree lines in `.gitignore`, a tool config, and `.claude/settings.json` are the one exception, and only as approved.

package/skills/init-buddy-agent-harness/references/agent-worktrees.md

@@ -0,0 +1,59 @@
+# Agent worktrees
+
+Claude Code runs a session started with `--worktree`, and a subagent isolated in a worktree, in a git worktree under `.claude/worktrees/<name>/` at the repository root, on a branch named `worktree-<name>`. The place is by design: no setting moves it, and only a `WorktreeCreate` hook, which replaces Claude Code's git logic outright, can put worktrees elsewhere. That is rarely worth it, so do not offer it.
+
+Each worktree is a whole checkout inside the repository, config files included. A repository that does not account for that pays three ways:
+
+- **`git status` lists `.claude/worktrees/` as untracked.** Claude Code does not ignore the directory itself; its documentation tells users to.
+- **Tools that walk the tree find each worktree's config.** Biome stops with "Found a nested root configuration, but there's already a root configuration", and a pre-commit hook running it fails every commit until the worktrees are gone. ESLint, Prettier, knip, and a tsconfig `include` walk the same tree.
+- **Agent worktrees branch from the default branch.** Unless `worktree.baseRef` is `"head"`, a subagent asked to build on a feature branch starts from `main` without that branch's commits, and its work comes back as merge conflicts.
+
+Two offers follow. Make them only where Claude Code is in use: a `.claude/` directory exists, or the owner enabled Claude Code in this run. Each is offered on its own, and the owner's answer to one decides nothing about the other.
+
+## P1: ignore the worktree directory
+
+**Covered when** `git check-ignore -q .claude/worktrees/` succeeds, and each tool config listed below that the repository has already excludes `.claude/worktrees`. A rule on a parent directory counts. Where that rule is `.claude/` whole, it also ignores `.claude/skills`, which `doctor` reports as `ignored-bridge`; that is `repair`'s, not this offer's.
+
+Offer each missing line as its own item, naming the file and showing the line:
+
+| File | Line to add |
+| --- | --- |
+| `.gitignore` | `.claude/worktrees/` |
+| `biome.json` or `biome.jsonc` | `"!**/.claude/worktrees"` as an element of `files.includes`; where `files.includes` is absent, `"files": { "includes": ["**", "!**/.claude/worktrees"] }` |
+| `.eslintignore` | `**/.claude/worktrees` |
+| `eslint.config.*` (flat config) | `"**/.claude/worktrees/**"` in a global `ignores` entry |
+| `.prettierignore` | `**/.claude/worktrees` |
+| `knip.json` or `knip.jsonc` | `"**/.claude/worktrees/**"` in `ignore` |
+| `tsconfig.json` whose `include` reaches the repository root | `"**/.claude/worktrees"` in `exclude` |
+
+Look for each file; offer only for the files that exist. Biome is the confirmed failure, so lead with it where it is present. A tool set to read `.gitignore`, such as Biome with `vcs.useIgnoreFile`, is still offered its own line: whether it then skips a nested config in an ignored directory is not documented. Say so.
+
+A tsconfig whose `include` names only `src` never reaches `.claude/`, so it is covered and needs nothing.
+
+**A tsconfig `exclude` replaces the default.** With no `exclude`, TypeScript excludes `node_modules` and the `outDir` by default, and writing an `exclude` drops that default. Where the file has none, offer `["node_modules", "**/.claude/worktrees"]` and name the trade, rather than a one-element list.
+
+## P2: set `worktree.baseRef` to `"head"`
+
+**Covered when** the project's `.claude/settings.json` sets `worktree.baseRef` to either value. An explicit `"fresh"` is the owner's answer; offer nothing and say so.
+
+Explain the trade-off before asking, in about these words:
+
+> Claude Code branches every agent worktree from the repository's default branch on the remote unless `worktree.baseRef` is `"head"`. The default suits agents given tasks unrelated to what you are working on: each starts from a clean tree. It surprises anyone working on a feature branch: an agent asked to build on it starts from `main`, misses its commits, and its work comes back in conflict. `"head"` branches from your current `HEAD` instead, unpushed commits included.
+
+Then offer the setting, merged into `.claude/settings.json`:
+
+```json
+{
+	"worktree": {
+		"baseRef": "head"
+	}
+}
+```
+
+The setting accepts only those two values, not a branch name. Write it in the project's `.claude/settings.json`, which is committed, so everyone who clones the repository gets the same base. Where the owner wants it for themselves only, name `.claude/settings.local.json` instead and write there on their approval.
+
+## Writing
+
+Edit each file in place, as the rule in the skill says: add the one line, element, or key, and leave every other byte as it was. Create `.gitignore` or `.claude/settings.json` when it is missing; that is still an approved write, so it is offered first like any other.
+
+A decline writes nothing. `doctor` reports what is still missing as `worktrees-untracked`, `worktrees-scanned`, and `worktree-base-unset`, so the owner can come back to it.