chore: improve contribution guidelines and add PR template

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,6 +7,9 @@ assignees: ''
 
 ---
 
+> [!IMPORTANT]
+> Wait for a maintainer to approve this issue before opening a PR. We'll signal approval with a comment or label. Feature PRs without an approved issue will be closed.
+
 ## ✨ Feature Request
 
 **Is your feature request related to a problem? Please describe.**

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Description
+
+<!-- What does this PR do? Why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] Feature (requires an approved issue — see below)
+- [ ] Refactor / chore
+- [ ] Documentation
+
+## Checklist
+
+- [ ] I have linked the related issue below
+- [ ] My code follows the existing style and conventions
+- [ ] I have tested my changes locally
+- [ ] I have included screenshots for any UI changes
+
+## Linked issue
+
+Closes #<!-- issue number -->
+
+> **Feature PRs without a linked, approved issue will be closed without review.**
+> Open or comment on a [feature request](https://github.com/kanbn/kan/issues/new?template=feature_request.md) first and wait for maintainer approval before building.

CONTRIBUTING.md

@@ -1,52 +1,54 @@
 # Contributing to Kan
 
-Thank you for your interest in contributing to Kan! This document provides guidelines and instructions for contributing to the project.
+Thank you for your interest in contributing to Kan!
 
-## Getting Started
+## Before you start
+
+**Open an issue before writing code for a new feature.**
+
+Feature PRs opened without a prior approved issue will be closed without review - not because the idea is bad, but because we can't review code for features we haven't aligned on yet. This protects your time as much as ours.
+
+The process is:
+
+1. Open a [feature request](https://github.com/kanbn/kan/issues/new?template=feature_request.md) and describe what you want to build
+2. Wait for a maintainer to respond and signal approval (we aim to respond within a few days)
+3. Once approved, open a PR that links the issue
+
+Bug fixes and documentation improvements don't need prior approval - just open a PR.
+
+---
+
+## Getting started
 
 1. Fork the repository
 2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/kan.git`
-3. Create a new branch: `git checkout -b feat/your-feature-name`
+3. Create a branch: `git checkout -b feat/your-feature-name` or `fix/your-fix-name`
 4. Install dependencies: `pnpm install`
 5. Copy `.env.example` to `.env` and configure your environment variables
 6. Make your changes
-7. Commit your changes: `git commit -m "feat: description of changes"`
+7. Commit using [conventional commits](https://www.conventionalcommits.org/): `git commit -m "feat: description"`
-8. Push to your fork: `git push origin feat/your-feature-name`
+8. Push and open a Pull Request
-9. Open a Pull Request
 
-## Development Guidelines
+## Pull request expectations
 
-### Code Style
+- Link the related issue (required for features)
+- Write a clear description of what changed and why
+- Include screenshots for any UI changes
+- Keep PRs focused - one feature or fix per PR
+- All CI checks must pass before review
 
-- Follow the existing code style
+## Code style
-- Use meaningful variable and function names
+
-- Add comments for complex logic
+- Follow the existing patterns in the codebase
+- Use meaningful names - avoid comments that just restate what the code does
 - Keep functions focused and concise
 
-### Commits
+## Need help?
 
-- Use clear and descriptive commit messages
+- Join our [Discord server](https://discord.gg/e6ejRb6CmT)
-- Reference issue numbers when applicable
+- Check existing issues and PRs before opening new ones
-- Keep commits focused on single changes
-
-### Pull Requests
-
-- Provide a clear description of the changes
-- Include screenshots for UI changes
-- Keep PRs focused on a single feature/fix
-
-## Need Help?
-
-- Join our [Discord server](https://discord.gg/e6ejRb6CmT) for questions
-- Check existing issues and pull requests
 - Email [henry@kan.bn](mailto:henry@kan.bn) for major concerns
 
-## Code of Conduct
-
-Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
-
-We aim to foster an inclusive and welcoming community. Harassment and abusive behavior will not be tolerated.
-
 ## License
 
 By contributing to Kan, you agree that your contributions will be licensed under the AGPLv3 License.