diff --git a/.agents/skills/create-adapter/SKILL.md b/.agents/skills/create-adapter/SKILL.md index d7c949ca0..7947dae32 100644 --- a/.agents/skills/create-adapter/SKILL.md +++ b/.agents/skills/create-adapter/SKILL.md @@ -1,6 +1,8 @@ --- name: create-evlog-adapter description: Create a new built-in evlog adapter to send wide events to an external observability platform. Use when adding a new drain adapter (e.g., for Elasticsearch, Honeycomb, SigNoz, etc.) to the evlog package. Covers source code, build config, package exports, tests, e2e, and all documentation. +metadata: + internal: true --- # Create evlog Adapter @@ -29,7 +31,7 @@ Recent examples: `feat(loki): add the Grafana Loki drain adapter`, `feat(clickho | 6 | `packages/evlog/test/toolkit/__snapshots__/api-surface.test.ts.snap` | Regenerated by running the tests after a build (`pnpm run build` then `pnpm test`) | | 7 | `apps/docs/content/4.integrate/adapters/{category}/{NN}.{name}.md` | Create adapter doc page in the right category | | 8 | `apps/docs/content/4.integrate/adapters/01.overview.md` | Add adapter to overview (frontmatter link + card) | -| 9 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Add adapter row in the Drain Adapters table + frontmatter description | +| 9 | `skills/review-logging-patterns/SKILL.md` | Add adapter row in the Drain Adapters table + frontmatter description | | 10 | `.changeset/{name}-adapter.md` | Create changeset (`minor`) describing the adapter | | 11 | `.github/workflows/semantic-pull-request.yml` + `.github/pull_request_template.md` | Register `{name}` as a PR scope in both files | @@ -166,7 +168,7 @@ Edit `apps/docs/content/4.integrate/adapters/01.overview.md` in **two** places ( ## Step 8: Update the Public Skill -In `apps/docs/skills/review-logging-patterns/SKILL.md` (published on evlog.dev via `/.well-known/skills/`): +In `skills/review-logging-patterns/SKILL.md` (published on evlog.dev via `/.well-known/skills/`): 1. Add a row to the **Drain Adapters** table: `| {Name} | evlog/{name} | {NAME}_API_KEY, ... |` 2. Add the adapter name to the `description:` line in the YAML frontmatter diff --git a/.agents/skills/create-enricher/SKILL.md b/.agents/skills/create-enricher/SKILL.md index d900f0981..91b716cec 100644 --- a/.agents/skills/create-enricher/SKILL.md +++ b/.agents/skills/create-enricher/SKILL.md @@ -1,6 +1,8 @@ --- name: create-evlog-enricher description: Create a new built-in evlog enricher to add derived context to wide events. Use when adding a new enricher (e.g., for deployment metadata, tenant context, feature flags, etc.) to the evlog package. Covers source code, tests, and all documentation. +metadata: + internal: true --- # Create evlog Enricher @@ -23,7 +25,7 @@ Enrichers live in the core package surface (`evlog/enrichers`), so use the `core | 2 | Same file — `createDefaultEnrichers()` | Decide whether the enricher belongs in the default composition (see below) | | 3 | `packages/evlog/test/toolkit/enrichers.test.ts` | Add tests (one `describe` block per enricher) | | 4 | `apps/docs/content/5.use-cases/5.enrichers.md` | Add a section for the enricher + update the import list and, if applicable, the "All built-in enrichers" default composition text | -| 5 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Add the enricher to the `Built-in:` line in the Enrichers section | +| 5 | `skills/review-logging-patterns/SKILL.md` | Add the enricher to the `Built-in:` line in the Enrichers section | | 6 | `packages/evlog/README.md` | Add the enricher to the Built-in Enrichers section (root `README.md` is a symlink to it) | | 7 | `.changeset/{name}-enricher.md` | Create changeset (`minor`) | @@ -119,7 +121,7 @@ Custom-enricher authoring docs live separately at `apps/docs/content/6.extend/5. ## Step 4: Update the Public Skill -In `apps/docs/skills/review-logging-patterns/SKILL.md` (published on evlog.dev), find the **Enrichers** section and add the new enricher to the `Built-in:` line. +In `skills/review-logging-patterns/SKILL.md` (published on evlog.dev), find the **Enrichers** section and add the new enricher to the `Built-in:` line. ## Step 5: Update README diff --git a/.agents/skills/create-framework-integration/SKILL.md b/.agents/skills/create-framework-integration/SKILL.md index dd254b2d1..4a999ffc4 100644 --- a/.agents/skills/create-framework-integration/SKILL.md +++ b/.agents/skills/create-framework-integration/SKILL.md @@ -1,6 +1,8 @@ --- name: create-evlog-framework-integration description: Create a new evlog framework integration to add automatic wide-event logging to an HTTP framework. Use when adding middleware/plugin support for a framework (e.g., Koa, H3 standalone, Deno Fresh, etc.) to the evlog package. Covers source code, build config, package exports, tests, example app, and all documentation. +metadata: + internal: true --- # Create evlog Framework Integration @@ -45,7 +47,7 @@ feat({framework}): add {Framework} middleware integration | 8 | `apps/docs/content/1.start/3.installation.md` | Add card in "Choose Your Framework" | | 9 | `apps/docs/content/0.landing.md` | Add framework code snippet slot | | 10 | `apps/docs/app/components/features/FeatureFrameworks.vue` | Add framework tab | -| 11 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Add framework setup section + update frontmatter description | +| 11 | `skills/review-logging-patterns/SKILL.md` | Add framework setup section + update frontmatter description | | 12 | `packages/evlog/README.md` | Add framework section + row in the Framework Support table | | 13 | `examples/{framework}/` | Create example app with test UI (auto-discovered by `pnpm example {framework}` — no root script needed) | | 14 | `.changeset/{framework}-integration.md` | Create changeset (`minor`) | @@ -287,7 +289,7 @@ Icons use Simple Icons format: `i-simple-icons-{name}`. ## Step 9: Update the Public Skill -In `apps/docs/skills/review-logging-patterns/SKILL.md` (published on evlog.dev): +In `skills/review-logging-patterns/SKILL.md` (published on evlog.dev): 1. Add `### {Framework}` in the **"Framework Setup"** section, in the same order as the docs 2. Include: import + `initLogger` + middleware setup; native logger access; a `useLogger()` snippet, or the accessor that replaces it when the integration has no ALS; full pipeline example (`drain`, `enrich`, `keep`) diff --git a/.agents/skills/create-map-rule/SKILL.md b/.agents/skills/create-map-rule/SKILL.md index f46670733..2f2767055 100644 --- a/.agents/skills/create-map-rule/SKILL.md +++ b/.agents/skills/create-map-rule/SKILL.md @@ -1,6 +1,8 @@ --- name: create-evlog-map-rule description: Add a new rule or a new framework adapter to `evlog map` in @evlog/cli. Use when adding a coverage check (requirement or opportunity) that scores entry points, or when extending the map scanner to a new framework. Covers rule source, registry, types, tests, docs, and the published skill. +metadata: + internal: true --- # Create an `evlog map` Rule (or Framework Adapter) @@ -43,7 +45,7 @@ Current requirements: `wide-event` (40), `audit` (25), `structured-errors` (20), | 4 | `packages/cli/test/map/rules.test.ts` | Add cases (the file has an ESLint-`RuleTester`-style `Case` harness — `runRuleSet` exercises one rule in isolation) | | 5 | `apps/docs/content/3.cli/3.rules.md` | Add a row to the Requirements or Opportunities table + a `### {title}` section | | 6 | `apps/docs/content/3.cli/4.scoring.md` | Requirements only: reflect the new weight in the scoring explanation | -| 7 | `apps/docs/skills/review-logging-patterns/references/code-review.md` | Add a row to the matching rules table | +| 7 | `skills/review-logging-patterns/references/code-review.md` | Add a row to the matching rules table | | 8 | `.changeset/{id}-map-rule.md` | Changeset for `"@evlog/cli": minor` | **Important**: Do NOT consider the task complete until all applicable touchpoints have been addressed. @@ -118,7 +120,7 @@ Read `apps/docs/AGENTS.md` before touching anything under `apps/docs/`. Then in ## Step 7: Published Skill -`apps/docs/skills/review-logging-patterns/references/code-review.md` mirrors the rules tables (requirements + opportunities) and maps each rule to a skill section. Add the row and, if the rule promotes a feature the skill documents elsewhere, link the section. +`skills/review-logging-patterns/references/code-review.md` mirrors the rules tables (requirements + opportunities) and maps each rule to a skill section. Add the row and, if the rule promotes a feature the skill documents elsewhere, link the section. ## Step 8: Changeset @@ -149,7 +151,7 @@ Teaching `evlog map` a new framework is a different, heavier change: the adapter | 5 | `packages/cli/test/map/adapters.test.ts` + `detect.test.ts` + `fixtures/` | Route extraction + detection tests against a fixture tree | | 6 | `packages/cli/src/lib/init/` | Decide whether `evlog init` gains the framework too (separate scope of work — flag it explicitly in the PR if not) | | 7 | `apps/docs/content/3.cli/2.map.md` + `0.overview.md` | Update the supported-frameworks statements | -| 8 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Update every "Nuxt, Nitro, Next.js, and TanStack Start" list (frontmatter description + CLI section) — same in `references/code-review.md` and `apps/docs/skills/build-audit-logs/SKILL.md` (Pass 2) and `analyze-logs/SKILL.md` (init suggestion) | +| 8 | `skills/review-logging-patterns/SKILL.md` | Update every "Nuxt, Nitro, Next.js, and TanStack Start" list (frontmatter description + CLI section) — same in `references/code-review.md` and `skills/build-audit-logs/SKILL.md` (Pass 2) and `analyze-logs/SKILL.md` (init suggestion) | | 9 | `scripts/cli-sandbox.mjs` | Add the framework to `APPS` (reuse the map fixture) so `pnpm cli:sandbox` covers it and `--smoke` exercises every CLI command against it | | 10 | `.changeset/{framework}-map-adapter.md` | Changeset for `"@evlog/cli": minor` | diff --git a/.agents/skills/write-evlog-content/SKILL.md b/.agents/skills/write-evlog-content/SKILL.md index cd03e5f52..2b29aa830 100644 --- a/.agents/skills/write-evlog-content/SKILL.md +++ b/.agents/skills/write-evlog-content/SKILL.md @@ -1,6 +1,8 @@ --- name: write-evlog-content -description: Write, review, and rewrite any evlog content: a docs page, the landing, a blog post, a package README, a skill, an AGENTS.md, a changeset. Load before drafting or editing prose in apps/docs/content, before writing a blog post, before touching a SKILL.md or an AGENTS.md, and whenever content is reviewed for voice, accuracy, or AI-generated slop. Carries the evlog voice, the atomic rules, the terminology, the competitor dossiers, and the AI-tell corpus with the legitimate twin for each tell. +description: "Write, review, and rewrite any evlog content: a docs page, the landing, a blog post, a package README, a skill, an AGENTS.md, a changeset. Load before drafting or editing prose in apps/docs/content, before writing a blog post, before touching a SKILL.md or an AGENTS.md, and whenever content is reviewed for voice, accuracy, or AI-generated slop. Carries the evlog voice, the atomic rules, the terminology, the competitor dossiers, and the AI-tell corpus with the legitimate twin for each tell." +metadata: + internal: true --- # Writing evlog content @@ -41,7 +43,7 @@ Everything evlog ships as prose, on both sides of the line: | Read by | Surfaces | What decides quality | | --- | --- | --- | | People | docs pages, the landing, blog posts, the package READMEs | Whether the reader can act, and whether they believe the page | -| Agents | `.agents/skills/`, `apps/docs/skills/`, the `AGENTS.md` files | Whether an agent does the right thing having read only this | +| Agents | `.agents/skills/`, `skills/`, the `AGENTS.md` files | Whether an agent does the right thing having read only this | The house rules cross the line: punctuation, terminology, accuracy, dead links. Rhythm does not. A skill whose four steps read as four parallel imperatives is a procedure, and the scanner leaves rhythm alone there. See `rules/machine.md`. diff --git a/.agents/skills/write-evlog-content/references/rules/machine.md b/.agents/skills/write-evlog-content/references/rules/machine.md index d1308df81..85f5d70b6 100644 --- a/.agents/skills/write-evlog-content/references/rules/machine.md +++ b/.agents/skills/write-evlog-content/references/rules/machine.md @@ -1,6 +1,6 @@ # Rules for the surfaces an agent reads -Applies to `.agents/skills/`, `apps/docs/skills/`, and every `AGENTS.md`. Read `universal.md` first: the house rules hold here too, punctuation included. +Applies to `.agents/skills/`, `skills/`, and every `AGENTS.md`. Read `universal.md` first: the house rules hold here too, punctuation included. What changes is who is reading. A docs page is read by someone who can tell that a sentence is vague and go look elsewhere. A skill is read by a model that will act on it, at the altitude the file sets, without the option of doubting it. So the failure modes invert: rhythm stops mattering, and precision, ordering, and scope start deciding outcomes. diff --git a/.agents/skills/write-evlog-content/references/surfaces/skill.md b/.agents/skills/write-evlog-content/references/surfaces/skill.md index 9b26c6f17..267a36504 100644 --- a/.agents/skills/write-evlog-content/references/surfaces/skill.md +++ b/.agents/skills/write-evlog-content/references/surfaces/skill.md @@ -3,7 +3,7 @@ Two sets, and they are not the same product. - `.agents/skills/` is internal. It is loaded by agents working in this repository, and it can assume the checkout, the commands, and the conventions. -- `apps/docs/skills/` is published, served from the docs site under `.well-known/skills`. It is loaded by someone else's agent, in someone else's repository, against evlog as a dependency. +- `skills/` is published, served from the docs site under `.well-known/skills`. It is loaded by someone else's agent, in someone else's repository, against evlog as a dependency. A skill written for one and moved to the other is wrong in both directions: the internal one leaks repo paths, the published one is vague about a codebase it should know. diff --git a/AGENTS.md b/AGENTS.md index 74d2b3290..bee2093cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,7 +48,8 @@ apps/docs/ Docus documentation site — has its own AGENTS.md apps/* Framework playgrounds (next, nitro, nitro-v2, nuxthub, lab, telemetry, ...) — `pnpm playground` to pick one examples/ ~22 runnable examples, one per framework — includes the community-*-skeleton dirs used by the create-adapter/enricher/framework skills scripts/ Repo tooling (run-app, cli-sandbox, release-notes, content-lint) -.agents/skills/ Internal skills for creating adapters, enrichers, and framework integrations, and for writing content +.agents/skills/ Internal skills for creating adapters, enrichers, and framework integrations, and for writing content — each carries `metadata: internal: true` in its frontmatter so the skills CLI skips them for public installs +skills/ Published skills (analyze-logs, build-audit-logs, review-logging-patterns) — served by the docs site via `/.well-known/skills/` and discovered by `npx skills add hugorcd/evlog` ``` ## Conventions @@ -68,7 +69,7 @@ scripts/ Repo tooling (run-app, cli-sandbox, release-notes, co - `.agents/skills/create-framework-integration/SKILL.md` - `.agents/skills/create-map-rule/SKILL.md` (also covers new `evlog map` framework adapters) - Writing or reviewing prose, a docs page, the landing, a blog post, a package README, a skill, an AGENTS.md, a changeset? Read `.agents/skills/write-evlog-content/SKILL.md` first, and run `pnpm content:lint ` before the review. It carries the voice, the atomic rules, the terminology, the competitor dossiers, and the AI-tell corpus with the legitimate twin for each tell. These files are content too: `pnpm content:lint --surface skill` and `--surface agents` rank them. -- **Skills must stay in sync with the code.** There are two sets: internal skills in `.agents/skills/` and published skills in `apps/docs/skills/` (served from the docs site via `.well-known/skills`). When a change touches something a skill documents (an adapter, enricher, integration, API surface, or workflow), update the affected SKILL.md (and its `references/`) in the same PR. A skill that describes the old behavior is worse than no skill. +- **Skills must stay in sync with the code.** There are two sets: internal skills in `.agents/skills/` and published skills in `skills/` at the repo root (served from the docs site via `.well-known/skills`, and discovered by a bare `npx skills add hugorcd/evlog`). When a change touches something a skill documents (an adapter, enricher, integration, API surface, or workflow), update the affected SKILL.md (and its `references/`) in the same PR. A skill that describes the old behavior is worse than no skill. ### Code style: no slop @@ -135,7 +136,7 @@ A task is complete when **all** of the following pass: 4. New public APIs have JSDoc 5. New exports are registered in `package.json#exports`, `package.json#typesVersions`, and `tsdown.config.ts` 6. If adapter/enricher/integration: the matching `.agents/skills/create-*/SKILL.md` was followed -7. Any skill (internal `.agents/skills/` or published `apps/docs/skills/`) documenting the changed behavior was updated in the same PR +7. Any skill (internal `.agents/skills/` or published `skills/`) documenting the changed behavior was updated in the same PR 8. A changeset is included for any user-facing change (`pnpm changeset`) ## Boundaries diff --git a/apps/docs/nuxt.config.ts b/apps/docs/nuxt.config.ts index 9624ae13d..49237766d 100644 --- a/apps/docs/nuxt.config.ts +++ b/apps/docs/nuxt.config.ts @@ -6,6 +6,16 @@ const contentCommitDates = readContentCommitDates(import.meta.dirname) export default defineNuxtConfig({ extends: ['docus'], + docus: { + skills: { + // The published skills live at the repo root (`skills/`) so a bare + // `npx skills add hugorcd/evlog` discovers them: the installer only scans + // conventional root-level directories. Docus defaults to `skills/` inside + // the app, so point it back at the shared source of truth. + dir: '../../skills', + }, + }, + experimental: { appManifest: true, emitRouteChunkError: 'automatic-immediate', diff --git a/apps/evi/agent/lib/content/selection.test.ts b/apps/evi/agent/lib/content/selection.test.ts index 7b6993607..1a1816ca8 100644 --- a/apps/evi/agent/lib/content/selection.test.ts +++ b/apps/evi/agent/lib/content/selection.test.ts @@ -29,8 +29,8 @@ describe('groupOf', () => { it('groups a skill by its own directory, not by the whole tree', () => { expect(groupOf(page('.agents/skills/create-adapter/references/test-template.md', 100, 0, 'skill'))) .toBe('.agents/skills/create-adapter') - expect(groupOf(page('apps/docs/skills/analyze-logs/SKILL.md', 100, 0, 'skill'))) - .toBe('apps/docs/skills/analyze-logs') + expect(groupOf(page('skills/analyze-logs/SKILL.md', 100, 0, 'skill'))) + .toBe('skills/analyze-logs') }) it('keeps the flat surfaces in one group each', () => { diff --git a/apps/evi/agent/skills/contributing/SKILL.md b/apps/evi/agent/skills/contributing/SKILL.md index 0975bd59d..d228cb4d5 100644 --- a/apps/evi/agent/skills/contributing/SKILL.md +++ b/apps/evi/agent/skills/contributing/SKILL.md @@ -18,7 +18,7 @@ What follows is the shape of the answer, so you know what to look for and what t - **The scope list is a closed set, and you read it before you write the title.** `.github/workflows/semantic-pull-request.yml` holds the only scopes CI accepts. Anything else fails `Validate PR title`, and a scope that merely sounds plausible (`evlog`, the package name, the app directory) is the usual way that happens. A change confined to `apps/docs` is `docs:`, with no scope: `docs` is already the type. - **A bug fix needs a failing regression test first**, then the fix. - **New exports** go in `packages/evlog/package.json` (`exports` and `typesVersions`) *and* `tsdown.config.ts`. -- **Skills must stay in sync.** If a change touches something a skill documents, the SKILL.md changes in the same PR, both the internal `.agents/skills/` and the published `apps/docs/skills/`. +- **Skills must stay in sync.** If a change touches something a skill documents, the SKILL.md changes in the same PR, both the internal `.agents/skills/` and the published `skills/`. ## The Definition of Done diff --git a/apps/evi/agent/skills/repo-health-sweep/SKILL.md b/apps/evi/agent/skills/repo-health-sweep/SKILL.md index fffb61616..6c04df299 100644 --- a/apps/evi/agent/skills/repo-health-sweep/SKILL.md +++ b/apps/evi/agent/skills/repo-health-sweep/SKILL.md @@ -33,7 +33,7 @@ describes. - Internal: `.agents/skills/*` (create-adapter, create-enricher, create-framework-integration, create-map-rule) and `apps/evi/agent/skills/*`. -- Published: `apps/docs/skills/*` (analyze-logs, build-audit-logs, +- Published: `skills/*` (analyze-logs, build-audit-logs, review-logging-patterns). - What to check: every API name, option, default, or adapter the skill shows. An `evlog.X` option must exist under that name; a function signature must be diff --git a/apps/evi/agent/skills/self-review/SKILL.md b/apps/evi/agent/skills/self-review/SKILL.md index 5f0c53312..4e32b988c 100644 --- a/apps/evi/agent/skills/self-review/SKILL.md +++ b/apps/evi/agent/skills/self-review/SKILL.md @@ -41,7 +41,7 @@ Something is produced and nothing consumes it. For each connection, extension an | Root `AGENTS.md` | Every framework integration exposes the same contract: `evlog()`, `useLogger()`, `log.fork()`. `evlog/workers` is the documented exception. | | `apps/evi/docs/capability-placement.md` | The two-layer rule: a file under `agent/` outside `agent/lib/` holding logic instead of wiring, an `agent/lib/` module with no colocated `*.test.ts`, or a caller check written inline instead of going through `agent/lib/trust.ts`. | | `packages/evlog/test/README.md` | A framework test driving the app by hand instead of through its real request driver. | -| Root `AGENTS.md` | A behavior change whose matching `.agents/skills/` or `apps/docs/skills/` SKILL.md still describes the old shape. | +| Root `AGENTS.md` | A behavior change whose matching `.agents/skills/` or `skills/` SKILL.md still describes the old shape. | ## C. Prose that outran the tools diff --git a/apps/evi/agent/subagents/content_review/instructions.md b/apps/evi/agent/subagents/content_review/instructions.md index 8879a0457..0435dc2a4 100644 --- a/apps/evi/agent/subagents/content_review/instructions.md +++ b/apps/evi/agent/subagents/content_review/instructions.md @@ -18,7 +18,7 @@ The scan is evidence, not a second opinion. Calling it again on the same page re **Read the page in full**, from `/workspace/repo/`. The scanner measured prose. You are reading a page, including the code, the MDC components, and the frontmatter. -**Know which audience it is written for.** A docs page, the landing, a blog post, and a package README are read by a person who can doubt them. A skill under `.agents/skills/` or `apps/docs/skills/`, and any `AGENTS.md`, is read by an agent that will act on it. On the second kind, `machine.md` replaces the rhythm rules entirely: judge precision, ordering, bounds, and whether every path and command still exists. Uniform imperatives are a procedure, not a template lock. +**Know which audience it is written for.** A docs page, the landing, a blog post, and a package README are read by a person who can doubt them. A skill under `.agents/skills/` or `skills/`, and any `AGENTS.md`, is read by an agent that will act on it. On the second kind, `machine.md` replaces the rhythm rules entirely: judge precision, ordering, bounds, and whether every path and command still exists. Uniform imperatives are a procedure, not a template lock. **Sort the candidates before judging them.** A house rule was already decided by the maintainer: `U-14` punctuation, `T-13` assistant framing, `T-15` a retired entry point. One occurrence is a finding and there is nothing to weigh. A rhythm is yours to decide, and that is where the next step applies. diff --git a/apps/evi/agent/subagents/content_rewrite/instructions.md b/apps/evi/agent/subagents/content_rewrite/instructions.md index 417a005b5..9bb5f925e 100644 --- a/apps/evi/agent/subagents/content_rewrite/instructions.md +++ b/apps/evi/agent/subagents/content_rewrite/instructions.md @@ -25,7 +25,7 @@ The caller sends you a page path and the review's findings, each with a rule or - **Every link target.** If the sentence holding a link goes, the link moves to the sentence replacing it. - **Code blocks**, unless a finding says the code is wrong. Language and file label included. - **The page's answer.** A rewrite that changes what the page teaches is a different page, and that is a decision for the maintainer. -- **Procedure, bounds, and `description`, on any file an agent reads.** A skill under `.agents/skills/` or `apps/docs/skills/`, and any `AGENTS.md`, reaches you only for house-rule fixes: punctuation, a dead link, a retired entry point, a wrong term. If a finding on one of those files asks for anything else, leave it and report it under `Not applied`. `M-09`. +- **Procedure, bounds, and `description`, on any file an agent reads.** A skill under `.agents/skills/` or `skills/`, and any `AGENTS.md`, reaches you only for house-rule fixes: punctuation, a dead link, a retired entry point, a wrong term. If a finding on one of those files asks for anything else, leave it and report it under `Not applied`. `M-09`. ## The bar for a replacement sentence diff --git a/scripts/content-lint/README.md b/scripts/content-lint/README.md index 33843ff97..4b4bc6efc 100644 --- a/scripts/content-lint/README.md +++ b/scripts/content-lint/README.md @@ -47,7 +47,7 @@ Defined in `lib/surfaces.mjs`, not in the caller: | --- | --- | --- | | `landing` `docs` `reference` `blog` | `apps/docs/content` | everything | | `readme` | `packages/*/README.md` | everything | -| `skill` | `.agents/skills/`, `apps/docs/skills/` | house rules and drift only | +| `skill` | `.agents/skills/`, `skills/` | house rules and drift only | | `agents` | `AGENTS.md`, `apps/*/AGENTS.md` | house rules and drift only | Rhythm checks are off on the last two. Those files are read by an agent that will act on them, and four parallel imperatives there are a procedure, not a template. diff --git a/scripts/content-lint/lib/surfaces.mjs b/scripts/content-lint/lib/surfaces.mjs index af9788236..62ce156c0 100644 --- a/scripts/content-lint/lib/surfaces.mjs +++ b/scripts/content-lint/lib/surfaces.mjs @@ -34,7 +34,7 @@ const PROFILES = { export const SURFACES = Object.keys(PROFILES) /** Trees scanned whole. */ -const TREES = ['apps/docs/content', 'apps/docs/skills', '.agents/skills'] +const TREES = ['apps/docs/content', 'skills', '.agents/skills'] /** * The doctrine's own reference files quote the prose they ban, worked pair by @@ -55,7 +55,7 @@ export function surfaceOf(path) { return /\/(7\.reference|4\.integrate)\//.test(normalized) ? 'reference' : 'docs' } if (normalized.endsWith('AGENTS.md')) return 'agents' - if (normalized.startsWith('.agents/skills/') || normalized.startsWith('apps/docs/skills/')) return 'skill' + if (normalized.startsWith('.agents/skills/') || normalized.startsWith('skills/')) return 'skill' if (normalized === 'README.md' || /^(packages|apps)\/[^/]+\/README\.md$/.test(normalized)) return 'readme' return 'docs' } diff --git a/scripts/content-lint/lib/surfaces.test.mjs b/scripts/content-lint/lib/surfaces.test.mjs index 45a8983a3..c25a97985 100644 --- a/scripts/content-lint/lib/surfaces.test.mjs +++ b/scripts/content-lint/lib/surfaces.test.mjs @@ -14,7 +14,7 @@ describe('surfaceOf', () => { it('tells the surfaces an agent reads from the ones a person reads', () => { expect(surfaceOf('.agents/skills/create-adapter/SKILL.md')).toBe('skill') - expect(surfaceOf('apps/docs/skills/analyze-logs/SKILL.md')).toBe('skill') + expect(surfaceOf('skills/analyze-logs/SKILL.md')).toBe('skill') expect(surfaceOf('AGENTS.md')).toBe('agents') expect(surfaceOf('apps/docs/AGENTS.md')).toBe('agents') expect(surfaceOf('packages/evlog/README.md')).toBe('readme') diff --git a/apps/docs/skills/analyze-logs/SKILL.md b/skills/analyze-logs/SKILL.md similarity index 100% rename from apps/docs/skills/analyze-logs/SKILL.md rename to skills/analyze-logs/SKILL.md diff --git a/apps/docs/skills/build-audit-logs/SKILL.md b/skills/build-audit-logs/SKILL.md similarity index 100% rename from apps/docs/skills/build-audit-logs/SKILL.md rename to skills/build-audit-logs/SKILL.md diff --git a/apps/docs/skills/build-audit-logs/references/framework-wiring.md b/skills/build-audit-logs/references/framework-wiring.md similarity index 100% rename from apps/docs/skills/build-audit-logs/references/framework-wiring.md rename to skills/build-audit-logs/references/framework-wiring.md diff --git a/apps/docs/skills/review-logging-patterns/SKILL.md b/skills/review-logging-patterns/SKILL.md similarity index 100% rename from apps/docs/skills/review-logging-patterns/SKILL.md rename to skills/review-logging-patterns/SKILL.md diff --git a/apps/docs/skills/review-logging-patterns/references/code-review.md b/skills/review-logging-patterns/references/code-review.md similarity index 100% rename from apps/docs/skills/review-logging-patterns/references/code-review.md rename to skills/review-logging-patterns/references/code-review.md diff --git a/apps/docs/skills/review-logging-patterns/references/drain-pipeline.md b/skills/review-logging-patterns/references/drain-pipeline.md similarity index 100% rename from apps/docs/skills/review-logging-patterns/references/drain-pipeline.md rename to skills/review-logging-patterns/references/drain-pipeline.md diff --git a/apps/docs/skills/review-logging-patterns/references/structured-errors.md b/skills/review-logging-patterns/references/structured-errors.md similarity index 100% rename from apps/docs/skills/review-logging-patterns/references/structured-errors.md rename to skills/review-logging-patterns/references/structured-errors.md diff --git a/apps/docs/skills/review-logging-patterns/references/wide-events.md b/skills/review-logging-patterns/references/wide-events.md similarity index 100% rename from apps/docs/skills/review-logging-patterns/references/wide-events.md rename to skills/review-logging-patterns/references/wide-events.md