AGENTS.md

1# Agent Instructions — agents-md-sync
2 
3Instructions for AI coding agents working on this repository. For what the tool itself does, see `README.md`.
4 
5## Project
6 
7Node/TypeScript CLI that composes an `AGENTS.md` from markdown fragments 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.
8 
9## Stack
10 
11- **Language:** TypeScript, Node 20+
12- **Runner:** `tsx` for dev, `tsc` for build
13- **CLI:** `commander`
14- **Validation:** `zod`
15- **HTTP:** `undici` (or built-in `fetch`)
16- **Tests:** `vitest`
17 
18## Coding
19 
20- TypeScript strict mode. No `any` without a written reason.
21- 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.
22- No comments that restate the code. Only comment non-obvious *why*.
23- Use Node's built-in `fetch` unless a specific `undici` feature is needed.
24- Do NOT introduce a heavy templating engine. Include markers are `<!-- include: NAME.md -->` and are resolved by simple string replacement.
25- Fragment resolution is profile-aware: `profiles/<profile>/NAME.md` wins over `common/NAME.md`. Keep `compose.ts` pure and test both paths.
26- 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.
27- v1 allows exactly ONE profile per target. Multi-profile (polyglot) support is out of scope. Do not add it without a design discussion.
28 
29## Testing
30 
31- Unit tests go in `tests/` and mirror `src/` layout.
32- `src/compose.ts` MUST be covered by unit tests — it is the only pure-logic module and the heart of the tool.
33- 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.
34- Run tests with `npm test` (vitest). Every PR must pass tests locally before opening.
35- **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 fragment changes, the sample file must be updated in the same commit. CI fails if committed samples drift from what `compose.ts` produces.
36 
37## Review & Git
38 
39- No direct pushes to `master`/`main`. Always work on a feature branch and open a PR.
40- 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`.
41- Commits: short imperative subject line, body optional. No Conventional Commits requirement yet.
42 
43## Build & Run
44 
45```bash
46npm install
47npm run build          # tsc to dist/
48npx tsx src/index.ts --config examples/targets.json --dry-run
49```
50 
51## Bitbucket API notes
52 
53- Target is **Bitbucket Data Center** (self-hosted). API base: `/rest/api/1.0/`. Do NOT use Bitbucket Cloud endpoints (`/2.0/`).
54- Auth: `Authorization: Bearer $BITBUCKET_TOKEN`.
55- File write is `PUT /projects/{key}/repos/{slug}/browse/{path}` with multipart form fields `content`, `message`, `branch`, `sourceCommitId`.
56- When the PR branch already exists, update it — do not create a second branch.
57 
58## Do not
59 
60- Do not push directly to `master`/`main`.
61- 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.
62- 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.
63- Do not skip pre-commit hooks (`--no-verify`) or Git signing without explicit user approval.
64- Do not add support for Bitbucket Cloud or GitHub in v1 — it's out of scope.
65