Set Up Agent Instructions for FinStack Monorepo

Problem/Feature Description

FinStack is a financial technology platform structured as a JavaScript/TypeScript monorepo with six independent packages. Each package has its own deployment pipeline, team ownership, and set of constraints. Agents working across the monorepo frequently make mistakes — editing packages they shouldn't touch, running commands in the wrong order, and missing environment setup requirements that only appear in CI and not in local scripts.

The engineering lead wants authoritative agent instruction files that reflect the actual non-obvious constraints in this codebase. No such files exist yet. Your job is to audit the provided repository files, identify what agents genuinely cannot discover on their own, produce the appropriate agent instruction files, and surface any genuine ambiguities as targeted questions rather than guesses.

Since you cannot interactively ask questions, write your questions in a file called questions.md so the team can review and answer them. Then proceed to write the best AGENTS.md content you can given what you know, noting where your assumptions might need validation.

Output Specification

Produce the following files:

• One or more AGENTS.md files placed wherever they would be most useful given the structure of this codebase
• questions.md — targeted questions about genuine ambiguities found during the audit; focus on questions that cannot be answered from the provided files
• audit-notes.md — items considered but excluded, each with a one-line reason

Input Files

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

=============== FILE: package.json =============== { "name": "finstack-monorepo", "private": true, "workspaces": ["packages/*"], "scripts": { "build": "turbo run build", "test": "turbo run test", "lint": "turbo run lint", "dev": "turbo run dev --parallel" }, "devDependencies": { "turbo": "^1.13.0", "typescript": "^5.3.0" }, "packageManager": "pnpm@8.15.0" }

=============== FILE: pnpm-lock.yaml =============== lockfileVersion: '6.0'

settings: autoInstallPeers: true excludeLinksFromLockfile: false

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

FinStack Monorepo

A monorepo containing all FinStack platform services.

Packages

Development

Install dependencies:

pnpm install

Run all services in development mode:

pnpm dev

Run tests across all packages:

pnpm test

=============== FILE: turbo.json =============== { "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }, "test": { "dependsOn": ["^build"], "env": ["DATABASE_URL", "REDIS_URL"] }, "lint": {}, "dev": { "cache": false, "persistent": true } } }

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

on: [push, pull_request]

env: INTEGRATION: "true" PNPM_VERSION: "8.15.0"

jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v3 with: version: ${{ env.PNPM_VERSION }} - run: pnpm install --frozen-lockfile - run: pnpm build - run: pnpm test - run: pnpm lint

deploy-api: needs: test if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: ./scripts/deploy.sh api

deploy-payments: needs: test if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest # DO-NOT-DEPLOY: payments deploys require SRE sign-off # See: https://internal.finstack.io/runbook/payments-deploy steps: - uses: actions/checkout@v4 - run: echo "Manual deployment required - see runbook"

=============== FILE: packages/api/package.json =============== { "name": "@finstack/api", "version": "2.1.0", "scripts": { "build": "tsc", "test": "jest", "dev": "ts-node-dev src/index.ts", "lint": "eslint src" } }

=============== FILE: packages/web/package.json =============== { "name": "@finstack/web", "version": "1.8.0", "scripts": { "build": "next build", "test": "jest", "dev": "next dev", "lint": "next lint" } }

=============== FILE: packages/auth/package.json =============== { "name": "@finstack/auth", "version": "1.3.0", "scripts": { "build": "tsc", "test": "jest", "dev": "ts-node-dev src/index.ts", "lint": "eslint src" } }

=============== FILE: packages/payments/package.json =============== { "name": "@finstack/payments", "version": "1.0.4", "scripts": { "build": "tsc", "test": "jest", "dev": "ts-node-dev src/index.ts", "lint": "eslint src" } }

=============== FILE: packages/payments/README.md ===============

@finstack/payments

Payment processing service for FinStack.

IMPORTANT: This package handles PCI-DSS regulated code. Changes require security review. Deployments must be manually triggered by the SRE team — do not deploy via standard CI pipeline.

Contact sre-team@finstack.io for all deployment requests.

=============== FILE: packages/shared/package.json =============== { "name": "@finstack/shared", "version": "3.0.1", "scripts": { "build": "tsc", "test": "jest", "lint": "eslint src" } }

=============== FILE: packages/cli/package.json =============== { "name": "@finstack/cli", "version": "0.9.0", "scripts": { "build": "tsc", "test": "jest", "lint": "eslint src" } }

=============== FILE: .env.example =============== DATABASE_URL=postgres://localhost:5432/finstack_dev REDIS_URL=redis://localhost:6379 NODE_ENV=development