buddy-agent-harness 0.16.0 → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/dist/cli.mjs +243 -11
- package/dist/index.d.mts +68 -5
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +248 -12
- package/dist/index.mjs.map +1 -1
- package/dist/skill-scripts/doctor.mjs +44 -43
- package/dist/skill-scripts/init.mjs +44 -43
- package/dist/skill-scripts/mcp.mjs +44 -43
- package/dist/skill-scripts/reference.mjs +44 -43
- package/llms.txt +3 -2
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills/doctor-buddy-agent-harness/SKILL.md +5 -1
- package/skills/doctor-buddy-agent-harness/references/global-instructions.md +30 -0
- package/skills/doctor-buddy-agent-harness/references/harnesses/claude-code.md +3 -2
- package/skills/doctor-buddy-agent-harness/references/harnesses/codex.md +4 -2
- package/skills/doctor-buddy-agent-harness/references/harnesses/copilot-cli.md +3 -2
- package/skills/doctor-buddy-agent-harness/references/harnesses/cursor.md +1 -1
- package/skills/doctor-buddy-agent-harness/references/harnesses/gemini-cli.md +2 -2
- package/skills/doctor-buddy-agent-harness/scripts/doctor.mjs +44 -43
- package/skills/enhance/SKILL.md +16 -5
- package/skills/enhance/references/session-scope.history.md +9 -0
- package/skills/enhance/references/session-scope.md +75 -0
- package/skills/enhance/scripts/doctor.mjs +486 -0
- package/skills/init-buddy-agent-harness/SKILL.md +1 -1
- package/skills/init-buddy-agent-harness/scripts/doctor.mjs +44 -43
- package/skills/init-buddy-agent-harness/scripts/init.mjs +44 -43
- package/skills/reference/SKILL.md +1 -1
- package/skills/reference/scripts/reference.mjs +44 -43
- package/skills/repair/SKILL.md +3 -1
- package/skills/repair/scripts/doctor.mjs +44 -43
- package/skills/repair/scripts/mcp.mjs +44 -43
- package/src/diagnose-bridges/diagnose-bridges.ts +27 -2
- package/src/diagnose-bridges/diagnose-global-instructions.ts +154 -0
- package/src/diagnose-bridges/diagnose-instructions.ts +7 -2
- package/src/diagnose-bridges/doctor-guidance.ts +152 -6
- package/src/diagnose-bridges/doctor.command.ts +6 -1
- package/src/harness-registry/harness-registry.ts +38 -4
- package/src/harness-registry/instruction-bridge.ts +25 -9
- package/src/index.ts +8 -0
- package/src/skill-scripts/launchers.ts +1 -0
package/llms.txt
CHANGED
|
@@ -16,7 +16,7 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
|
|
|
16
16
|
|
|
17
17
|
- [CLI Overview](https://repobuddy.github.io/buddy-agent-harness/cli/): The buddy-agent-harness command line, and when to use it instead of the skill.
|
|
18
18
|
- [`buddy-agent-harness init`](https://repobuddy.github.io/buddy-agent-harness/cli/init/): Set up canonical agent skills for the harnesses already enabled in a repository.
|
|
19
|
-
- [`buddy-agent-harness doctor`](https://repobuddy.github.io/buddy-agent-harness/cli/doctor/): Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md. Read-only.
|
|
19
|
+
- [`buddy-agent-harness doctor`](https://repobuddy.github.io/buddy-agent-harness/cli/doctor/): Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md — and whether each harness's user-scope file loads ~/.agents/AGENTS.md. Read-only.
|
|
20
20
|
- [`buddy-agent-harness mcp`](https://repobuddy.github.io/buddy-agent-harness/cli/mcp/): Work with the golden MCP server set at .agents/buddy-agent-harness/mcp.toml.
|
|
21
21
|
- [`buddy-agent-harness mcp project`](https://repobuddy.github.io/buddy-agent-harness/cli/mcp/): Project the golden MCP server set into each enabled harness. A dry run unless --write; never overwrites a change made on the harness side.
|
|
22
22
|
- [`buddy-agent-harness mcp reconcile`](https://repobuddy.github.io/buddy-agent-harness/cli/mcp/): Import a harness-side MCP change into the golden set, one approved field at a time. A dry run unless --accept names a field.
|
|
@@ -78,9 +78,10 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
|
|
|
78
78
|
|
|
79
79
|
- [Library: `cli.ts`](https://repobuddy.github.io/buddy-agent-harness/library/init/): exports `run`.
|
|
80
80
|
- [Library: `diagnose-bridges/diagnose-bridges.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `diagnoseBridges`, type `BridgeFinding`, type `BridgeKind`, type `BridgeReport`, type `BridgeStatus`, type `DiagnoseOptions`, type `DiagnoseResult`, type `DivergenceReport`.
|
|
81
|
+
- [Library: `diagnose-bridges/diagnose-global-instructions.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `diagnoseGlobalInstructions`, type `GlobalInstructionKind`, type `GlobalInstructionReport`, type `GlobalInstructionStatus`.
|
|
81
82
|
- [Library: `diagnose-bridges/diagnose-instructions.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `diagnoseInstructions`, type `InstructionKind`, type `InstructionReport`, type `InstructionStatus`.
|
|
82
83
|
- [Library: `diagnose-bridges/doctor.command.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `buildDoctorReport`, `doctorCommand`, type `DoctorReference`, type `DoctorReport`.
|
|
83
|
-
- [Library: `diagnose-bridges/doctor-guidance.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `bridgeRepairs`, `doctorRepairs`, `doctorSkill`, `instructionRepairs`, `renderDoctorSkill`, type `BridgeProblem`, type `ConfigurationFault`, type `ConfigurationProblem`, type `DoctorProblem`, type `InstructionProblem`, type `McpProblem`, type `Repair`.
|
|
84
|
+
- [Library: `diagnose-bridges/doctor-guidance.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `bridgeRepairs`, `doctorRepairs`, `doctorSkill`, `globalInstructionRepairs`, `instructionRepairs`, `renderDoctorSkill`, type `BridgeProblem`, type `ConfigurationFault`, type `ConfigurationProblem`, type `DoctorProblem`, type `GlobalInstructionProblem`, type `InstructionProblem`, type `McpProblem`, type `Repair`.
|
|
84
85
|
- [Library: `diagnose-bridges/git-bridge-state.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports type `DivergenceDirection`.
|
|
85
86
|
- [Library: `diagnose-mcp/diagnose-mcp.ts`](https://repobuddy.github.io/buddy-agent-harness/library/mcp/): exports `diagnoseMcp`, type `DiagnoseMcpOptions`.
|
|
86
87
|
- [Library: `diagnose-mcp/mcp-baseline.ts`](https://repobuddy.github.io/buddy-agent-harness/library/mcp/): exports type `McpDirection`.
|
package/package.json
CHANGED
package/plugin.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
3
3
|
"name": "buddy-agent-harness",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.18.0",
|
|
5
5
|
"description": "Initialize standards-based agent configuration across agent harnesses",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "repobuddy"
|
|
@@ -17,7 +17,7 @@ Diagnose it:
|
|
|
17
17
|
node scripts/doctor.mjs
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
That path is relative to this skill's own directory: `scripts/doctor.mjs` is a self-contained bundle built from this package's source and shipped inside the skill folder through the npm package, so it runs against the current working directory with nothing downloaded and no `node_modules` needed. Fall back to `npx -y buddy-agent-harness@^0.
|
|
20
|
+
That path is relative to this skill's own directory: `scripts/doctor.mjs` is a self-contained bundle built from this package's source and shipped inside the skill folder through the npm package, so it runs against the current working directory with nothing downloaded and no `node_modules` needed. Fall back to `npx -y buddy-agent-harness@^0.18.0 doctor` when `scripts/doctor.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.
|
|
21
21
|
|
|
22
22
|
The command is read-only. It never repairs anything, so it is safe to run at any point, including from a session-start hook.
|
|
23
23
|
|
|
@@ -27,6 +27,8 @@ The command is read-only. It never repairs anything, so it is safe to run at any
|
|
|
27
27
|
|
|
28
28
|
`instructions` is everything standing between a harness and `AGENTS.md`, with a `status` of `ok`, `missing`, `unbridged`, `unreadable`, `shadowing`, or `superseded`. The last two are not bridges: they are files that suppress an `AGENTS.md` the harness would otherwise read by itself. A separate section because nothing about any of them is shared with `bridges`: a different `kind`, a different status vocabulary, and a repair that is never a command.
|
|
29
29
|
|
|
30
|
+
`globalInstructions` is the same question one level up: whether each harness installed for this user loads `~/.agents/AGENTS.md` through its own user-scope file, with a `status` of `ok`, `missing`, `unbridged`, or `overridden`. No harness reads that file by itself, so text placed there reaches only the harnesses whose row is `ok`. The rows are there whether or not the file exists; a finding is raised only when it exists and goes unread.
|
|
31
|
+
|
|
30
32
|
`findings` explains each problem and carries more than the two sections above: the configuration, MCP, and non-standard findings have no section of their own, because they are about files rather than about bridges. `help` carries each repair, one row per distinct repair, with two columns:
|
|
31
33
|
|
|
32
34
|
- `command` — a shell invocation that, run exactly as given, **completes** the repair.
|
|
@@ -50,6 +52,7 @@ Every `problem` name routes to exactly one page. Load the page for the finding i
|
|
|
50
52
|
| --- | --- |
|
|
51
53
|
| `references/bridges.md` | any `bridges` row that is not `ok` |
|
|
52
54
|
| `references/instructions.md` | any `instructions` row that is not `ok` |
|
|
55
|
+
| `references/global-instructions.md` | any `globalInstructions` row that is not `ok` |
|
|
53
56
|
| `references/configuration.md` | a finding about the configuration around the bridges rather than a bridge |
|
|
54
57
|
| `references/mcp.md` | any finding whose path is an MCP locator — **always** before acting on a credential finding |
|
|
55
58
|
| `references/nonstandard.md` | a finding about configuration only one harness can read |
|
|
@@ -61,4 +64,5 @@ Every `problem` name routes to exactly one page. Load the page for the finding i
|
|
|
61
64
|
- Edit skills at `.agents/skills/<name>/SKILL.md`. Editing through a bridge is only safe when that bridge is a symlink.
|
|
62
65
|
- Do not add bridges to `.gitignore`. An untracked bridge swallows a real edit silently.
|
|
63
66
|
- Never repeat a value from a file an `mcp-literal-secret` or `mcp-committed-secret` finding points at. The report withheld it on purpose, and quoting it back puts it in the transcript anyway.
|
|
67
|
+
- Never write outside the repository. A `globalInstructions` repair is a step for the user to take in their own home directory; hand it over exactly as reported.
|
|
64
68
|
- Write instructions in `AGENTS.md`, never in `CLAUDE.md`. Content written there reaches one harness, drifts from the canonical file, and — because Claude Code prefers it — takes `AGENTS.md` out of that harness's context entirely.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
|
|
2
|
+
|
|
3
|
+
# Global instruction findings
|
|
4
|
+
|
|
5
|
+
`~/.agents/AGENTS.md` is the user-scope counterpart of the root `AGENTS.md`: instructions that hold in every repository one person opens. No harness reads it by itself. Each reads a user-scope file of its own, and that file has to load the global one — by an import where the harness supports one that reaches the home directory, and otherwise by being a symlink to it.
|
|
6
|
+
|
|
7
|
+
| Harness | User-scope file | What loads `~/.agents/AGENTS.md` |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `claude-code` | `~/.claude/CLAUDE.md` | add the line `@~/.agents/AGENTS.md` to ~/.claude/CLAUDE.md |
|
|
10
|
+
| `codex` | `~/.codex/AGENTS.md` | run `ln -s ~/.agents/AGENTS.md ~/.codex/AGENTS.md` |
|
|
11
|
+
| `copilot-cli` | `~/.copilot/copilot-instructions.md` | run `ln -s ~/.agents/AGENTS.md ~/.copilot/copilot-instructions.md` |
|
|
12
|
+
| `gemini-cli` | `~/.gemini/GEMINI.md` | run `ln -s ~/.agents/AGENTS.md ~/.gemini/GEMINI.md` |
|
|
13
|
+
|
|
14
|
+
Cursor keeps its user rules in a settings panel rather than a file, so there is nothing on disk to check; Devin Desktop documents no user-scope path. Neither gets a row.
|
|
15
|
+
|
|
16
|
+
A harness's directory can be moved by a variable: `CLAUDE_CONFIG_DIR` for `claude-code` (`~/.claude`), `CODEX_HOME` for `codex` (`~/.codex`), `COPILOT_HOME` for `copilot-cli` (`~/.copilot`). Where one is set and non-empty, the row and the step name the file under it, written from the variable — `$CODEX_HOME/AGENTS.md` — so the step works in the shell the user ran `doctor` from.
|
|
17
|
+
|
|
18
|
+
| Finding | What it means | Repair |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| `global-instructions-missing` | no user-scope instruction file at this path — the harness loads none of ~/.agents/AGENTS.md | hand the user the step the harness page names for that file; write nothing yourself |
|
|
21
|
+
| `global-instructions-unbridged` | the file holds its own content and does not load ~/.agents/AGENTS.md — text placed there reaches no session of this harness | hand the user the step the harness page names for that file, keeping what the file says; write nothing yourself |
|
|
22
|
+
| `global-instructions-overridden` | the harness reads this file in place of its own user-scope file, so whatever that file loads goes unread, and this one does not load ~/.agents/AGENTS.md | hand the user the move of what that file says into the global file, and its removal; write nothing yourself |
|
|
23
|
+
|
|
24
|
+
**Hand the step over; never take it.** The file is in the user's home directory, outside the repository this tool works in, so every repair carries an empty `command` and names the step for the user to take themselves.
|
|
25
|
+
|
|
26
|
+
`unbridged` is the one to read carefully. The file is there and holds instructions of its own, so the harness loads something — just not the global file. Where the bridge is a symlink, the file it replaces holds content that has to move into `~/.agents/AGENTS.md` first, or it is lost.
|
|
27
|
+
|
|
28
|
+
`overridden` is the quietest. The user-scope file may be bridged perfectly and still go unread, because the harness reads another file in its place: Codex reads `AGENTS.override.md` before `AGENTS.md`, and uses whichever first holds more than whitespace. The finding names that file. Its content moves into `~/.agents/AGENTS.md` before it is removed; where the user-scope file has a problem of its own, that finding is reported beside it, so both steps are handed over at once.
|
|
29
|
+
|
|
30
|
+
A row is reported for every harness installed for this user, whether or not `~/.agents/AGENTS.md` exists, so a skill handing text over for that file can say which harnesses will load it. A finding is raised only where the file exists and a harness is not loading it.
|
|
@@ -16,13 +16,14 @@ Where `doctor` looks inside a repository.
|
|
|
16
16
|
|
|
17
17
|
## User scope
|
|
18
18
|
|
|
19
|
-
Described, never written: `init` and `doctor`
|
|
19
|
+
Described, never written: `init` works inside a repository, and `doctor` reads only the instruction bridge here, to report whether it loads `~/.agents/AGENTS.md`.
|
|
20
20
|
|
|
21
21
|
| What | Path |
|
|
22
22
|
| --- | --- |
|
|
23
23
|
| detection directory | `.claude` |
|
|
24
24
|
| skills projection | `.claude/skills` — written by `init` |
|
|
25
|
-
| instruction bridge |
|
|
25
|
+
| instruction bridge | `.claude/CLAUDE.md` — the line `@~/.agents/AGENTS.md`, which loads `~/.agents/AGENTS.md` |
|
|
26
|
+
| moved by | `CLAUDE_CONFIG_DIR` — set and non-empty, it replaces `.claude`, and every path under it moves with it |
|
|
26
27
|
| MCP configuration | none |
|
|
27
28
|
|
|
28
29
|
## Configuration only this harness reads
|
|
@@ -15,13 +15,15 @@ Where `doctor` looks inside a repository.
|
|
|
15
15
|
|
|
16
16
|
## User scope
|
|
17
17
|
|
|
18
|
-
Described, never written: `init` and `doctor`
|
|
18
|
+
Described, never written: `init` works inside a repository, and `doctor` reads only the instruction bridge here, to report whether it loads `~/.agents/AGENTS.md`.
|
|
19
19
|
|
|
20
20
|
| What | Path |
|
|
21
21
|
| --- | --- |
|
|
22
22
|
| detection directory | `.codex` |
|
|
23
23
|
| skills projection | none — reads `.agents/skills` natively |
|
|
24
|
-
| instruction bridge |
|
|
24
|
+
| instruction bridge | `.codex/AGENTS.md` — a symlink to `~/.agents/AGENTS.md`, since no import this file supports reaches it |
|
|
25
|
+
| moved by | `CODEX_HOME` — set and non-empty, it replaces `.codex`, and every path under it moves with it |
|
|
26
|
+
| suppresses `AGENTS.md` | `.codex/AGENTS.override.md` — this harness reads `AGENTS.md` itself, and reads one of these instead where it finds one |
|
|
25
27
|
| MCP configuration | none |
|
|
26
28
|
|
|
27
29
|
## Configuration only this harness reads
|
|
@@ -15,13 +15,14 @@ Where `doctor` looks inside a repository.
|
|
|
15
15
|
|
|
16
16
|
## User scope
|
|
17
17
|
|
|
18
|
-
Described, never written: `init` and `doctor`
|
|
18
|
+
Described, never written: `init` works inside a repository, and `doctor` reads only the instruction bridge here, to report whether it loads `~/.agents/AGENTS.md`.
|
|
19
19
|
|
|
20
20
|
| What | Path |
|
|
21
21
|
| --- | --- |
|
|
22
22
|
| detection directory | `.copilot` |
|
|
23
23
|
| skills projection | none — reads `.agents/skills` natively |
|
|
24
|
-
| instruction bridge |
|
|
24
|
+
| instruction bridge | `.copilot/copilot-instructions.md` — a symlink to `~/.agents/AGENTS.md`, since no import this file supports reaches it |
|
|
25
|
+
| moved by | `COPILOT_HOME` — set and non-empty, it replaces `.copilot`, and every path under it moves with it |
|
|
25
26
|
| MCP configuration | none |
|
|
26
27
|
|
|
27
28
|
## Configuration only this harness reads
|
|
@@ -15,7 +15,7 @@ Where `doctor` looks inside a repository.
|
|
|
15
15
|
|
|
16
16
|
## User scope
|
|
17
17
|
|
|
18
|
-
Described, never written: `init` and `doctor`
|
|
18
|
+
Described, never written: `init` works inside a repository, and `doctor` reads only the instruction bridge here, to report whether it loads `~/.agents/AGENTS.md`.
|
|
19
19
|
|
|
20
20
|
| What | Path |
|
|
21
21
|
| --- | --- |
|
|
@@ -15,13 +15,13 @@ Where `doctor` looks inside a repository.
|
|
|
15
15
|
|
|
16
16
|
## User scope
|
|
17
17
|
|
|
18
|
-
Described, never written: `init` and `doctor`
|
|
18
|
+
Described, never written: `init` works inside a repository, and `doctor` reads only the instruction bridge here, to report whether it loads `~/.agents/AGENTS.md`.
|
|
19
19
|
|
|
20
20
|
| What | Path |
|
|
21
21
|
| --- | --- |
|
|
22
22
|
| detection directory | `.gemini` |
|
|
23
23
|
| skills projection | none — reads `.agents/skills` natively |
|
|
24
|
-
| instruction bridge |
|
|
24
|
+
| instruction bridge | `.gemini/GEMINI.md` — a symlink to `~/.agents/AGENTS.md`, since no import this file supports reaches it |
|
|
25
25
|
| MCP configuration | none |
|
|
26
26
|
|
|
27
27
|
## Configuration only this harness reads
|