foomakers · rucka · Jul 8, 2026 · Jul 6, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/.claude/skills/pair-capability-setup-gates/SKILL.md b/.claude/skills/pair-capability-setup-gates/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pair-capability-setup-gates
-description: "Configures CI/CD quality gates per quality-assurance guidelines, producing pipeline configuration for the adopted tech stack. Reads existing gate config from way-of-working. Idempotent: detects existing configuration, confirms rather than re-configuring."
+description: "Configures CI/CD quality gates per quality-assurance guidelines, producing pipeline configuration for the adopted tech stack. Provisions shared lint/format config packages and husky pre-commit/pre-push hooks. Reads existing gate config from way-of-working. Idempotent: detects existing configuration, confirms rather than re-configuring."
 version: 0.4.1
 author: Foomakers
 ---
@@ -27,13 +27,16 @@ Configure CI/CD quality gates for the project. Reads quality assurance guideline
 
 1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) → look for Quality Gates section and Custom Gate Registry.
 2. **Check**: Scan for existing CI/CD pipeline files (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, etc.).
-3. **Branch**:
-   - **Gates fully configured** (Quality Gates section + Custom Gate Registry + pipeline files exist) → present current config:
+3. **Check**: Scan for existing shared lint/format config packages (e.g. `tools/*-config`, `packages/*-config`) and hook manager setup (`.husky/`, `lefthook.yml`, `.git/hooks/` via `simple-git-hooks`, etc.).
+4. **Branch**:
+   - **Gates fully configured** (Quality Gates section + Custom Gate Registry + pipeline files + shared config/hooks exist) → present current config:
 
      > Quality gates already configured:
      > - Quality gate command: `[command]`
      > - Custom gates: [N gates listed]
      > - CI/CD pipeline: [file(s)]
+     > - Shared config packages: [package list | none found]
+     > - Hook manager: [husky | override | none found]
      >
      > Update configuration? (Only if developer explicitly requests.)
 
@@ -47,6 +50,7 @@ Configure CI/CD quality gates for the project. Reads quality assurance guideline
 1. **Act**: Read quality assurance guidelines:
    - [quality-assurance.md](../../../.pair/knowledge/guidelines/technical-standards/git-workflow/quality-assurance.md) — gate types and checklists
    - [quality-gates.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/quality-gates.md) — gate framework and registry format
+   - [shared-config-packages.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/shared-config-packages.md) — shared-config-package pattern, per-type overrides, `tools/*` reference implementation
 2. **Act**: Read adopted tech stack:
    - [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) — languages, test framework, linter, formatter
    - [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) — existing process
@@ -96,12 +100,29 @@ Configure CI/CD quality gates for the project. Reads quality assurance guideline
    - Other → document commands for manual pipeline setup
 3. **Verify**: Configuration files written.
 
-### Step 5: Record Decision
+### Step 5: Provision Shared Lint/Format Config + Hooks
+
+1. **Check**: For each config already detected in Step 1 that is not conflicting, skip provisioning it and note it as already present.
+2. **Act**: Following [shared-config-packages.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/shared-config-packages.md), provision one shared config package per lint/format concern the adopted tech stack uses (lint, format, types, and any project-specific linters). Split each into base + per-type presets (backend/frontend/shared-lib) only where the tool's rules actually diverge by runtime — pair's own `tools/*` is the reference implementation.
+3. **Act**: Install the hook manager and wire the hooks:
+   - **Check Step 1.3 first**: if a hook manager was already detected on disk, it is the de facto override — use it, record it in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) if not already recorded, and skip installing husky.
+   - **Otherwise, husky is the KB default** (decision D21/Q11). Use it unless [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) records a hook-manager override — if it does, use the overridden tool instead.
+   - `.husky/pre-commit` (or equivalent) — fast local checks (lint and/or type-check).
+   - `.husky/pre-push` (or equivalent) — pre-push lint (at minimum the adopted lint command; may be the full quality-gate command).
+   - Wire the install step (e.g. `"prepare": "husky install"`) into the root `package.json`.
+4. **Verify**: Run the adopted lint command — it passes out of the box (AC3). Confirm the hook files are executable and fire on a trial commit/push.
+
+**Edge Cases:**
+
+- **Existing conflicting config** (a workspace already has its own lint/format config file that would be replaced): ask before overwriting — "Found existing `[file]`. Replace with the shared config, keep it, or merge?" Never overwrite silently.
+- **Non-JS project**: the shared-config-package mechanism (`extends`/`require`/package-manager fields) is JS/TS-specific. Degrade to documenting the pattern generically (see shared-config-packages.md § Non-JS / Polyglot Projects) and pointing to the ecosystem's equivalent config package; skip file generation.
+
+### Step 6: Record Decision
 
 1. **Act**: Compose `/pair-capability-record-decision`:
    - `$type: non-architectural`
    - `$topic: quality-gate-configuration`
-   - `$summary: "Quality gates configured: [gate list]. Command: [command]. CI: [pipeline type]."`
+   - `$summary: "Quality gates configured: [gate list]. Command: [command]. CI: [pipeline type]. Shared config packages: [list]. Hook manager: [husky | override]."`
 2. **Verify**: Decision recorded.
 
 ## Output Format
