feat(repo): professionalization infrastructure (priorities 1-2)

.github/CODEOWNERS

@@ -0,0 +1,26 @@
+# Skill Router Owners
+
+Core routing engine and CLI:
+* @coderdoctor97 skill.py
+
+Installer:
+* @coderdoctor97 install.py
+
+Tests and benchmarks:
+* @coderdoctor97 tests/
+* @coderdoctor97 benchmarks/
+
+CI/CD and repository configuration:
+* @coderdoctor97 .github/
+
+Documentation:
+* @coderdoctor97 README.md
+* @coderdoctor97 SKILL.md
+* @coderdoctor97 docs/
+* @coderdoctor97 CONTRIBUTING.md
+* @coderdoctor97 CHANGELOG.md
+* @coderdoctor97 SECURITY.md
+
+Packaging and manifest:
+* @coderdoctor97 manifest.json
+* @coderdoctor97 pyproject.toml (when added)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Report a routing or installation issue
+title: "[bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Skill Router version**
+<!-- Run: python3 skill.py --version -->
+
+**Python version**
+<!-- Run: python --version -->
+
+**Operating system**
+<!-- e.g. Ubuntu 24.04, Windows 11, macOS 14 -->
+
+**Agent / environment**
+<!-- e.g. Claude Code, DeepSeek Harness, generic -->
+
+**Reproduction steps**
+1. …
+2. …
+3. …
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened, including the full CLI output or `--debug` output.
+
+**Minimal example**
+If possible, provide the exact `route` command and request string:
+```bash
+python3 skill.py route "your request here" --root /path/to/repo --debug
+```
+
+**Additional context**
+Add any other context about the problem here. Do not include secrets or private source code.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Propose a new feature or improvement
+title: "[feat] "
+labels: enhancement
+---
+
+**Problem**
+What problem would this feature solve?
+
+**Proposed solution**
+How would you like it to work?
+
+**Alternatives considered**
+What other approaches did you consider?
+
+**Compatibility impact**
+Would this change routing semantics? Would it require changes to skill manifests? Would it break existing installations?
+
+**Additional context**
+Add any other context or examples here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Pull Request Checklist
+
+- [ ] **What changed?** Describe the change in one or two sentences.
+- [ ] **Why?** Explain the motivation (bug fix, routing improvement, infrastructure, docs, etc.).
+- [ ] **Tests performed**
+  - [ ] `python tests/run_tests.py` passes
+  - [ ] `python skill.py validate --root .` exits 0
+  - [ ] Routing regression cases added (if routing behavior changed)
+- [ ] **Benchmark impact**
+  - [ ] `python skill.py benchmark` shows no regression (or improvement)
+  - [ ] Gold-set cases remain correct
+- [ ] **Documentation impact**
+  - [ ] `README.md` updated (if user-facing behavior changed)
+  - [ ] `SKILL.md` updated (if skill contract changed)
+  - [ ] `CONTRIBUTING.md` updated (if contributor workflow changed)
+- [ ] **Breaking changes**
+  - [ ] None
+  - [ ] Listed below with migration instructions
+
+**Additional notes**

.github/workflows/benchmark.yml

@@ -0,0 +1,44 @@
+name: Benchmark
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Run benchmark
+        run: |
+          python skill.py benchmark --repeat 3 | tee benchmark-output.txt
+
+      - name: Check for regressions
+        run: |
+          # Parse accuracy from benchmark output — fail if it drops below baseline
+          ACC=$(python skill.py benchmark --repeat 3 2>&1 | grep "^accuracy:" | awk '{print $2}' | cut -d'=' -f1 | tr -d ' ')
+          echo "Accuracy: $ACC"
+          python -c "
+          import sys
+          acc = float('$ACC'.split('/')[0]) / float('$ACC'.split('/')[1])
+          if acc < 1.0:
+              print(f'REGRESSION: accuracy dropped to {acc}')
+              sys.exit(1)
+          print(f'Benchmark passed: accuracy = {acc}')
+          "
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          retention-days: 30
+        continue-on-error: true

.github/workflows/lint.yml

@@ -0,0 +1,45 @@
+name: Lint and Validate
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Syntax check — skill.py
+        run: python -c "import py_compile; py_compile.compile('skill.py', doraise=True)"
+
+      - name: Syntax check — install.py
+        run: python -c "import py_compile; py_compile.compile('install.py', doraise=True)"
+
+      - name: Validate router state
+        run: python skill.py validate --root .
+
+      - name: Check manifest consistency
+        run: |
+          python -c "
+          import json, sys
+          # Verify this skill's own manifest is valid
+          m = json.load(open('manifest.json'))
+          assert m['name'] == 'skill-router', 'manifest name mismatch'
+          assert len(m['commands']) > 0, 'no commands declared'
+          print(f'manifest valid: {m[\"name\"]} v{m.get(\"version\", \"?\")}')
+          "

.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Verify Python version
+        run: python --version
+
+      - name: Run test suite
+        run: python tests/run_tests.py
+
+      - name: Upload test results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-py${{ matrix.python-version }}
+          retention-days: 7

.gitignore

@@ -1,3 +1,12 @@
 __pycache__/
 *.pyc
+.coverage
+htmlcov/
+.tox/
 skill-registry/.route-cache.json
+benchmark-results/
+.eggs/
+*.egg-info/
+dist/
+build/
+wheels/

