buddy-agent-harness 0.1.0

package/skills/init/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: init
+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 coding-agent harnesses.
+---
+
+# Harness Init
+
+Give the repository one canonical agent configuration — a root `AGENTS.md` and an `.agents/` tree — then bridge the harnesses that cannot read it directly.
+
+Most of the field already reads `.agents/skills/` natively: Codex, Cursor, GitHub Copilot CLI, and Devin Desktop need no projection at all. Only Claude Code and Gemini CLI read solely their own directory and need a link. Keep that asymmetry in mind — this is a consolidation job, not a copy-everywhere job.
+
+`references/standard.md` defines the baseline every repository gets. Read the file below for each harness you are enabling, and only those.
+
+| Harness | Skills projection | Instruction bridge | Read |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/skills` | `CLAUDE.md` with `@AGENTS.md` | `references/harnesses/claude-code.md` |
+| Gemini CLI | `.gemini/skills` | `.gemini/settings.json` edit | `references/harnesses/gemini-cli.md` |
+| Codex | none | none | `references/harnesses/codex.md` |
+| Cursor | none | none written; one gap to report | `references/harnesses/cursor.md` |
+| GitHub Copilot CLI | none | none | `references/harnesses/copilot-cli.md` |
+| Devin Desktop | none | none | `references/harnesses/devin-desktop.md` |
+
+`init` writes skills projections only. Every instruction bridge above is manual work in Phase 4.
+
+Work in five phases. Do not skip Phase 3.
+
+## 1. Survey
+
+Locate the Git repository root; the canonical configuration always lives there, including in a monorepo.
+
+Inventory both the canonical surface (`AGENTS.md`, `.agents/AGENTS.md`, `.agents/skills/`, and any nested `AGENTS.md` below the root) and every pre-existing harness artifact listed in `references/detection.md`. Read what you find. Write nothing yet.
+
+## 2. Classify
+
+Sort each finding into exactly one bucket:
+
+- **already canonical** — leave it. Nested `AGENTS.md` files belong here: they are scoped instructions, never content to merge upward.
+- **already linked** — a symlink resolving into `.agents/`; skip it. This is what makes re-runs idempotent.
+- **consolidatable** — harness instruction files whose content belongs in `AGENTS.md`.
+- **portable** — skill and command directories that move into `.agents/skills/`.
+- **canonical-only** — MCP servers, rules, subagents, hooks, output styles. No safe cross-harness mapping exists, so report them and leave them alone.
+
+## 3. Confirm
+
+Present the plan before touching anything the user wrote: what will be created, which content moves into `AGENTS.md`, which harness files would become pointers, any frontmatter to be added (show the derived `name` and `description` verbatim), which harnesses will be enabled, and what is being left alone and why.
+
+Get explicit approval before any step that deletes, replaces, or rewrites a user-authored file. Creating a missing directory, a missing `AGENTS.md`, or a `CLAUDE.md` bridge stub needs no approval, and neither does the non-material region in `references/agents-md.md` — report these rather than asking.
+
+One case does need asking even though it only creates a file: a nested `AGENTS.md` that reverses a root rule, where bridging it hands Claude Code a contradiction it has no rule for resolving. Raise that file, bridge the others, and keep going.
+
+## 4. Apply
+
+1. Scaffold the baseline in `references/standard.md`: `.agents/`, `.agents/skills/`, and a root `AGENTS.md` if absent. Never clobber an existing one. `references/agents-md.md` decides what belongs in that file — a repository with no instruction content still needs one derived and confirmed, not an empty heading.
+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. Run `npx -y buddy-agent-harness init` at the repository root. 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. If the command reports a conflict, resolve the named target and retry. Use `--force` only to replace that exact projection; use `--copy` only where links are unavailable — a copy is a snapshot, not a live projection, so say so when you fall back.
+6. Apply the instruction bridges `init` does not write. Claude Code reads `CLAUDE.md`, not `AGENTS.md` — create a `CLAUDE.md` containing `@AGENTS.md`. Gemini CLI needs `AGENTS.md` added to `context.fileName` in `.gemini/settings.json`. Both are detailed in the matching `references/harnesses/<harness>.md`; apply only the ones you enabled. Where nested `AGENTS.md` files exist, write the same stub in each directory holding one — `references/agents-md.md` covers the one case that stops for approval first.
+7. If any 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` 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.
+
+`init` is not a formatter. If the repository has one, run it over the written files and say so.
+
+## Rules
+
+- Never invent project policy, and never make a material change to a user's `AGENTS.md`. `references/agents-md.md` draws the line: a statement that would stop being true if `init`'s output were removed describes the tool's own artifact and is non-material.
+- Never convert tool settings between formats without a documented mapping. Unmapped settings stay canonical.
+- Symlinks belong in version control. Leave them tracked; do not add them to `.gitignore`.
+- Only `.agents/skills/` is an established convention. Do not invent `.agents/rules/`, `.agents/commands/`, or `.agents/agents/` and present 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, and only Claude Code reads them.
+- Local agent configuration only. Do not change workflows, GitHub Actions, repository settings, security scanning, branch rules, or unrelated project files.

