docs: add AGENTS.md for contributors and AI coding assistants

[twoeths]

This pull request introduces an AGENTS.md file to streamline contributions to this repository.

The newly added document provides:

• Project Overview: A high-level understanding of the repo's purpose and structure.
• Development Guidelines: Instructions for setting up the development environment and running tests.
• Coding Conventions: Linting and formatting standards to ensure code consistency.
• Contribution Steps: Best practices for creating branches, committing changes, and opening pull requests.
• Testing Best Practices: Guidelines to maintain code quality and avoid regressions.
• Common Development Tasks: Notes on syncing with upstream, generating documentation, and addressing reviewer feedback.

Why this is useful:

By centralizing these details, this document aims to improve collaboration among developers and AI coding assistants.

---

Guidelines improved and tailored for this repository. Inspired by upstream conventions.

[twoeths]

Suggested change

	- Run lint checks: `npm run lint`
	- Run lint checks: `pnpm run lint`

all steps should be pnpm instead

[Copilot]

Pull request overview

This pull request adds an AGENTS.md file intended to provide guidance for AI coding assistants and human contributors. However, the document contains multiple inaccuracies regarding the repository's structure, tooling, and commands that would mislead contributors.

Changes:

• Adds new AGENTS.md documentation file with project overview, build instructions, code style guidelines, and contribution workflow

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This document duplicates and conflicts with the existing comprehensive CONTRIBUTING.md file. The existing CONTRIBUTING.md already covers all these topics (build process, code style, contribution guidelines, testing) with more accurate and detailed information. Adding AGENTS.md creates maintenance burden and confusion since:

1. CONTRIBUTING.md is the standard filename for contribution documentation in open source projects
2. The information in AGENTS.md contains inaccuracies (wrong package manager commands, incorrect directory structure) while CONTRIBUTING.md is accurate
3. Contributors and AI assistants would need to check both files, not knowing which is authoritative

Consider either updating CONTRIBUTING.md with AI-specific guidance or removing this file in favor of the existing documentation.

