From 6cc1ebd76f898531a760d6030e8b4a4e07ed23ae Mon Sep 17 00:00:00 2001 From: jprisant <6282841+jprisant@users.noreply.github.com> Date: Sat, 20 Jun 2026 00:49:47 -0700 Subject: [PATCH] docs: add repo AGENTS.md + CLAUDE.md (dogfood D5/D10) + repo-health review - AGENTS.md: the neutral repo now models the cross-tool context convention it governs (what this repo is, commands, guardrails, where things live, a pointer to OVERVIEW.md). CLAUDE.md is a thin shim referencing it. - docs/internal/2026-06-20_repo-health-review.md: a registry conformance snapshot (the GP-6 lag is now visible: tfs at plugin v0.11.0 but Standard pin 0.8) plus the deferred recommendations with reasons (_agent-context dissolution, registry standard/tier surfacing, re-pin automation, pin-currency policy, casing). agent-plugins-only; additive; nothing touches other repos or the schema'd registry. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 42 +++++++++++++++++++ CLAUDE.md | 5 +++ .../internal/2026-06-20_repo-health-review.md | 41 ++++++++++++++++++ 3 files changed, 88 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 docs/internal/2026-06-20_repo-health-review.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61c1307 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# AGENTS.md - agent-plugins + +Orientation for any agent (Claude Code, Codex, or other) working in this repository. This is the canonical, tool-agnostic context file; `CLAUDE.md` is a thin shim that points here. + +## What this repo is + +`agent-plugins` is the **Product on Purpose marketplace registry** and the **neutral home of the family's standards governance**. It is deliberately NOT a plugin (it has no `library.json`): it hosts the marketplace catalog, the listing contract, the Standard's governance, and the cross-repo orchestration and convergence program. It is the one repo in the family that can neutrally own the law the member plugins must obey. + +The four member plugins it lists live in their own repos: `pm-skills`, `thinking-framework-skills`, `writing-style-catalog`, `agent-skills-toolkit`. + +## Commands + +- **Validate the registry:** `node scripts/validate-registry.mjs` (CI runs it via `.github/workflows/validate-registry.yml`; set `GITHUB_TOKEN` to raise the API rate limit). This checks each marketplace entry resolves, versions agree, and the metadata version is consistent. +- The family **conformance runner** (the 30-check gate that grades plugins) currently lives in `agent-skills-toolkit/scripts/`; it relocates into `standards/checks/` in Phase 0 of the standards roadmap (see below). It does not grade this repo (this repo is not a plugin). + +## Guardrails + +- **`main` is PR-protected:** branch, open a PR, squash-merge; the `validate` check gates every merge. Never push to `main` directly. +- **Family writing rule:** never use em-dashes (U+2014) or en-dashes (U+2013); use `" - "` (space hyphen space) or restructure. This is enforced by a hook and applies to every file. +- **Reference IDs carry a human-readable handle** on first use (for example "D5 (dissolve _agent-context)", not bare "D5"). +- **Re-pinning a plugin** (advancing its `sha`/`version` in the registry) follows the re-pin convention in [`CONTRIBUTING.md`](CONTRIBUTING.md) Section 5 (L4) and "The re-pin checklist": bump `metadata.version`, add a `CHANGELOG.md` entry, keep versions consistent. Do not hand-edit a `sha` without the checklist. +- **Listing contract:** what makes a repo listable is [`CONTRIBUTING.md`](CONTRIBUTING.md) clauses L1-L6 (binds the Standard by version pin, never restates it). + +## Where things live + +| Path | What | +|---|---| +| `.claude-plugin/marketplace.json` | the registry: the four plugins pinned by `sha` + `version` | +| `CONTRIBUTING.md` | the listing contract (L1-L6) + the re-pin checklist | +| `standards/` | the Standard's governance: `GOVERNANCE.md` (amendment lifecycle), `decisions/` (family-law ADRs, starting at 0001), `domains/astro-sites/` (the first graduated domain). The Standard text + checks relocate here in Phase 0. | +| `docs/internal/` | program docs: `program-roadmap.md`, `registry-maintenance.md`, `orchestration/`, `convergence/`, `audits/`, and `standards-plan-roadmap/` (the standards roadmap package) | +| `docs/internal/standards-plan-roadmap/` | the standards program: `OVERVIEW.md` (read this for the WHY), `02-roadmap.md` (the 6 phases), `03-decisions.md` (the 17 locked decisions), `06-tier-requirements.md` (Bronze/Silver/Gold), `plans/` (Phase 0 plan + change manifest), `spikes/`, `drafts/` | +| `scripts/validate-registry.mjs` | the registry validator | +| `_local/` | gitignored scratch (per decision D6; note the on-disk dir is currently `_LOCAL` pending the D6 casing convergence - `_LOCAL` and `_local` collide on a case-insensitive filesystem, which is why D6 standardizes on lowercase) | + +## Start here for the why + +For the full reasoning behind the standards system - decouple-and-pin, the tiers, governance, cross-tool targeting, and the 17 decisions - read [`docs/internal/standards-plan-roadmap/OVERVIEW.md`](docs/internal/standards-plan-roadmap/OVERVIEW.md). + +## Conventions in flux (this repo is a convergence target) + +The family is converging on a shared scaffolding standard (decisions D5/D6 in the roadmap package). For this repo that means: the casing settles to lowercase `_local/`, and the `_agent-context/` directory is slated for dissolution (session logs move to gitignored `_local/session-logs/`). These land through the governance lifecycle, not unilaterally; until then `_agent-context/session-logs/` remains the committed convention here. See the standards-plan-roadmap package for the decisions. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2272659 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# CLAUDE.md + +This repository's agent guidance lives in [`AGENTS.md`](AGENTS.md), the canonical tool-agnostic context file (per decision D10, cross-tool targeting: one `AGENTS.md` source, thin per-tool shims, never divergent copies). + +Read [`AGENTS.md`](AGENTS.md) first. It covers what this repo is, the commands, the guardrails (PR-protected `main`, the no-dash writing rule, the re-pin convention), and where everything lives. diff --git a/docs/internal/2026-06-20_repo-health-review.md b/docs/internal/2026-06-20_repo-health-review.md new file mode 100644 index 0000000..e4840d3 --- /dev/null +++ b/docs/internal/2026-06-20_repo-health-review.md @@ -0,0 +1,41 @@ +# Repo health review - agent-plugins (2026-06-20) + +A point-in-time review of this repository's own health, beyond the standards roadmap. It records what was executed in this pass (all scoped to `agent-plugins` only), a registry conformance snapshot for visibility, and the recommendations deliberately deferred with their reasons. Companion: the standards program lives in [`standards-plan-roadmap/`](standards-plan-roadmap/00-README.md). + +## Scope + +Only `agent-plugins` changes. Nothing here touches `agent-skills-toolkit`, the org `.github` repo, or the other plugins, and nothing modifies the Anthropic-schema'd `marketplace.json` or pre-empts a governance-lifecycle decision. + +## Executed in this pass + +1. **Dogfooded the cross-tool context convention (D5/D10).** Added a root [`AGENTS.md`](../../AGENTS.md) (canonical, tool-agnostic orientation) and a thin [`CLAUDE.md`](../../CLAUDE.md) shim that references it. The neutral repo that governs the family's dual-audience standard now models it: what this repo is, the commands, the guardrails (PR-protected `main`, the no-dash rule, the re-pin convention), and a map of where everything lives, with a pointer to `OVERVIEW.md` for the why. Additive only; this repo is not a plugin, so the conformance runner does not grade it. +2. **Branch hygiene.** Deleted stale branches left behind by squash-merged PRs (re-pin and docs branches). The live work is all in `main`; the deletions remove clutter only. + +## Registry conformance snapshot + +Registry `metadata.version` 1.27.0. The plugin `version` (advanced on each re-pin) is distinct from the Standard `pin` (each plugin's own `library.json` `standard`, adopted on its own cadence) - the gap between them is the version-pin lag (GP-6). + +| Plugin | Plugin version | Standard pin | Tier | Listing notes | +|---|---|---|---|---| +| agent-skills-toolkit | 1.6.0 | **0.12** (current) | advanced (Gold) | the self-proving reference; owns the Standard until Phase 0 relocation | +| thinking-framework-skills | 0.11.0 | **0.8** (4 minors behind) | advanced (Gold) | GP-6 lag: actively re-pinned for plugin version, but the Standard pin has not advanced; 81 post-0.8 findings surface as warnings | +| writing-style-catalog | 0.2.0 | **0.11** | universal (Bronze) | one minor behind | +| pm-skills | 2.26.0 | **none** | n/a | **P0**: no `library.json`, so it cannot pin the Standard at all + ships an embedded self-listing marketplace (GP-1, GP-2; Phase 1) | + +Reading: only `agent-skills-toolkit` is current; `pm-skills` is invisible to the governance system until it gains a `library.json`; `tfs` shows the unbounded-lag problem. This is the visibility the registry itself does not yet surface (see deferred item 2). + +## Deferred (documented, with reasons) + +These are real improvements, intentionally NOT done in this pass: + +1. **Dissolve this repo's `_agent-context/` (D5).** `agent-plugins` still commits `_agent-context/session-logs/` (the split pattern D5 retires). NOT done unilaterally: it is a ratified-clause + push-campaign item (roadmap Phase 3), and moving committed session-log history into gitignored `_local/` removes provenance from git - a maintainer decision that should go through the governance lifecycle, not a drive-by edit. The new `AGENTS.md` documents this repo as a convergence target. +2. **Surface `standard` + `tier` in the registry itself.** `marketplace.json` shows `name`/`sha`/`version`/`strict` but not the Standard pin or tier, so a consumer cannot see conformance state at a glance. NOT done by editing `marketplace.json`: it carries the Anthropic `marketplace.schema.json`, and adding non-standard fields risks `claude plugin validate` and the loader. The canonical surfacing mechanism (extra fields vs a generated companion `INDEX`/badge) is a Phase 2 design decision. The snapshot above is the interim visibility surface. +3. **Re-pin automation.** The `CHANGELOG` is dominated by manual `chore(marketplace): re-pin ...` PRs. A scheduled or dispatch workflow that opens a re-pin PR when a plugin tags a release would cut recurring toil. NOT done: it is a feature needing design (it must read other repos' tags via the GitHub API and open PRs), so it belongs in a spec, not an unprompted build. Recommended as a backlog item. +4. **A pin-currency policy + drift surfacing (GP-6).** There is no bound on how far a plugin's Standard pin may lag (tfs is 4 minors behind). A SHOULD-level "re-pin within N minors," surfaced by the existing `validate-registry` workflow, would make lag visible and bounded. NOT done: a SHOULD clause is a Standard amendment (lifecycle), and the surfacing ties to deferred item 2. Recommended; ties to GP-6. +5. **Casing convergence `_LOCAL` -> `_local` (D6).** Both names resolve to one directory on a case-insensitive filesystem (the live D6 footgun). NOT done here: it is part of the mechanical push campaign (D2/D6), best applied fleet-wide, not in one repo ahead of the others. + +## Confidence and notes + +- The executed changes are **additive and low-risk** (two new root docs + branch deletions); they cannot break the registry or the gate. +- The snapshot is **accurate as of `metadata.version` 1.27.0**; it is a point-in-time read, not a living surface (a living surface is deferred item 2). +- The deferred items are deferred on principle, not omission: each either touches another repo, the schema'd registry, or a clause that must move through governance. They are captured here so they are not lost.