package/skills/init/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Initialize Agent Harnesses"
+  short_description: "Link canonical skills across agent harnesses"
+  default_prompt: "Use $init to initialize canonical skills in this repository."

package/skills/init/references/agents-md.md

@@ -0,0 +1,131 @@
+# Deriving AGENTS.md
+
+What to put in `AGENTS.md`, and what to keep out of it.
+
+`AGENTS.md` is read on every session, so every line costs context each time. Include a line only when it changes what the agent does.
+
+## What counts as existing
+
+Derivation is the greenfield path. Take it only after establishing that no instruction content exists, which is not the same as no instruction file existing.
+
+**Existing means authored by a person and carrying content.** A file a previous run wrote is not existing content, and neither is an empty one.
+
+| Found | Read it as | Do |
+| --- | --- | --- |
+| root `AGENTS.md` with body content | the canonical file | never rewrite it. Derive nothing. Append only what the user approves, plus the non-material region below |
+| root `AGENTS.md` with nothing but a heading, or empty | a placeholder | treat as absent, derive, and confirm before filling it |
+| `.agents/AGENTS.md` with content | canonical shared instructions, not the root file | leave it alone. Do not derive anything that restates it, and do not merge it upward |
+| a harness instruction file with authored content — `CLAUDE.md`, `.cursorrules`, `.cursor/rules/**`, `.github/copilot-instructions.md`, `.github/instructions/**`, `GEMINI.md`, `.windsurfrules` | existing content | consolidate into `AGENTS.md` preserving the author's wording. Replace the original with a pointer only where approved |
+| `CLAUDE.md` whose whole body is `@AGENTS.md`, or a symlink to `AGENTS.md` | a bridge a previous run created | not content. Skip it — this is what makes re-runs idempotent |
+| a nested `AGENTS.md` — `apps/web/AGENTS.md`, `packages/<name>/AGENTS.md` | canonical instructions scoped to that subtree | leave it alone. Never merge it upward, never derive against it. See below |
+| none of the above | greenfield | derive, then confirm every surviving line |
+
+Both can be true at once: a repository can have a `.cursorrules` to consolidate *and* gaps worth deriving. Consolidate first, then derive only what the consolidated content does not already cover.
+
+Never make a material change to an existing `AGENTS.md`. Never invent policy in either case.
+
+## Nested AGENTS.md
+
+Nested files are part of the format: a subproject may carry its own `AGENTS.md`, and the standard's published rule is that the file closest to the one being edited wins.
+
+`init` never consolidates one upward. Merging a nested file into the root would change which files it applies to, turning subtree-scoped instructions into repository-wide ones. Report each nested file, leave it in place.
+
+Two things do need doing when Claude Code is enabled.
+
+**Bridge every nested file by default.** Claude Code reads `CLAUDE.md`, and the root bridge covers only the root file — instructions in `apps/web/AGENTS.md` reach Codex and Cursor and are invisible to Claude Code until `apps/web/CLAUDE.md` exists. Write one stub per directory holding a nested file, the same way the root stub is written and without asking. A relative `@AGENTS.md` resolves against the file containing the import, so the stub is byte-identical at every level. Report the set; do not enumerate it as a question.
+
+**Stop on a file that contradicts the root.** Bridging does not preserve the standard's nearest-wins rule — `references/harnesses/claude-code.md` has the model. A nested file that *adds* facts behaves the same everywhere and is safe to bridge unattended. One that *reverses* a root rule — "this package uses vitest, not jest" — is an override for Codex and a contradiction for Claude Code, so bridging it silently hands Claude two incompatible instructions with no rule for choosing.
+
+Read the root file and each nested file before writing stubs. For any nested file that negates, replaces, or narrows a root rule rather than adding to it, ask before bridging that one, and offer the three options: bridge it anyway and accept the ambiguity, reword the nested rule as additive so every harness agrees, or leave it unbridged so Claude Code keeps the root behavior. Bridge the rest without waiting on the answer.
+
+Report the comparison, not just the count. Name each nested file and say it was judged additive. This is the only check standing between a missed contradiction and a silently broken bridge, so it has to be reviewable — "wrote 12 stubs" is not.
+
+Do not resolve it by rewriting the user's nested file. Which option they want is policy.
+
+## Material and non-material changes
+
+The approval rule guards project content. It does not guard `init`'s own bookkeeping, and treating the two the same means the generated-bridge note either never gets written or gets buried in an approval prompt nobody reads.
+
+A change is **non-material** when the line describes what `init` created in this repository and asserts nothing about how the project works.
+
+The discriminator: **would the statement stop being true if `init`'s output were removed?**
+
+| Answer | Reading | Approval |
+| --- | --- | --- |
+| yes — it only holds because `init` ran | describes the tool's own artifact | write it; report it |
+| no — it holds regardless | project content: derived, inferred, or policy | approval, as always |
+
+`.claude/skills/ is generated by buddy-agent-harness init` is true only because a bridge exists. `Use pnpm` is true whether or not `init` ever ran. Only the first is non-material.
+
+Non-material writes are confined to a managed region so user prose is never touched:
+
+```markdown
+<!-- buddy-agent-harness:begin -->
+
+Skills are canonical in `.agents/skills/` — create and edit them there.
+`.claude/skills/` is a generated bridge to it; never write to it directly.
+`CLAUDE.md` is a generated pointer to this file. Shared instructions belong
+here; keep only Claude-specific notes there.
+
+<!-- buddy-agent-harness:end -->
+```
+
+Name the bridges this repository actually has, not the example above. Drop the `CLAUDE.md` line where no stub was written, and the skills line where no skills bridge exists — a warning about a path that does not exist teaches an agent to distrust the rest.
+
+- **Append-only.** Place the region at the end. Never reorder or remove what the user wrote.
+- **Idempotent.** A re-run rewrites the region in place. Two regions is a bug.
+- **Never silent.** Report the write, the same as any other change.
+- **Self-repairing.** A missing region is restored on the next run. Absence is not consent: the region is far more often lost to a rewrite, a merge resolution, or a pass trimming the file toward the line limit than removed on purpose — and what it protects is exactly what stops a copied bridge from forking.
+- **Emptying it opts out.** Markers with nothing between them are a deliberate choice; leave them empty. Deleting the markers is not, and gets the region back. This keeps the opt-out in the file it governs, where the person who wants it can see it.
+
+```markdown
+<!-- buddy-agent-harness:begin -->
+<!-- buddy-agent-harness:end -->
+```
+
+Nothing else qualifies. A fact read out of the codebase is material even when it feels obvious, and a policy stays material even when `init` is confident about it.
+
+## What earns a line
+
+Ask: **would the agent get this wrong, or spend tokens finding it?**
+
+| Keep | Cut |
+| --- | --- |
+| a constraint that fails the build in a non-obvious way | anything one cheap read away — `package.json` scripts, `tsconfig.json`, the file tree |
+| an ordered workflow with a step nobody would guess | anything a formatter, linter, or type checker already enforces |
+| a decision table resolving a real ambiguity between two plausible paths | anything the model already defaults to, such as "ask before deleting files" |
+| a short snippet from real code that shows the house pattern | architecture tours, history, and rationale |
+
+Pair every "don't" with a "do". A file of unpaired prohibitions makes an agent explore more and finish less.
+
+"We use TypeScript" in a repository full of `.ts` files is the shape to avoid. "Every exported binding needs an explicit type annotation or `typecheck` fails" is the shape to keep.
+
+## Derive
+
+1. Read `package.json` (scripts, `engines`), the TypeScript, test, and lint configs, CI workflows, release configuration, and any existing `README.md`.
+2. List each candidate fact with the file it came from. A fact with no source is invention — drop it.
+3. Apply the test above. Most candidates fail it. Cut them.
+4. Show the user every surviving line beside its source, and get approval.
+5. Write only what was approved.
+
+If nothing survives, write the heading and a one-line statement of what the repository is, then stop. Do not pad to look complete.
+
+## Push the rest down
+
+| Content | Home |
+| --- | --- |
+| a procedure, or depth about one domain | a skill in `.agents/skills/` — only its `name` and `description` stay in context, and the body loads when the description matches |
+| payload a skill needs only sometimes | `references/` beside that `SKILL.md`, loaded on demand |
+| rationale, background, evidence | the documentation site, not agent context |
+
+A section of `AGENTS.md` that only some tasks need is a skill that has not been extracted yet.
+
+## Limits
+
+- Target under 150 lines. Past that, added lines cost more than they return.
+- State facts, not instructions, unless the user authored the instruction.
+- Derivable is not the same as worth including — a discoverable fact restated here goes stale the first time someone moves the file.
+
+## CLAUDE.md
+
+Claude Code does not read `AGENTS.md`. Create `CLAUDE.md` containing `@AGENTS.md` and nothing else, unless the user adds Claude-specific notes below the import. Never copy `AGENTS.md` content into it — two homes for one fact is how they diverge.

