hyperpolymath · Sep 19, 2026 · Sep 19, 2026
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,103 @@
+# Clone the repository
+
+git clone <https://github.com/hyperpolymath/asdf-tool-plugins.git> cd
+asdf-tool-plugins
+
+# Using Guix (recommended for reproducibility)
+
+guix develop
+
+# Or using toolbox/distrobox
+
+toolbox create asdf-tool-plugins-dev toolbox enter asdf-tool-plugins-dev
+\# Install dependencies manually
+
+# Verify setup
+
+just check \# or: cargo check / mix compile / etc. just test \# Run test
+suite
+
+
+    ### Repository Structure
+
+asdf-tool-plugins/ ├── src/ \# Source code (Perimeter 1-2) ├── lib/ \#
+Library code (Perimeter 1-2) ├── extensions/ \# Extensions (Perimeter 2)
+├── plugins/ \# Plugins (Perimeter 2) ├── tools/ \# Tooling (Perimeter
+2) ├── docs/ \# Documentation (Perimeter 3) │ ├── architecture/ \# ADRs,
+specs (Perimeter 2) │ └── proposals/ \# RFCs (Perimeter 3) ├── examples/
+\# Examples (Perimeter 3) ├── spec/ \# Spec tests (Perimeter 3) ├──
+tests/ \# Test suite (Perimeter 2-3) ├── .well-known/ \# Protocol files
+(Perimeter 1-3) ├── .github/ \# GitHub config (Perimeter 1) │ ├──
+ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md \# This file ├── GOVERNANCE.md ├── LICENSE ├──
+MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix \# Guix
+flake (Perimeter 1) └── Justfile \# Task runner (Perimeter 1)
+
+
+    ---
+
+    ## How to Contribute
+
+    ### Reporting Bugs
+
+    **Before reporting**:
+    1. Search existing issues
+    2. Check if it's already fixed in `main`
+    3. Determine which perimeter the bug affects
+
+    **When reporting**:
+
+    Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include:
+
+    - Clear, descriptive title
+    - Environment details (OS, versions, toolchain)
+    - Steps to reproduce
+    - Expected vs actual behaviour
+    - Logs, screenshots, or minimal reproduction
+
+    ### Suggesting Features
+
+    **Before suggesting**:
+    1. Check the [roadmap](ROADMAP.md) if available
+    2. Search existing issues and discussions
+    3. Consider which perimeter the feature belongs to
+
+    **When suggesting**:
+
+    Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include:
+
+    - Problem statement (what pain point does this solve?)
+    - Proposed solution
+    - Alternatives considered
+    - Which perimeter this affects
+
+    ### Your First Contribution
+
+    Look for issues labelled:
+
+    - [`good first issue`](https://github.com/hyperpolymath/asdf-tool-plugins/labels/good%20first%20issue) — Simple Perimeter 3 tasks
+    - [`help wanted`](https://github.com/hyperpolymath/asdf-tool-plugins/labels/help%20wanted) — Community help needed
+    - [`documentation`](https://github.com/hyperpolymath/asdf-tool-plugins/labels/documentation) — Docs improvements
+    - [`perimeter-3`](https://github.com/hyperpolymath/asdf-tool-plugins/labels/perimeter-3) — Community sandbox scope
+
+    ---
+
+    ## Development Workflow
+
+    ### Branch Naming
+
+docs/short-description \# Documentation (P3) test/what-added \# Test
+additions (P3) feat/short-description \# New features (P2)
+fix/issue-number-description \# Bug fixes (P2) refactor/what-changed \#
+Code improvements (P2) security/what-fixed \# Security fixes (P1-2)
+
+
+    ### Commit Messages
+
+    We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+():
+
+\[optional body\]
+
+\[optional footer\]
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
diff --git a/asdf-ada-plugin/README.adoc b/asdf-ada-plugin/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall ada <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-age-plugin/README.adoc b/asdf-age-plugin/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall age <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-apko-plugin/README.adoc b/asdf-apko-plugin/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall apko <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-arangodb-plugin/README.adoc b/asdf-arangodb-plugin/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall arangodb <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh
@@ -62,7 +62,7 @@ section "Category 1: Documentation"
 
 check "README exists" "[[ -f README.adoc ]]"
 check "README is comprehensive (>100 lines)" "[[ -f README.adoc ]] && [[ \$(wc -l < README.adoc) -gt 100 ]]"
-check "CONTRIBUTING exists" "[[ -f CONTRIBUTING.adoc ]]"
+check "CONTRIBUTING exists" "[[ -f ../../../.github/CONTRIBUTING.md ]]"
 check "CODE_OF_CONDUCT.adoc exists" "[[ -f CODE_OF_CONDUCT.adoc ]]"
 check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]]"
 check "SECURITY.adoc exists" "[[ -f SECURITY.adoc ]]"
@@ -103,7 +103,7 @@ check "Input validation present" "grep -q 'ASDF_INSTALL_VERSION' bin/download"
 # =============================================================================
 section "Category 4: Contributing"
 
-check "CONTRIBUTING comprehensive (>50 lines)" "[[ -f CONTRIBUTING.adoc ]] && [[ \$(wc -l < CONTRIBUTING.adoc) -gt 50 ]]"
+check "CONTRIBUTING comprehensive (>50 lines)" "[[ -f ../../../.github/CONTRIBUTING.md ]] && [[ \$(wc -l < ../../../.github/CONTRIBUTING.md) -gt 50 ]]"
 check "CODE_OF_CONDUCT follows Contributor Covenant" "grep -q 'Contributor Covenant' CODE_OF_CONDUCT.adoc"
 check "Issue templates exist" "[[ -d .github/ISSUE_TEMPLATE ]]"
 check "Bug report template exists" "[[ -f .github/ISSUE_TEMPLATE/bug_report.md ]]"

diff --git a/asdf-augmenters/asdf-ghjk/scripts/setup-dev.sh b/asdf-augmenters/asdf-ghjk/scripts/setup-dev.sh
@@ -107,6 +107,6 @@ echo "Next steps:"
 echo "  1. Run tests: ./test/bats/bin/bats test/"
 echo "  2. Lint code: shellcheck bin/* lib/*.sh lib/*.bash"
 echo "  3. Try installing ghjk: asdf install ghjk latest"
-echo "  4. Read CONTRIBUTING.adoc for development guidelines"
+echo "  4. Read ../../../.github/CONTRIBUTING.md for development guidelines"
 echo ""
 echo "Happy coding! 🎉"
diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/ada/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/ada/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall ada <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/age/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/age/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall age <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/apko/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/apko/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall apko <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/arangodb/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/arangodb/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall arangodb <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/bebop/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/bebop/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall bebop <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/borg/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/borg/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall borg <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/casket-ssg/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/casket-ssg/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall casket-ssg <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/cassandra/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/cassandra/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall cassandra <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/cfssl/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/cfssl/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall cfssl <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/cobalt/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/cobalt/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall cobalt <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/cobol/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/cobol/README.adoc
@@ -69,7 +69,7 @@ asdf uninstall cobol <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/coredns/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/coredns/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall coredns <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License

diff --git a/asdf-augmenters/asdf-plugin-collection/plugins/cosign/README.adoc b/asdf-augmenters/asdf-plugin-collection/plugins/cosign/README.adoc
@@ -68,7 +68,7 @@ asdf uninstall cosign <version>
 
 === Contributing
 
-Contributions welcome! Read the link:CONTRIBUTING.adoc[contributing
+Contributions welcome! Read the link:../../../../.github/CONTRIBUTING.md[contributing
 guidelines] first.
 
 === License