buddy-agent-harness 1.1.0 → 1.2.0

package/skills/enhance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: enhance
-description: Use this skill when a repository already has an AGENTS.md and you want to add guidance it is missing, or to refresh a vetted section it carries in an outdated form — offering each one at a time and writing only what the user approves. Runs on its own or straight after init.
+description: Adds guidance missing from a repository's existing AGENTS.md, or refreshes a vetted section it carries in an outdated form — offering each one at a time and writing only what the user approves. Runs on its own or straight after init.
 argument-hint: '[--root <dir>]'
 ---
 
@@ -12,13 +12,15 @@ The split matters: initialization has to run everywhere and invent nothing, so i
 
 Every addition is **offered, never written on sight**. An addition asserts something about how the repository is worked in — it stays true whether or not this tool ever ran — so it is material under the rule in `references/agents-md.md`, and material content needs approval. Nothing here goes inside the `buddy-agent-harness` managed region; that region is for the tool's own bookkeeping.
 
-Three additions ship today: `references/delegation.md`, `references/list-identifiers.md`, and `references/session-scope.md`. Classify, offer, and report each one on its own; the owner's answer to one decides nothing about the others. Each addition's reference file carries the text to offer, a `## Covered when` criterion for the subject already being present, a `## Stale when` section naming the history file its stale check reads and what else that check needs for this addition, and a `## Where it belongs` recommendation naming which instruction file the text should go in. The retired wordings themselves are kept beside it — `references/<addition>.history.md` — and are what a present section is compared against.
+Four additions ship today: `references/delegation.md`, `references/list-identifiers.md`, `references/session-scope.md`, and `references/references-as-links.md`. Classify, offer, and report each one on its own; the owner's answer to one decides nothing about the others. Each addition's reference file carries the text to offer, a `## Covered when` criterion for the subject already being present, a `## Stale when` section naming the history file its stale check reads and what else that check needs for this addition, and a `## Where it belongs` recommendation naming which instruction file the text should go in. The retired wordings themselves are kept beside it — `references/<addition>.history.md` — and are what a present section is compared against.
+
+Beside the additions, it offers the two **agent-worktree settings** in `references/agent-worktrees.md`: lines in `.gitignore`, a tool config, and `.claude/settings.json` rather than prose in `AGENTS.md`. Step 6 is theirs, and they are the only writes this skill makes outside the root `AGENTS.md`.
 
 ## 1. Find the instruction file
 
 Where the invocation names `--root <dir>`, that directory is the repository: read and write inside it only. Otherwise locate the Git repository root. The target is the root `AGENTS.md`.
 
-If there is no root `AGENTS.md`, stop and say so. This skill adds to an existing file; creating one is `init`'s job, so point there and write nothing. Still report in full as step 6 says — what you read, that nothing was written — with **not judged** as each addition's verdict.
+If there is no root `AGENTS.md`, stop and say so. This skill adds to an existing file; creating one is `init`'s job, so point there and write nothing. Still report in full as step 7 says — what you read, that nothing was written — with **not judged** as each addition's verdict.
 
 A nested `AGENTS.md` is never a target. It governs its own subtree, and none of these additions are subtree-scoped.
 
@@ -108,7 +110,7 @@ A section from a retired wording in a file that is **not** the root `AGENTS.md`
 
 Where an addition is **absent**, show its text **verbatim** — the whole thing, not a summary — say where it would go, and ask.
 
-**Where it goes is part of the offer, and the addition decides it.** Read its `## Where it belongs` and lead with what that section recommends. An addition whose subject is the repository belongs in the repository's `AGENTS.md`; one whose subject is how the agent works belongs in the owner's own global instruction file, because it holds in every repository they open and a copy per repository is a copy per repository to keep in step. Delegation, list identifiers, and session scope are all the second kind, and their references recommend the global file.
+**Where it goes is part of the offer, and the addition decides it.** Read its `## Where it belongs` and lead with what that section recommends. An addition whose subject is the repository belongs in the repository's `AGENTS.md`; one whose subject is how the agent works belongs in the owner's own global instruction file, because it holds in every repository they open and a copy per repository is a copy per repository to keep in step. Delegation, list identifiers, session scope, and references as links are all the second kind, and their references recommend the global file.
 
 The global file is `~/.agents/AGENTS.md`, the user-scope counterpart of the root `AGENTS.md`. No harness reads it by itself; a harness reads it only where a user-scope instruction file of its own loads it. **Say whether the harness in use does**, and do not judge that yourself — `doctor` owns the check:
 