package/skills/init/references/detection.md

@@ -0,0 +1,34 @@
+# Detection
+
+What to look for during the survey, and where each finding belongs.
+
+| Class | Look for | Disposition |
+| --- | --- | --- |
+| Instructions | `AGENTS.md`, `.agents/AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.cursor/rules/**`, `.github/copilot-instructions.md`, `.github/instructions/**`, `GEMINI.md`, `.windsurfrules` | consolidate into `AGENTS.md`; confirm before replacing anything |
+| Nested instructions | `**/AGENTS.md` below the root, and any `**/CLAUDE.md` beside one | canonical and scoped — report, never merge upward. Bridging is per directory and per approval; see `agents-md.md` |
+| Skills | `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.github/skills/`, `.windsurf/skills/`, `.gemini/skills/` | move to `.agents/skills/`, fix frontmatter, then link back |
+| Commands | `.claude/commands/*.md`, `.cursor/commands/*.md` | move to `.agents/skills/<name>/SKILL.md`. Claude Code has merged commands into skills, so this follows the harness rather than fighting it |
+| Subagents | `.claude/agents/` | canonical-only — no cross-harness format exists. Report; leave in place |
+| Rules | `.cursor/rules/**.mdc`, `.claude/rules/`, `.windsurf/rules/` | canonical-only — `.mdc` and `.md` are not interchangeable, and path-scoping syntax differs. Report |
+| MCP servers | `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.claude/settings.json` | canonical-only. Report; never convert between formats |
+| Hooks, LSP, output styles | hook blocks in settings files, `.claude/output-styles/` | canonical-only. Hook event names differ by case across harnesses, so no safe projection exists. Report |
+
+For every entry, record which of three states it is in:
+
+- a real file or directory the user authored,
+- a symlink already resolving into `.agents/` — a previous run, skip it,
+- something occupying a projection target that is neither — a conflict to surface in Phase 3.
+
+## Choosing harnesses
+
+The enabled set is the union of three sources: Claude Code and Cursor unconditionally, any harness whose detection directory already exists, and any the user names with `--harness`. `init` detects the second group itself — you do not need to pass it.
+
+There is no way to disable a harness. Never offer the user a choice that excludes Claude Code or Cursor; `init` enables them whatever the answer, so the question would be a fiction.
+
+Enabling a harness is not the same as writing files for it. Most enabled harnesses read `.agents/skills/` natively and receive nothing — see the table in `SKILL.md` for which ones get a projection. Report both facts, because only the projections are a real diff.
+
+`init` records nothing on disk about a run. The enabled set is recomputed from detection every time, so a stored copy could only ever go stale or contradict what is actually there. The command's own output is the report — read it, do not look for a file.
+
+Antigravity and VS Code are native readers and are not registry entries — never write anything for them. Do not treat a `.vscode/` directory as a signal that any harness needs configuring.
+
+Detecting a harness directory means the repository has configuration to reconcile. It does not by itself mean the user wants that harness maintained — say which harnesses you are enabling and why, and let the user correct the part that is actually variable.

