skillpacks 0.1.0

package/docs/QUICKSTART.md

@@ -0,0 +1,137 @@
+# Quickstart
+
+Get from clone to a working skill in under 5 minutes.
+
+## Prerequisites
+
+- **Node.js 18+** for the `skillpacks` npm CLI and package build
+- **bash** shell (macOS, Linux, or WSL on Windows) for clone-based `./init.sh`, `scripts/pack.sh`, and remaining shell-backed `skillpacks` commands
+- **jq** for git-checkout `scripts/pack.sh` write commands and `skillpacks install-deck` materialization: `brew install jq` (macOS) or `apt install jq` (Debian/Ubuntu). Node-owned `skillpacks install`, `remove`, `refresh`, `doctor`, `prune`, `pin`, `unpin`, `status`, `list-packs`, `set-mode`, and `set-update-mode` do not require `jq`
+- **Claude Code** or **OpenAI Codex** installed on your machine
+- **pnpm** (optional, for running tests): `npm install -g pnpm`
+
+## 1. Choose an Install Path
+
+### Source checkout
+
+Use the source checkout when you are developing this repository or before the public npm package is published:
+
+```bash
+git clone <this-repo-url> ~/agentic-skills
+cd ~/agentic-skills
+./init.sh
+```
+
+`init.sh` symlinks the global core skills into `~/.claude/skills/` and `~/.codex/skills/`. Domain packs are not installed globally — that is intentional context hygiene.
+
+### npm CLI
+
+After the first public package is published, use `npx skillpacks` from the project that should receive local skills:
+
+```bash
+cd ~/my-project
+npx skillpacks --version
+npx skillpacks list
+```
+
+The npm CLI does not install global core skills by default. It writes project-local pack configuration and skill roots in the current working directory.
+
+## 2. Install a Pack in Your Project
+
+Navigate to any project repository and install the pack that matches your domain:
+
+```bash
+cd ~/my-project
+~/agentic-skills/scripts/pack.sh install devtool    # for developer tools
+~/agentic-skills/scripts/pack.sh install game        # for games
+~/agentic-skills/scripts/pack.sh install business-discovery  # for SaaS/business apps
+```
+
+With npm after publication:
+
+```bash
+npx skillpacks install devtool
+npx skillpacks install game
+npx skillpacks install business-discovery
+```
+
+This creates `.agents/project.json` and project-local skill roots in `.claude/skills/` and `.codex/skills/`.
+
+The npm CLI can also install a canonical deck from manifest metadata:
+
+```bash
+npx skillpacks install-deck business-afps
+npx skillpacks install-deck devtool-afps
+npx skillpacks install-deck game-afps
+```
+
+## 3. Reload Skills in Your CLI
+
+Skills are not hot-reloaded. After installing:
+
+- **Claude Code:** run `/reload-skills`, then `/clear` or restart the session. If `.claude/skills/` did not exist when the session started, restart Claude Code entirely.
+- **Codex:** start a fresh Codex CLI session.
+
+## 4. Verify the Installation
+
+Source checkout:
+
+```bash
+~/agentic-skills/scripts/pack.sh status
+```
+
+npm after publication:
+
+```bash
+npx skillpacks status
+```
+
+Or from within Claude Code: run `/pack` with no arguments. From Codex: run `$pack`.
+
+## 5. Run Your First Skill
+
+The AFPS (Alignment First, Prototype Second) workflow is the default product workflow. A typical first cycle:
+
+**Claude Code:**
+```
+/codebase-status          # see what you're working with
+/idea-scope-brief         # shape a rough idea into a scoped brief
+```
+
+**Codex:**
+```
+$codebase-status
+$idea-scope-brief
+```
+
+For projects with an existing `tasks/todo.md`:
+```
+/exec                     # execute the next planned step
+```
+
+## 6. Confirm It Worked
+
+After running a skill, look for these artifacts:
+
+- `tasks/todo.md` — updated task list
+- `tasks/history.md` — shipped work log entry
+- A git commit with the skill's output
+- An alignment page in `alignment/` (for research skills)
+
+## Migration Notes
+
+Moving from a source checkout to npm does not change the project-local files. From the target project directory, run the npm command that matches your existing pack designation:
+
+```bash
+npx skillpacks refresh
+npx skillpacks doctor
+```
+
+`skillpacks@<semver>` selects the package snapshot. Skill pins remain skill-level pins, for example `npx skillpacks pin quality-sweep v0.0`. If a pinned archive version is not present in the installed npm package, upgrade the npm package or use a source checkout that contains that archive.
+
+## What's Next
+
+- Run `/skills` or `$skills` to browse all available skills
+- See [pack-workflow-matrix.md](pack-workflow-matrix.md) for workflow ordering and dependencies
+- See [skill-anatomy.md](skill-anatomy.md) to understand or create skills
+- See [troubleshooting.md](troubleshooting.md) if something goes wrong

