Support local .env in addition to ~/.env

[aireilly]

Problem

All scripts that load environment variables hardcode ~/.env as the only .env file location. If a user has a project-local .env file (the standard convention for most projects), it is completely ignored.

This forces users to store all credentials in ~/.env, which prevents per-project credential overrides and conflicts with the common .env-in-project-root convention.

Feedback

it forces the ~/.env file when one might have it in the local .env

Affected files

Python scripts (3)

• plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py — load_env_file() only checks ~/.env
• plugins/docs-tools/skills/jira-writer/scripts/jira_writer.py — same
• plugins/docs-tools/skills/git-pr-reader/scripts/git_pr_reader.py — same

Shell scripts (3)

• plugins/docs-tools/skills/docs-workflow-create-mr/scripts/create_mr.sh — source ~/.env
• plugins/docs-tools/skills/docs-workflow-jira-ready/scripts/jira-ready-check.sh — source ~/.env
• plugins/docs-tools/skills/docs-workflow-create-jira/scripts/create-jira-ticket.sh — source ~/.env

Documentation

• plugins/docs-tools/README.md — instructs users to create ~/.env only
• Multiple SKILL.md and agent files reference ~/.env exclusively

Proposed fix

Update load_env_file() to check both locations, with local .env taking precedence over ~/.env (local overrides global):

Python:

def load_env_file():
    """Load environment variables from .env files.
    
    Loads ~/.env first (global defaults), then ./.env (local overrides).
    """
    for env_path in [os.path.expanduser("~/.env"), ".env"]:
        if os.path.exists(env_path):
            with open(env_path) as f:
                for line in f:
                    line = line.strip()
                    if line and not line.startswith("#") and "=" in line:
                        key, value = line.split("=", 1)
                        # For ~/.env: setdefault (don't overwrite existing)
                        # For ./.env: overwrite (local takes precedence)
                        if env_path == ".env":
                            os.environ[key.strip()] = value.strip()
                        else:
                            os.environ.setdefault(key.strip(), value.strip())

Shell:

# Load global defaults, then local overrides
source ~/.env 2>/dev/null || true
source .env 2>/dev/null || true

Precedence order (highest wins)

1. Pre-existing environment variables (already set in shell)
2. Local .env (project-specific overrides)
3. ~/.env (global defaults)

Additional considerations

• Update plugins/docs-tools/README.md to document both locations
• Update SKILL.md files that reference ~/.env to mention local .env as an alternative
• Ensure .env is in .gitignore (it already should be, but verify)