package/skills/init/references/frontmatter.md

@@ -0,0 +1,63 @@
+# Frontmatter for cross-harness skills
+
+Linking a skill into every harness is easy. Making it *behave* the same in every harness is not. Each harness parses the frontmatter fields it knows and silently drops the rest.
+
+## Required, everywhere
+
+```yaml
+---
+name: release-checklist
+description: Runs the release checklist. Use when cutting a release or publishing a package version.
+---
+```
+
+- `name` — 1–64 characters, lowercase letters, digits, and hyphens. No leading, trailing, or consecutive hyphens. **It must match the parent directory name.**
+- `description` — 1–1024 characters. Say what the skill does *and* when to use it; this is the only text most harnesses see when deciding whether to load it.
+
+## Two rules that decide whether a skill loads at all
+
+Harnesses are told to validate leniently, but the leniency is asymmetric:
+
+| Problem | Result |
+| --- | --- |
+| `name` does not match the directory | warning, still loads |
+| `name` longer than 64 characters | warning, still loads |
+| `description` missing or empty | **skill is skipped** |
+| YAML fails to parse | **skill is skipped** |
+
+So the two failures that actually cost you a skill are a missing description and broken YAML. The most common cause of broken YAML is an unquoted colon:
+
+```yaml
+# Breaks on strict parsers
+description: Use this skill when: the user asks about PDFs
+
+# Correct
+description: "Use this skill when: the user asks about PDFs"
+```
+
+**Quote any description containing a colon.** When migrating existing skills, check this first.
+
+Enforcing `name` == directory name is also worth doing even though it is only a warning: Claude Code ignores `name` for command resolution and uses the directory name, so matching them removes the discrepancy entirely.
+
+## Which harness understands which field
+
+| Field | Recognized by |
+| --- | --- |
+| `name`, `description` | all |
+| `license`, `metadata`, `compatibility` | accepted broadly, largely ignored |
+| `allowed-tools` | most; **not** Kiro CLI or Zencoder |
+| `context: fork`, `agent:` | Claude Code only |
+| `disable-model-invocation` | Claude Code, Cursor |
+| `paths`, legacy `globs` | Cursor only |
+| `model` | Copilot CLI only |
+| hook configuration | Claude Code, Cline, Kiro CLI |
+
+Codex additionally reads an `agents/openai.yaml` **sidecar file** beside `SKILL.md` — not frontmatter. See `harnesses/codex.md`; never add one unprompted.
+
+## What follows from that
+
+Claude Code has the largest field surface, so a skill authored for it and shared everywhere carries fields the other harnesses parse and discard. That is a small, unavoidable context cost — accept it rather than maintaining divergent copies.
+
+The cost that is *not* acceptable is silent behavior loss. **Anything that must hold on every harness has to be stated in the Markdown body, not only in a harness-specific field**, because the body is the one part every harness reads. Treat harness-specific frontmatter as an optimization layered on top of instructions that already work without it.
+
+When adding frontmatter to a skill that lacks it, derive `name` from the directory and `description` from the first heading or opening paragraph, then show the user the derived values for approval. If nothing usable can be derived, ask — never write a placeholder description, because a vague description is worse than the warning it silences.