Suggested change

	# AGENTS.md - Guide for AI Coding Assistants and Contributors
	## Overview
	This document serves as a guide for both AI coding assistants and human developers contributing to this repository. Its purpose is to ensure consistency in contributions, streamline workflows, and adhere to the project’s standards.
	---
	## Project Overview
	This repository, `lodestar`, is a continuation and personalization of the original Lodestar project. It focuses on:
	- **Streamlined Consensus Layer Development**: Building and maintaining core functionalities inspired by Ethereum specifications.
	- **Customization**: Features tailored to personal workflows and experimental improvements.
	---
	## Directory Structure
	An overview of the repository setup:
	- **src/**: Contains core source code.
	- **tests/**: Includes unit and integration tests.
	- **docs/**: Project documentation.
	- **scripts/**: Utility scripts for automation.
	- **configs/**: Configuration files for different environments.
	---
	## Build Process
	Before contributing, ensure you set up the development environment correctly:
	1. **Install Dependencies**:
	```bash
	npm install
	```
	2. **Build Project**:
	```bash
	npm run build
	```
	3. **Run Tests**:
	```bash
	npm test
	```
	---
	## Code Style
	Follow these conventions to maintain consistency:
	1. **Linting**:
	- Run lint checks: `npm run lint`
	- Fix issues automatically: `npm run lint:fix`
	2. **Formatting**:
	- Use Prettier for formatting.
	- Ensure no trailing whitespace or unused imports.
	---
	## Contribution Guidelines
	1. **Fork and Clone**:
	```bash
	git clone https://github.com/twoeths/lodestar.git
	```
	2. **Create a Feature Branch**:
	```bash
	git checkout -b feature/<short-name>
	```
	3. **Commit Messages**:
	- Use descriptive commit messages.
	- Example: `feat: add support for new state transition logic`.
	4. **Pull Request Guidelines**:
	- Draft pull requests for incomplete contributions.
	- Include a detailed description for reviewers.
	---
	## Testing Guidelines
	1. Always write tests for new features.
	2. Run all tests locally before creating a pull request:
	```bash
	npm test
	```
	3. If end-to-end or integration tests are required, document assumptions.
	---
	## Common Development Tasks
	1. **Sync with Upstream**:
	```bash
	git fetch upstream
	git merge upstream/main
	```
	2. **Generate Documentation**:
	```bash
	npm run docs
	```
	3. **Address Issues/Reviews**:
	- Use GitHub Issues for tracking bugs/enhancements.
	- Respond promptly to reviewer comments.
	---
	## Improvements
	This document is tailored to the needs of this forked repository. Contributors are encouraged to suggest any additional tasks or workflows that improve clarity and productivity in this file.
	# AGENTS.md – Guidance for AI Coding Assistants
	This file provides **AI-specific** guidance only. It is **not** a replacement for the
	project’s contribution documentation.
	## Source of truth
	- `CONTRIBUTING.md` is the **authoritative** document for:
	- project layout and directory structure
	- build, test, and development commands
	- code style, linting, and formatting requirements
	- contribution and pull request workflow
	- `README.md` and in-code comments provide additional project-specific context.
	AI assistants and contributors **must not** rely on this file for concrete commands
	(e.g., package manager usage, scripts, or paths). Always prefer and quote the
	instructions from `CONTRIBUTING.md` and other existing documentation.
	---
	## Guidelines for AI assistants
	When generating or modifying code or documentation in this repository, AI assistants
	should:
	1. **Read existing docs first**
	- Consult `CONTRIBUTING.md`, `README.md`, and relevant files in the codebase
	before proposing changes.
	- Do not invent new build/test commands or directory structures; reuse what is
	already documented.
	2. **Avoid duplicating documentation**
	- Do not introduce new documents that restate content from `CONTRIBUTING.md`.
	- When guidance is needed, link to or reference existing sections instead.
	3. **Be conservative with changes**
	- Prefer minimal, well-scoped edits that respect existing patterns and styles.
	- If unsure about conventions, point maintainers to the relevant code or docs
	rather than guessing.
	4. **Highlight assumptions**
	- Clearly state when a suggestion is based on an assumption or inference from
	limited context.
	- Encourage maintainers to verify commands or workflows against
	`CONTRIBUTING.md`.
	---
	## For human contributors
	If you notice discrepancies between AI-generated suggestions and the project’s
	documented workflows:
	- Treat `CONTRIBUTING.md` and other project docs as the single source of truth.
	- Prefer updating `CONTRIBUTING.md` rather than expanding this file.
	- Keep this file focused on AI-usage notes, not on project-specific commands.
	Suggestions for improving this AI guidance are welcome, but avoid adding build
	steps, directory descriptions, or contribution rules that would duplicate or
	conflict with `CONTRIBUTING.md`.

[Copilot]

The build process section is missing important prerequisites. According to CONTRIBUTING.md, before running these commands, contributors need to:

1. Install NodeJS (LTS) - specifically Node 22.22.0 or 24.13.0 per package.json
2. Install pnpm package manager
3. Run "corepack enable" to enable Corepack (especially important for managing pnpm)
4. Additional prerequisites for MacOS users (python, coreutils)

These missing steps would cause the documented commands to fail for new contributors.

Suggested change

	1. **Install Dependencies**:
	```bash
	npm install
	```
	2. **Build Project**:
	```bash
	npm run build
	```
	3. **Run Tests**:
	1. **Prerequisites**:
	- Install **Node.js LTS**. This project currently supports **Node 22.22.0** or **Node 24.13.0** (see `package.json`).
	- Install the **pnpm** package manager (see https://pnpm.io/installation).
	- Enable **Corepack** to manage `pnpm`:
	```bash
	corepack enable
	```
	- **macOS only**: ensure `python` and `coreutils` are installed (e.g., via Homebrew: `brew install python coreutils`).
	2. **Install Dependencies**:
	```bash
	npm install

3. Build Project:

   npm run build

4. Run Tests:

[Copilot]

This repository uses pnpm as its package manager (as specified in package.json), not npm. The command should be "pnpm install" instead of "npm install". This is also documented in CONTRIBUTING.md and README.md.

[Copilot]

This command should be "pnpm build" not "npm run build". The repository uses pnpm as its package manager, as documented in package.json with "packageManager": "pnpm@10.24.0".

Suggested change

	npm run build
	pnpm build

[Copilot]

This command should be "pnpm test" not "npm test". The repository uses pnpm, and package.json defines the test script that should be run via pnpm.

[Copilot]

The command should be "pnpm test" not "npm test". Additionally, CONTRIBUTING.md recommends more specific test commands: "pnpm test:unit" for unit tests during development, with "pnpm test" running all tests including spec and e2e tests which require additional setup.

[Copilot]

The command "npm run docs" does not exist in package.json. The correct command is "pnpm docs:build" which runs documentation building, or "pnpm docs:serve" to serve the documentation locally.

Suggested change

	npm run docs
	pnpm docs:build # build documentation
	pnpm docs:serve # serve documentation locally

[Copilot]

The document claims this is "a continuation and personalization of the original Lodestar project" and describes it as a forked repository with "Customization: Features tailored to personal workflows and experimental improvements." However, the existing documentation (README.md, CONTRIBUTING.md) refers to this as the main ChainSafe/lodestar repository without any indication of it being a fork. This creates confusion about the actual nature and ownership of this repository. The project overview should accurately reflect whether this is the upstream ChainSafe repository or a personal fork.

[Copilot]

The directory structure description is inaccurate for this monorepo. This repository uses a packages-based monorepo structure, not a simple src/tests layout. The actual structure includes:

• packages/: Contains all package modules (beacon-node, cli, api, etc.)
• Each package has its own src/ and test/ directories
• docs/, scripts/, and configs/ directories exist at root as stated

The directory structure section should be updated to reflect the monorepo architecture seen in README.md and package.json.

Suggested change

	An overview of the repository setup:
	- **src/**: Contains core source code.
	- **tests/**: Includes unit and integration tests.
	- **docs/**: Project documentation.
	- **scripts/**: Utility scripts for automation.
	- **configs/**: Configuration files for different environments.
	An overview of the monorepo setup:
	- **packages/**: Contains all package modules (e.g., `beacon-node`, `cli`, `api`, etc.).
	- **packages/<package-name>/src/**: Core source code for each package.
	- **packages/<package-name>/test/**: Unit and integration tests for each package.
	- **docs/**: Project documentation at the repository root.
	- **scripts/**: Utility scripts for automation at the repository root.
	- **configs/**: Configuration files for different environments at the repository root.

[Copilot]

This repository uses Biome for linting and formatting, not Prettier. While Prettier is included as a dev dependency (for markdown files based on docs:lint scripts), the primary code style tool is Biome as indicated by biome.jsonc and the lint commands in package.json that run "biome check".

Suggested change

	- Use Prettier for formatting.
	- Ensure no trailing whitespace or unused imports.
	- Use Biome as the primary tool for formatting (see `biome.jsonc` and lint scripts).
	- Prettier is only used for Markdown/docs via `docs:lint`-related scripts.
	- Ensure no trailing whitespace or unused imports.