ARPAHLS · rosspeili · Jul 30, 2026 · Jul 28, 2026 · Jul 29, 2026
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,33 @@
+## Description
+
+<!-- Summarize what changed, why it is needed, and the approach taken. -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] Feature or enhancement
+- [ ] Documentation
+- [ ] Session logic
+- [ ] CLI
+- [ ] Settings or configuration
+- [ ] Tests or CI
+
+## Validation
+
+- [ ] The scope matches the linked issue and contains no unrelated changes.
+- [ ] Tests were added or updated for behavior changes.
+- [ ] The relevant tests and full `pytest` suite pass locally.
+- [ ] The CI-blocking Flake8 checks pass locally.
+- [ ] `CHANGELOG.md` was updated under `[Unreleased]` for user-visible changes, or is not applicable.
+- [ ] `rooms.settings.example.yaml` was updated for settings schema changes, or is not applicable.
+- [ ] User-facing documentation was updated where needed.
+
+## Test Results
+
+<!-- List the commands run and their results. -->
+
+## Related Issues
+
+<!-- Use "Fixes #N" to close an issue on merge or "Refs #N" for context. -->
+
+Fixes #
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,59 +4,143 @@
   # Contributing to Rooms
 </div>
 
-<br/>
+Thank you for helping improve Rooms. This guide is the entry point for code, CLI, settings, documentation, and test contributions. Rooms is local-first: changes should preserve user privacy, predictable orchestration, and offline-friendly testing.
 
-Thank you for your interest in contributing to Rooms. We welcome contributions from the community to help make this framework even better for local-first multi-agent orchestration.
+## Navigation
 