package/skills/init/references/harnesses/claude-code.md

@@ -0,0 +1,51 @@
+# Claude Code
+
+Reads neither `.agents/skills/` nor `AGENTS.md`. **Both bridges are required.**
+
+## Bridge 1 — skills
+
+`buddy-agent-harness init` creates this:
+
+```
+.claude/skills → ../.agents/skills
+```
+
+If the directory-level link ever fails, fall back to documented per-skill symlinks (`.claude/skills/<name>` → the canonical skill directory).
+
+## Bridge 2 — instructions
+
+`init` does **not** do this. Create by hand:
+
+```markdown
+<!-- CLAUDE.md -->
+@AGENTS.md
+```
+
+Claude-specific notes may follow below the import.
+
+`ln -s AGENTS.md CLAUDE.md` also works, but **prefer the import** — on Windows a symlink needs Administrator or Developer Mode.
+
+## Nested instruction files
+
+Claude Code concatenates every `CLAUDE.md` from the filesystem root down to the working directory; the nearest is read last but does not win. The `AGENTS.md` standard says the nearest file wins. Conflicts are undefined here — the docs say Claude may pick one arbitrarily.
+
+So a nested `AGENTS.md` needs its own `CLAUDE.md` stub to be visible at all, and gets additive rather than override semantics once it has one. `references/agents-md.md` has the rule; do not bridge a nested file that reverses a root instruction without saying what will happen.
+
+## Frontmatter
+
+Claude Code recognizes the most fields (`context: fork`, `agent:`, `disable-model-invocation`, `once`, `${CLAUDE_SKILL_DIR}`). Other harnesses drop them silently.
+
+- Restate anything load-bearing in the Markdown body.
+- **Enforce `name` equal to the directory name.** Claude Code treats `name` as a display label only and resolves the command from the directory name; matching them removes the discrepancy.
+
+## Leave alone — canonical-only
+
+Report these and do not convert them:
+
+- `.claude/agents/` (subagents), `.claude/rules/`, `.claude/output-styles/`
+- hook blocks in `.claude/settings.json` — event names differ by case across harnesses
+- MCP server definitions
+
+## Commands
+
+`.claude/commands/*.md` are **portable** — migrate to `.agents/skills/<name>/SKILL.md`. Claude Code has merged commands into skills, so this follows the harness rather than fighting it.

