docs: add AGENTS.md house rules; add PR template and issue forms

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,38 @@
+---
+name: Bug report
+description: Report a problem to help us improve
+labels: [bug]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened? What did you expect?
+      placeholder: Clear, concise description of the bug
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps To Reproduce
+      description: List exact steps and any commands run
+      placeholder: |
+        1. …
+        2. …
+        3. …
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, shell, relevant versions
+      placeholder: macOS 14 / Fedora 40, zsh 5.9, VS Code 1.xx
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: Paste errors or attach screenshots
+      render: shell

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+---
+blank_issues_enabled: false
+contact_links:
+  - name: Questions
+    url: https://github.com/benrozsa/dotfiles/discussions
+    about: Ask usage questions and get support here

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+---
+name: Feature request
+description: Suggest an idea or improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve?
+      placeholder: I need a way to …
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What would you like to see? Be specific.
+      placeholder: Add a flag … / create a script …
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches and why they’re not ideal
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Links, prior art, screenshots

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+Title
+
+- Use Conventional Commits: type(scope): short summary
+  - Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+
+Summary
+
+- What does this change do and why?
+
+Changes
+
+- Bullet the key changes
+- Reference issues (e.g., Closes #123)
+
+Testing
+
+- How did you validate the changes?
+
+Checklist
+
+- [ ] Title follows Conventional Commits
+- [ ] CI passes (ShellCheck, Yamllint, Actionlint)
+- [ ] Docs updated (README/CONTRIBUTING/CHANGELOG as needed)
+

.github/workflows/shellcheck.yml

@@ -35,9 +35,25 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+      - name: Install ShellCheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
       - name: Run ShellCheck
-        uses: ludeeus/action-shellcheck@v2
-        with:
-          severity: error
-          check_together: true
-          path: .
+        shell: bash
+        run: |
+          set -euo pipefail
+          mapfile -t files < <(git ls-files \
+            '**/*.sh' \
+            '**/*.bash' \
+            '**/*.zsh' \
+            '**/.bashrc' \
+            '**/.bash_aliases' \
+            '**/.zshrc' \
+            '**/.profile')
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No shell files to check."
+            exit 0
+          fi
+          echo "Checking ${#files[@]} file(s) with ShellCheck..."
+          shellcheck -S error -x "${files[@]}"

AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS House Rules
+
+These are persistent, repo-local instructions for AI assistants and automation working in this repository. Follow them in every session.
+
+## Safety & Workflow
+
+- Never push directly to `main`. Open a PR from a branch.
+- Keep PRs small, focused, and well-titled (Conventional Commits).
+- Use the PR template. Provide a clear Summary, Changes, and Testing notes.
+- Confirm before destructive or sweeping changes; prefer additive or reversible edits.
+- Do not modify credentials, tokens, or secrets. Never log secrets.
+
+## Commits & Releases
+
+- Conventional Commits for titles: `type(scope): summary` (feat, fix, docs, ci, chore, refactor, test, build, perf, revert).
+- Update `CHANGELOG.md` as the canonical source for release notes.
+- For releases: create short GitHub Release highlights and link to the matching changelog section.
+- Use SemVer-lite during 0.x (patch=docs/CI/meta; minor=features; major=breaking).
+
+## CI & Quality
+
+- Ensure CI passes before merge: ShellCheck, Yamllint, Actionlint.
+- Pin or avoid third-party GitHub Actions when possible; prefer native tools (e.g., apt-get install).
+- Format shell with `shfmt` (2 spaces, `-i 2 -ci -bn -sr`) and fix ShellCheck findings or justify exceptions inline.
+
+## Documentation
+
+- Keep README concise: quick start, requirements, revert path, platform notes.
+- Use CONTRIBUTING for deeper details (formatting, CI, release process).
+- Prefer clarity over cleverness; reflect actual behavior (e.g., PATH-based shfmt vs wrapper).
+
+## Scope Discipline
+
+- Make only changes explicitly requested or necessary to complete the task.
+- If you discover useful adjacent improvements, propose them in the PR description; do not include unless approved.
+
+## Branch Strategy
+
+- Branch naming: `type/scope/short-description` (e.g., `ci/shellcheck-native`, `docs/readme-badges`).
+- Keep linear history; avoid force-push to shared branches.
+
+## Communication
+
+- Be explicit about assumptions and side effects.
+- When uncertain, ask for confirmation with clear options.
+
+## Local Overrides & Safety
+
+- Respect user-local overrides (e.g., `*.local` files) and avoid clobbering personalized settings.
+- For installers or scripts, provide a `--dry-run` option when adding new ones.
+
+## Examples
+
+- Good PR title: `ci(shellcheck): install and run native shellcheck on ubuntu-latest`
+- Good commit title: `docs(readme): clarify shfmt from PATH`
+
+By following these, assistants and humans can collaborate safely and consistently.