CHANGELOG.md

@@ -1,9 +1,61 @@
 # Changelog
 
+All notable changes to Skill Router are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project uses
+[semantic versioning](https://semver.org/).
+
 ## Unreleased
 
-- Added a conservative global/project installer with explicit scope selection.
-- Added `--version` and `doctor` diagnostics to the router CLI.
-- Documented generic, Claude Code, and DeepSeek Harness `SKILL.md` layouts.
-- Organized the supplied Skill Router artwork under `assets/icon/`.
-- Reworked the GitHub README with installation, routing, configuration, and troubleshooting guidance.
+### Added
+- `.github/workflows/tests.yml` — CI test matrix (Python 3.10–3.13)
+- `.github/workflows/lint.yml` — CI validation and syntax checks
+- `.github/workflows/benchmark.yml` — Benchmark CI on main branch pushes
+- `.github/CODEOWNERS` — Code ownership definitions
+- `.github/ISSUE_TEMPLATE/bug_report.md` — Bug report template
+- `.github/ISSUE_TEMPLATE/feature_request.md` — Feature request template
+- `.github/PULL_REQUEST_TEMPLATE.md` — PR checklist
+- `SECURITY.md` — Security policy and vulnerability reporting process
+- `CODE_OF_CONDUCT.md` — Contributor Covenant Code of Conduct
+- `docs/` — Documentation structure (architecture, routing, configuration, agents, benchmarking, troubleshooting, development)
+- `benchmark-baseline.json` — Saved baseline for regression detection
+- `--save-baseline`, `--baseline`, `--gate` flags to benchmark runner
+- `--scaling` mode with preset corpus sizes (16/100/500/1000/5000)
+- `ambiguity_recall`, `latency_p95_ms`, `metadata_reduction_pct` metrics
+- `pyproject.toml` — Standard Python packaging
+- `src/skill_router/__init__.py` — Packaging shim for pip install
+- `models.py` — Extracted model layer (Skill, load_manifest)
+
+### Changed
+- Branding unified to "Skill Router" throughout public-facing files
+- `manifest.json` aliases cleaned up (removed "Skill_by_Satya" alias)
+- `CONTRACT_MARKER` updated to `<!-- Skill Router:routing-contract -->`
+- `CONTRIBUTING.md` expanded with routing behavior change guidelines
+- `.gitignore` expanded with `.coverage`, `htmlcov/`, `.tox/`, `benchmark-results/`, `*.egg-info/`, `dist/`, `build/`, `wheels/`
+- Windows path test failure fixed in `test_install.py`
+- Benchmark accuracy language scoped to reflect gold-set limitations
+- Troubleshooting table entry for benchmark accuracy clarified
+- `skill.py` built-in benchmark includes per-case latency and p95 reporting
+- Scaling results documented with honest interpretation
+
+### Fixed
+- Test failure on Windows due to path separator in `test_install.py`
+
+## [2.0.0] — 2025-01-15
+
+### Added
+- Two-stage deterministic routing (cheap filtering + structured ranking)
+- Three-way decisions: `route`, `ambiguous`, `no_route`
+- Multi-skill plans with disjoint-dimension detection
+- Positive and negative routing boundaries (`use_when`, `not_when`)
+- Explicit call bonus with anchor requirement (adversarial protection)
+- Three-pass penalty system (not_when, object mismatch, conflicts)
+- Result caching with fingerprint-based invalidation
+- Drift detection between corpus and routing manifest
+- Conservative bootstrap for existing or empty repositories
+- Validation with exit codes
+- Gold-set benchmark (36 cases, 16-skill corpus)
+- Global/project installer with agent-specific layouts
+- `--version`, `--debug`, `--no-cache` CLI flags
+- Host-AI sanity check in maintenance contract
+
+[2.0.0]: https://github.com/coderdoctor97/skill-router/releases/tag/v2.0.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and
+expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy toward other community members
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project maintainer at the email listed in
+`SECURITY.md`.
+
+All complaints will be reviewed and investigated promptly and fairly. The
+project team is obligated to maintain confidentiality with regard to the
+reporter of an incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

CONTRIBUTING.md

@@ -20,3 +20,23 @@ A new skill belongs under `skills/<name>/` in a target agent repository and shou
 ## Compatibility
 
 Keep agent-specific paths in the installer/layout layer. Do not add hard-coded home directories, credentials, or machine-specific paths. Document any compatibility claim with a reproducible test.
+
+## Routing Behavior Changes
+
+Routing changes are behavioral changes even when the public API doesn't change. Before modifying routing logic:
+
+1. Add a regression test in `tests/test_router.py`.
+2. Add a gold-set case in `benchmarks/gold-set.json` if the behavior is not already covered.
+3. Run the full benchmark and confirm no regressions.
+4. Include `--debug` output in the PR description.
+
+## Documentation
+
+- Update `README.md` for user-facing changes.
+- Update `docs/` for detailed reference changes.
+- Update `SKILL.md` if the skill contract changes.
+- Run `python3 skill.py validate --root .` to catch manifest issues.
+
+## Installer Changes
+
+The installer is an important trust surface. Changes to `install.py` must be covered by `tests/test_install.py`. Test fresh install, upgrade, dry-run, uninstall, and the safety checks that prevent overwriting unrelated files.