{"id":50516209,"url":"https://github.com/sdsrss/onboard","last_synced_at":"2026-06-03T00:04:15.793Z","repository":{"id":357791684,"uuid":"1238515516","full_name":"sdsrss/onboard","owner":"sdsrss","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-14T10:35:29.000Z","size":151,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T10:38:44.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sdsrss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T07:30:30.000Z","updated_at":"2026-05-14T10:35:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sdsrss/onboard","commit_stats":null,"previous_names":["sdsrss/onboard"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sdsrss/onboard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fonboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fonboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fonboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fonboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sdsrss","download_url":"https://codeload.github.com/sdsrss/onboard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fonboard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33842017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T00:04:15.223Z","updated_at":"2026-06-03T00:04:15.779Z","avatar_url":"https://github.com/sdsrss.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# /onboard\n\n\u003e Make any legacy project Claude-Code-ready — without forcing AI tooling on your teammates.\n\n[![Release](https://img.shields.io/github/v/release/sdsrss/onboard?label=release\u0026color=blue)](https://github.com/sdsrss/onboard/releases)\n[![License](https://img.shields.io/github/license/sdsrss/onboard)](./LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-7c3aed)](https://docs.claude.com/en/docs/claude-code/plugins)\n[![Tests](https://img.shields.io/badge/tests-224%20passing-brightgreen)](./tests)\n\n**📖 Read this in other languages: [English](./README.md) · [简体中文](./README.zh-CN.md)**\n\n`/onboard` is a [Claude Code](https://claude.com/claude-code) Skill that walks a *legacy* project through a structured 10-phase onboarding protocol — discovering stacks, generating a token-compact `CLAUDE.md`, configuring guard hooks, aligning CI with local commands — **all offer-only, never auto-installing system tools**. Default `--local-only` mode writes zero project files; team members pulling the branch see nothing.\n\nCurrent version: **v3.2.0**.\n\n---\n\n## Why?\n\n| Problem | What `/onboard` does |\n|---|---|\n| Cold-starting Claude Code on a legacy repo takes hours of project archaeology | 10-phase protocol auto-discovers stacks, lockfiles, CI, forbidden zones, behavioral conventions (8-dimension deep analysis in Phase 1.7) |\n| A 5KB `CLAUDE.md` chews 5K tokens every turn | Extraction-first template, hard token ceiling at 5000 (soft cap 2500), empty sections omitted entirely |\n| AI-tool adoption shouldn't pollute the team's repo by default | `--local-only` is the default — all outputs land in `.claude/local-only/` + `.git/info/exclude`; zero `.gitignore` change, zero commits |\n| Letting an LLM `brew install` or `npm i` whatever it wants is a recipe for disaster | Iron Law 7 + meta-rule 19: every system install is **offer-only**, every project dependency change is batch-AUTH'd by a human |\n| `--uninstall` should be possible | v2.8+ marker/manifest/snapshot protocol makes every PROJECT write reversible (Iron-level reversibility) |\n\n## Features\n\n- **Multi-language stack support** (v2.4) — first-class for repos like TypeScript frontend + Python backend + ML pipeline; Phase 1 detects each stack, Phase 4 applies lint/format/typecheck per-stack, Phase 7 hook dispatches by file extension via `stacks.json`.\n- **Two modes** — `--local-only` (default, zero team pollution) and `--share` (opt-in, OUTPUT files committed).\n- **4 guard hooks** wired via `.claude/settings.json` — `guard-bash` (deny dangerous shell), `guard-edit` (forbidden-zone protection), `post-edit-check` (multi-stack format check), `stop-verify` (lint + typecheck on touched files).\n- **Doctor mode** (`--doctor`, v2.5+) — D1-D15 health checks, no writes, reports `healthy | drifted | broken`.\n- **Reversible by design** (v2.8+) — marker + manifest + snapshot make `--uninstall` precise; `=skill` (L1 only) and `=all` (L1+L2+L3) modes (v2.11+).\n- **Plugin marketplace standard** (v2.9+) — `/plugin marketplace add sdsrss/onboard` works natively.\n- **Lazy-loaded spec** (v3.0+) — SKILL.md keeps a compact entry; consumer Claude reads `phases/phase-7.md` / `phases/uninstall.md` / `references/state-schema.md` only when entering those scopes (meta-rule 27).\n- **Compact plan output** (v3.1+) — Phase 2 / 2.5 cards default to Top-N highlights (Top 3 for plan, Top 1-2 per install category), remainder folded as `+N more`; `--verbose-plan` restores full listing. Phase 0 now emits a first-run session-auth tip. Skill description expanded with English trigger surface for better discovery.\n- **Plugin matrix sub-file** (v3.2+) — 15-plugin recommendation matrix extracted to `references/recommendations.md`; SKILL.md keeps a 7-bullet sentinel summary; consumer Claude Reads the sub-file when entering Phase 2.5 (meta-rule 27 enumeration expanded to 4 sub-files). 3/3 Opus subagent dogfood verified the lazy-load contract.\n\n## Quick start\n\n### Option A · Claude Code plugin marketplace (recommended)\n\n```text\n/plugin marketplace add sdsrss/onboard\n/plugin install onboard\n```\n\nUpgrade:\n\n```text\n/plugin marketplace update onboard\n/plugin update onboard\n```\n\n### Option B · `curl | bash` universal installer\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/sdsrss/onboard/main/install.sh | bash             # install\ncurl -sSL https://raw.githubusercontent.com/sdsrss/onboard/main/install.sh | bash -s -- update\ncurl -sSL https://raw.githubusercontent.com/sdsrss/onboard/main/install.sh | bash -s -- doctor\ncurl -sSL https://raw.githubusercontent.com/sdsrss/onboard/main/install.sh | bash -s -- uninstall\n```\n\nEnvironment overrides: `ONBOARD_TARGET=project|user` · `ONBOARD_REPO` · `ONBOARD_BRANCH` · `ONBOARD_ALLOW_DIRTY=1` · `ONBOARD_CONFIRM_UNINSTALL=yes`.\n\n### Option C · Manual `git clone`\n\nThe skill files live at `skills/onboard/` inside the repo (Claude Code plugin convention), so a direct clone to `~/.claude/skills/onboard` would nest `SKILL.md` two levels deep. Clone to a fresh scratch dir, then copy the skill subtree:\n\n```bash\nSRC=$(mktemp -d -t onboard-src.XXXXXX)\ngit clone --depth 1 https://github.com/sdsrss/onboard.git \"$SRC\"\nmkdir -p ~/.claude/skills\ncp -r \"$SRC/skills/onboard\" ~/.claude/skills/\nchmod +x ~/.claude/skills/onboard/hooks/*.sh ~/.claude/skills/onboard/scripts/*.sh\nrm -rf \"$SRC\"\n```\n\n\u003e Using `mktemp -d` avoids `fatal: destination path … already exists` if you re-run after a typo.\n\n### First run\n\nIn a git-initialized project root:\n\n```text\n/onboard\n```\n\nClaude prints an **execution plan** first — phase list, current mode (`--local-only` by default), file-change budget, size class, total ETA — then waits for your confirmation. Each phase ends with a phase card showing what was changed.\n\n---\n\n## Modes\n\n| Mode | When to use | What gets written |\n|---|---|---|\n| `--local-only` (default, v2.6+) | Personal use on a team repo · team has no AI policy yet · OSS repo where you're a contributor · trial run | `CLAUDE.local.md` · `.claude/settings.local.json` · `.claude/local-only/*` · `.git/info/exclude` markers. **Zero changes** to tracked files. |\n| `--share` (opt-in) | Team has approved AI tooling · solo project where you want multi-machine sync · the team wants `CLAUDE.md` reviewed in PR | `CLAUDE.md` (tracked) · `.claude/settings.json` · `.claude/onboarding-logs/*` · revised `.gitignore` · optionally opens PR / MR via host adapter (`gh` / `glab` / `tea`) |\n\n**Why local-only is the default**: most teams have only a few AI-tool early adopters. Default-commit means one person's experiment forces tooling on the rest of the team. Default-local-only = zero team pollution risk; promote to `--share` after team alignment.\n\n**Mode is not silently switched**: changing modes mid-project requires `/onboard --update [--share|--local-only]` with hard AUTH.\n\n---\n\n## How it works\n\nFull protocol in [`skills/onboard/SKILL.md`](./skills/onboard/SKILL.md). The 10 phases and your role at each:\n\n| Phase | What happens | Your role |\n|---|---|---|\n| 0 · Preflight | git topology, host detection, tool availability | Resolve dirty tree / submodule / detached HEAD if flagged |\n| 0.5 · Migration | Inherit prior `--update` decisions | Skip if first run |\n| 1 · Discovery | Multi-stack detection, lockfiles, CI parsing | Review the \"Environment Report\" |\n| 1.5 · Blocking Decisions | Forbidden-zone candidates, lockfile/CI choices | Answer via enumerated DSL |\n| 1.7 · Deep Analysis (v2.7) | 8-dimension behavioral profile | Approve / correct findings |\n| 2 · Authorization | Touch budget, write scope | `proceed safe` / `approve install \u003cid\u003e` / `skip \u003cid\u003e` |\n| 2.5 · Install Plan (v2.7) | dev tools · system CLIs · runtimes · plugins | Batch authorize 4 lists |\n| 3 · CLAUDE.md | Extraction template, token-budget enforced | Review draft (hard cap 5000 tokens) |\n| 4 · Dev \u0026 Lint | Per-stack lint / format / typecheck integration | — |\n| 5 · Test | Test runner discovery + sanity | — |\n| 6 · Commit \u0026 CI Gates | Pre-commit / pre-push hooks | — |\n| 7 · Claude Code Hooks | 4 hooks installed via `settings.json` | — |\n| 8 · `.gitignore` \u0026 Verification | Final wiring; in `--share` mode offers PR/MR | — |\n\nRun a single phase with `/onboard --phase=\u003cn\u003e`. Re-onboard with `--resume` (same version) or `--update` (cross-version migration via Phase 0.5).\n\n---\n\n## Hooks\n\nFour hooks installed in `.claude/settings.json` (share) or `.claude/settings.local.json` (local-only):\n\n| Hook | Event | Purpose |\n|---|---|---|\n| `guard-bash.sh` | `PreToolUse` / `Bash` | Deny `rm -rf /`, force-push to main, `curl \\| sh`, project-defined `ONBOARD_FORBIDDEN_COMMANDS` regex list (v2.12.0+) |\n| `guard-edit.sh` | `PreToolUse` / `Edit\\|Write\\|MultiEdit` | Block edits inside `ONBOARD_FORBIDDEN_PATHS` (confirmed forbidden zones) |\n| `post-edit-check.sh` | `PostToolUse` / `Edit\\|Write\\|MultiEdit` | Log touched file + per-stack format check |\n| `stop-verify.sh` | `Stop` | Lint + typecheck on touched files per `ONBOARD_STOP_MODE` (`light` / `standard` / `strict`) |\n\nAll four follow **Iron Law 15** (exit 0 + stdout JSON, never mixed) and **Iron Law 19** (warn-only checks must exit 0).\n\n**Third-party hook coexistence** (v2.5+): independent matcher-block strategy — onboard never overwrites existing hooks, both are listed and Claude Code's \"deny-first\" semantics apply.\n\n**Plugin install path note**: `${CLAUDE_PLUGIN_ROOT}` is ephemeral (changes every plugin update). Onboard's Phase 7 default is to invoke `scripts/mirror-hooks.sh` (v2.10.1+, idempotent) to mirror hooks to a stable `~/.claude/onboard-runtime/hooks/` location; `settings.json` references the mirror.\n\n---\n\n## Doctor / Update / Uninstall\n\n```text\n/onboard --doctor              # D1-D15 health check, no writes\n/onboard --update              # cross-version migration (Phase 0.5)\n/onboard --update --local-only # switch from --share back to local-only\n/onboard --dry-run             # preview without writing\n/onboard --uninstall           # remove all onboard writes from this project\n/onboard --uninstall=skill     # uninstall only L1 user-global skill, preserve project config\n```\n\n**Uninstall protocol** (v2.8+, three-layer model in v2.11+): `=skill` clears L1 user-global (`~/.claude/skills/onboard/` + plugin cache + mirror), preserves project-side L2 (settings hook references) and L3 (hook scripts) via keeper-rewrite (`.claude/onboard-keeper/`). `=all` clears all three layers. Marker/manifest/snapshot make every PROJECT write reversible; users can `restore-snapshot` to recover the pre-onboard state.\n\n---\n\n## Requirements\n\n| Platform | Status | Notes |\n|---|---|---|\n| Linux | First-class | — |\n| macOS | First-class (v2.5+) | `brew install coreutils` recommended for `gtimeout` |\n| WSL2 | First-class | Treated as Linux |\n| Windows native | Not supported | Use WSL2 |\n\n**Tools**: `git`, `bash 3.2+`, `jq` (all required — installer refuses without jq because guard hooks shell out to it; missing jq silently disables `permissionDecision` deny payloads) · `coreutils` on macOS (strongly recommended) · `make` (optional).\n\n**Git host adapters** (Phase 8 PR/MR offer, never auto-execute): GitHub (`gh`), GitLab (`glab`), Gitea/Forgejo/Codeberg (`tea`); Bitbucket and unknown hosts fall back to web URLs.\n\n---\n\n## Verification\n\nAfter install + first run:\n\n```text\n/hooks\n```\n\nShould list 4 hook configs (PreToolUse × 2, PostToolUse, Stop). Test a forbidden-zone edit to confirm `guard-edit.sh` denies it; test a deliberate lint error to confirm `stop-verify.sh` blocks the Stop event.\n\nRun the in-repo test suite:\n\n```bash\nbash tests/run.sh\n# 10 integration tests / 224 assertions / 0 fail\n```\n\n---\n\n## Troubleshooting\n\n| Symptom | Check |\n|---|---|\n| `/onboard` not in command list | SKILL.md frontmatter `disable-model-invocation: true` may hit issue [anthropic#43875](https://github.com/anthropics/claude-code/issues/43875); temporarily remove or switch to Command form |\n| Hooks not firing | `/hooks` to confirm loaded; check `${CLAUDE_PROJECT_DIR}` expansion; verify `ls -l .claude/skills/onboard/hooks/` shows executable |\n| `guard-edit` false positive | Inspect `ONBOARD_FORBIDDEN_PATHS` env (colon-separated, no quotes, no spaces) |\n| `stop-verify` timing out | Lower `ONBOARD_STOP_MODE` to `light`, or tune per-stack `lint_timeout_sec` / `typecheck_timeout_sec` in `stacks.json` (v2.12+) |\n| `--update` migration fails | Old state backed up to `.claude/onboarding-state.v\u003cold\u003e.json.bak`; check Phase 0.5 output |\n\nFull troubleshooting + edge cases in [`SKILL.md`](./skills/onboard/SKILL.md) § \"异常处理\".\n\n---\n\n## Contributing\n\nThis repo evolved through **4 simulation-based stress testing rounds** in the v2 series (v2.0 → v2.4 was net-line-decrease; v2.5-v2.12 added features on real-run evidence). The v3 series begins with C1 SKILL.md shallow-split (lazy-load contract). Any change should follow this pattern:\n\n1. Run current version (simulated or real)\n2. Number each issue (P-A, P-B, …) with Critical / High / Medium / Low severity\n3. Accept-or-reject each with written rationale\n4. Roll the accepted set into the next version\n\nNo speculative features. See [`CLAUDE.md`](./CLAUDE.md) for full repo-maintainer conventions (Iron Laws, meta-rules, validation commands, file-classification, multi-stack discipline).\n\n**Bug reports**: capture the failing-state evidence (error message, state file, phase card) and open an issue. Evidence-driven PRs welcome.\n\n---\n\n## License\n\n[MIT](./LICENSE) — `Copyright (c) sds`.\n\n---\n\n## Links\n\n- [Full protocol spec (SKILL.md)](./skills/onboard/SKILL.md) · [Phase 7 hooks](./skills/onboard/phases/phase-7.md) · [Uninstall mode](./skills/onboard/phases/uninstall.md) · [State schema](./skills/onboard/references/state-schema.md)\n- [Changelog](./CHANGELOG.md) (full history; v3.2.0 = current)\n- [Releases](https://github.com/sdsrss/onboard/releases)\n- [Issues](https://github.com/sdsrss/onboard/issues)\n- [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/overview)\n- [Claude Code plugins documentation](https://docs.claude.com/en/docs/claude-code/plugins)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fonboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdsrss%2Fonboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fonboard/lists"}