@@ -116,7 +118,7 @@ The global file is `~/.agents/AGENTS.md`, the user-scope counterpart of the root
 node scripts/doctor.mjs
 ```
 
-That path is relative to this skill's own directory; fall back to `npx -y buddy-agent-harness@1.1.0 doctor` when it is missing or cannot be run. Read the `globalInstructions` row for the harness you are running in:
+That path is relative to this skill's own directory; fall back to `npx -y buddy-agent-harness@1.2.0 doctor` when it is missing or cannot be run. Read the `globalInstructions` row for the harness you are running in:
 
 - **`ok`** — say that this harness loads `~/.agents/AGENTS.md`, through the file the row names.
 - **`missing` or `unbridged`** — say that it does not yet, so the text would reach no session of this harness until it does. Name the file the row gives, and hand over the step that bridges it beside the text: `references/global-instructions.md` names it per harness, and where `doctor` reported a finding for that file, its `help` row carries the same step. Where the row is `unbridged` and the step is a symlink, say that what the file holds moves into `~/.agents/AGENTS.md` first.
@@ -144,7 +146,7 @@ Where you **cannot tell**, say that first, in those words. Then show three texts
 
 Put the third every time the repository can actually do it, because the owner may not remember either, and the question they care about is not where the section came from but **which wording serves them better**. Provenance is a stand-in for that; when the stand-in fails, ask the real question.
 
-Measurement means running each wording against a set of real tasks and comparing how the agent behaves — whatever harness this repository has for that addition's wording. In this package's own repository `eval-delegation` scores Delegation's and `eval-list-identifiers` scores List identifiers'; Session scope has none, and a consumer repository will have its own or none. **Look before you offer it.** Where the repository has no harness for that addition, say the third answer would need one it does not have, and put the other two.
+Measurement means running each wording against a set of real tasks and comparing how the agent behaves — whatever harness this repository has for that addition's wording. In this package's own repository `eval-delegation` scores Delegation's and `eval-list-identifiers` scores List identifiers'; Session scope and References as links have none, and a consumer repository will have its own or none. **Look before you offer it.** Where the repository has no harness for that addition, say the third answer would need one it does not have, and put the other two.
 
 **Ask before running it, and never run it unasked** — it is many model runs, and the owner is the one paying for them.
 
@@ -169,9 +171,15 @@ On approval of a **removal**, remove that one section — from its heading throu
 
 On a decline, write nothing. A declined replacement leaves the section exactly where it stands, and so does an unanswered question.
 
-## 6. Report
+## 6. Offer the agent-worktree settings
+
+Where Claude Code is in use — a `.claude/` directory exists — read `references/agent-worktrees.md` and judge **P1**, ignoring `.claude/worktrees/`, and **P2**, setting `worktree.baseRef` to `"head"`, against the files that page names. Each is covered, or offered on its own, one line per file, with P2's trade-off explained before you ask. On approval, write exactly the line approved into that file and leave every other byte of it as it was: change the one key or array element, keep key order, indentation, and comments. On a decline, write nothing.
+
+These are settings, not additions. They have no history file, no global destination, and no `prose-update` comparison: a line is there or it is not. Where no `AGENTS.md` exists the run stops at step 1 and offers neither; `init`, which it points to, offers both.
+
+## 7. Report
 
-Report every run, whichever way it went: what you read, the verdict for each addition and why — already global, already current, absent, the owner's own, from a retired wording, undecidable, or not judged — what you offered, which destination you recommended, and what was written. For an already-current addition your instructions from outside the repository also carry, say the owner reads it twice. Wherever those instructions cover an addition's subject, name that copy and its verdict. A hand-off for the owner to place globally is an outcome, not a decline; say so. A run that offers nothing still reports — that is the only way the user can tell "already covered" from "did not look".
+Report every run, whichever way it went: what you read, the verdict for each addition and why — already global, already current, absent, the owner's own, from a retired wording, undecidable, or not judged — what you offered, which destination you recommended, and what was written. For an already-current addition your instructions from outside the repository also carry, say the owner reads it twice. Wherever those instructions cover an addition's subject, name that copy and its verdict. A hand-off for the owner to place globally is an outcome, not a decline; say so. Report each agent-worktree offer as written, declined, or already covered, naming the file. A run that offers nothing still reports — that is the only way the user can tell "already covered" from "did not look".
 
 ## Rules
 
@@ -182,5 +190,5 @@ Report every run, whichever way it went: what you read, the verdict for each add
 - **Never run an evaluation unasked.** It costs the owner many model runs. Offer it; wait.
 - **Never edit an addition to fit a repository.** The wording is fixed. Offer it as written or not at all.
 - **Name `~/.agents/AGENTS.md` as the global file.** Name a harness's own user-scope file only where that harness documents it.
-- **Never touch the managed region**, a nested `AGENTS.md`, or any file other than the root `AGENTS.md`.
-- Local agent configuration only. Do not change workflows, repository settings, or unrelated project files.
+- **Never touch the managed region**, a nested `AGENTS.md`, or any file other than the root `AGENTS.md` — except the agent-worktree lines in step 6, as approved.
+- Local agent configuration only. Do not change workflows, repository settings, or unrelated project files; the agent-worktree lines are the one exception.

package/skills/enhance/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.

package/skills/enhance/references/references-as-links.history.md

@@ -0,0 +1,9 @@
+# Superseded wordings: References as links
+
+Every wording this addition has retired, newest first, each exactly as it was offered. Read this
+file when a `## References as links` section is already present and reads as covered; it is what
+the section in front of you is compared against.
+
+Nothing here is ever offered. The text to offer is in `references-as-links.md`.
+
+None yet. This addition still offers its first wording.

