buddy-agent-harness 1.1.0 → 1.3.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. Beside the owner's global file, `~/.agents/AGENTS.md`, written only where the owner picks it (step 5), 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`.
+Where the invocation names `--root <dir>`, that directory is the repository: read and write inside it only, apart from `~/.agents/AGENTS.md` as step 5 allows. 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.
 
@@ -89,7 +91,7 @@ Once both answers are yes, offer the replacement. Do **not** then read the secti
 
 **Where your instructions from outside the repository cover the subject in another form, classify that copy.** An uncovered addition whose subject they cover — judged by meaning, as above — is not absent. Ask the second question of that **global copy**, against the same texts and in the same way as of a repository section, and offer nothing for the repository whatever it answers. Its verdict is the one a repository section would get, placed **in your instructions from outside the repository**: from a retired wording, the owner's own, or you cannot tell. Say, as for already global, that a copy in the root `AGENTS.md` would add the team and nothing else, that the owner would then read the subject twice, and that they can ask for it.
 
-Classify a global copy the same way whatever the repository holds — a covered or already-current section included — and hand over the current text for one from a retired wording (step 4).
+Classify a global copy the same way whatever the repository holds — a covered or already-current section included — and offer the current text in place of one from a retired wording (step 4).
 
 Each addition ends this step in one of six states:
 
@@ -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.3.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.
@@ -126,7 +128,7 @@ That path is relative to this skill's own directory; fall back to `npx -y buddy-
 
 Name both destinations and what each buys — the global file reaches every repository the owner opens and nobody else; the project file reaches everyone who clones it, at a copy per repository.
 
-**A global placement is handed over, not written.** This skill writes the root `AGENTS.md` and nothing else, so give the text and the path and stop there. Do not offer to write outside the repository, and do not treat the hand-off as a decline — report it as what it is.
+**Ask which destination the owner wants, and write the one they pick.** Put the recommended destination first and the other as the alternative, and ask for one or neither. Either is written on that yes and neither without it: the root `AGENTS.md`, or the end of `~/.agents/AGENTS.md` (step 5). The owner's choice of the other destination is an approval of that one, not a decline. A bridging step from the `doctor` row above stays handed over: it changes a harness's own user-scope file, which this skill does not write.
 
 Where an addition came from a **retired wording**, show the section as it stands in `AGENTS.md`, then the current text **verbatim**, say that it would replace that section and nothing else, and ask.
 
@@ -134,7 +136,7 @@ Where an addition came from a **retired wording**, show the section as it stands
 
 **Where your instructions from outside the repository carry the current text, put removal beside the replacement.** Offer the replacement as above, and say that it would have the owner read the text twice, once from each place. Then offer removing the section as the other answer: name every paragraph of the owner's it would take, and say the team's agents would no longer read it. This holds however the section was placed — by the comparison, by the owner's answer, or by measurement.
 
-Where a **global copy** came from a retired wording — whatever the repository holds, a current section included — show it as it stands, then the current text **verbatim**, name the file that holds it where you can see it, and say the current text would replace that section there. Name the owner's paragraphs it would take, as for a replacement. This skill writes nothing outside the repository, so this is handed over, as a global placement is; say so. Where a global copy cannot be placed, put it to the owner exactly as below; an answer that it came from here, or a measurement that puts the current text ahead, hands the current text over.
+Where a **global copy** came from a retired wording — whatever the repository holds, a current section included — show it as it stands, then the current text **verbatim**, name the file that holds it where you can see it, and say the current text would replace that section there. Name the owner's paragraphs it would take, as for a replacement. Where that file is `~/.agents/AGENTS.md`, offer the replacement and ask, as for one in the root `AGENTS.md`; it is written only on a yes (step 5). Where it is any other file — a harness's own user-scope file — or one you cannot see, hand the current text over for it instead and say so: this skill writes no other file outside the repository. Where a global copy cannot be placed, put it to the owner exactly as below; an answer that it came from here, or a measurement that puts the current text ahead, offers the current text as that replacement.
 
 Where you **cannot tell**, say that first, in those words. Then show three texts — the section as it stands, the retired wording it partly tracks, and the current text — and put three answers to the owner:
 