package/skills/init/references/harnesses/codex.md

@@ -0,0 +1,13 @@
+# Codex
+
+**Write nothing.** Codex reads `.agents/skills/` and `AGENTS.md` natively, and walks up to the repository root on its own.
+
+- Do not create `.codex/skills` — it is redundant.
+- Detection directory is `.codex`. Its presence enables Codex in the config record and changes nothing on disk.
+- Apply `frontmatter.md` as normal. Codex requires `name` and `description`, and rejects unquoted colons like every other harness.
+
+## Optional sidecar
+
+Codex alone reads `agents/openai.yaml` inside a skill directory (display name, icons, brand color, `allow_implicit_invocation`, MCP dependencies).
+
+Never add one unprompted. If the user asks for it, restate anything load-bearing in the `SKILL.md` body — no other harness reads the sidecar.

package/skills/init/references/harnesses/copilot-cli.md

@@ -0,0 +1,16 @@
+# GitHub Copilot CLI
+
+**Write nothing.** Copilot CLI reads `.agents/skills/` and `AGENTS.md` natively.
+
+- Detection directory is `.github/skills` — **not** `.github`. A repository with `.github/` but no `.github/skills/` does not enable Copilot CLI by detection.
+- Copilot also reads `.claude/skills`, `.github/skills`, `CLAUDE.md`, and `GEMINI.md`. Do not create any of them for Copilot's benefit.
+
+## Instruction consolidation
+
+`.github/copilot-instructions.md` and `.github/instructions/**` are **consolidatable** — move their content into `AGENTS.md` and leave a pointer, with approval.
+
+This is safe here because Copilot has no mode that reads only the harness file. Do not assume the same for Cursor.
+
+## Frontmatter
+
+`model` is Copilot-only; `license` and `allowed-tools` are accepted. Keep anything load-bearing in the body — see `frontmatter.md`.

package/skills/init/references/harnesses/cursor.md

