ModularityJS

Appearance

AGENTS.md ​

@modularityjs/manifest ships a modularityjs-agents-md bin that renders a single AGENTS.md file at your repo root. Drop it next to README.md and any LLM coding agent that auto-loads AGENTS.md — Claude Code, Cursor, Aider, Codex, Zed — gets the framework's conventions injected at the start of every task.

Use this when you can't or don't want to run the MCP server: AGENTS.md is a static file that ships with the repo, no host config required.

Generate ​

The bin is published as part of @modularityjs/manifest, so no install is needed.

bash
# Pipe to stdout (recommended; lets you review the diff before saving).
pnpm dlx @modularityjs/manifest > AGENTS.md

# Or write directly to a path.
pnpm dlx @modularityjs/manifest ./AGENTS.md

The package ships a single bin named modularityjs-agents-md; pnpm dlx resolves it automatically. The first positional argument (if any) is taken as the output file path — no agents-md subcommand exists.

If @modularityjs/manifest is already installed in your project (typical for monorepos that depend on the framework), use pnpm exec instead — faster, no fetch:

bash
pnpm exec modularityjs-agents-md > AGENTS.md

In a fresh checkout, run pnpm install first — pnpm exec only resolves the bin once node_modules are linked. Inside the framework monorepo itself, also run pnpm --filter @modularityjs/manifest build once so the compiled bin entry exists.

Commit the resulting file. Agents pick it up automatically; no other configuration.

What's in the file ​

The generator pulls from the bundled manifest catalogue and renders these sections, in order:

  1. Header — framework version stamp + regenerate command.
  2. Mental model — abstract DI, contract/driver split, the module system.
  3. Hard rules — no inversify imports, pass the driver explicitly, etc.
  4. Anti-patterns — common mistakes that look right but aren't.
  5. Package picker — dynamic table mapping contracts to their drivers.
  6. Extensions and CLI commands — every cross-contract extension and CLI add-on.
  7. Minimal boot recipe — a complete, compile-tested boot example.
  8. Auth wiring — driver pool, request identity, JWT/OIDC quirks.
  9. Database wiring — TypeORM and Prisma, entity pools, migrations.
  10. Validation wiring — Zod / AJV + @Validated* decorators.
  11. Storage wiring — contract/driver split, read/write shapes, key namespaces.
  12. Cache wiring — get/set/invalidateTag, TTL, driver-swap one-liner.
  13. Session wiring — SessionService + the Fastify extension, @Session(), rolling cookies.
  14. Events wiring — @OnEvent, once vs local, memory vs Redis fanout.
  15. Outbox wiring — transactional staging, store/publisher composition, scheduler trigger.
  16. File-uploads wiring — multipart, temp files, Fastify plugin order.
  17. WebSocket wiring — gateways, @OnMessage, lifecycle gotchas.
  18. Lifecycle hooks — forward / reverse order, throw semantics.
  19. Pool vs. preference vs. named — when to use which, plus Named bindings and Override for surgical overrides.
  20. Where to find more — links to the framework's guide, package docs, and source.

The minimal boot recipe is compile-tested before release — wrong code in the template would propagate to every consumer's AGENTS.md on the next regen, so it's gated.

When to regenerate ​

Regen after any of:

  • Adding a new @modularityjs/* package, or renaming one.
  • Adding, renaming, or removing a public symbol from a package's barrel export.
  • Changing a package's modularityjs.kind or modularityjs.extends in package.json.
  • Bumping the framework to a new release (the version stamp at the top will be stale otherwise).

Inside this monorepo the freshness gate is pnpm check-manifest, which regenerates manifest.json and fails CI on drift. Downstream consumers don't get that gate — they regenerate on demand.

When to use this vs. the MCP server ​

Use AGENTS.md when:

  • You want a single, reviewable artefact in the repo.
  • Your agent doesn't support MCP (older releases of some tools).
  • You want every task to start with the full conventions blob already in context.

Use the MCP server when:

  • You want token economy — agents fetch the 2 KB they need rather than the full 50 KB blob per session.
  • You want live access to per-page docs, wiring recipes, and the package catalogue without rebuilding the static file.
  • Your team's agents already speak MCP.

The two are not exclusive. Many repos ship both: AGENTS.md for unconditional priming and the MCP server for follow-up queries.

Customising ​

The generator is not configurable by design — the value of AGENTS.md is that every repo using ModularityJS gets the same agent guide, kept in sync with the framework release. If you need to add project-specific guidance, append it to the generated file under a ## Project-specific notes heading; future regens overwrite only what they produced.

If you want to build your own generator on top of the catalogue, the helpers in @modularityjs/manifest (loadManifest, findPackage, findSymbol, driversOf, packagesByKind, transitiveDependencies) are stable and documented, and renderAgentsMd(manifest) is exported if you'd rather re-use the standard renderer wholesale.