DEVELOPMENT.md

Development Notes (for humans and AI agents)

Before implementing a new tool or feature:

1. Check https://github.com/amcbstudio for existing repositories.
2. Do not duplicate functionality.
3. Prefer extending an existing tool only if it does not break its contract.

Hard constraints (non-negotiable)

• If a script uses #!/bin/sh, it MUST be strictly POSIX-compliant.

  • No bashisms (local, arrays, [[ ]], process substitution, etc).
  • If bash is required, the shebang MUST explicitly be #!/usr/bin/env bash.

• jq programs MUST NOT interpolate shell variables directly.

  • Always pass data via --arg / --argjson.
  • This avoids injection bugs and preserves determinism.

• stdout is reserved for machine-readable output only.

  • Human-oriented messages, diagnostics, and errors go to stderr.

Style guidelines

• Small tools > large tools
• One responsibility per tool
• Clear input/output boundaries
• Avoid cleverness
• Prefer clarity over brevity if forced to choose

Testing

• Include simple, reproducible test cases.
• Tests should be runnable locally without external services.
• Golden-file tests are preferred where applicable.

Documentation

• Documentation should explain what the tool does, not why it is interesting.
• Examples must be copy-pasteable.
• Do not include long explanations or narratives.