[Gdewilde]

Summary

Adds portman --initAgents, which writes standing instructions for coding agents to AGENTS.md in the current directory, and to CLAUDE.md when that file already exists.

The Portman section tells agents:

• how to run the contract tests: npx @apideck/portman --cliOptionsFile <path> when a portman-cli.json exists (in ./ or ./portman/, the --init default), otherwise a generic -l <openapi-file> -c portman-config.json -b <baseUrl> --runNewman command
• that a failing contract test means the implementation or the spec is wrong. Agents should fix the code or deliberately change the spec, and never edit the generated collection or disable checks in portman-config.json to get a green run
• to append --newmanRunOptions '{"abortOnFailure":false}' to see all failures, because Portman aborts on the first failure by default
• where to find the docs (https://getportman.com/docs) and the docs MCP server (https://getportman.com/mcp)

Design

• A boolean flag, following --init: it is handled early in src/index.ts and exits, without loading a spec or config. The CLI has no subcommands (yargs runs in strict, flag-only mode), so a flag is the consistent choice.
• It is idempotent: the block is wrapped in <!-- portman:start --> / <!-- portman:end -->. When the markers exist, the block between them is replaced. Otherwise the block is appended after the existing content, separated by a blank line. Content outside the markers is preserved.
• It is non-interactive (no prompts), so agents and scripts can run it.
• The logic lives in src/utils/initAgents.ts (initAgents(cwd), renderAgentInstructions, upsertAgentInstructions).

Tests

• src/utils/initAgents.test.ts (temp dirs): creates AGENTS.md, uses the detected portman-cli.json, appends while preserving content, re-runs idempotently while preserving surrounding content, updates CLAUDE.md only when it exists
• Portman.test.ts, tsc --noEmit, oxlint and oxfmt pass
• Manual CLI run on Node 22 in an empty dir that has CLAUDE.md + portman-cli.json: both files written, a re-run leaves one block

Limitations

• If CLAUDE.md only imports AGENTS.md (@AGENTS.md), the block ends up in an agent's context twice. Harmless, but it could be skipped in a follow-up.
• portman-cli.json is only detected in ./ and ./portman/.

🤖 Generated with Claude Code