@@ -0,0 +1,23 @@
+# Cursor
+
+**Write no skills projection.** Cursor reads `.agents/skills/` natively, plus `.cursor/skills/` and compat reads of `.claude/skills/` and `.codex/skills/`.
+
+Cursor is enabled unconditionally alongside Claude Code, so it appears in the config record whether or not `.cursor/` exists. That record changes nothing on disk.
+
+## Report the instruction gap
+
+Cursor reads `AGENTS.md` in **Agent mode only**. Chat and Composer read `.cursorrules` and `.cursor/rules/*.mdc` instead.
+
+Tell the user: a repository that consolidates into `AGENTS.md` keeps its instructions in Agent mode and loses them in Chat and Composer.
+
+**Report this as contested.** It is secondary-sourced, not confirmed from Cursor's own documentation. Do not state it as settled fact.
+
+## Do not
+
+- **Do not generate `.cursor/rules/*.mdc` from `AGENTS.md`.** Rules are canonical-only — `.mdc` and `.md` are not interchangeable and path-scoping has no `AGENTS.md` equivalent.
+- **Do not delete or rewrite `.cursorrules` or `.cursor/rules/**` on the assumption that `AGENTS.md` covers them.** In Chat and Composer it does not.
+- Do not assert whether Cursor's `.agents/skills` discovery recurses into nested subdirectories. It is untested.
+
+## Frontmatter
+
+`paths`, `disable-model-invocation`, and legacy `globs` are Cursor-recognized. Other harnesses drop them — keep load-bearing behavior in the body, per `frontmatter.md`.

package/skills/init/references/harnesses/devin-desktop.md

@@ -0,0 +1,19 @@
+# Devin Desktop (formerly Windsurf)
+
+**Write nothing.** Devin Desktop reads `.agents/skills/` natively — it is the recommended path of the nine it scans.
+
+Windsurf was rebranded to Devin Desktop on 2026-06-02. Use `devin-desktop`; `windsurf` still works as a deprecated alias.
+
+## The alias
+
+`--harness windsurf` enables a legacy entry that still creates `.windsurf/skills → ../.agents/skills`. Devin also scans `.windsurf/skills/`, so the projection works — it is redundant, not broken.
+
+- For a new repository, use `--harness devin-desktop` and write nothing.
+- If a repository already has a `.windsurf/skills` link, leave it. Report it as legacy compatibility, and mention the rename.
+- `init` reports any enabled deprecated name in its `deprecated` result field. Surface that to the user.
+
+## Instructions
+
+Whether Devin Desktop reads `AGENTS.md` is **not established**. Do not assert it either way, and do not write an instruction bridge for it.
+
+`.windsurfrules` and `.windsurf/rules/` are **canonical-only**. Report them and leave them in place.

package/skills/init/references/harnesses/gemini-cli.md

@@ -0,0 +1,33 @@
+# Gemini CLI
+
+Reads `.agents/skills` at **user scope only**. At project scope it reads `.gemini/skills/` and nothing else, so **both bridges are required**.
+
+Do not enable Gemini CLI speculatively — unlike Cursor, enabling it writes a real directory and symlink. Enable it only via `--harness gemini-cli` or a pre-existing `.gemini/` directory.
+
+## Bridge 1 — skills
+
+`buddy-agent-harness init` creates this when `gemini-cli` is enabled:
+
+```
+.gemini/skills → ../.agents/skills
+```
+
+## Bridge 2 — instructions
+
+`init` does **not** do this, and it cannot be a link. Add `AGENTS.md` to `context.fileName` in `.gemini/settings.json`:
+
+```json
+{
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  }
+}
+```
+
+`AGENTS.md` is not in the default list. **Without this edit Gemini CLI gets no instructions at all** from a repository that consolidated into `AGENTS.md`.
+
+When the file already exists:
+
+- Get approval first — it is user-authored.
+- Add to the array; do not replace it. Preserve surrounding settings.
+- Keep `GEMINI.md` in the list if the repository still has one.

package/skills/init/references/standard.md

