Skip to content

docs: add build, architecture, and convention sections to AGENTS.md #311

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

Open
dpearson2699 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add build, architecture, and convention sections to AGENTS.md #311

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0b49fe9
docs: add build, architecture, and convention sections to AGENTS.md
dpearson2699 Apr 4, 2026
e4f46df
docs: update contributing workflow and attribution guidelines in AGEN…
dpearson2699 Apr 4, 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
89 changes: 82 additions & 7 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,61 @@
# Development Rules

## Build & Test
- `npm run build` - Build (tsup, ESM)
- `npm run test` - Unit/integration tests (Vitest)
- `npm run test:smoke` - Smoke tests (builds first, serial execution)
- `npm run lint` / `npm run lint:fix` - ESLint
- `npm run format` - Prettier
- `npm run typecheck` - TypeScript type checking (`tsc --noEmit`)
- `npm run docs:update` - Regenerate `docs/TOOLS.md` from manifests
- `npm run docs:check` - Validate docs match CLI surface

## Architecture
ESM TypeScript project (`type: module`). Key layers:

- `src/cli/` - CLI entrypoint, yargs wiring, daemon routing
- `src/server/` - MCP stdio server, lifecycle, workflow/resource registration
- `src/runtime/` - Config bootstrap, session state, tool catalog assembly
- `src/core/manifest/` - YAML manifest loading, validation, tool module imports
- `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`)
- `src/mcp/resources/` - MCP resource implementations
- `src/integrations/` - External integrations (Xcode mcpbridge proxy)
- `src/utils/` - Shared helpers (execution, logging, validation, responses)
- `src/visibility/` - Tool/workflow exposure predicates
- `src/daemon/` - Background daemon for persistent sessions
- `src/types/` - Shared type definitions

See `docs/` for detailed documentation (architecture, configuration, tools, troubleshooting).

## Developer Documentation
- `docs/dev/CONTRIBUTING.md` - Full contributing guide (setup, debugging, PR submission)
- `docs/dev/ARCHITECTURE.md` - Detailed architectural overview and component design
- `docs/dev/TESTING.md` - Testing guidelines, dependency injection patterns, coverage standards
- `docs/dev/MANIFEST_FORMAT.md` - YAML manifest schema reference for tools and workflows
- `docs/dev/MANUAL_TESTING.md` - Manual testing procedures
- `docs/dev/RELEASE_PROCESS.md` - Release workflow
- `docs/dev/CODE_QUALITY.md` - Code quality standards and ESLint rules

## Contributing Workflow
1. Create a branch from `main`
2. Make changes following the conventions in this file
3. Run the pre-commit checklist before committing:
```bash
npm run lint:fix
npm run typecheck
npm run format
npm run build
npm run docs:check
npm test
```
4. Update `CHANGELOG.md` under `## [Unreleased]`
5. Update documentation if adding or modifying features
6. Clone and test against example projects (e.g., `XcodeBuildMCP-iOS-Template`) when changes affect runtime behavior
7. Push and create a pull request with a clear description
8. Link any related issues

For full setup, debugging with Reloaderoo, and plugin development details, see `docs/dev/CONTRIBUTING.md`.

## Code Quality
- No `any` types unless absolutely necessary
- Check node_modules for external API type definitions instead of guessing
Expand All @@ -8,19 +64,38 @@
- Always ask before removing functionality or code that appears to be intentional
- Follow TypeScript best practices

## Import Conventions
- ESM with explicit `.ts` extensions in `src/` (tsup rewrites to `.js` at build)
- No `.js` imports in `src/` (enforced by ESLint)
- No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`)

## Test Conventions
- Vitest with colocated `__tests__/` directories using `*.test.ts`
- Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution)
- Use `vi.mock`/`vi.hoisted` for isolation; inject executors and mock file systems
- MCP integration tests use `McpServer`, `InMemoryTransport`, and `Client`
- External dependencies (command execution, file system) must use dependency injection via `createMockExecutor()` / `createMockFileSystemExecutor()`
- See `docs/dev/TESTING.md` for full testing guidelines

## Tool Development
- Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations
- Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules
- Tool modules export a Zod schema, a pure `*Logic` function, and a `handler` via `createTypedTool` or `createSessionAwareTool`
- Resources export `{ uri, name, description, mimeType, handler }`

## Commands
- NEVER commit unless user asks

## GitHub
When reading issues:
- Always read all comments on the issue
-

## Tools
- GitHub CLI for issues/PRs
- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.
- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.
- After modifying any skill source, run `npx skill-check <skill-directory>` and address all errors/warnings before handoff.
-

## Style
- Keep answers short and concise
- No emojis in commits, issues, PR comments, or code
Expand All @@ -29,7 +104,7 @@ When reading issues:

## Docs
- If modifying or adding/removing tools run `npm run docs:update` to update the TOOLS.md file, never edit this file directly.
-

### Changelog
Location: `CHANGELOG.md`

Expand All @@ -39,17 +114,17 @@ Use these sections under `## [Unreleased]`:
- `### Changed` - Changes to existing functionality
- `### Fixed` - Bug fixes
- `### Removed` - Removed features
-

#### Rules
- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist
- New entries ALWAYS go under `## [Unreleased]` section
- Append to existing subsections (e.g., `### Fixed`), do not create duplicates
- NEVER modify already-released version sections (e.g., `## [0.12.2]`)
- Each version section is immutable once released
-

#### Attribution
- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/cameroncook/XcodeBuildMCP/issues/123))`
- **External contributions**: `Added feature X ([#456](https://github.com/cameroncook/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))`
- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/XcodeBuildMCP/issues/123))`
- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))`

## **CRITICAL** Tool Usage Rules **CRITICAL**
- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.
Expand Down