Set Up Agent Instructions for a Growing Monorepo

Problem/Feature Description

infractl started as a small internal tool but has grown into a monorepo containing three distinct packages: a REST API service, a React web dashboard, and a command-line tool. Each package has different tech stacks, test setups, and workflows. The team now uses AI coding agents regularly, but the agents keep making mistakes that a human developer would have caught after spending a day in the codebase — running the wrong test commands, not knowing about subtle tool behaviors, and treating the whole repo as if it were a single Node app.

A team lead has asked you to create AGENTS.md files for this repository. The codebase is large enough that a single root-level file would become unwieldy and hard to maintain. The team wants a structure that scales as the project continues to grow.

Your job is to examine the repository files provided and produce appropriate agent instruction files. Focus on guidance that agents cannot learn by simply reading the source files — commands, constraints, and footguns that are easy to miss.

Output Specification

Produce one or more AGENTS.md files at appropriate locations in the repository. At minimum produce a root AGENTS.md. Document clearly which directories have their own agent instruction files.

Input Files

The following files are provided as inputs. Extract them before beginning.

=============== FILE: README.md ===============

infractl

A monorepo containing the infractl platform:

• packages/api — REST API built with Fastify and TypeScript, backed by SQLite
• packages/web — React dashboard (Vite + TypeScript)
• packages/cli — Node.js CLI tool distributed via npm

Getting Started

npm install       # installs all workspaces
npm run test      # runs tests across all packages
npm run build     # builds all packages

Each package can also be developed independently:

cd packages/api && npm test
cd packages/web && npm run dev
cd packages/cli && npm test

Contributing

See CONTRIBUTING.md for branch naming conventions and PR guidelines. =============== END FILE ===============

=============== FILE: package.json =============== { "name": "infractl", "private": true, "workspaces": ["packages/*"], "scripts": { "test": "npm run test --workspaces", "build": "npm run build --workspaces", "lint": "eslint packages --ext .ts,.tsx" }, "devDependencies": { "eslint": "^8.57.0", "typescript": "^5.4.0" } } =============== END FILE ===============

=============== FILE: packages/api/package.json =============== { "name": "@infractl/api", "scripts": { "test": "vitest run", "test:integration": "vitest run --config vitest.integration.config.ts", "build": "tsc", "start": "node dist/index.js" }, "dependencies": { "fastify": "^4.26.0", "better-sqlite3": "^9.4.0" }, "devDependencies": { "vitest": "^1.4.0" } } =============== END FILE ===============

=============== FILE: packages/web/package.json =============== { "name": "@infractl/web", "scripts": { "dev": "vite", "build": "vite build", "test": "vitest run" }, "dependencies": { "react": "^18.2.0", "react-dom": "^18.2.0" }, "devDependencies": { "vite": "^5.2.0", "vitest": "^1.4.0" } } =============== END FILE ===============

=============== FILE: packages/cli/package.json =============== { "name": "@infractl/cli", "bin": { "infractl": "dist/cli.js" }, "scripts": { "test": "jest", "build": "tsc" }, "dependencies": { "commander": "^12.0.0" }, "devDependencies": { "jest": "^29.0.0" } } =============== END FILE ===============

=============== FILE: .github/workflows/ci.yml =============== name: CI

on: [push, pull_request]

jobs: test-api: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install - name: Unit tests run: npm test working-directory: packages/api - name: Integration tests # DATABASE_RESET=1 is required: integration tests check row counts after # inserting fixtures, so a leftover database from a previous run causes # assertion mismatches. Without this flag tests appear to pass (0 failures) # but results are meaningless because fixtures were never inserted. env: DATABASE_RESET: "1" run: npm run test:integration working-directory: packages/api

test-web: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install - run: npm test working-directory: packages/web

test-cli: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install - run: npm test working-directory: packages/cli =============== END FILE ===============

=============== FILE: packages/cli/src/cli.ts =============== import { Command } from 'commander'; import { writeFileSync } from 'fs'; import { homedir } from 'os'; import { join } from 'path';

const CONFIG_PATH = join(homedir(), '.appname', 'config.json');

const program = new Command();

program .command('configure') .option('--dry-run', 'Preview changes without applying them') .action((options) => { const config = buildConfig(options); if (options.dryRun) { console.log('Preview:', JSON.stringify(config, null, 2)); } // Config is always persisted regardless of --dry-run, so that // subsequent commands can read the resolved values. This is intentional // but surprises users who expect --dry-run to be fully non-destructive. writeFileSync(CONFIG_PATH, JSON.stringify(config)); }); =============== END FILE ===============