package/skills/enhance/references/references-as-links.md

@@ -0,0 +1,76 @@
+# Addition: References as links
+
+## Covered when
+
+The merged view already tells the agent **to write an issue, pull request, or commit it mentions as
+a link the user can follow, not as a bare number**. Any of these counts:
+
+- a rule to write references to issues, pull requests, or commits as Markdown links or full URLs, under any heading
+- a rule that a reference the agent puts to the user names its repository and links to the item's page
+
+A convention for commit messages or pull request bodies — "close the issue with `Closes #12`" — is
+not coverage: it governs text GitHub renders, not what the agent puts to the user. Neither is a rule
+to qualify a number with its repository alone, such as `owner/repo#12`, which still leads nowhere
+in a terminal. Neither is a rule that appears only in a skill body — this addition is for the
+always-loaded file.
+
+## Stale when
+
+Compare the `## References as links` section already in the file against
+`references-as-links.history.md` by the procedure in step 3 of the skill, with the text below as the
+current text.
+
+`references-as-links.history.md` holds no retired wording yet. Until it does, a section that is not
+already current is compared against the text below, standing in for a retired wording: both answers
+yes is this text edited, and gets the replacement offer; both no is the owner's own; a disagreement
+you cannot tell. The paragraphs a replacement would remove are the ones the text below does not
+contain.
+
+A section whose example link names a different repository or item is still this text edited when
+its sentences survive: the example is part of the wording, not the owner's own content.
+
+Where you cannot tell, the third answer needs a harness that scores this addition's wording, and none
+does: `eval-delegation` scores Delegation's and `eval-list-identifiers` scores List identifiers', and
+neither covers this one. Put two answers, not three, and say settling it by measurement would need a
+harness that does not exist yet.
+
+## Offer this text verbatim
+
+```markdown
+## References as links
+
+Write each issue, pull request, or commit you mention as a Markdown link to its page, such as
+[cyber-agentkit#222](https://github.com/cyber-uni/cyber-agentkit/pull/222), not a bare `#222`. A bare
+number is a link only on GitHub itself; in a terminal or a chat it leads nowhere, and across
+repositories it names the wrong one.
+```
+
+## Where it belongs
+
+**Recommend the owner's own global instruction file, not this repository's `AGENTS.md`.**
+
+The text says how to present a reference to the user, which holds in every repository the owner
+opens, so the global file, `~/.agents/AGENTS.md`, is its one home.
+
+Offer this repository's `AGENTS.md` as the alternative, and name what each one buys:
+
+| Destination | Reaches | Costs |
+| --- | --- | --- |
+| the owner's global file | every repository they open, themselves only | one copy, and nothing to keep in step |
+| this repository's `AGENTS.md` | everyone who clones it, and any agent CI runs | a copy per repository, and a second copy in context for anyone who already has it globally |
+
+A global placement is **handed over, not made**: give the text and the path, say it goes at the end
+of that file, and stop there.
+
+## Do not edit it
+
+The wording is fixed. In particular, do not swap the example link for one in this repository — the
+section has to hold in every repository it is read in, and an example naming one of them reads as a
+rule about that one. Offer it as written or not at all.
+
+If the text is ever revised, the same change must do two things:
+
+- append the outgoing wording to `references-as-links.history.md`, newest first, exactly as it was offered;
+- add scenarios for the **shape of that revision** and pass the gate against the new pair.
+
+Where the owner picks this repository over their global file, place it at the end of their prose, outside the `buddy-agent-harness` managed region.