Skip to content

docs: add repository agent guide #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
princeofscale merged 2 commits into from
Jul 14, 2026
Merged

docs: add repository agent guide #28

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5a97db
docs: add repository agent guide
Jul 14, 2026
296ec15
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# BloxForge agent guide

This file is the primary operating guide for AI coding agents working in this repository. Follow any more specific `AGENTS.md` found deeper in the tree as well.

## Project purpose

BloxForge is a local-first Model Context Protocol server and Roblox Studio plugin. It lets MCP clients inspect and modify Roblox experiences through a localhost bridge. Preserve local-only operation, user control, and compatibility with existing MCP clients.

## Repository map

- `packages/core/` — shared tool definitions, handlers, bridge code, builders, and tests.
- `packages/robloxstudio-mcp/` — main CLI and published full server package.
- `packages/robloxstudio-mcp-inspector/` — read-focused inspector CLI and package.
- `packages/studio-plugin/` — TypeScript source compiled into the Roblox Studio Luau plugin.
- `scripts/` — build, documentation, package, release, and smoke-test utilities.
- `tests/` — repository-level integration and regression coverage.
- `docs/` — maintained user and contributor documentation.
- `evals/` — evaluation fixtures and scenarios.

Do not commit generated build output, package tarballs, installed Studio plugins, credentials, or local tool state.

## Working rules

1. Inspect the current branch, worktree, and relevant tests before editing. Preserve unrelated user changes.
2. Fix behavior at the shared layer when both the full server and inspector are affected.
3. Keep tool schemas, handlers, facade exports, output schemas, tests, and generated documentation synchronized.
4. Treat the localhost bridge and plugin protocol as a compatibility boundary. Avoid silent request or response shape changes.
5. Keep the plugin load order deterministic. Plugin changes must be validated against compiled Luau, not only TypeScript source.
6. Keep secrets out of source, logs, fixtures, changelogs, commits, and command output. Never print npm or GitHub tokens.
7. Prefer small, direct changes using existing utilities and dependencies. Do not add abstractions or packages without a concrete need.
8. Use Conventional Commits and explain user-visible changes in `CHANGELOG.md`.
9. Do not edit generated tool-reference content by hand; regenerate it with the repository scripts.
10. Do not use destructive Git operations or rewrite shared history unless the user explicitly requests it.

## Local validation

Install exact dependencies with:

```sh
npm ci
```

Run checks relevant to the change. Before a release, run the complete set:

```sh
npm run lint
npm run typecheck
npm test -- --runInBand
npm run build:all
npm run plugin:smoke
npm run plugin:runtime-smoke
Comment on lines +50 to +51

@coderabbitai coderabbitai Bot Jul 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Use the repository’s actual plugin validation script names.

The supplied package.json defines test:plugin:smoke and test:plugin:runtime; these commands will fail as written:

-npm run plugin:smoke
-npm run plugin:runtime-smoke
+npm run test:plugin:smoke
+npm run test:plugin:runtime
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
npm run plugin:smoke
npm run plugin:runtime-smoke
npm run test:plugin:smoke
npm run test:plugin:runtime
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` around lines 50 - 51, Update the plugin validation commands in
AGENTS.md to use the package.json-defined scripts test:plugin:smoke and
test:plugin:runtime instead of plugin:smoke and plugin:runtime-smoke.

npm run docs:check
npm run verify-package
npm run release:check
```

Use a temporary `MCP_PLUGINS_DIR` while developing or testing plugin installation so the real Roblox Studio plugin directory is not modified.

## Documentation

Keep `README.md`, `docs/architecture.md`, `docs/known-limitations.md`, `docs/tools-reference.md`, and `docs/troubleshooting.md` aligned with the product. Add a new documentation file only when the information does not fit one of these maintained documents.

## Release checklist

1. Set the same version in the root package, every published workspace, and `package-lock.json`.
2. Move completed entries into the matching `CHANGELOG.md` release section.
3. Run `npm run release:check` and confirm the working tree contains only intended release changes.
4. Create and push `v<version>` only after the release commit is on the default branch.
5. The tag workflow publishes npm packages and creates the GitHub release. Prereleases such as `-rc.1` use the npm `next` dist-tag and a GitHub prerelease.
6. Verify the npm package versions, dist-tags, GitHub release assets, and workflow status before declaring the release complete.