Add AGENTS.md authoring/review tooling (agentsmd-author, agentsmd-audit, provider-adapter-author) #79

New Issue

Claude · 2026-07-23T16:54:57Z

Claude commented

2026-07-23 16:54:57 +00:00

Context

kyberforge is scoped to meta-tooling for building/maintaining the holocron marketplace itself (skills, agents, plugins, marketplace entries) — not generic capabilities for an arbitrary target repo. Authoring/reviewing a target repo's AGENTS.md file is repo-agnostic documentation tooling, so it belongs outside kyberforge. See ADR-0012 (docs/adr/0012-agentsmd-tooling-in-core-plugin.md) for the full decision record. Research backing this was done in advance at plugins/core/docs/research/docs/agentsmd/ (overview.md, configuration.md, examples.md, sources.md — sourced from the official agents.md spec).

Plan — three new skills in the `core` plugin (core's first active skills)

agentsmd-author — creates/updates a target repo's AGENTS.md, including nested monorepo placement (nearest-file-wins precedence per the spec). Closes out by invoking agentsmd-audit inline (mirrors the skill-author/skill-audit pattern). When it detects an existing provider-specific file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) with content duplicating what AGENTS.md should own, it calls provider-adapter-author via skill composition.
agentsmd-audit — single combined pass, three mandatory checks against AGENTS.md only:
- secrets/credentials (governance.md hard prohibition — AGENTS.md is committed content)
- structural completeness (common-sections checklist: setup, code style, testing, security, PR conventions)
- accuracy/drift (do referenced commands/paths actually resolve against the repo)
  Never inspects provider adapter files.
provider-adapter-author — detects/converts a provider-specific instruction file into a thin adapter importing AGENTS.md (mirrors this repo's own two-tier CLAUDE.md pattern, ADR-0002/0003). Self-validates via its own bundled deterministic script (scripts/validate-adapter.sh: checks for import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — no LLM judgment needed for this mechanical check.

Build order

agentsmd-audit first (no deps) → provider-adapter-author (no deps) → agentsmd-author (depends on both existing, since it invokes/composes into them).

Each of the three skills will be authored via kyberforge:skill-author and independently re-audited via a clean-context skill-audit recheck per the standard forge workflow.

This is a planning/documentation issue only — no implementation is included here.

## Context kyberforge is scoped to meta-tooling for building/maintaining the holocron marketplace itself (skills, agents, plugins, marketplace entries) — not generic capabilities for an arbitrary target repo. Authoring/reviewing a target repo's AGENTS.md file is repo-agnostic documentation tooling, so it belongs outside kyberforge. See ADR-0012 (`docs/adr/0012-agentsmd-tooling-in-core-plugin.md`) for the full decision record. Research backing this was done in advance at `plugins/core/docs/research/docs/agentsmd/` (overview.md, configuration.md, examples.md, sources.md — sourced from the official agents.md spec). ## Plan — three new skills in the `core` plugin (core's first active skills) 1. **`agentsmd-author`** — creates/updates a target repo's AGENTS.md, including nested monorepo placement (nearest-file-wins precedence per the spec). Closes out by invoking `agentsmd-audit` inline (mirrors the `skill-author`/`skill-audit` pattern). When it detects an existing provider-specific file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) with content duplicating what AGENTS.md should own, it calls `provider-adapter-author` via skill composition. 2. **`agentsmd-audit`** — single combined pass, three mandatory checks against AGENTS.md only: - secrets/credentials (governance.md hard prohibition — AGENTS.md is committed content) - structural completeness (common-sections checklist: setup, code style, testing, security, PR conventions) - accuracy/drift (do referenced commands/paths actually resolve against the repo) Never inspects provider adapter files. 3. **`provider-adapter-author`** — detects/converts a provider-specific instruction file into a thin adapter importing AGENTS.md (mirrors this repo's own two-tier CLAUDE.md pattern, ADR-0002/0003). Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — no LLM judgment needed for this mechanical check. ## Build order `agentsmd-audit` first (no deps) → `provider-adapter-author` (no deps) → `agentsmd-author` (depends on both existing, since it invokes/composes into them). Each of the three skills will be authored via `kyberforge:skill-author` and independently re-audited via a clean-context `skill-audit` recheck per the standard forge workflow. --- This is a planning/documentation issue only — no implementation is included here.

Claude added the Kind/Feature

Priority

Medium

3

labels 2026-07-23 16:54:57 +00:00

Claude referenced a pull request that will close this issue

2026-07-23 17:33:14 +00:00

feat(core): add AGENTS.md authoring/review tooling #80

Defame1297 closed this issue

2026-07-23 17:46:09 +00:00

Sign in to join this conversation.