docs: add contribution guidelines

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,24 +1,22 @@
 name: Bug Report
 description: Report a bug in DimOS
-labels: ["bug"]
+type: Bug
 body:
   - type: textarea
     id: description
     attributes:
       label: Description
+      description: Describe what happened and include any details that seem relevant.
       value: |
-        ## System
-        <!-- e.g. Ubuntu 24.04, macOS 15.4 -->
+        ## What happened?
 
-        ## Robot/Sim/Hardware (including firmware version)
-        <!-- e.g. Unitree Go2 EDU 1.1.7, or Unity sim etc -->
+        ## What did you expect?
 
         ## Steps to reproduce
 
-        ## DimOS version
-        <!-- branch name or commit: git rev-parse --short HEAD -->
+        ## Environment
+        <!-- OS, Python version, DimOS branch/commit, robot/sim/hardware, firmware when relevant -->
 
         ## Logs / screenshots
-
     validations:
-      required: true
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -3,10 +3,27 @@ description: Suggest a new feature or improvement for DimOS
 labels: ["feature"]
 body:
   - type: textarea
-    id: description
+    id: motivation
     attributes:
-      label: Description
+      label: Problem or motivation
       description: What do you want and why?
-
     validations:
       required: true
+  - type: textarea
+    id: request-or-plan
+    attributes:
+      label: Request or implementation plan
+      description: If this is a request, describe the desired behavior. If you plan to implement it, describe your proposed approach.
+    validations:
+      required: false
+  - type: dropdown
+    id: contribution-intent
+    attributes:
+      label: How would you like to help?
+      options:
+        - "I can implement this"
+        - "I can test or review this"
+        - "Request only"
+        - "Not sure yet"
+    validations:
+      required: false

.github/pull_request_template.md

@@ -1,21 +1,30 @@
+## Contribution path
+
+<!-- Choose one path. See CONTRIBUTING.md. -->
+
+- [ ] Small, safe change that does not need a tracking issue
+- [ ] Linked issue/discussion: DIM-XXX / #XXX / URL
+
 ## Problem
 
-<!-- What feature are you adding, or what is broken/missing/sub-optimal? -->
-<!-- Context, symptoms, motivation. Link the issue. -->
+<!-- What motivated this PR? What is broken, missing, confusing, or useful? -->
 
-Closes DIM-XXX
+Closes #
 
 ## Solution
 
-<!-- What you changed and why this approach -->
-<!-- Key design decisions / tradeoffs -->
-<!-- Keep it high-signal; deep planning belongs in the issue. -->
+<!-- What approach did you take? Keep this short; the diff shows the details. -->
 
 ## How to Test
 
-<!-- oneliner required to run the actual feature -->
-<!-- blueprint for robot changes, benchmarks for transport changes etc -->
+<!-- Manual reviewer instructions for using the changed feature.
+For docs-only or template-only PRs, this may be blank. -->
 
-## Contributor License Agreement
+## Checklist
 
+- [ ] I followed the contribution path above.
+- [ ] This PR is scoped to one issue or clearly stated problem.
+- [ ] I have run the relevant checks for the files I changed.
+- [ ] I have reviewed and understand the changes in this PR.
+- [ ] I disclosed AI assistance if it materially helped prepare this PR.
 - [ ] I have read and approved the [CLA](https://github.com/dimensionalOS/dimos/blob/main/CLA.md).

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to DimOS
+
+DimOS welcomes community contributions. This guide explains how to start work, communicate scope, and submit a pull request that maintainers can review efficiently.
+
+## Before you code
+
+Choose the path that keeps discussion focused:
+
+- Small, safe changes can go straight to a pull request.
+- Non-trivial changes should start with a GitHub issue before implementation.
+- If you already have a draft pull request for a non-trivial change, open or link an issue for the design discussion and keep the PR focused on the implementation.
+- Core architecture changes should start with a GitHub issue or discussion before implementation.
+
+New contributors can start with issues labeled `good first issue`.
+
+Core architecture includes modules, streams, transports, blueprints, agents, public APIs, robot/platform support, and major dependency changes.
+
+## Pull requests
+
+Before opening a pull request, make sure it is:
+
+- scoped to one issue or clearly stated problem
+- linked to the relevant issue or discussion, unless it is a small, safe change
+- focused, without unrelated cleanup or formatting changes
+- clear about what changed and why
+- validated with the checks relevant to the files you changed
+
+The pull request template asks for the details maintainers need. Keep deeper design discussion in the issue or discussion that the PR links to, not in the PR thread.
+
+## Validation
+
+Run the relevant local checks before submitting. Pre-commit and CI will also guide you toward the required checks for the files you changed.
+
+For test guidance, see [docs/development/testing.md](docs/development/testing.md).
+
+## AI-assisted contributions
+
+AI-assisted contributions are welcome when the human contributor owns the result.
+
+If AI materially helped prepare a pull request, disclose that in the PR. You are responsible for understanding the change, checking it against the agreed scope, and running relevant validation.
+
+If you use an AI coding agent, review its work before submitting. Do not submit an agent-generated PR that you cannot explain yourself. If the PR is not ready for human review, keep it as a draft.
+
+Before submitting, make sure you can explain in your own words:
+
+- what changed and why
+- which issue or discussion scope the PR follows
+- what checks you ran and the results
+- any risks, assumptions, or follow-up work
+
+## Contributor License Agreement
+
+Before submitting a pull request, read and approve the [Contributor License Agreement](CLA.md).