-**Documentation:** see the [docs hub](docs/README.md) for architecture, settings, examples, and testing guides.
+| Section | Purpose |
+| :--- | :--- |
+| [Ways to contribute](#ways-to-contribute) | Choose the right scope and verification path |
+| [Getting started](#getting-started) | Fork, sync, branch, and install |
+| [Universal expectations](#universal-expectations) | Follow project-wide contribution standards |
+| [Pull request process](#pull-request-process) | Prepare a reviewable PR |
+| [Related documents](#related-documents) | Find architecture, testing, and configuration references |
 
----
+## Ways to contribute
 
-## How to Contribute
+Start from an approved or assigned issue when possible. For larger behavior or architecture changes, discuss the approach with maintainers before implementation.
 
-### Reporting Bugs
-Use the Bug Report template to describe the issue. Provide clear steps to reproduce the bug and include information about your environment (OS, Python version, Local LLM provider).
+Use the GitHub [Bug Report](https://github.com/ARPAHLS/rooms/issues/new?template=bug_report.yml) or [Feature Request](https://github.com/ARPAHLS/rooms/issues/new?template=feature_request.yml) template when opening new work.
 
-### Suggesting Enhancements
-Use the Feature Request template. Explain the motivation behind the suggestion and how it benefits the framework.
+| Type | Typical paths | Labels | Verify locally |
+| :--- | :--- | :--- | :--- |
+| Core framework | `rooms/agent.py`, `rooms/session.py`, `rooms/config.py` | `enhancement`, `session-logic` | Relevant unit tests plus the full suite |
+| CLI wizard | `cli.py`, `rooms/skills_cli.py` | `cli` | `tests/test_cli.py`, CLI settings smoke tests |
+| Settings | `rooms/settings.py`, `rooms.settings.example.yaml` | `enhancement`, `cli` | `tests/test_settings.py`, `tests/test_cli_settings_smoke.py` |
+| Documentation | `README.md`, `docs/`, `CONTRIBUTING.md` | `documentation` | Run `pytest tests/test_docs_hub.py -q` |
+| Tests | `tests/test_*.py` | `testing` | Run the changed test and the full suite |
+| Bug fix | Paths identified by the issue | `bug` | Add a regression test that fails before the fix |
+| Good first issue | Usually focused docs, tests, or small fixes | `good first issue` | Follow the verification path for the underlying type |
 
-### Pull Requests
-1. **Fork the Repository**: Create your own branch from `main`.
-2. **Implement Changes**: Follow the project's coding style and naming conventions.
-3. **Run Tests**: Ensure all existing tests pass by running:
-   ```bash
-   $env:PYTHONPATH="."; python -m pytest tests/ -v
-   ```
-4. **Add Tests**: If you are adding new logic, please include corresponding tests in `tests/test_session.py`.
-5. **Submit PR**: Provide a clear description of what the PR changes and why.
-6. **Update Changelog**: Please note that a project changelog exists at `CHANGELOG.md`. Contributors will be requested to update the `[Unreleased]` section of the changelog once official versioned releases begin.
----
+## Getting started
+
+### 1. Fork and clone
+
+Fork [ARPAHLS/rooms](https://github.com/ARPAHLS/rooms), then clone your fork and register the upstream repository:
+
+```bash
+git clone https://github.com/<your-username>/rooms.git
+cd rooms
+git remote add upstream https://github.com/ARPAHLS/rooms.git
+```
+
+### 2. Sync and branch
+
+Create every branch from the latest upstream `main`:
+
+```bash
+git fetch upstream
+git checkout main
+git pull --ff-only upstream main
+git checkout -b feat/issue-47-short-description
+```
+
+Use `<type>/issue-<number>-<short-description>`, with a focused prefix such as `feat`, `fix`, `docs`, or `test`. Do not work directly on `main`.
+
+### 3. Install dependencies
+
+Rooms targets Python 3.13. Create a virtual environment, then install runtime and contributor tools:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+python -m pip install -r requirements.txt pytest flake8
+```
+
+## Universal expectations
+
+### Scope and style
+
+- Keep the diff limited to the issue's acceptance criteria; avoid unrelated refactors.
+- Match existing Python, Markdown, Pydantic, and CLI patterns in nearby files.
+- Add or update documentation when behavior, settings, or commands change.
+- Keep inference tests deterministic. Mock LiteLLM, Ollama, filesystem, and Skillware boundaries rather than calling live services.
+- Never commit API keys, `.env`, or `rooms.settings.yaml`. Credentials belong in the environment; see [Settings & preflight](docs/SETTINGS.md).
+
+### Design principles
+
+- **Local-first:** Prefer private, offline-capable workflows and local inference where practical.
+- **Zero-leakage:** Do not send user data or credentials to third parties without explicit configuration.
+- **Aesthetic CLI:** Keep terminal output clear, consistent, and polished when changing user-facing flows.
+
+### Changelog policy
+
+Update the `[Unreleased]` section of [CHANGELOG.md](CHANGELOG.md) when a PR changes user-visible behavior, configuration, CLI output, or documented workflows users rely on. Use the existing `Added`, `Changed`, or `Fixed` headings. Tests, internal refactors, and minor wording fixes usually do not need an entry. Do not create a release version heading unless a maintainer requests it.
+
+### Tests and CI
+
+Run the full suite and the CI-blocking Flake8 checks before opening a PR:
+
+```bash
+PYTHONPATH=. python -m pytest tests/test_docs_hub.py -q  # documentation link checks
+PYTHONPATH=. python -m pytest tests/ -v
+python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+```
+
+See [Testing Strategy](docs/TESTING.md) for focused commands and mocking examples. GitHub Actions repeats lint and test checks on pull requests.
+
+### Git authorship
+
+Use an email verified on your GitHub account so commits are attributed correctly. Check before committing:
 
-## Design Philosophy
+```bash
+git config user.name
+git config user.email
+```
 
-**Local-First**
-Always favor solutions that respect user privacy and offline execution.
+If needed, set a verified email with `git config user.email "you@example.com"`. GitHub's private `noreply` address is also acceptable when enabled in your [email settings](https://github.com/settings/emails).
 
-**Aesthetic Excellence**
-All CLI and documentation updates should prioritize a premium, modern feel.
+## Pull request process
 
-**Zero-Leakage**
-Be cautious with third-party integrations that might leak data.
+1. Link the assigned or approved issue using `Fixes #123` or `Refs #123`.
+2. Implement only the requested scope and add tests for behavior changes.
+3. Update `rooms.settings.example.yaml` when the supported settings schema changes.
+4. Update `[Unreleased]` when required by the changelog policy above.
+5. Run focused tests, the full test suite, and Flake8 locally.
+6. Commit with a short imperative subject such as `fix: handle empty persona list` or `docs: clarify settings precedence`.
+7. Push the branch to your fork and open a PR against `ARPAHLS/rooms` `main` using the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
+8. Ensure CI passes and address review feedback on the same branch.
 
-## Automated Checks
-Every push and Pull Request is automatically verified by our GitHub Actions CI/CD pipeline, which runs:
-- **Style Checks**: Code formatting and linting via `flake8`.
-- **Logic Verification**: Full suite of `pytest` unit tests for turn orchestration, expertise scoring, and session memory.
+PR descriptions should explain what changed, why it changed, and how it was verified. Include screenshots only when terminal output or another visible workflow changes.
 
-Ensure your changes pass locally before submitting to maintain the build status.
+## Related documents
 
-## Project Roadmap
-Check our [GitHub Issues](https://github.com/arpahls/Rooms/issues) to see what we are currently working on.
+| Document | Purpose |
+| :--- | :--- |
+| [Architecture](docs/ARCHITECTURE.md) | LiteLLM routing, sessions, orchestration, and storage |
+| [Examples](docs/EXAMPLES.md) | Scenario and parameter guidance |
+| [Settings & preflight](docs/SETTINGS.md) | YAML, environment variables, and Ollama checks |
+| [Testing Strategy](docs/TESTING.md) | Pytest scope, commands, and mocking patterns |
+| [Documentation hub](docs/README.md) | Index of all project guides |
+| [Agent contribution workflow (planned)](https://github.com/ARPAHLS/rooms/issues/48) | Tracks the dedicated workflow guide for contributing agents |
+| [Changelog](CHANGELOG.md) | Current `[Unreleased]` changes |
+| [Pull request template](.github/PULL_REQUEST_TEMPLATE.md) | Required PR summary and checklist |
+| [GitHub Issues](https://github.com/ARPAHLS/rooms/issues) | Open work and issue templates |
 
 ---
 
 <div align="center">
   <img src="https://raw.githubusercontent.com/arpahls/cfd/main/assets/arpalogo26.png" width="40" alt="ARPA Logo">
   <br>
-  <sub>Developed and Maintained by <b>ARPA HELLENIC LOGICAL SYSTEMS</b></sub>
+  <sub>Developed and maintained by <b>ARPA HELLENIC LOGICAL SYSTEMS</b></sub>
 </div>
diff --git a/README.md b/README.md
@@ -63,7 +63,7 @@ The framework allows extreme granularity in handling session configurations:
 | [Examples & best practices](docs/EXAMPLES.md) | Parameter cheat sheet, personas, scenarios, edge cases |
 | [Skillware integration](docs/SKILLWARE.md) | Skills CLI, wizard assignment, runtime behavior |
 | [Testing](docs/TESTING.md) | Pytest, mocking, CI smoke tests |
-| [Contributing](CONTRIBUTING.md) | Bugs, PRs, design philosophy |
+| [Contributing](CONTRIBUTING.md) | Contribution types, fork workflow, local checks, and PR process |
 | [Changelog](CHANGELOG.md) | Notable updates |
 
 ## Project Structure

diff --git a/docs/README.md b/docs/README.md
@@ -22,7 +22,8 @@ Welcome to the Rooms documentation hub. Start here to find the right guide by au
 
 | Topic | Location |
 |-------|----------|
-| Contributing, design philosophy, PR workflow | [CONTRIBUTING.md](../CONTRIBUTING.md) |
+| Contribution types, fork setup, local checks, and PR workflow | [CONTRIBUTING.md](../CONTRIBUTING.md) |
+| Pull request description and review checklist | [Pull request template](../.github/PULL_REQUEST_TEMPLATE.md) |
 | Notable changes | [CHANGELOG.md](../CHANGELOG.md) |
 | Roadmap and open work | [GitHub Issues](https://github.com/arpahls/Rooms/issues) |