@@ -0,0 +1,26 @@
+# The standard baseline
+
+What to create in every repository, before any harness-specific work.
+
+## Create
+
+| Path | When |
+| --- | --- |
+| `AGENTS.md` at the repository root | if absent — never clobber an existing one; contents per `agents-md.md` |
+| `.agents/` | if absent |
+| `.agents/skills/<name>/SKILL.md` | one directory per skill; frontmatter per `frontmatter.md` |
+
+Optional, only when the repository already has content for them: `.agents/AGENTS.md` for shared behavior, and a skill's `scripts/`, `references/`, `assets/` subdirectories.
+
+## Constraints
+
+- **Do not create `.agents/rules/`, `.agents/commands/`, or `.agents/agents/`.** Only `.agents/skills/` is read by any harness. Creating the others and calling them standard is invention.
+- **Do not invent policy for `AGENTS.md`.** Write only content the user authored or approved. Deriving facts from the repository is not invention; asserting rules nobody agreed to is. See `agents-md.md`.
+- Call `.agents/` a convention, not a standard, in any user-facing output.
+- `AGENTS.md` has no schema and no required sections. Do not impose one.
+
+## Next
+
+Three harnesses need nothing beyond this baseline. `SKILL.md` has the table of which need augmentation; read only the matching `harnesses/<harness>.md`.
+
+Background on where these formats come from: [Open Standards](https://repobuddy.github.io/buddy-agent-harness/agent-configuration/open-standards/).

package/src/cli.ts

@@ -0,0 +1,16 @@
+import { cli } from 'clibuilder'
+import { initCommand } from './initialize-harnesses/init.command.ts'
+
+export async function main(): Promise<void> {
+	const app = cli({
+		name: 'buddy-agent-harness',
+		version: '0.1.0',
+		description: 'Initialize agent harness skill compatibility in consumer repositories.',
+	})
+	try {
+		await app.command(initCommand).parse(process.argv)
+	} catch (error) {
+		process.stdout.write(`error: ${error instanceof Error ? error.message : 'Invalid command.'}\n`)
+		process.exitCode = 2
+	}
+}

package/src/harness-registry/harness-registry.ts

@@ -0,0 +1,60 @@
+import { lstatSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type HarnessName =
+	| 'claude-code'
+	| 'cursor'
+	| 'codex'
+	| 'copilot-cli'
+	| 'gemini-cli'
+	| 'devin-desktop'
+	| 'windsurf'
+
+/**
+ * `skillsDirectory` is the projection target a harness needs to see `.agents/skills`.
+ * A harness that reads `.agents/skills` natively has none, and is never projected into.
+ */
+export type Harness = {
+	name: HarnessName
+	detect: string
+	skillsDirectory?: string
+	/** Set when this name has been superseded; the value is the name that replaces it. */
+	deprecated?: HarnessName
+}
+
+/**
+ * Codex, Cursor, Copilot CLI, and Devin Desktop read `.agents/skills` directly, so they need no
+ * projection. Only Claude Code and Gemini CLI read solely their own directory.
+ *
+ * `windsurf` is the former name of Devin Desktop, rebranded 2026-06-02. It is retained as a
+ * deprecated alias: Devin still scans the legacy `.windsurf/skills` path, so its projection keeps
+ * working, but new repositories should enable `devin-desktop` and have nothing written for them.
+ *
+ * See `.research/agentic-configuration-standards/` for the per-harness sources.
+ */
+export const harnessRegistry: readonly Harness[] = [
+	{ name: 'claude-code', detect: '.claude', skillsDirectory: '.claude/skills' },
+	{ name: 'cursor', detect: '.cursor' },
+	{ name: 'codex', detect: '.codex' },
+	{ name: 'copilot-cli', detect: '.github/skills' },
+	{ name: 'gemini-cli', detect: '.gemini', skillsDirectory: '.gemini/skills' },
+	{ name: 'devin-desktop', detect: '.devin' },
+	{ name: 'windsurf', detect: '.windsurf', skillsDirectory: '.windsurf/skills', deprecated: 'devin-desktop' },
+]
+
+/** Enabled whether or not the repository already contains their directories. */
+const defaultHarnesses: readonly HarnessName[] = ['claude-code', 'cursor']
+
+function directoryExists(path: string): boolean {
+	try {
+		return lstatSync(path).isDirectory()
+	} catch {
+		return false
+	}
+}
+
+/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
+export function selectHarnesses(root: string, preferred: readonly HarnessName[]): Harness[] {
+	const enabled = new Set<HarnessName>([...defaultHarnesses, ...preferred])
+	return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.detect)))
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export type { HarnessName } from './harness-registry/harness-registry.ts'
+export { harnessRegistry } from './harness-registry/harness-registry.ts'
+export { activate, harnessCommand, initCommand } from './initialize-harnesses/init.command.ts'
+export type { InitializeOptions, InitializeResult } from './initialize-harnesses/initialize-harnesses.ts'
+export { initializeHarnesses } from './initialize-harnesses/initialize-harnesses.ts'