package/docs/decks.md

@@ -0,0 +1,189 @@
+# Decks
+
+A **deck** is a named workflow sequence — a documentation and installation concept that guides which packs to install and in what order. Decks are not a directory or runtime primitive; they describe a canonical path through the skill system.
+
+A **workflow** is the runtime execution of a deck's skill sequence in a specific project.
+
+## The Five Decks
+
+Decks sit on two axes: **domain** (business / consumer, developer / OSS, or game / playable entertainment) and **tempo** (rapid vs. deliberate). Not every domain has both tempos yet.
+
+|  | Business / Consumer | Developer / OSS | Game / Playable Entertainment |
+| --- | --- | --- | --- |
+| **Rapid** (days) | VARD | ORD | Not defined yet |
+| **Deliberate** (weeks–months) | Business AFPS | Devtool AFPS | Game AFPS |
+
+Rapid decks are for weekly experiments. Deliberate decks are for products that justify full discovery, lifecycle planning, and growth strategy.
+
+Source-checkout deck installs use the underlying pack commands shown below. After the first public npm package is published, the equivalent npm path is:
+
+```bash
+npx skillpacks install-deck vard
+npx skillpacks install-deck ord
+npx skillpacks install-deck business-afps
+npx skillpacks install-deck business-afps --full
+npx skillpacks install-deck devtool-afps
+npx skillpacks install-deck game-afps
+```
+
+In the current release candidate, npm deck materialization still uses the packaged shell backend, so `install-deck` requires `bash` and `jq`. Direct npm pack installs such as `npx skillpacks install devtool` are Node-owned and do not require `jq`.
+
+---
+
+## VARD — Viral App Rapid Distribution
+
+**Tempo:** Rapid (idea to shipped app in days)
+**Domain:** Business / consumer apps
+
+**Install:**
+
+```bash
+scripts/pack.sh install vard
+```
+
+**Canonical chain:**
+
+```text
+vard-scan -> vard-align -> vard-ship
+```
+
+**Skills:**
+- `vard-scan` — scan for viral app opportunities
+- `vard-align` — go/no-go feasibility check
+- `vard-ship` — deploy, landing page, analytics, ship log
+
+**Graduation:** When an experiment shows traction, graduate to Business AFPS:
+
+```bash
+scripts/pack.sh install business-discovery
+```
+
+Then start the deliberate pipeline with `/idea-scope-brief` or `/customer-discovery`.
+
+---
+
+## ORD — OSS Rapid Distribution
+
+**Tempo:** Rapid (pain point to published package in days)
+**Domain:** Developer tools / OSS
+
+**Install:**
+
+```bash
+scripts/pack.sh install ord
+```
+
+**Canonical chain:**
+
+```text
+ord-scan -> ord-align -> ord-ship
+```
+
+**Skills:**
+- `ord-scan` — scan for OSS tool opportunities
+- `ord-align` — validate feasibility, check npm namespace
+- `ord-ship` — publish to npm, README, repo setup, ship log
+
+**Graduation:** When a package gains traction (stars, downloads, issues), graduate to Devtool AFPS:
+
+```bash
+scripts/pack.sh install devtool
+```
+
+Then start the deliberate pipeline with `/devtool-adoption` or `/devtool-positioning`.
+
+---
+
+## Business AFPS — Deliberate Business Pipeline
+
+**Tempo:** Deliberate (weeks to months)
+**Domain:** Business / consumer / SaaS products
+
+**Install:**
+
+```bash
+scripts/pack.sh install business-discovery
+```
+
+Add packs progressively as the product matures:
+
+```bash
+scripts/pack.sh install customer-lifecycle   # after ICP + competitive analysis
+scripts/pack.sh install business-growth      # after lifecycle evidence
+scripts/pack.sh install business-ops         # for ongoing operations
+```
+
+**Canonical chain:**
+
+```text
+business-discovery -> customer-lifecycle -> business-growth -> business-ops
+```
+
+See `docs/pack-workflow-matrix.md` for the full default route with optional detours.
+
+---
+
+## Devtool AFPS — Deliberate Devtool Pipeline
+
+**Tempo:** Deliberate (weeks to months)
+**Domain:** Developer tools, CLIs, libraries, SDKs
+
+**Install:**
+
+```bash
+scripts/pack.sh install devtool
+```
+
+**Canonical chain:**
+
+```text
+devtool-positioning -> devtool-adoption -> devtool-dx-journey -> devtool-docs-audit -> devtool-monetization
+```
+
+**Skills:** `devtool-positioning`, `devtool-adoption`, `devtool-user-map`, `devtool-workflow`, `devtool-integration-map`, `devtool-dx-journey`, `devtool-docs-audit`, `devtool-monetization`.
+
+---
+
+## Game AFPS — Deliberate Game Development Pipeline
+
+**Tempo:** Deliberate (weeks to months)
+**Domain:** Video games and playable entertainment
+
+**Install:**
+
+```bash
+scripts/pack.sh install game
+```
+
+**Canonical chain:**
+
+```text
+game-audience -> game-fantasy -> game-genre-map -> game-comparables
+-> game-core-loop -> game-prototype-test -> game-playtest-metrics
+-> game-store-page-test -> game-launch -> game-roadmap
+```
+
+**Skills:** `game-audience`, `game-fantasy`, `game-genre-map`, `game-comparables`, `game-core-loop`, `game-prototype-test`, `game-playtest-metrics`, `game-store-page-test`, `game-launch`, `game-roadmap`, `game-workflow`.
+
+Game AFPS uses the AFPS tempo with game-specific proof gates: align on audience, fantasy, genre, and comparable expectations first; then validate the playable loop, playtest evidence, store-page promise, launch plan, and roadmap.
+
+---
+
+## Graduation Path
+
+Rapid decks feed into deliberate decks when experiments prove out:
+
+```text
+VARD ──(traction)──> Business AFPS
+ORD  ──(traction)──> Devtool AFPS
+```
+
+The graduation signal differs by deck:
+- **VARD → Business AFPS:** Users return, share organically, or revenue appears. The experiment justifies full customer discovery and lifecycle planning.
+- **ORD → Devtool AFPS:** npm downloads grow, GitHub stars accumulate, or issues from real users arrive. The package justifies full positioning, adoption strategy, and documentation depth.
+
+Game AFPS currently has no rapid feeder deck. Small game prototypes should either start directly with `game-audience` / `game-core-loop` inside the `game` pack or use Game AFPS when the concept warrants deliberate playtest-driven validation.
+
+## npm Distribution
+
+When distributed via npm, decks map to package-list and registry-tag metadata that the CLI can materialize from the current backend. The npm package semver selects the bundled deck and skill snapshot, while skill-level pins continue to use each skill's `version:` value. See `docs/skillpacks-npm-distribution.md` and `alignment/idea-scope-brief-npm-distribution.html` for the approved distribution route.

