docs: add contribution process, maintainer guide, and stale bot

- CONTRIBUTING.md: issue-first rule, design principles, rejection guidelines, review process
- docs/maintainer-guide.md: public maintenance process, versioning, bug severity, release flow
- .github/workflows/stale.yml: auto-stale at 30 days, auto-close at 44 days
- README.md: add CI badge
- .gitignore: exclude private maintainer SOP

Author: agntlab

.github/workflows/stale.yml

@@ -0,0 +1,24 @@
+name: 'Close stale issues'
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
+
+permissions:
+  issues: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. If this is still relevant, please comment to keep it open.'
+          close-issue-message: 'Closed due to inactivity. Feel free to reopen with new information.'
+          days-before-stale: 30
+          days-before-close: 14
+          stale-issue-label: 'stale'
+          exempt-issue-labels: 'confirmed,help-wanted,critical'
+          stale-pr-message: 'This PR has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs.'
+          days-before-pr-stale: 21
+          days-before-pr-close: 14
+          stale-pr-label: 'stale'

.gitignore

@@ -0,0 +1,2 @@
+# Private maintainer files
+docs/maintainer-sop-private.md

CONTRIBUTING.md

@@ -2,17 +2,32 @@
 
 Thanks for your interest in improving the Notetaker skill. This is a single-file product, so contributions tend to be focused and high-impact.
 
+## Before You Start
+
+**Open an issue first.** All contributions start as an issue - bug report, feature request, or skill improvement. Wait for a `confirmed` or `help-wanted` label before starting work. This prevents wasted effort on changes that don't align with the project direction.
+
+PRs without a linked issue will be closed with a note to open an issue first.
+
 ## License
 
-This project uses MIT license. By submitting a pull request, you agree that your contributions are licensed under the same MIT license. No CLA required.
+MIT license. By submitting a pull request, you agree that your contributions are licensed under the same terms. No CLA required.
+
+## Design Principles
+
+These guide every decision. PRs that conflict with these principles will be rejected:
+
+1. **Minimal friction** - The skill exists to capture ideas before they're forgotten. Anything that adds steps or cognitive load works against this
+2. **Small by design** - The skill file stays under ~1,500 words. Complexity lives in `references/`, not in the main file
+3. **Capture, don't act** - Claude records and moves on. It never analyzes, expands, or offers to help with note content during capture
+4. **Voice-first** - Primary use case is hands-free dictation. Triggers must work when spoken, not just typed
 
 ## What to Contribute
 
 **High value:**
-- New trigger patterns that feel natural
 - Voice cleanup rule improvements (especially for non-English speakers)
 - Edge cases where classification fails
-- Real-world session transcripts showing unexpected behavior
+- Real-world session transcripts showing unexpected behaviour
+- Bug fixes with clear reproduction steps
 
 **Lower priority:**
 - Formatting changes to the skill file
@@ -21,11 +36,12 @@ This project uses MIT license. By submitting a pull request, you agree that your
 
 ## How to Submit
 
-1. Fork the repository
-2. Create a branch: `improvement/short-description`
-3. Make your changes
-4. Test by uploading the modified `notetaker.md` to a Claude Project and running through 10+ notes
-5. Submit a PR using the template
+1. Open an issue and wait for `confirmed` or `help-wanted` label
+2. Fork the repository
+3. Create a branch: `improvement/short-description`
+4. Make your changes
+5. Test by uploading the modified `notetaker.md` to a Claude Project and running through 10+ notes
+6. Submit a PR referencing the issue number
 
 ## Skill File Changes
 
@@ -37,14 +53,26 @@ All changes to `notetaker.md` require:
 
 See `.github/SKILL_REVIEW_CHECKLIST.md` for the full review criteria.
 
+## Review Process
+
+PRs are reviewed within 72 hours. Three outcomes:
+
+- **Approve** - Merged via squash commit
+- **Request changes** - One round of revision. Clear feedback on what needs to change
+- **Close** - With an explanation. Common reasons:
+  - Out of scope for the skill's purpose
+  - Adds complexity that outweighs the benefit
+  - Conflicts with design principles above
+  - No linked issue or issue wasn't confirmed
+
+Rejections are not personal. If you disagree, discuss in the issue - not the PR.
+
 ## Reporting Issues
 
 Use the issue templates:
-- **Bug report:** Claude does something wrong during capture or processing
-- **Feature request:** A new capability you want
-- **Skill improvement:** A better way to phrase an existing instruction
-
-Include a conversation transcript when reporting bugs. Copy-paste the exchange showing the problem.
+- **Bug report** - Claude does something wrong during capture or processing. Include a conversation transcript
+- **Feature request** - A new capability you want. Explain the use case, not just the feature
+- **Skill improvement** - A better way to phrase an existing instruction
 
 ## Code of Conduct
 

README.md

@@ -2,6 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](CHANGELOG.md)
+[![CI](https://github.com/agntlab/claude-notetaker/actions/workflows/skill-scan.yml/badge.svg)](https://github.com/agntlab/claude-notetaker/actions/workflows/skill-scan.yml)
 
 Voice-friendly note capture for Claude. Capture ideas hands-free while driving, walking, or cooking. Fillers, false starts, and dictation artifacts are cleaned up automatically. Notes are organized into handoff files you can pick up in future sessions.
 

docs/maintainer-guide.md

@@ -0,0 +1,56 @@
+# Maintainer Guide
+
+How this project is maintained, so contributors know what to expect.
+
+## Contribution Flow
+
+1. **Issue first** - All work starts as an issue. Bug reports, feature requests, and improvements go through issue templates
+2. **Triage** - Issues are reviewed within 48 hours and labelled: `confirmed`, `help-wanted`, `cannot-reproduce`, or closed with explanation
+3. **PR** - Once an issue has `confirmed` or `help-wanted`, contributors can fork, branch, and submit a PR referencing the issue
+4. **Review** - PRs are reviewed within 72 hours. One round of revision if needed
+5. **Merge** - Squash merge to keep history clean. CHANGELOG updated with each release
+
+## Bug Severity
+
+| Label | Definition | Response Time |
+|-------|-----------|---------------|
+| `critical` | Skill breaks Claude's behaviour (e.g., acts on note content, ignores triggers entirely) | Fixed within 1 week by maintainer |
+| `minor` | Edge case, cosmetic, or non-blocking issue | Labelled `help-wanted` for community |
+
+## Versioning
+
+This project uses [Semantic Versioning](https://semver.org/):
+
+- **Patch** (3.0.x) - Bug fixes, typo corrections
+- **Minor** (3.x.0) - New triggers, new reference files, non-breaking improvements
+- **Major** (x.0.0) - Breaking changes to skill structure, trigger removals
+
+## Release Process
+
+1. Changes merged to `main` via squash merge
+2. CHANGELOG.md updated
+3. Git tag created (e.g., `v3.0.1`)
+4. GitHub Release published with CHANGELOG entry as notes
+
+## Branch Protection
+
+- All changes to `main` go through PRs
+- CI must pass before merge
+- Maintainer approval required
+- Squash merge only
+
+## Stale Issues
+
+- Issues with no activity for 30 days receive a `stale` label
+- 14 more days of silence and the issue is closed
+- Stale issues can be reopened with new information
+
+## If a Bad Merge Gets Through
+
+1. Revert via `git revert` (not force push)
+2. Comment on the original PR explaining what broke
+3. Open a new issue for the proper fix
+
+## Decision Log
+
+Non-obvious design decisions are recorded in `docs/decisions/`. Format: `YYYY-MM-DD-decision-title.md` with context, options considered, and reasoning. This prevents re-litigating settled decisions.