Advisory report for n8n agent instruction context

Feature Requests
1

The idea is:

Add an optional, advisory-only way for maintainers and contributors to inspect n8n’s repository agent instruction context.

I maintain Tokn, a small OSS CLI for inspecting and linting repository instruction files used by coding agents, such as AGENTS.md, Copilot instructions and visible Claude surfaces.

I tried Tokn locally against n8n-io/n8n because the repo already has a mature agent development setup with root and scoped AGENTS.md files, CLAUDE.md bridge files, Claude task runner workflows, and package specific agent guidance.

The idea is only to make an advisory report available if maintainers find it useful.

Command used:

npx @tokn-labs/tokn@0.4.0 instructions-lint . \
  --fail-on-severity off \
  --format markdown

Snapshot from n8n-io/n8n commit 60e23e10:

  • 18 instruction files discovered
  • 8 AGENTS.md files actively linted
  • 10 CLAUDE.md files detected as visibility-only surfaces
  • 10,732 estimated active instruction tokens
  • 292 parsed active instruction statements
  • largest target load: 6,252 estimated tokens
  • 57 advisory warnings, 0 errors

The report surfaced advisory items like:

  • broad always-on instruction load for some target files
  • repository wide guidance that may be carrying scoped package details
  • duplicate or overlapping instructions across root/package scopes
  • large examples or narrative paragraphs that may be harder for agents to scan
  • CLAUDE.md surfaces that are visible but not fully linted by Tokn yet

My use case:

As a contributor or maintainer using coding agents on a large monorepo, I want to understand which repository instruction files are active, how much estimated context they add, and where instruction overlap or drift may be happening.

For n8n specifically, this could help answer questions like:

  • Which AGENTS.md files apply to a given package or target file?
  • Are root instructions carrying guidance that should live in narrower package-scoped files?
  • Are AGENTS.md and CLAUDE.md surfaces drifting from each other?
  • Is any single target file receiving a very large instruction load?
  • Are contributors able to run the same local advisory check before changing agent guidance?

I think it would be beneficial to add this because:

  • make AGENTS.md / CLAUDE.md drift visible as the repo evolves
  • help maintainers see which instruction files can load for which areas
  • keep agent guidance compact enough for coding-agent context windows
  • give contributors a repeatable local command for instruction hygiene
  • keep it advisory-only, with no failing CI and no workflow behavior changes

This seems aligned with n8n’s existing investment in agent-development workflows, but it should stay passive unless maintainers explicitly want more.

Any resources to support this?

I can share the generated markdown report first if maintainers want to review it. It is about 315 lines, so I am not attaching it up front to keep this request readable.

Are you willing to work on this?

Yes, I am willing to work on this. If maintainers think this is useful, I can follow up with a very small PR that only adds a report-only tokn.config.json or a short docs note showing how to run the advisory report locally with --fail-on-severity off.

If this is not the right fit for the n8n repo, I can keep it as an external/community-side report instead.