Skip to content

AGENTS.md

Latest commit

 

History

History
131 lines (110 loc) · 6.34 KB

AGENTS.md

File metadata and controls

131 lines (110 loc) · 6.34 KB

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: 
    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
  • NEVER use inline imports - no await import("./foo.js"), no import("pkg").Type in type positions, no dynamic imports for types. Always use standard top-level imports.
  • NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead
  • 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
  • No fluff or cheerful filler text
  • Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!")

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

Format

Use these sections under ## [Unreleased]:

  • ### Added - New features
  • ### 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/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.
  • You MUST read every file you modify in full before editing.