package/docs/packs.md

@@ -0,0 +1,293 @@
+# Project-Local Skill Packs
+
+Project-local packs keep domain-specific workflows out of global assistant context.
+
+## Design
+
+- Global skills live in `global/{claude,codex}`.
+- Domain packs live in `packs/<pack>/{claude,codex}`.
+- Project designation lives in `.agents/project.json`.
+- Mixed monorepos can declare scoped domain routing in `.agents/project.json.project_scopes`.
+
+Example:
+
+```json
+{
+  "project_type": "game",
+  "enabled_packs": ["game"],
+  "skill_pack_version": 1
+}
+```
+
+Mixed monorepo example:
+
+```json
+{
+  "project_type": "devtool",
+  "enabled_packs": ["devtool", "business-discovery", "business-growth"],
+  "skill_pack_version": 1,
+  "project_scopes": [
+    {
+      "path": "apps/pitwall-local",
+      "project_type": "devtool",
+      "packs": ["devtool"],
+      "purpose": "Pitwall Local / OSS developer utility work."
+    },
+    {
+      "path": "apps/pitwall-calcllm",
+      "project_type": "business-app",
+      "packs": ["business-discovery", "business-growth"],
+      "purpose": "CalcLLM-powered connected edition research, GTM, monetization, and SaaS product work."
+    },
+    {
+      "path": "packages/calcllm-sync",
+      "project_type": "business-app",
+      "packs": ["business-discovery", "business-growth"],
+      "purpose": "Connected-edition sync and SaaS integration work."
+    }
+  ]
+}
+```
+
+In this model, `project_type` is the default designation for uncategorized work, `enabled_packs` is the union of local skills available in the repo, and each `project_scopes[]` entry tells agents which pack family to apply for a path or glob.
+
+## Commands
+
+Source-checkout commands:
+
+```bash
+scripts/pack.sh list
+scripts/pack.sh recommend
+scripts/pack.sh install game
+scripts/pack.sh install business-discovery
+scripts/pack.sh install business-growth
+scripts/pack.sh install business-ops
+scripts/pack.sh install devtool
+scripts/pack.sh install creator-foundation
+scripts/pack.sh install youtube-ops
+scripts/pack.sh install code-quality
+scripts/pack.sh install agentic-skills-bench
+scripts/pack.sh install monorepo
+scripts/pack.sh install remotion
+scripts/pack.sh install project-fleet
+scripts/pack.sh install alignment-loop
+scripts/pack.sh remove game
+scripts/pack.sh refresh
+scripts/pack.sh status
+scripts/pack.sh doctor                     # read-only drift report; non-zero exit if any install is stale
+scripts/pack.sh set-update-mode <mode>     # mode is one of: warn | auto | unset
+```
+
+npm CLI equivalents after publication:
+
+```bash
+npx skillpacks list
+npx skillpacks install game
+npx skillpacks install business-discovery
+npx skillpacks install devtool
+npx skillpacks install code-quality
+npx skillpacks remove game
+npx skillpacks refresh
+npx skillpacks status
+npx skillpacks doctor
+npx skillpacks set-update-mode <mode>
+```
+
+`npx skillpacks install <name>` accepts either a pack name or a skill name from the packaged manifest. Node-owned npm commands preserve `.agents/project.json` fields without requiring `jq`; source-checkout `scripts/pack.sh` write commands still use `jq` for structured JSON edits.
+
+`doctor` and `set-update-mode` are part of the skill-install drift model — see [Skill-install drift](#skill-install-drift-track-latest-vs-pinned) below.
+
+The npm CLI can install canonical decks from manifest metadata: `npx skillpacks install-deck vard`, `npx skillpacks install-deck ord`, `npx skillpacks install-deck business-afps`, `npx skillpacks install-deck devtool-afps`, and `npx skillpacks install-deck game-afps`. Deck materialization still uses the packaged shell backend in this phase, so it requires `bash` and `jq`.
+
+Assistant-native usage also supports guided setup:
+
+- Claude: run `/pack` with no arguments.
+- Codex: run `$pack` with no arguments.
+
+If `.agents/project.json` already exists, bare `pack` refreshes local skill roots from the committed project designation. If it is missing, the assistant inspects the repository, recommends a pack, and asks before installing. Claude uses AskUserQuestion for that checkpoint; Codex uses a text-based Pack Decision Checkpoint that waits for an explicit reply before writing `.agents/project.json`.
+
+The `refresh` command recreates `.claude/skills` and `.codex/skills` managed skill roots from `.agents/project.json`; it is not an in-session Claude Code or Codex skill reload. After `install`, `remove`, or `refresh`, start a fresh CLI session if the changed skills are not visible.
+
+## Local Skill Roots
+
+Pack install creates repo-managed skill roots in the current project:
+
+```text
+.claude/skills/<skill>/SKILL.md
+.codex/skills/<skill>/SKILL.md
+```
+
+The skill source stays centralized in this repository. Projects opt into packs without copying skill bodies, and active installed roots exclude archived `SKILL.md` snapshots.
+
+## Pack Selection
+
+- Use `business-discovery` for ICP, market/customer discovery, value proposition, positioning, lean canvas, and journeys.
+- Use `business-growth` for GTM, growth, metrics, monetization, landing copy, experiments, and PMF.
+- Use `business-ops` for assumptions, feedback/cohorts/retros, risks, runway, stakeholder updates, platform strategy, and research reconciliation.
+- Use `code-quality` as an additive pack for behavior-preserving refactors, type hygiene, import honesty, dependency-boundary cleanup, and module organization.
+- Use `agentic-skills-bench` when working in this repository and needing to verify or benchmark-test one skill with the local harness.
+- Use `game` for Game AFPS: video games, prototypes, playable entertainment, loop validation, playtests, and store-page/wishlist validation.
+- Use `devtool` for SDKs, CLIs, APIs, libraries, infrastructure products, and developer-facing platforms.
+- Use `creator-foundation` for creator-media evidence foundations, dossiers, positioning, programming, series, product-led media mapping, and metrics review.
+- Use `youtube-ops` for YouTube channel/video audits, unlisted prelaunch reviews, external-video context, competitive research, packaging, metadata, portfolio, benchmarking, search, and cadence.
+- Use `monorepo` for pnpm workspace monorepos, with optional Turborepo, that need package-aware lane specs, guardrails, and scoped shipping.
+- Use `remotion` for Remotion-oriented format research, scene-by-scene video scripting, and build/scaffold planning.
+- Use `project-fleet` for control repos that manage many downstream repos, clone/spec-store portfolios, or spin-offs.
+- Use `alignment-loop` for lightweight operator-agent calibration before committing to a full spec-interview pipeline.
+- PoketoWork kanban packs are hibernated while Poketo.work is being rebuilt.
+
+The hibernated packs are preserved under `archive/hibernated-packs/2026-06-poketowork-rebuild/` and are not available for active install or recommendation.
+
+`business-app` is a compatibility alias that expands to `business-discovery`, `business-growth`, and `business-ops`. `creator-media` is a compatibility alias that expands to `creator-foundation` and `youtube-ops`.
+
+For the full workflow/dependency matrix, see [`docs/pack-workflow-matrix.md`](pack-workflow-matrix.md).
+
+## Monorepo Pack
+
+The `monorepo` pack is an execution overlay for pnpm workspace repositories. It targets repositories with `pnpm-workspace.yaml` and optionally `turbo.json`.
+
+```bash
+scripts/pack.sh install monorepo
+```
+
+Skills:
+
+```text
+mono-detect, mono-exec, mono-guard, mono-ship
+```
+
+The pack uses an augmentation injection pattern. Its skills add pre/post behavior around the global `exec` and `ship` contracts instead of replacing them:
+
+- `mono-detect` writes `.agents/monorepo.json` with workspace packages, package paths, package scripts, dependency graph, and Turborepo awareness.
+- `mono-exec` injects monorepo detection, lane-spec generation, guard pre-flight checks, serial cross-cutting work, and package-scoped dispatch around standard `run`.
+- `mono-guard` validates lane specs before dispatch and checks integrated diffs against declared ownership after dispatch.
+- `mono-ship` injects package-scoped test/lint/build and transitive-dependent validation before delegating to standard `ship`.
+
+This differs from the former `*-kanban` duplication pattern. The hibernated kanban packs provided alternate command variants such as `exec-kanban`, `ship-kanban`, and `ship-end-kanban`; the active monorepo pack keeps the global lifecycle skills authoritative and makes them workspace-aware through pre/post steps.
+
+Lane dispatch uses two artifacts:
+
+```text
+.agents/lane-specs.json
+tasks/lane-specs.md
+```
+
+`.agents/lane-specs.json` is the machine-readable lane plan. `tasks/lane-specs.md` is the committed human-readable mirror. Lane lifecycle values are `draft`, `approved`, `dispatched`, `integrated`, and `failed`; package lanes declare `packages`, `owns`, `must_not_edit`, `depends_on`, and `mode`.
+
+Specs and roadmap phases may declare package scope with YAML frontmatter:
+
+```yaml
+---
+packages: [api, web]
+scope: cross-cutting
+---
+```
+
+Use `scope: package-scoped` when work is contained to declared package paths, `scope: cross-cutting` when work touches shared packages or multiple package boundaries, and `scope: root-only` for root config, scripts, docs, or repository policy. If `scope` is omitted, agents infer `package-scoped` for one package and `cross-cutting` for multiple packages.
+
+## Remotion Pack
+
+The `remotion` pack contains the production path that turns reference-video research and creator-media strategy into Remotion-ready artifacts.
+
+```bash
+scripts/pack.sh install remotion
+```
+
+Skills:
+
+```text
+youtube-format-research, video-script, video-build
+```
+
+Default flow:
+
+```text
+youtube-format-research -> video-script -> video-build
+```
+
+Install it alongside `creator-foundation` and, when YouTube evidence is needed, `youtube-ops` for the full path from channel evidence, positioning, programming, or product-led media strategy into production:
+
+```bash
+scripts/pack.sh install creator-foundation youtube-ops remotion
+```
+
+## Alignment Loop Pack
+
+The `alignment-loop` pack is a lightweight planning on-ramp for projects that need shared taste and intent before a full specification cycle.
+
+```bash
+scripts/pack.sh install alignment-loop
+```
+
+Skills:
+
+```text
+taste-calibration, destination-doc, vertical-slice-splitter
+```
+
+Default flow:
+
+```text
+taste-calibration -> destination-doc -> vertical-slice-splitter -> implementation
+```
+
+## Compatibility
+
+If a tool does not discover project-local `.claude/skills` or `.codex/skills`, use the global `pack` and `research-roadmap` skills as launchers. They should read `.agents/project.json` and the local pack files directly.
+
+Do not install `packs/*` globally as a fallback; that recreates the context pollution this design avoids.
+
+Commit `.agents/project.json` with the project. Do not commit generated local skill roots under `.claude/skills` or `.codex/skills`; recreate them with `/pack`, `$pack`, or `scripts/pack.sh refresh`.
+
+`scripts/pack.sh install`, `remove`, `refresh`, and `set-mode` preserve existing `project_scopes`, `notes`, and `skill_updates` fields when `jq` is available. The npm `skillpacks` Node-owned project commands preserve `project_scopes`, `notes`, `pinned_versions`, `enabled_skills`, `skill_updates`, and `agent_mode` without requiring `jq`; see `docs/skillpacks-npm-distribution.md` for the current command compatibility matrix.
+
+To migrate an existing project from a local checkout workflow to npm after publication, keep `.agents/project.json` committed and run `npx skillpacks refresh` from that project. The generated `.claude/skills` and `.codex/skills` roots will be recreated from the package snapshot. If the project pins a skill version, the installed package must include that skill's `archive/<version>/SKILL.md`.
+
+Pack writes use `.agents/.pack.lock` with owner metadata (`pid`, `started_at`, `command`). If a previous pack command exits without releasing the lock and its recorded process is no longer running, the next pack command removes the stale lock automatically. If a live process still owns the lock, timeout errors include the owner metadata.
+
+## Skill-install drift (track-latest vs pinned)
+
+Installs are **copies** of canonical sources stamped with a `.agentic-skills-managed` marker. The marker now records `source_version` (the canonical `version:` at install time) and `source_sha` (a deterministic content hash of the source, excluding `archive/` and the marker). This makes "the canonical skill moved ahead of my installed copy" observable.
+
+- **Track-latest (default).** A plain managed copy follows canonical. When the canonical source changes, the recorded `source_sha` no longer matches, and the install is reported as `stale`.
+- **Pinned (frozen).** `scripts/pack.sh pin <skill> <ver>` installs `archive/<ver>` as a **symlink**; pinned installs report `pinned` and are never `stale`. `unpin` returns the skill to track-latest. There is no separate per-skill "policy" field — pinned vs latest is encoded solely by presence in `.agents/project.json` `pinned_versions`.
+
+Report and refresh:
+
+```bash
+scripts/pack.sh doctor     # read-only drift report (ok / stale / unknown / pinned / missing-source); non-zero exit if any stale
+scripts/pack.sh refresh    # re-copy installs from canonical, rewriting markers and clearing drift
+```
+
+`doctor` statuses: `ok` (matches canonical), `stale (vOld → vNew)` (canonical moved), `unknown` (a pre-upgrade marker has no `source_sha` — run `refresh` once to enable tracking, never a false `stale`), `pinned vX (frozen)`, and `missing-source` (canonical path gone). `doctor` only detects *canonical moved*; it does not detect local edits to an installed copy.
+
+**Update mode.** `.agents/project.json` may carry `skill_updates.mode` — `warn` (default) or `auto`. Set it with `scripts/pack.sh set-update-mode <warn|auto|unset>`. A trigger (the session-start hook, or sync-with-approval) that sees `mode == auto`, or global `~/.agentic-skills/preferences.json` `skills.auto_refresh == true`, runs `refresh` automatically; otherwise it only warns. `doctor` itself never mutates — it renders the effective policy.
+
+**Session-start hook (opt-in, off by default).** `/init-agentic-skills` offers to enable a `SessionStart` hook (`scripts/skill-drift-hook.sh`) that warns about stale installs at session start, or auto-refreshes when `skills.auto_refresh` / `skill_updates.mode == auto` is set. Register or remove the hook directly with `scripts/init-agentic-skills.sh hook enable|disable`, which writes (or clears) the `~/.claude/settings.json` `SessionStart` entry and sets the `session_start_hook` preference. Preferences live in `~/.agentic-skills/preferences.json` under `skills` (`session_start_hook`, `auto_refresh`); set them with `scripts/init-agentic-skills.sh set-pref <key> <value>` and inspect them with `scripts/init-agentic-skills.sh show-prefs`. Disable by declining the prompt, running `scripts/init-agentic-skills.sh set-pref session_start_hook false`, or `scripts/init-agentic-skills.sh hook disable`.
+
+Global installs follow the same model: `scripts/init-agentic-skills.sh doctor` reports global drift against `global/<tool>/<skill>`, and `/init-agentic-skills update` re-copies them (the global "refresh").
+
+## Team Setup Checklist
+
+For teams adopting agentic-skills across multiple developers:
+
+1. **Choose a checkout path.** Each developer clones this repo locally. The path does not need to match across developers, but `scripts/pack.sh refresh` may need to re-run if the checkout moves.
+2. **Run `./init.sh` once per developer.** This installs global core skills to each developer's `~/.claude/skills/` and `~/.codex/skills/`.
+3. **Commit `.agents/project.json`.** This file records the project's pack designation and should be checked into the target project repository.
+4. **Never commit generated skill roots.** `.claude/skills/` and `.codex/skills/` in consumer projects are generated from `.agents/project.json`. Add them to `.gitignore`.
+5. **Run `scripts/pack.sh refresh` after pulling pack changes.** When `.agents/project.json` changes upstream (e.g. a new pack is added), each developer runs refresh to recreate their local skill roots.
+6. **Restart CLI after install/remove/refresh.** Skills are not hot-reloaded. Claude Code: `/reload-skills` then `/clear` or restart. Codex: fresh session.
+7. **Agree on shipping workflow.** The default is direct-to-primary (commit and push to main/master). If your team uses feature branches, note this in `.agents/project.json` `notes` or your project's CLAUDE.md.
+
+## Former Global Domain Skills
+
+Business/product workflows that used to be globally installed now live in narrow business packs. Prefer the current lane:
+
+```bash
+scripts/pack.sh install business-discovery
+scripts/pack.sh install customer-lifecycle
+scripts/pack.sh install business-growth
+scripts/pack.sh install business-ops
+```
+
+`business-app` remains a compatibility alias that installs all four. Creator-media and YouTube work is split between `creator-foundation`, `youtube-ops`, and `remotion`; fleet/portfolio work lives in `project-fleet`.