AGENTS.md — jira-communication

Development guide for maintaining and extending the Jira communication scripts.

Overview

Python CLI scripts using uv run. Each script is standalone with PEP 723 inline dependencies.

Setup & environment

Development requires Python 3.10+ and uv. No virtual environment needed - uv run handles dependencies.

Build & tests

# Test a script works
uv run scripts/core/jira-validate.py --help

# Test against real Jira (need ~/.env.jira configured)
uv run scripts/core/jira-validate.py --verbose

Code style & conventions

Script structure:

Use argparse with subcommands
Import shared lib: from lib.client import get_jira_client
PEP 723 header for inline dependencies
PYTHONPATH manipulation at top (copy from existing scripts)

Output formats: Every script must support --json, --quiet, and default table output via lib/output.py.

Write operations: Destructive operations (delete, move) must include --dry-run flag.

Security & safety

Never hardcode credentials
Use lib/config.py for env loading
Test --dry-run before actual writes

PR/commit checklist

Script follows existing structure (copy from similar script)
All three output formats work (--json, --quiet, table)
--dry-run for any write operation
--help is descriptive
Update SKILL.md with new script docs

Good vs. bad examples

Adding a new script:

# ✓ Copy structure from existing script
# ✓ Use lib/ imports
# ✓ Support all output formats

# ✗ Write from scratch without looking at patterns
# ✗ Hardcode auth or skip --dry-run

When stuck

Copy structure from scripts/core/jira-issue.py (good reference)
Check lib/ for shared utilities
Run --help on similar scripts

House rules

Don't read SKILL.md for development - it's user docs
Test against real Jira before PR

Maintaining this file: See root AGENTS.md for convention reference.