@@ -113,6 +134,8 @@ GATE CONFIGURATION COMPLETE:
 ├── CI:              [N gates configured]
 ├── Pre-production:  [N gates configured | N/A]
 ├── Pipeline:        [file path | manual]
+├── Shared configs:  [package list | N/A — non-JS, documented pointer only]
+├── Hooks:           [husky pre-commit + pre-push | override: <tool> | N/A]
 ├── Adoption:        [way-of-working.md — updated]
 ├── Record:          [ADL path — created]
 └── Status:          [Complete | Confirmed existing | Updated]
@@ -135,10 +158,12 @@ When invoked **independently**:
 - If tech-stack.md is not found, ask developer for tooling choices to generate appropriate gate commands.
 - If `/pair-capability-record-decision` is not installed, warn and skip decision recording.
 - If no CI/CD platform is detectable, document gate commands for manual execution and skip pipeline file generation.
+- If the project is not JS/TS, document the shared-config-package pattern generically (see [shared-config-packages.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/shared-config-packages.md) § Non-JS / Polyglot Projects) and skip config-file generation — point to the ecosystem's equivalent shared config package.
 
 ## Notes
 
-- This skill **modifies files** — it writes to way-of-working.md and creates/updates CI/CD pipeline configuration.
-- **Idempotent**: re-invocation on an already-configured project confirms the existing configuration. Update only on explicit developer request.
+- This skill **modifies files** — it writes to way-of-working.md, creates/updates CI/CD pipeline configuration, and provisions shared lint/format config packages + hook manager files (`.husky/` by default).
+- **Idempotent**: re-invocation on an already-configured project confirms the existing configuration, including already-provisioned shared configs and hooks. Update only on explicit developer request. If a conflicting local config is found, ask before overwriting — never overwrite silently.
 - Gate commands must be executable in the project's development environment. Verify commands exist before writing.
 - Custom Gate Registry format follows the table schema from [quality-gates.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/quality-gates.md): Order, Gate, Command, Scope Key, Required, Description.
+- **Hook manager default**: husky (decision D21/Q11). Adoption can override — record the override in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) and this skill reads it before provisioning.
diff --git a/.pair/adoption/decision-log/2026-07-08-husky-default-hook-manager.md b/.pair/adoption/decision-log/2026-07-08-husky-default-hook-manager.md
@@ -0,0 +1,43 @@
+# Decision: Husky as Default Git Hook Manager
+
+## Date
+
+2026-07-08
+
+## Status
+
+Active
+
+## Category
+
+Tooling Preference
+
+## Context
+
+Story #232 ("Shared lint/format config guideline + setup-gates provisioning") extends `pair-capability-setup-gates` to provision Git hooks (pre-commit lint/type-check, pre-push lint) alongside shared lint/format config packages. This requires a KB-wide default hook manager so `setup-gates` has a deterministic choice when a project has no hook manager on disk yet.
+
+During #232's refinement session this was resolved as an open question (**Q11**) and recorded only in the story body's "Refinement Session Insights" ("Q11 decided — husky default with adoption override") — never formalized as a decision record. The story's own Acceptance Criteria and Business Rules reference "decision Q11" and "D21" as if a durable record existed, creating a dangling citation. This ADL closes that gap.
+
+## Decision
+
+**Husky is the KB default Git hook manager.** `pair-capability-setup-gates` installs husky (`.husky/pre-commit`, `.husky/pre-push`, `"prepare": "husky install"`) when provisioning hooks on a project with no hook manager already detected on disk.
+
+This follows **D21** ("Adoption = solo delta" — convention over configuration): the default lives entirely in the KB, so a project that accepts husky writes nothing extra to its adoption files. A project may override the hook manager by recording the override in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md); `setup-gates` reads that override before defaulting to husky, and an already-detected on-disk hook manager (Step 1.3 of `SKILL.md`) takes precedence over both.
+
+## Alternatives Considered
+
+- **lefthook**: faster (Go binary, no Node dependency), but adds a non-JS toolchain requirement to every bootstrapped project — inconsistent with the KB's JS/TS-first reference implementation (`tools/*` shared config packages already assume a Node toolchain).
+- **simple-git-hooks**: minimal footprint, but lacks husky's `prepare` lifecycle integration and is less commonly known, raising onboarding friction for contributors already familiar with husky from this monorepo's own tooling.
+- **No default (always ask)**: rejected — contradicts D21's convention-over-configuration principle; would force every bootstrap to answer a question with an obvious, low-stakes default.
+
+## Consequences
+
+- `pair-capability-setup-gates` (both the dataset source and the installed mirror) provisions husky by default; no adoption file changes are required for projects that accept the default.
+- Projects that already use a different hook manager, or that explicitly record an override in `way-of-working.md`, are unaffected — `setup-gates` defers to that choice.
+- Non-JS projects degrade to a documentation pointer (see [shared-config-packages.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/shared-config-packages.md) § Non-JS / Polyglot Projects) — husky provisioning is skipped, not forced.
+
+## Adoption Impact
+
+- No mandatory change to any project's adoption files — the husky default requires zero adoption footprint (D21).
+- [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) gains an optional "Hook manager" override field, used only when a project deviates from husky.
+- `pair-capability-setup-gates` `SKILL.md` (dataset + installed mirror) documents this decision inline (Notes section: "Hook manager default: husky (decision D21/Q11)").
diff --git a/apps/website/content/docs/reference/guidelines-catalog.mdx b/apps/website/content/docs/reference/guidelines-catalog.mdx
@@ -58,7 +58,7 @@ Code organization, principles, and quality standards.
 | **Design Principles** | SOLID, DRY, KISS, composition over inheritance, evidence-based do/don't design rules |
 | **Framework Patterns** | Framework-specific patterns and best practices |
 | **Package Management** | Dependency management, monorepo patterns |
