@dzhechkov/adapter-agents-md 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dzhechko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @dzhechkov/adapter-agents-md
+
+The **AGENTS.md** platform adapter for [DZ Harness Hub](https://github.com/djd1m/dz-harness-hub) — flattens canonical skills into a single, root-level `AGENTS.md`.
+
+```bash
+dz init --target agents-md --select design-thinking
+```
+
+## What it emits
+
+`AGENTS.md` is the emerging cross-tool convention read by ~15 agents (Cursor, Zed, Warp, Aider, goose, Gemini CLI, RooCode, Kilo, Junie, Trae, Augment, Devin, pi, Windsurf, …). It is one **root-level, plain-Markdown** file — no YAML frontmatter, no per-skill directory:
+
+```
+AGENTS.md   # a plain-Markdown "## <skill>" section per selected skill, inside a dz-managed fenced block
+```
+
+Unlike the skill-tree adapters (one directory per skill) and unlike copilot (one instruction file **per** skill), one `AGENTS.md` holds **all** selected skills.
+
+## Intentionally lossy — and merge-not-overwrite
+
+Like copilot, this is a **lossy** adapter. AGENTS.md loses:
+
+- **YAML frontmatter** — the section is plain Markdown;
+- **progressive disclosure** — the whole section is always-on;
+- **per-skill file boundaries** — every skill collapses into one file;
+- **assets** — `scripts/`/`references/` are not carried.
+
+Because `AGENTS.md` is often **hand-authored**, aggregation into the real file (at the operations layer) uses `@dzhechkov/core`'s `mergeAgentsMd`, which owns only a fenced block:
+
+```
+<!-- dz:skills BEGIN (managed by dz — do not edit) -->
+…skill sections…
+<!-- dz:skills END -->
+```
+
+Everything **outside** the fence is preserved byte-for-byte. The merge is idempotent.
+
+Per the `@dzhechkov/core` `Adapter` contract the loss surfaces as a **warning**; under `strict` the adapter **throws**. The canonical skill stays the lossless source of truth — recompiling to `claude` is still full fidelity.

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@dzhechkov/adapter-agents-md` — the `AGENTS.md` platform adapter.
+ *
+ * `AGENTS.md` is the emerging cross-tool convention read by ~15 agents (Cursor,
+ * Zed, Warp, Aider, goose, Gemini CLI, RooCode, Kilo, Junie, Trae, Augment,
+ * Devin, pi, Windsurf, …): a SINGLE, root-level, PLAIN-Markdown file — NO YAML
+ * frontmatter, NO per-skill directory.
+ *
+ * Like {@link https://github.com/features/copilot | copilot} this is an
+ * intentionally **lossy** adapter (frontmatter + progressive disclosure +
+ * per-skill file boundaries are flattened away). UNLIKE copilot — which emits
+ * one instruction file PER skill — AGENTS.md is ONE file for ALL selected
+ * skills. This adapter's `compile` therefore emits just the rendered SECTION for
+ * a single skill at path `AGENTS.md`; the aggregation across skills and the
+ * merge-not-overwrite into any user-authored AGENTS.md happens at the
+ * operations layer via `core`'s {@link mergeAgentsMd}.
+ *
+ * Per the {@link Adapter} contract, loss surfaces as a warning; under `strict`
+ * it throws. The canonical skill stays the lossless source of truth.
+ *
+ * @packageDocumentation
+ */
+import type { Adapter } from '@dzhechkov/core';
+/** The single, root-level file every AGENTS.md-aware tool reads. */
+export declare const AGENTS_MD_PATH = "AGENTS.md";
+/** Package version. Kept in sync with `package.json`. */
+export declare const ADAPTER_AGENTS_MD_VERSION = "0.1.0";
+/**
+ * The `AGENTS.md` adapter — an intentionally **lossy**, **flattening**
+ * {@link Adapter}. `compile` renders ONE skill as a plain-Markdown section at
+ * `AGENTS.md`; the ops layer aggregates + merges these into the real file.
+ */
+export declare const agentsMdAdapter: Adapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EACV,OAAO,EAMR,MAAM,iBAAiB,CAAC;AAEzB,oEAAoE;AACpE,eAAO,MAAM,cAAc,cAAc,CAAC;AAE1C,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,OAiD7B,CAAC"}

package/dist/index.js

@@ -0,0 +1,79 @@
+/**
+ * `@dzhechkov/adapter-agents-md` — the `AGENTS.md` platform adapter.
+ *
+ * `AGENTS.md` is the emerging cross-tool convention read by ~15 agents (Cursor,
+ * Zed, Warp, Aider, goose, Gemini CLI, RooCode, Kilo, Junie, Trae, Augment,
+ * Devin, pi, Windsurf, …): a SINGLE, root-level, PLAIN-Markdown file — NO YAML
+ * frontmatter, NO per-skill directory.
+ *
+ * Like {@link https://github.com/features/copilot | copilot} this is an
+ * intentionally **lossy** adapter (frontmatter + progressive disclosure +
+ * per-skill file boundaries are flattened away). UNLIKE copilot — which emits
+ * one instruction file PER skill — AGENTS.md is ONE file for ALL selected
+ * skills. This adapter's `compile` therefore emits just the rendered SECTION for
+ * a single skill at path `AGENTS.md`; the aggregation across skills and the
+ * merge-not-overwrite into any user-authored AGENTS.md happens at the
+ * operations layer via `core`'s {@link mergeAgentsMd}.
+ *
+ * Per the {@link Adapter} contract, loss surfaces as a warning; under `strict`
+ * it throws. The canonical skill stays the lossless source of truth.
+ *
+ * @packageDocumentation
+ */
+import { assertSafeId, renderAgentsMdSection } from '@dzhechkov/core';
+/** The single, root-level file every AGENTS.md-aware tool reads. */
+export const AGENTS_MD_PATH = 'AGENTS.md';
+/** Package version. Kept in sync with `package.json`. */
+export const ADAPTER_AGENTS_MD_VERSION = '0.1.0';
+/**
+ * The `AGENTS.md` adapter — an intentionally **lossy**, **flattening**
+ * {@link Adapter}. `compile` renders ONE skill as a plain-Markdown section at
+ * `AGENTS.md`; the ops layer aggregates + merges these into the real file.
+ */
+export const agentsMdAdapter = {
+    platform: 'agents-md',
+    compile(skill, ctx) {
+        // Defend at the adapter boundary — ids are not guaranteed safe at this layer.
+        try {
+            assertSafeId(skill.id);
+        }
+        catch (err) {
+            return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
+        const files = [
+            {
+                path: AGENTS_MD_PATH,
+                encoding: 'utf-8',
+                content: renderAgentsMdSection(skill),
+            },
+        ];
+        const lossy = `agents-md is a lossy target: "${skill.id}" is flattened into a plain-Markdown ` +
+            `section of a single root-level AGENTS.md (YAML frontmatter, progressive disclosure, ` +
+            `and per-skill file boundaries are dropped; scripts/ and other assets are not carried).`;
+        if (ctx.strict === true) {
+            return Promise.reject(new Error(`adapter-agents-md: refusing lossy compile under strict mode — ${lossy}`));
+        }
+        return Promise.resolve({ files, warnings: [lossy] });
+    },
+    verify(emit) {
+        const errors = [];
+        // Carry the lossy-compile warning(s) through so `dz verify --target agents-md`
+        // never reports skills as clean with no loss notice (mirrors copilot).
+        const warnings = [...emit.warnings];
+        const file = emit.files.find((f) => f.path === AGENTS_MD_PATH);
+        if (!file) {
+            errors.push(`no ${AGENTS_MD_PATH} was emitted`);
+        }
+        else {
+            if (file.content.trim().length === 0) {
+                errors.push(`${AGENTS_MD_PATH} is empty`);
+            }
+            // AGENTS.md is PLAIN Markdown — it must NOT open with a YAML frontmatter fence.
+            if (/^?---[ \t]*\r?\n/.test(file.content)) {
+                errors.push(`${AGENTS_MD_PATH} must be plain Markdown with no leading "---" frontmatter fence`);
+            }
+        }
+        return Promise.resolve({ ok: errors.length === 0, errors, warnings });
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAUtE,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;AAE1C,yDAAyD;AACzD,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAY;IACtC,QAAQ,EAAE,WAAW;IACrB,OAAO,CAAC,KAAqB,EAAE,GAAmB;QAChD,8EAA8E;QAC9E,IAAI,CAAC;YACH,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,KAAK,GAAiB;YAC1B;gBACE,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,qBAAqB,CAAC,KAAK,CAAC;aACtC;SACF,CAAC;QAEF,MAAM,KAAK,GACT,iCAAiC,KAAK,CAAC,EAAE,uCAAuC;YAChF,sFAAsF;YACtF,wFAAwF,CAAC;QAC3F,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,iEAAiE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC7G,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,IAAgB;QACrB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,+EAA+E;QAC/E,uEAAuE;QACvE,MAAM,QAAQ,GAAa,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE9C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,CAAC,IAAI,CAAC,MAAM,cAAc,cAAc,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,GAAG,cAAc,WAAW,CAAC,CAAC;YAC5C,CAAC;YACD,gFAAgF;YAChF,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3C,MAAM,CAAC,IAAI,CAAC,GAAG,cAAc,iEAAiE,CAAC,CAAC;YAClG,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACxE,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@dzhechkov/adapter-agents-md",
+  "version": "0.1.1",
+  "description": "AGENTS.md platform adapter - flattens canonical skills into a single root-level AGENTS.md (plain Markdown, no frontmatter; intentionally lossy, merge-not-overwrite).",
+  "type": "module",
+  "license": "MIT",
+  "author": "dzhechko",
+  "keywords": [
+    "agent-skills",
+    "agents-md",
+    "agents.md",
+    "adapter",
+    "harness"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@dzhechkov/core": "0.2.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "yaml": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/djd1m/dz-harness-hub.git",
+    "directory": "packages/@dzhechkov/adapter-agents-md"
+  },
+  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/adapter-agents-md#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+/**
+ * `@dzhechkov/adapter-agents-md` — the `AGENTS.md` platform adapter.
+ *
+ * `AGENTS.md` is the emerging cross-tool convention read by ~15 agents (Cursor,
+ * Zed, Warp, Aider, goose, Gemini CLI, RooCode, Kilo, Junie, Trae, Augment,
+ * Devin, pi, Windsurf, …): a SINGLE, root-level, PLAIN-Markdown file — NO YAML
+ * frontmatter, NO per-skill directory.
+ *
+ * Like {@link https://github.com/features/copilot | copilot} this is an
+ * intentionally **lossy** adapter (frontmatter + progressive disclosure +
+ * per-skill file boundaries are flattened away). UNLIKE copilot — which emits
+ * one instruction file PER skill — AGENTS.md is ONE file for ALL selected
+ * skills. This adapter's `compile` therefore emits just the rendered SECTION for
+ * a single skill at path `AGENTS.md`; the aggregation across skills and the
+ * merge-not-overwrite into any user-authored AGENTS.md happens at the
+ * operations layer via `core`'s {@link mergeAgentsMd}.
+ *
+ * Per the {@link Adapter} contract, loss surfaces as a warning; under `strict`
+ * it throws. The canonical skill stays the lossless source of truth.
+ *
+ * @packageDocumentation
+ */
+
+import { assertSafeId, renderAgentsMdSection } from '@dzhechkov/core';
+import type {
+  Adapter,
+  CanonicalSkill,
+  CompileContext,
+  EmitResult,
+  SkillAsset,
+  VerifyResult,
+} from '@dzhechkov/core';
+
+/** The single, root-level file every AGENTS.md-aware tool reads. */
+export const AGENTS_MD_PATH = 'AGENTS.md';
+
+/** Package version. Kept in sync with `package.json`. */
+export const ADAPTER_AGENTS_MD_VERSION = '0.1.0';
+
+/**
+ * The `AGENTS.md` adapter — an intentionally **lossy**, **flattening**
+ * {@link Adapter}. `compile` renders ONE skill as a plain-Markdown section at
+ * `AGENTS.md`; the ops layer aggregates + merges these into the real file.
+ */
+export const agentsMdAdapter: Adapter = {
+  platform: 'agents-md',
+  compile(skill: CanonicalSkill, ctx: CompileContext): Promise<EmitResult> {
+    // Defend at the adapter boundary — ids are not guaranteed safe at this layer.
+    try {
+      assertSafeId(skill.id);
+    } catch (err) {
+      return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+
+    const files: SkillAsset[] = [
+      {
+        path: AGENTS_MD_PATH,
+        encoding: 'utf-8',
+        content: renderAgentsMdSection(skill),
+      },
+    ];
+
+    const lossy =
+      `agents-md is a lossy target: "${skill.id}" is flattened into a plain-Markdown ` +
+      `section of a single root-level AGENTS.md (YAML frontmatter, progressive disclosure, ` +
+      `and per-skill file boundaries are dropped; scripts/ and other assets are not carried).`;
+    if (ctx.strict === true) {
+      return Promise.reject(new Error(`adapter-agents-md: refusing lossy compile under strict mode — ${lossy}`));
+    }
+    return Promise.resolve({ files, warnings: [lossy] });
+  },
+
+  verify(emit: EmitResult): Promise<VerifyResult> {
+    const errors: string[] = [];
+    // Carry the lossy-compile warning(s) through so `dz verify --target agents-md`
+    // never reports skills as clean with no loss notice (mirrors copilot).
+    const warnings: string[] = [...emit.warnings];
+
+    const file = emit.files.find((f) => f.path === AGENTS_MD_PATH);
+    if (!file) {
+      errors.push(`no ${AGENTS_MD_PATH} was emitted`);
+    } else {
+      if (file.content.trim().length === 0) {
+        errors.push(`${AGENTS_MD_PATH} is empty`);
+      }
+      // AGENTS.md is PLAIN Markdown — it must NOT open with a YAML frontmatter fence.
+      if (/^?---[ \t]*\r?\n/.test(file.content)) {
+        errors.push(`${AGENTS_MD_PATH} must be plain Markdown with no leading "---" frontmatter fence`);
+      }
+    }
+
+    return Promise.resolve({ ok: errors.length === 0, errors, warnings });
+  },
+};