@@ -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.
 
@@ -159,9 +161,9 @@ Do not argue for any of it past one sentence. The user is reading the actual tex
 
 On approval of an **addition** for the repository, or a request for the team copy of an **already global** one, write the section into the root `AGENTS.md` at the end of the owner's prose, outside the managed region, preserving the surrounding file exactly.
 
-On approval of a **global placement**, write nothing. Give the text and `~/.agents/AGENTS.md`, and say it belongs at the end of that file. Where the harness in use does not load that file yet, give the step that bridges it too. Nothing outside the repository is written, the bridge included, and the run still reports.
+On approval of the **global destination**, write the section at the end of `~/.agents/AGENTS.md`, creating the file where it does not exist, and leave every other byte of it as it was. The repository's `AGENTS.md` is left as it stands. Where the harness in use does not load that file yet, hand over the step that bridges it; that step is never written here.
 
-On approval of a **replacement**, replace that one section in place — from its heading through to the next heading of the same or higher level — and leave every other byte of the file as it was. Do not relocate it, do not reformat around it, and do not touch the managed region.
+On approval of a **replacement** — in the root `AGENTS.md`, or of a global copy in `~/.agents/AGENTS.md` — replace that one section in place — from its heading through to the next heading of the same or higher level — and leave every other byte of the file as it was. Do not relocate it, do not reformat around it, and do not touch the managed region.
 
 Strip the fence when you write. The ``` markers around the addition in its reference file are there so you can see where the text begins and ends; the section goes into `AGENTS.md` as prose, not as a code block.
 
@@ -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, naming the file each write went to. 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-over — a bridging step, or the current text for a global copy in a file this skill does not write — 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,6 @@ 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 `~/.agents/AGENTS.md` in step 5 and the agent-worktree lines in step 6, each as approved.
+- **Never write a harness's own user-scope file**, such as `~/.claude/CLAUDE.md`. A step for it is handed over.
+- 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/delegation.md

@@ -51,7 +51,7 @@ Offer this repository's `AGENTS.md` as the alternative, and name what each one b
 
 The project file is the right pick for one reason and it is worth stating: a team's agents read the repository, not the maintainer's home directory. Where the owner wants the guidance to reach contributors, `AGENTS.md` is the only lever, and the duplicate copy is what that costs.
 
-This skill writes the root `AGENTS.md` and nothing else, so 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.
+Ask which of the two the owner wants, leading with the global file. Where they pick it, write the text at the end of `~/.agents/AGENTS.md` on that yes, as step 5 of the skill says; never without it.
 
 ## Do not edit it
 

package/skills/enhance/references/list-identifiers.md

@@ -49,8 +49,8 @@ Offer this repository's `AGENTS.md` as the alternative, and name what each one b
 | 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.
+Ask which of the two the owner wants, leading with the global file. Where they pick it, write the
+text at the end of `~/.agents/AGENTS.md` on that yes, as step 5 of the skill says; never without it.
 
 ## Do not edit 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 |
+
+Ask which of the two the owner wants, leading with the global file. Where they pick it, write the
+text at the end of `~/.agents/AGENTS.md` on that yes, as step 5 of the skill says; never without it.
+
+## 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.

package/skills/enhance/references/session-scope.md

@@ -58,8 +58,8 @@ Offer this repository's `AGENTS.md` as the alternative, and name what each one b
 | 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.
+Ask which of the two the owner wants, leading with the global file. Where they pick it, write the
+text at the end of `~/.agents/AGENTS.md` on that yes, as step 5 of the skill says; never without it.
 
 ## Do not edit it