-| **Quality Standards** | Code metrics, complexity thresholds, maintainability |
+| **Quality Standards** | Code metrics, complexity thresholds, maintainability, shared lint/format config packages |
 
 ### Collaboration
 

diff --git a/apps/website/content/docs/tutorials/team-setup.mdx b/apps/website/content/docs/tutorials/team-setup.mdx
@@ -137,6 +137,8 @@ Edit `.pair/adoption/tech/way-of-working.md` to define your team's quality gate:
 
 Every developer and every AI assistant will run these checks before committing.
 
+Prefer automation over hand-editing: `/pair-capability-setup-gates` provisions shared lint/format config packages (per-type overrides for backend/frontend/shared-lib workspaces) plus pre-commit + pre-push hooks, defaulting to husky. See the [shared config packages guideline](https://github.com/foomakers/pair/blob/main/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/code-design/quality-standards/shared-config-packages.md) for the pattern — pair's own `tools/*` is the reference implementation. Override the hook manager by recording your choice in `way-of-working.md` before running the skill.
+
 ### 7. Record key decisions
 
 For significant decisions that need rationale, create Architecture Decision Records (`/pair-next` may suggest this when decisions are pending):

diff --git a/packages/knowledge-hub/dataset/.pair/adoption/tech/way-of-working.md b/packages/knowledge-hub/dataset/.pair/adoption/tech/way-of-working.md
@@ -12,6 +12,8 @@ This document defines the **validated development practices and team workflows**
 
 - `pnpm quality-gate` is the adopted project-level quality gate command.
 - Quality gate includes: type checking (`ts:check`), testing (`test`), linting (`lint`), formatting (`prettier:fix`).
+- **Hook manager**: `husky` (KB default, decision D21/Q11) — pre-commit runs fast local checks, pre-push runs lint. Override here if the project uses a different hook manager (e.g. `lefthook`, `simple-git-hooks`); `/pair-capability-setup-gates` reads this override before provisioning.
+- **Shared config packages**: see [shared-config-packages.md](../../knowledge/guidelines/code-design/quality-standards/shared-config-packages.md) for the lint/format/type-config pattern and per-type override structure.
 
 ### Custom Gate Registry
 

diff --git a/...-hub/dataset/.pair/knowledge/guidelines/code-design/quality-standards/README.md b/...-hub/dataset/.pair/knowledge/guidelines/code-design/quality-standards/README.md
@@ -22,6 +22,7 @@ Quality standards provide guidance on linting, formatting, code metrics, coverag
 - `linting-tools.md` (recommended linters and rules)
 - `eslint.md` (ESLint configuration and conventions)
 - `prettier-formatting.md` (formatting rules)
+- `shared-config-packages.md` (shared-config-package pattern, per-type overrides, `tools/*` reference)
 - `code-metrics.md` (metrics & measurement)
 - `coverage.md` (coverage targets and strategies)
 - `technical-debt.md` (tracking and remediation)
@@ -66,6 +67,7 @@ Guidelines for linting, formatting, code metrics, test coverage and automation t
 - `linting-tools.md`
 - `eslint.md`
 - `prettier-formatting.md`
+- `shared-config-packages.md`
 - `code-metrics.md`
 - `coverage.md`
 - `technical-debt.md`

diff --git a/...-hub/dataset/.pair/knowledge/guidelines/code-design/quality-standards/eslint.md b/...-hub/dataset/.pair/knowledge/guidelines/code-design/quality-standards/eslint.md
@@ -115,7 +115,7 @@ For existing codebases, introduce ESLint rules gradually:
 
 ### Team Configuration
 
-**Shared Config Package**: Create a shared ESLint configuration package for consistency across projects. This centralizes rule decisions and makes updates easier.
+**Shared Config Package**: Create a shared ESLint configuration package for consistency across projects. This centralizes rule decisions and makes updates easier. See [shared-config-packages.md](shared-config-packages.md) for the full pattern (per-type presets, bin wrappers, reference implementation).
 
 **Rule Documentation**: Document the reasoning behind custom rules, especially those that differ from community standards. This helps team members understand the rationale.