AGENTS.md

This file provides high-level guidance for **AI agents (e.g. OpenAI Codex)** that interact with the Magek Framework repository. Follow these instructions to reliably set up the development environment, run the full test & lint suite, and keep your contributions consistent with the project's convent

promptBeginner5 min to valuemarkdown

0 views

Feb 7, 2026

AGENTS.md

Purpose

This file provides high-level guidance for AI agents (e.g. OpenAI Codex) that interact with the Magek Framework repository. Follow these instructions to reliably set up the development environment, run the full test & lint suite, and keep your contributions consistent with the project's conventions.

1. Repository Overview

Monorepo layout – The project is organised as a Rush/PNPM monorepo:
- ```
packages/*
```
  → Production TypeScript packages (framework, providers, CLI, etc.).
- ```
tools/*
```
  → Internal tooling packages (e.g. shared ESLint config).
- ```
scripts/*
```
  → Bash & PowerShell helpers. The most important is
```
scripts/check-all-the-things.sh
```
  which runs the entire CI pipeline locally.
- ```
docs/
```
  → Documentation (Markdown files).
- ```
common/
```
  → Rush-generated files (lock-file, temp folders, etc.).
Main configuration – See
```
rush.json
```
(build graph), the root
```
tsconfig.json
```
, ESLint/prettier configs, and
```
.nvmrc
```
.
Node / PNPM versions – The repo targets Node 22.x and PNPM 9.x (managed automatically by Rush).

2. Quick-start Commands for Agents

Task	Command	Notes
Install global Rush	`npm i -g @microsoft/rush`	(One-time)
Install	`rush install`	(One-time)
Install deps only	`rush update`
Build all packages	`rush rebuild`	TypeScript compilation & type-check
Fix linter issues	`rush lint:fix`	Uses project ESLint rules
Run unit tests	`rush test`	Mocha across all packages
Package-scoped test	`cd packages/<name> && rushx test`

Tip: Use
rush clean
&
rush purge
before a fresh install to remove caches. Codex Warning: Avoid running
rush clean
or
scripts/check-all-the-things.*
scripts here. The sandbox has no internet access after setup, so removed dependencies cannot be reinstalled.

Start in
packages/framework-core/src
– Contains the core domain logic (commands, events, GraphQL generation, etc.).
Provider implementations live in
```
packages/framework-provider-*/src
```
.
CLI entry point is
```
packages/cli/bin/run
```
(OCLIF-based CLI).
Shared types are in
```
packages/common
```
.

All production code is TypeScript; tests use Mocha. Standard utilities such as lodash are intentionally avoided—prefer simple, functional helpers.

4. Coding Conventions to Follow

Language: TypeScript (ES2022) and ES modules only (no CommonJS). No default exports, prefer named exports.
Style: The project ships its own ESLint & Prettier config (
```
@magek/eslint-config
```
). Always run
```
rush lint:fix
```
before committing.
Functional-first: Favour pure functions over classes unless state is required. Prefer
```
const
```
/immutability.
Dependency injection: Avoid hard-coded dependencies; design modules and functions to accept their dependencies as parameters to facilitate testing and composition.

Commit messages must follow the Conventional Commits spec. Examples:

feat(core): add optimistic concurrency control

fix(cli): validate project name before scaffolding

Branch naming:
```
feature/<topic>
```
,
```
fix/<topic>
```
,
```
doc/<topic>
```
(see CONTRIBUTING.md for details).

5. Testing Strategy

Unit tests (Mocha) run quickly and should cover most changes.
The CI pipeline mirrors the steps in
```
scripts/check-all-the-things.sh
```
; ensure it passes locally before creating a pull request.

6. Pull Requests & Releases

Fork → Branch → PR against
main
.
Make sure
```
./scripts/check-all-the-things.sh
```
exits without errors.
After review, core maintainers will trigger full CI and (if applicable) publish to npm following semver derived from Conventional Commits.

7. Useful References

Documentation: https://docs.magek.ai
Discord: https://discord.gg/bDY8MKx
CONTRIBUTING guidelines:
```
CONTRIBUTING.md
```
Code of Conduct:
```
CODE_OF_CONDUCT.md
```

Happy hacking, and remember: If it compiles and the test suite passes, you're halfway there!

Purpose

1. Repository Overview

Monorepo layout – The project is organised as a Rush/PNPM monorepo:

```
packages/*
```
→ Production TypeScript packages (framework, providers, CLI, etc.).
```
tools/*
```
→ Internal tooling packages (e.g. shared ESLint config).
```
scripts/*
```
→ Bash & PowerShell helpers. The most important is
```
scripts/check-all-the-things.sh
```
which runs the entire CI pipeline locally.
```
docs/
```
→ Documentation (Markdown files).
```
common/
```
→ Rush-generated files (lock-file, temp folders, etc.).

Main configuration – See

rush.json

(build graph), the root

tsconfig.json

, ESLint/prettier configs, and

.nvmrc

Node / PNPM versions – The repo targets Node 22.x and PNPM 9.x (managed automatically by Rush).

2. Quick-start Commands for Agents

Task	Command	Notes
Install global Rush	`npm i -g @microsoft/rush`	(One-time)
Install	`rush install`	(One-time)
Install deps only	`rush update`
Build all packages	`rush rebuild`	TypeScript compilation & type-check
Fix linter issues	`rush lint:fix`	Uses project ESLint rules
Run unit tests	`rush test`	Mocha across all packages
Package-scoped test	`cd packages/<name> && rushx test`

Tip: Use

rush clean

rush purge

before a fresh install to remove caches. Codex Warning: Avoid running

rush clean

scripts/check-all-the-things.*

scripts here. The sandbox has no internet access after setup, so removed dependencies cannot be reinstalled.

3. Code Navigation Tips

Start in
packages/framework-core/src
– Contains the core domain logic (commands, events, GraphQL generation, etc.).

Provider implementations live in

packages/framework-provider-*/src

CLI entry point is

packages/cli/bin/run

(OCLIF-based CLI).

Shared types are in

packages/common

All production code is TypeScript; tests use Mocha. Standard utilities such as lodash are intentionally avoided—prefer simple, functional helpers.

4. Coding Conventions to Follow

Language: TypeScript (ES2022) and ES modules only (no CommonJS). No default exports, prefer named exports.

Style: The project ships its own ESLint & Prettier config (

@magek/eslint-config

). Always run

rush lint:fix

before committing.

Functional-first: Favour pure functions over classes unless state is required. Prefer

const

/immutability.

Dependency injection: Avoid hard-coded dependencies; design modules and functions to accept their dependencies as parameters to facilitate testing and composition.

Commit messages must follow the Conventional Commits spec. Examples:

feat(core): add optimistic concurrency control

fix(cli): validate project name before scaffolding

Branch naming:

feature/<topic>

fix/<topic>

doc/<topic>

(see CONTRIBUTING.md for details).

AGENTS.md

AGENTS.md

Purpose

1. Repository Overview

2. Quick-start Commands for Agents

3. Code Navigation Tips

4. Coding Conventions to Follow

5. Testing Strategy

6. Pull Requests & Releases

7. Useful References

Related Skills

Markdown Converter

Nano Banana Pro

1password

AGENTS.md

Purpose

1. Repository Overview

2. Quick-start Commands for Agents

3. Code Navigation Tips

4. Coding Conventions to Follow

5. Testing Strategy

6. Pull Requests & Releases

7. Useful References