Agent Instructions — agents-md-sync

Instructions for AI coding agents working on this repository. For what the tool itself does, see README.md.

Project

Node/TypeScript CLI that composes an AGENTS.md from markdown partials held in a central Bitbucket template repo, commits and pushes the result to a tool-owned branch on each target Bitbucket Data Center repo, and — when --pr is passed — opens or updates a pull request for that branch. Greenfield — currently only README and this file exist.

Stack

• Language: TypeScript, Node 20+
• Runner: tsx for dev, tsc for build
• CLI: commander
• Validation: zod
• HTTP: undici (or built-in fetch)
• Tests: vitest

Coding

• TypeScript strict mode. No any without a written reason.
• Prefer small, pure functions. Keep I/O (Bitbucket API, fs) at the edges; keep composition logic pure so it can be unit-tested without network.
• No comments that restate the code. Only comment non-obvious why.
• Use Node's built-in fetch unless a specific undici feature is needed.
• Do NOT introduce a heavy templating engine. Include markers are <!-- include: NAME.md --> and are resolved by simple string replacement.
• Partial resolution is profile-aware: profiles/<profile>/NAME.md wins over common/NAME.md. Keep compose.ts pure and test both paths.
• The default AGENTS.md.tmpl skeleton lives as a DEFAULT_SKELETON constant in src/templateLoader.ts. A profile can opt into a bespoke skeleton by dropping AGENTS.md.tmpl into its directory; absent that file, the default is used.
• v1 allows exactly ONE profile per target. Multi-profile (polyglot) support is out of scope. Do not add it without a design discussion.

Testing

• Unit tests go in tests/ and mirror src/ layout.
• src/compose.ts MUST be covered by unit tests — it is the only pure-logic module and the heart of the tool.
• Network-touching code (src/bitbucket.ts, src/sync.ts) is tested via mocked fetch or integration tests against a sandbox repo, never against real production Bitbucket repos.
• Run tests with npm test (vitest). Every PR must pass tests locally before opening.
• Sample outputs are golden fixtures. examples/sample-output-<profile>.md is re-rendered on every build and test run by composing each profile in examples/template-repo/profiles/ against examples/template-repo/common/. npm run build and npm test both invoke the render step. If a profile partial changes, the sample file must be updated in the same commit. CI fails if committed samples drift from what compose.ts produces.

Review & Git

• No direct pushes to master/main. Always work on a feature branch and open a PR.
• This repo is NOT a fork. Standard PR targeting applies — but if that ever changes, confirm the PR target with the user before running gh pr create.
• Commits: short imperative subject line, body optional. No Conventional Commits requirement yet.

Build & Run

npm install
npm run build          # tsc to dist/
npx tsx src/index.ts --config examples/targets.json --dry-run

Bitbucket API notes

• Target is Bitbucket Data Center (self-hosted). API base: /rest/api/1.0/. Do NOT use Bitbucket Cloud endpoints (/2.0/).
• Auth: Authorization: Bearer $BITBUCKET_TOKEN.
• File write is PUT /projects/{key}/repos/{slug}/browse/{path} with multipart form fields content, message, branch, sourceCommitId.
• When the PR branch already exists, update it — do not create a second branch.

Do not

• Do not push directly to master/main.
• Do not commit secrets, tokens, or targets.json files that contain real Bitbucket URLs/credentials. Add a .env and examples/targets.json with dummy values only.
• Do not touch any file in a target repo's .agents/ directory. That directory is 100% repo-owned — the tool reads .agents/<NAME>.md files as per-section addenda when composing AGENTS.md, but only writes AGENTS.md itself.
• Do not skip pre-commit hooks (--no-verify) or Git signing without explicit user approval.
• Do not add support for Bitbucket Cloud or GitHub in v1 — it's out of scope.